Phase 5: multi-host agents (0.5.0)

- stackpilot-agent: slim token-guarded FastAPI (reuses compose_service) exposing
  stack CRUD/lifecycle/logs + system info; same image, different CMD. agent/
  Dockerfile + compose + .env.example.
- Central proxy: Agent model, agent_service (httpx ping/proxy + live status:
  online/offline/unauthorized + hostname/last_seen), routers/agents.py
  (CRUD + ping + proxied stacks/lifecycle/logs/system).
- Frontend: Settings → Remote hosts (add/check/remove, connectivity dot); Stacks
  grouped by host; remote stack detail with lifecycle, live logs, compose/.env edit.

Verified end-to-end: agent+main on a shared network — register (good/bad token),
list/create/start/logs/delete remote stacks, offline detection (502).

Remote backup destinations (SFTP/S3) deferred.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

README.md

@@ -4,8 +4,8 @@ A self-hosted Docker Compose manager for power users and homelab enthusiasts —
 as intuitive as Dockge, as capable as Portainer for Compose workflows.
 
 > **Status:** Phase 1 (Core) + Phase 2 (Volumes & GPU) + Phase 3 (Quality of
-> Life) + Phase 4 (Operations) complete. Multi-host agents are planned for a
-> later phase.
+> Life) + Phase 4 (Operations) + Phase 5 (Multi-host) complete. Remote backup
+> destinations (SFTP/S3) are planned for a later phase.
 
 ## What works today (Phase 1)
 
@@ -70,9 +70,30 @@ as intuitive as Dockge, as capable as Portainer for Compose workflows.
 - **Audit log page**: searchable, paginated view of all recorded actions.
 - **Mobile-responsive layout**: off-canvas sidebar + adaptive spacing.
 
-> **Not yet:** multi-host agents (a second deployable agent app + remote proxying)
-> and remote backup destinations (SFTP/S3) are intentionally deferred to a future
-> phase — backups currently download to / upload from the browser.
+### Phase 5 — Multi-host
+
+- **Remote agents**: deploy `stackpilot-agent` (same image, different CMD) on any
+  host — it needs only the Docker socket and a shared `AGENT_TOKEN`, and exposes a
+  slim, token-guarded stack/system API (no UI, no DB).
+- **Central management**: add hosts under **Settings → Remote hosts** (name, agent
+  URL, token) with a live connectivity dot. The Stacks page groups stacks by host
+  ("This host" + one section per agent); remote stacks have their own detail view
+  with full lifecycle (start/stop/restart/pull/update/down), live logs, and
+  compose/.env editing — all proxied to the agent.
+
+> **Not yet:** remote backup destinations (SFTP/S3) — backups currently download
+> to / upload from the browser.
+
+## Deploying an agent on another host
+
+```bash
+cd agent
+cp .env.example .env          # set a strong AGENT_TOKEN
+docker compose up -d          # exposes the agent on :5010
+```
+
+Then in the central UI: **Settings → Remote hosts → Add host** with
+`http://<that-host>:5010` and the same `AGENT_TOKEN`.
 
 ## Architecture
 
@@ -174,6 +195,21 @@ GET    /api/auth/users                            POST /api/auth/users
 PATCH  /api/auth/users/{id}                        DELETE /api/auth/users/{id}
 ```
 
+### Phase 5 endpoints
+
+```
+GET    /api/agents                                POST /api/agents
+PUT    /api/agents/{id}                            DELETE /api/agents/{id}
+POST   /api/agents/{id}/ping                       GET  /api/agents/{id}/system
+GET    /api/agents/{id}/stacks | /{sid}            GET  /api/agents/{id}/stacks/{sid}/logs
+POST   /api/agents/{id}/stacks                     PUT  /api/agents/{id}/stacks/{sid}
+DELETE /api/agents/{id}/stacks/{sid}               POST /api/agents/{id}/stacks/{sid}/{action}
+
+agent (on the remote host, Bearer AGENT_TOKEN):
+GET    /agent/ping | /system | /stacks | /stacks/{id} | /stacks/{id}/logs
+POST   /agent/stacks | /stacks/{id}/{action}       PUT/DELETE /agent/stacks/{id}
+```
+
 ## Security notes
 
 - The Docker socket is only ever touched by the backend process; it is never