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.

## Provider model

A transport provider is the implementation AMPG uses to publish one protocol target.
Every provider must resolve to a local endpoint, generated config, managed state, and a
health check.

Provider sources:

- `configured`: explicit config from `gateway.toml` or approved generated snippets.
- `bundled-sidecar`: a provider shipped with AMPG or an app bundle and run from AMPG
  state.
- `system-adopted`: a healthy daemon that AMPG did not start and does not own.
- `system-managed`: an installed daemon binary supervised through AMPG-owned state.
- `platform-package`: a daemon package installed by an allowlisted apply stage.
- `operator-interface`: physical or link-layer setup that remains operator-owned.
- `external`: render outputs and review artifacts only.

## Discovery order

For each enabled protocol, AMPG checks:

1. Explicit config in `gateway.toml`.
2. Bundled AMPG providers for the current platform.
3. AMPG-owned state from previous runs.
4. Common system services and ports.
5. Known config paths for supported daemons.
6. Platform package backends for managed install stages.

The result is shown in `ampg status` as `provider_source`. `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 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.