The node agent
Status: available, opt-in. sol2docker works fully without an agent — every page degrades to what the Engine API alone can prove, never to a broken one. This page lists the per-node features that light up once you deploy one, and why they're gated.
The agent is a separate Go codebase, shipped as the ghcr.io/sol2docker/agent
image. It reports outbound only, needs no inbound port, and
proves which node it is on with every report — so one node's agent can't report as, or collect
work queued for, another. See deploy examples to add it.
Why a per-node agent is needed
The Docker Engine API is per-node. A Swarm manager sees cluster-level objects (services, tasks, nodes, cluster-scoped networks/volumes/secrets/configs) but for anything on a node's local daemon it can only see and act on its own node:
docker imagesreturns only the manager's local images — not what each worker pulled.docker image prune/docker system pruneare node-local.- There is no live per-node CPU / RAM / disk metric in the API (
docker node inspectgives advertised capacity only). - Container lifecycle events are node-local — a manager sees swarm-object events cluster-wide, but container events only from its own daemon.
Anything needing "the real state of each node" needs code running on each node reporting back — that's the agent.
What it unlocks
Each row is something the Engine API alone can't answer honestly, and that becomes real with the agent. "Today" is exactly what the UI does without one — inferred, scoped to the manager, or an empty state. Nothing is faked to fill a gap.
| Feature | With the agent | Without an agent |
|---|---|---|
| Cross-node image inventory | Real image list on every node (refs, tags, digests, sizes, dangling, in-use) → a populated Swarm Images page. | The Swarm Images page shows an empty state prompting you to deploy an agent. |
| Fleet / per-node image prune | Prune dangling or all-unused images per node or fleet-wide, and see what each node reclaimed. | Prunes fan out via a fire-and-forget global job; they run, but report no per-node result. |
| Live node metrics | Actual CPU / RAM / disk usage per node → usage bars, host-pressure alerts, disk totals. | Node detail shows advertised capacity only; the dashboard omits host/disk panels. |
| Per-node local resources | Local-driver volumes and node-scoped networks as they truly exist. | Locality is inferred from task placement. |
| Engine health per node | Daemon version, storage driver, warnings, disk-pressure per node. | Only the manager daemon's info/version. |
| Worker-node events | Each agent forwards its daemon's lifecycle events → the Events page covers the whole cluster. | Manager's own container events plus cluster-wide swarm-object events only. |
Works without an agent
Everything else already works without an agent and stays that way — cluster lifecycle, services, service/task logs across all nodes (the manager proxies them cluster-wide via the Swarm logs API), secrets/configs, standalone containers, volume file-browse/backup, env health probes, and usage alerts on the daemon you're connected to.
Non-goals (even with the agent)
- Image build / push / tag / save-load — image creation belongs to CI, not here.
- Editing the daemon's own
daemon.json/ host configuration.