Agent Status Files
While it runs, every connect agent keeps a status file: a small JSON document saying what each of its
tunnels is doing, where they can be reached, whether the agent is signed in, and whether it is ready.
connect agent status reads these files, so it works without the management interface, without knowing
its address, and without credentials. Scripts and other tools can read them too.
Where they are
Each agent writes to its status directory, in this order of precedence:
status.directoryin the agent config;- the
CONNECT_AGENT_STATUS_DIRenvironment variable; ~/.config/dioad/connect/status.d.
| Install | Status directory |
|---|---|
| macOS, Linux or Windows, run as yourself | ~/.config/dioad/connect/status.d |
| Docker image | /persist/.config/dioad/connect/status.d, on the /persist volume |
connect-agent.service (systemd) |
/var/lib/connect-agent/.config/dioad/connect/status.d |
Agents that share a directory are listed together, including containers that share a volume. The directory is created readable only by its owner, like the agent's token file next to it, and an agent refuses a status directory other users can write to.
Reading them
# Every running agent and its tunnels
connect agent status
# Only the agents started with this config file
connect agent status --config /etc/dioad/connect/agent.yaml
# Public URLs, one per line
connect agent status --endpoint-urls
# Exit 0 only when every running agent is ready (the container HEALTHCHECK)
connect agent status --ready
# A tunnel list in the shape the management interface returns
connect agent status --json
# Each agent's whole status file
connect agent status --json --instances
Inside a container, run the same commands with docker exec:
docker exec dioad-connect /connect agent status
connect agent status falls back to asking the management interface when no running agent has a status
file, such as an agent from a release before status files. --source files or --source http picks one
explicitly. With --source files, --json has no counters or tunnel metadata; --source http still has
them.
When they change
An agent rewrites its file when a tunnel's state changes, when it signs in or loses its token, and when its
readiness changes. It never rewrites the file just to say it is still running, and the file has no byte
counts or other counters: those are in the management API and /metrics.
Each write replaces the file in one step, so a reader never sees half a document. A burst of changes is written once.
Running or not
An agent removes its status file when it shuts down. An agent that crashes or is killed cannot, so each
agent also holds a lock on a .lock file next to its status file for as long as it runs. The operating
system releases the lock when the process ends, however it ends, so a reader that can take the lock knows
the agent has gone. connect agent status leaves those agents out unless you pass --all, and the next
agent to start in the directory removes their files.
A held lock shows an agent is running wherever it runs, including in another container sharing the volume,
which connect agent status lists with that container's hostname. A free lock only shows an agent has exited
when it ran on the same kernel: on this host, or in a container on it. A file from another host, for example
in a directory shared over the network, whose lock this host cannot see, is listed as one whose agent "cannot
tell if running", and is not removed automatically.
Removing leftover files
To remove the files of agents that are no longer running without starting another agent, use --prune:
connect agent status --prune
It removes what an agent starting in the directory would, and a status file whose .lock file has been
deleted. It never removes the files of a running agent, and says which agents it removed.
It keeps the files of agents on other hosts that it cannot tell are running, and says how many it kept. Once
you know those agents have stopped, remove them too with --prune-other-hosts, and limit it to one agent with
--instance:
connect agent status --prune --prune-other-hosts --instance 3f9c2a7e
Only do this once those agents have stopped. An agent whose files are removed while it runs keeps serving
its tunnels, but connect agent status reports it as no longer running until it restarts. That includes its
own --ready health check, so a container running it is marked unhealthy.
connect agent status --ready only judges agents on its own host, so containers sharing a status volume each
answer their own health check.
Format
Each agent writes agent-<instance-id>.json, where the instance ID is random and new each time the agent
starts. The JSON Schema describes every
field. Go programs can read the files with the
sdk/agent/status package.
{
"schema_version": 1,
"instance_id": "3f9c2a7e0b1d4c58a6e2f1d09b7c4e21",
"pid": 1,
"hostname": "c0ffee123abc",
"version": "1.42.0",
"config_file": "/persist/.config/dioad/connect/agent.yaml",
"started_at": "2026-11-01T12:00:00Z",
"updated_at": "2026-11-01T12:00:04Z",
"management": { "listen_address": "0.0.0.0:4444" },
"identity": { "signed_in": true },
"ready": true,
"tunnels": [
{
"id": "96afc578-9a5d-420d-874f-736be19e38e2",
"name": "hello",
"type": "hello",
"endpoint": "https://connect.dioad.dev/connect/https",
"state": "running",
"established": true,
"endpoint_urls": ["https://hello.example.connect.dioad.dev:443"],
"changed_at": "2026-11-01T12:00:03Z"
}
]
}
| Field | Meaning |
|---|---|
schema_version |
The format version. A reader skips files with a newer version than it knows. |
hostname, boot_id |
Where the agent runs. Containers on one host share a boot ID. |
identity |
Present when the agent signs in. signed_in is false and waiting_since set while it has no token. |
ready, ready_errors |
The same verdict as the management interface's /health/ready, with what is not ready by service. |
tunnels[].state |
registered, connecting, running, stopping, failed or stopped, as the management console shows. |
tunnels[].reason |
Why a tunnel is not running when there is a specific cause, such as waiting_for_identity or quota_exceeded. |
tunnels[].next_retry_at |
When the next connection attempt is due, while one is pending. |
tunnels[].endpoint_urls |
The tunnel's public URLs, once the server has assigned them. |
Turning them off
status:
disabled: true
connect agent status then reaches the agent only through its management interface.