Agent configuration
Every environment variable the agent reads on a machine it does not own.
The agent listens on nothing and holds one credential. Its configuration is a validated schema read in exactly one place, like everything else here.
Required
| Variable | |
|---|---|
CONTROL_PLANE_URL | Where to dial. The path is appended for you. |
AGENT_TOKEN | Issued once by the portal when the server was registered, and never shown again. |
CONTROL_PLANE_URL=https://portal.example.com
AGENT_TOKEN=<the token the portal issued>Use an https:// control-plane URL — so the socket is wss:// — in anything
but a local experiment. The connection carries the token and every command the
control plane issues.
If you lose the token, rotate it from the server's page in the portal. The running agent keeps working until it reconnects; the old token stops being accepted immediately.
Host paths
| Variable | Default | |
|---|---|---|
HOST_PROC_PATH | Unset | Where the host's /proc is mounted inside the agent's container. |
HOST_SYS_PATH | Unset | The host's /sys. |
HOST_ROOT_PATH | Unset | The host's /. |
DOCKER_SOCKET_PATH | /var/run/docker.sock |
Leave these unset outside a container. Unset inside one means every metric describes the agent's container rather than the machine — which looks entirely plausible on a dashboard and is wrong.
The enrolment command the portal generates already sets them and bind-mounts the three paths.
Connection
| Variable | Default | |
|---|---|---|
AGENT_VERSION | 0.0.1 | Reported in the opening frame, so the portal can name a stale agent. |
AGENT_RECONNECT_MIN_SECONDS | 2 | |
AGENT_RECONNECT_MAX_SECONDS | 60 | The ceiling means a control plane down for a day is retried hourly rather than hammered. |
AGENT_HEARTBEAT_SECONDS | 25 | Deliberately below any sensible proxy idle timeout: more reverse proxies than not close an idle WebSocket at 60 seconds. |
AGENT_MAX_UPLOAD_BYTES | 209715200 | Cap on one uploaded archive. Matches the control plane's own cap — a lower value here would fail a deployment the portal already accepted. |
Running it
The portal generates the full docker run command when you register a server. Run it as root
on the target machine.
Give the container --restart unless-stopped, or a reboot leaves the server showing as not
connected with no container and no log to explain it.
Its logs
docker logs -f sthora-agentWhat the messages mean is in troubleshooting.