Multi-Host Management

dockmesh can manage a fleet of Docker hosts from a single server. Remote hosts run a lightweight agent binary that connects outbound to the server over mTLS — no inbound ports required on the remote side.

Adding a remote host

Agents → New agent
Enter a friendly name (only the name is asked here — tagging happens on the Hosts page after the agent comes online)
dockmesh generates an enrolment token — a one-time bearer string — and shows you the install command to paste on the remote host

That command points back to your dockmesh server (not a CDN) and looks like this:

curl -fsSL https://dockmesh.example.com/install/agent.sh?token=<enrollment-token> | sudo bash

Flags you can append (after | sudo bash -s --):

--as-root — run the agent as root instead of creating a dedicated dockmesh user (less secure, simpler)
--skip-docker — don’t try to install Docker even if it’s missing

The script downloads the agent binary, installs a systemd unit, performs the mTLS handshake using the one-time token, and registers the host. Within seconds it shows up in the UI as Online. The enrolment installer is currently Linux/systemd-only — for a macOS agent, build dockmesh-agent from source and start it manually with DOCKMESH_ENROLL_URL + DOCKMESH_TOKEN in its env.

How the agent works

Outbound WSS (WebSocket + TLS) connection from agent to server
mTLS: agent presents a client certificate issued during enrollment; server presents its cert
Multiplexed over a single TCP connection — stats, logs, exec, deploy commands all share it
Auto-reconnect with exponential backoff
Auto-upgrade: when the server is updated, agents are upgraded transparently on next connect

Because the connection is outbound, you can put agents behind NAT, in home labs, on edge devices — as long as they can reach the server URL, they work.

Fan-out views

Any list page (Containers, Stacks, Volumes, Images, Networks) has a host filter at the top. Leave it set to All hosts to see everything across the fleet with the host column populated. Filter to a single host for a focused view.

The Dashboard shows aggregate CPU, memory, and disk across all hosts, plus per-host tiles.

Host tags and groups

Tag hosts with arbitrary labels (prod, staging, gpu, eu-west-1) from the Hosts page (host detail → edit tags). Tags today drive two things:

RBAC role-scope — restrict a custom role’s reach to hosts matching specific tags
Registry credentials scope — apply a private-registry credential only to hosts carrying matching tags, so a Harbor PAT can be limited to prod agents

Tag-based routing for alerts and backup jobs is not wired up yet — both still target specific stacks / hosts directly. If you need “alert only when a prod host fires” today, scope it via the RBAC permission system or scope the rule to a specific host.

Removing a host

Agents → select agent → Revoke marks the agent revoked. The next handshake is rejected and the agent exits cleanly. To re-enrol, rotate the enrolment token on the agent detail page and run dockmesh-agent on the host with the new token.