adaptive-multi-protocol-gateway/docs/daemon-management.md

Daemon Management

Status: draft | Updated 2026-07-07 | 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:

1. Explicit config in gateway.toml.
2. AMPG-owned state from previous runs.
3. Common system services and ports.
4. 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 --free-domain-hints
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 deploy apply --stage packages --dry-run --profile mobile-i2p
python3 -m ampg --config gateway.toml deploy apply --stage packages --profile mobile-i2p --yes
python3 -m ampg --config gateway.toml deploy apply --stage state --dry-run --profile mobile-i2p
python3 -m ampg --config gateway.toml deploy apply --stage state --profile mobile-i2p --yes
python3 -m ampg --config gateway.toml deploy apply --stage supervisor --dry-run --profile mobile-i2p
python3 -m ampg --config gateway.toml deploy apply --stage supervisor --profile mobile-i2p --yes
python3 -m ampg --config gateway.toml deploy apply --stage start --dry-run --profile mobile-i2p
python3 -m ampg --config gateway.toml deploy apply --stage start --profile mobile-i2p --yes
python3 -m ampg --config gateway.toml deploy apply --stage addresses --dry-run --profile mobile-i2p
python3 -m ampg --config gateway.toml deploy apply --stage addresses --profile mobile-i2p --yes
python3 -m ampg --config gateway.toml deploy apply --stage health --dry-run --profile mobile-i2p
python3 -m ampg --config gateway.toml deploy apply --stage health --profile mobile-i2p --yes
python3 -m ampg --config gateway.toml doctor --platform android-termux

deploy plan summarizes the current deployment in plain stages: source, build, DNS, doctor, daemons, packages, 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. With --free-domain-hints, it also prints optional third-party community subdomain registries for operators who do not yet own a domain.

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.

deploy apply --stage packages installs selected managed-daemon packages with structured, allowlisted platform commands. Adopted and external daemons are skipped. Platforms without an automatic package backend remain manual review items.

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. deploy apply --stage addresses and addresses capture read daemon-written address files from AMPG state or a protocol address_file override, then update 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. deploy apply --stage health runs the published checks after addresses are configured or captured.

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.

deploy apply --stage packages is the first live apply stage. Dry-run mode prints AMPG_DEPLOY_PACKAGE rows. Live mode requires --yes, runs only structured package-manager commands for selected managed daemons, and reports installed, skipped, or blocked results. It does not write config, register services, start daemons, capture addresses, or run health checks.

deploy apply --stage state is the second live apply stage. Dry-run mode prints AMPG_DEPLOY_STATE rows. Live mode requires --yes, refuses unapproved or stale artifacts, creates AMPG-owned state directories, and copies approved managed-daemon config into gateway.state_dir. It does not install packages, edit adopted daemon configs, start services, or delete identity material.

deploy apply --stage supervisor is the third live apply stage. Dry-run mode prints AMPG_DEPLOY_SUPERVISOR rows. Live mode requires --yes, refuses unapproved or stale artifacts, requires the state stage to have copied managed config first, and writes AMPG-named service files for the selected platform. It does not install packages, start services, reload service managers, or delete service files.

deploy apply --stage start is the fourth live apply stage. Dry-run mode prints AMPG_DEPLOY_START rows with exact service-manager commands. Live mode requires --yes, requires both state and supervisor files to exist, and runs only structured platform commands for AMPG-named services. It does not install packages, rewrite config, remove files, capture addresses, or run health checks.

deploy apply --stage addresses is the fifth live apply stage. Dry-run mode prints AMPG_DEPLOY_ADDRESS rows for configured, skipped, missing, and capturable addresses. Live mode requires --yes and writes captured transport addresses under gateway.state_dir. It does not rewrite daemon config or run health checks.

deploy apply --stage health is the sixth live apply stage. Dry-run mode prints AMPG_DEPLOY_HEALTH rows with published fixture URLs and transport commands. Live mode requires --yes, runs those commands, and reports pass/fail. It does not change daemon config, service state, or address registries.

--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. deploy apply --stage packages is the executable package stage for supported automatic backends: Systemd hosts use sudo apt install, Termux uses pkg install, and macOS uses brew install. User-space Linux asks the operator to use the local package manager until AMPG has a concrete backend for that environment.

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.