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

# 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:

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

```sh
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 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 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. 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`.

`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.

`deploy apply --stage state` is the first 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 second 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.

`--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.