8.8 KiB
Daemon Management
Status: draft | Updated 2026-07-06 | Applies to: protocol adapters
AMPG can use daemons that already exist on a server or create AMPG-owned daemons when the selected protocol is not running. This keeps simple deployments simple while avoiding surprise edits to operator-owned services.
Ownership rules
Adopted daemons:
- are already installed and healthy.
- keep their existing service manager and primary config ownership.
- receive generated snippets only after the operator approves the plan.
- are never rewritten wholesale by AMPG.
Managed daemons:
- store config under
state_dir. - expose logs and health through AMPG.
- use AMPG-owned ports, sockets, hidden-service dirs, key files, and output roots.
- can be stopped, restarted, or removed by AMPG.
Discovery order
For each enabled protocol, AMPG checks:
- Explicit config in
gateway.toml. - AMPG-owned state from previous runs.
- Common system services and ports.
- Known config paths for supported daemons.
The result is shown in ampg status. ampg plan shows rendered outputs and reviewable
config artifacts.
Preflight commands
python3 -m ampg --config gateway.toml deploy plan --profile mobile-i2p
python3 -m ampg --config gateway.toml dns plan --profile vps-full
python3 -m ampg --config gateway.toml dns plan --profile vps-full --mode dynamic --behind-router
python3 -m ampg --config gateway.toml dns check --profile vps-full
python3 -m ampg --config gateway.toml status
python3 -m ampg --config gateway.toml doctor
python3 -m ampg --config gateway.toml install-plan --profile mobile-i2p
python3 -m ampg --config gateway.toml install-plan --profile mobile-i2p --write-artifacts
python3 -m ampg --config gateway.toml state-contract --profile mobile-i2p
python3 -m ampg --config gateway.toml addresses list --profile mobile-i2p
python3 -m ampg --config gateway.toml addresses capture --profile mobile-i2p
python3 -m ampg --config gateway.toml health-plan --profile mobile-i2p
python3 -m ampg --config gateway.toml apply --dry-run
python3 -m ampg --config gateway.toml apply --dry-run --profile mobile-i2p
python3 -m ampg --config gateway.toml apply --dry-run --protocol i2p
python3 -m ampg --config gateway.toml apply --dry-run --write-artifacts
python3 -m ampg --config gateway.toml approvals list --profile mobile-i2p
python3 -m ampg --config gateway.toml approvals approve --profile mobile-i2p --all
python3 -m ampg --config gateway.toml doctor --platform android-termux
deploy plan summarizes the current deployment in plain stages: source, build, DNS,
doctor, daemons, artifacts, addresses, and apply preflight. It prints the next commands
to run and does not change files or services.
dns plan prints clearnet DNS records and reachability hints. Static mode plans A/AAAA
and www records. Dynamic mode supports a Dynamic DNS hostname and warns when apex
records require provider-specific ALIAS/ANAME or API-updated A/AAAA support. With
--behind-router, it also lists port forwarding, IPv6, explicit router mapping,
reverse-tunnel, and DNS-01 certificate options.
status prints one row per enabled protocol with the selected platform provider,
adapter, installed/running daemon probe, action, and policy result.
doctor checks source paths, renderer support, route exposure, output readiness, and
daemon policy feasibility. It exits nonzero only for errors; missing build output is a
warning so operators can run it before the first build.
install-plan prints the package, state-directory, managed-config, supervisor, and
health-check steps needed for AMPG-owned daemons. It is dry-run only. Adopted daemons and
external-policy targets are shown as skipped, while unsupported platform/daemon pairs are
blocked.
install-plan --write-artifacts writes managed daemon configs and platform supervisor
files under the configured plan_root, grouped by site, protocol, and platform. For
Tor/I2P HTTP publishing, AMPG writes both transport-daemon artifacts and loopback nginx
artifacts. The generated daemon configs store runtime state, identity keys, logs, and
daemon-written addresses under gateway.state_dir.
state-contract prints the resolved managed-state paths for enabled protocols, including
which paths are AMPG-owned, daemon-written, required, or sensitive.
addresses list prints the effective public address for each enabled protocol:
configured, captured, derived, or placeholder. addresses capture reads daemon-written
address files from AMPG state or a protocol address_file override, then updates the
address registry under state_dir.
health-plan prints fixture-based checks to run after services start. Published checks
target real transport URLs; preview checks target local loopback preview endpoints.
Missing output blocks the plan, while placeholder transport addresses are review items.
approvals list prints generated artifact candidates and their digest status. approve
requires --all or a --kind filter, then records approvals only for artifacts that
exist and match the current generator output. Missing, edited, or stale artifacts remain
review items.
apply --dry-run prints the activation sequence for each enabled protocol: generated
output readiness, config artifacts to review, daemon action, address capture or reuse,
and post-apply health checks. It also prints AMPG_APPLY_PREFLIGHT plus blocked or
review preflight items across activation, managed-state copies, and supervisor actions.
It exits nonzero when the preflight status is blocked. --write-artifacts writes
reviewable config snippets to the configured plan root, then prints the copies from
approved artifacts into gateway.state_dir and the supervisor services that would be
registered or started. It still does not install or reload services.
--protocol scopes operational commands to selected enabled protocols. A clearnet
adopt failure will block a full activation run, but it will not block
apply --dry-run --protocol i2p because clearnet is outside that selected run.
--profile loads named command defaults from gateway.toml. Profiles can set selected
protocols, platform provider, and safe artifact-writing defaults. Explicit command-line
flags override profile defaults.
Platform providers describe how AMPG may supervise managed daemons:
linux-systemd: system service management after approval.linux-user: user-space foreground or user service management.macos-launchd: user LaunchAgents or foreground processes.android-termux: Termux-style user-space daemons for mobile/server experiments.unknown: render and plan only; daemon management is disabled.
Package commands in install-plan are review hints, not executed actions. Systemd hosts
currently emit apt-style package hints, Termux emits pkg, macOS emits brew, and
user-space Linux asks the operator to use the local user package manager.
Adapter notes
Clearnet
Default daemon: nginx.
AMPG should usually adopt clearnet ingress instead of managing it. Existing TLS, firewall, and reverse proxy rules are operator-owned. Managed clearnet is useful for development and single-purpose boxes.
Tor
Default daemon: Tor.
If Tor is already running, AMPG can add a hidden service snippet that points to the
privacy-html local server. If Tor is missing and policy is auto or manage, AMPG
creates an AMPG-owned Tor instance or service unit and stores hidden-service material
under the AMPG state directory.
I2P
Default daemon: i2pd.
AMPG first supports server tunnels through i2pd. I2P-Zero can be added as a second adapter with the same interface. Managed I2P must keep destination keys in AMPG state and include backup warnings in the plan.
Gemini
Default daemon: Agate.
Gemini is static-friendly and can be managed safely. AMPG generates .gmi output,
certificates when requested, and Agate plan values pointing at the Gemini output root.
Reticulum
Default daemon: rnsd or a compatible page server.
Reticulum management is split: AMPG can manage generated Micron pages and a page-serving
process, but physical interfaces such as LoRa, serial, packet radio, or custom transports
may require explicit operator setup. ampg plan must distinguish page-server readiness
from transport-interface readiness.
Safety requirements
- Show every config write before applying it.
- Generate snippets into the plan root before any install or reload step.
- Back up any adopted-daemon snippet AMPG touches.
- Never delete hidden-service keys, I2P keys, or Reticulum identities without an explicit destructive command.
- Refuse to bind public ports when the selected renderer is not built.
- Health-check every enabled protocol after apply.
Reusable checklist
- Adapter detects existing daemon state.
- Adapter can produce a dry-run plan.
- Managed config is isolated under AMPG state.
- Key material is backed up or clearly called out.
- Health check validates the generated site through the selected transport.