Summary
Implement the Linux host agent and the first home-main deployment adapter.
The agent must work behind home NAT and manage one persistent Classic server on
UDP port 1731 without exposing a remote shell or Docker socket.
Implementation / behavior
- Establish an authenticated outbound WebSocket to the control plane and
reconnect with bounded exponential backoff.
- Register capabilities and report bounded heartbeat, version, liveness, and
deployment status.
- Verify target, operation, commit, image repository, and digest against local
policy before doing work.
- Pull the exact GHCR image, back up server-data, and replace the Compose
service with graceful shutdown.
- Wait for the container health check and expected server heartbeat.
- Preserve the previous known-good image reference and restore it after a
failed deployment.
- Keep home-main on UDP 1731 with an independent state directory and QUIC
identity; never touch the later stable 5.34.x target on UDP 1730.
- Make every operation idempotent and report accepted, started, healthy,
failed, and rolled-back transitions.
Acceptance criteria
- The agent functions with no inbound TCP port, static IP, or hostname.
- A dropped connection during every lifecycle phase can be recovered without
running two deployments concurrently.
- Image references are digest-pinned before Compose replacement.
- Backups and data-format-changing rollback behavior are explicit and tested.
- The agent refuses arbitrary commands, paths, environment variables, image
registries, and unit names from the control plane.
- An installation runbook covers systemd, Docker permissions, GHCR access,
router UDP forwarding, logs, backups, and recovery.
Dependencies
Non-goals
- Do not grant the agent official-server deployment authority.
- Do not execute untrusted PR code on the deployment host.
Summary
Implement the Linux host agent and the first home-main deployment adapter.
The agent must work behind home NAT and manage one persistent Classic server on
UDP port 1731 without exposing a remote shell or Docker socket.
Implementation / behavior
reconnect with bounded exponential backoff.
deployment status.
policy before doing work.
service with graceful shutdown.
failed deployment.
identity; never touch the later stable 5.34.x target on UDP 1730.
failed, and rolled-back transitions.
Acceptance criteria
running two deployments concurrently.
registries, and unit names from the control plane.
router UDP forwarding, logs, backups, and recovery.
Dependencies
feat(control): implement NAT-friendly agent control plane #2
feat(webhook): receive verified GitHub events and persist target state #3
Non-goals