Runner reference

Everything about agentdock-runner in one place: its commands and exit codes, every key of runner.json, the files it keeps, its environment variables and logs, the OTLP receiver, and the commands the server can send it. The facts here are from runner 0.1.0.

Commands

Usage: agentdock-runner <command>
 
Commands:
  pair --server <url> --code <XXXX-XXXX> [--no-detect]
  run
  status
  profiles [--detect [--write]]
  install-service
  version

--server is the API origin: http(s)://host[:port][/path], without credentials, a query or a fragment. The runner posts to <server>/runners/pair and connects to <server>/runner (ws:// for http://, wss:// for https://). Behind the reference proxy that is https://<host>/api.

There is one more subcommand, exec-run <runDir>, which a skill run's tmux session executes. It is internal; do not call it yourself.

Exit codes

While running, the runner reconnects with exponential backoff from 1 to 60 seconds on any other disconnect.

runner.json

The config lives at $XDG_CONFIG_HOME/agentdock/runner.json, by default ~/.config/agentdock/runner.json. The runner writes it atomically with mode 0600. It is read when the daemon starts, so restart the runner after you edit it. An invalid file is refused with the names of the bad fields (never their values, since one of them is the token).

{
  "server": "https://agentdock.example.com/api",
  "runnerId": "...",
  "token": "...",
  "profiles": [
    { "id": "claude-default", "runtime": "claude", "env": {}, "args": [] }
  ],
  "projects": [],
  "disabledCommands": ["terminal.attach"],
  "otlp": { "enabled": true, "http": 4318, "codexExperimental": false },
  "fleet": { "pollSeconds": 15, "prPollSeconds": 60, "eventsPollSeconds": 5 },
  "queue": { "pollSeconds": 60 },
  "sessions": { "enabled": true, "ingestSince": "2026-10-13T09:00:00.000Z" },
  "skills": { "maxConcurrentRuns": 2, "maxTimeoutSec": 21600 }
}

Files

State lives under $XDG_STATE_HOME/agentdock/, by default ~/.local/state/agentdock/.

spool/                 events not yet acknowledged by the server
spool/runner.lock      one daemon per machine
offsets.json           how far each agent transcript was read
events-offsets.json    byte offset and inode of each project's events.jsonl
runs/<runId>/          one directory per skill run
  run.json             what to launch, as an argv
  state.json           the run's state
  stream.jsonl         the session's output stream
  stderr.log
  exit.json
  patch.diff           the full patch (the server keeps at most 128 KiB)

Events are delivered at least once: they sit in the spool until the server acknowledges them, so a runner that loses its connection catches up when it returns.

Service files:

Environment variables

Logs

Logs are JSON lines on stderr, with the token redacted.

Set AGENTDOCK_LOG=debug in the service's environment for more detail.

OTLP receiver

The runner listens for OpenTelemetry logs on 127.0.0.1:4318, so a Claude Code session with telemetry on reports each LLM request as it happens, before its transcript is read. Without it, tokens and cost still arrive from transcripts, just later.

• OTLP over HTTP only, on POST /v1/logs, as application/x-protobuf or application/json, optionally gzip. /v1/metrics and /v1/traces are accepted and discarded.
• Connections from anything but loopback are refused, and so are bodies over 4 MiB.
• Only claude_code.api_request records are read. Each becomes one LLM request with model, request id, token counts, duration and the runtime's own reported cost. Prompts, tool input and output, responses, email and account or organization ids are never sent on, even with OTEL_LOG_USER_PROMPTS=1.
• If the port is taken, the error is logged and the runner keeps running without the receiver.

Skill runs that AgentDock launches turn telemetry on by themselves. For any other Claude Code session on the machine:

CLAUDE_CODE_ENABLE_TELEMETRY=1 \
OTEL_LOGS_EXPORTER=otlp \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 \
claude

You can add OTEL_RESOURCE_ATTRIBUTES=agentdock.project=<id>,agentdock.slot=<slot>,agentdock.issue=<n>,agentdock.run=<run> to attribute requests directly. All four are optional; without them a request is matched to its session by session.id.

Command allowlist

The server can only ask a runner to do what is in this list. Each command has a schema for its arguments, a minimum role the requesting user must have on the project, and a timeout. There is no command that runs a shell string. Paths are confined to registered project roots and their .wt-<repo>-* sibling worktrees.

The timeout is how long the server waits for the command to answer, not how long the work may take: skill.run answers once the run is started.

Disabling commands

disabledCommands lets the owner of a machine refuse commands no matter what the server asks. A disabled command answers with the error disabled. For example, to forbid terminal attach and skill runs on this machine:

{
  "disabledCommands": ["terminal.attach", "skill.run", "skill.install"]
}

Restart the runner after the change. Disabling terminal.attach also turns off the runner's terminal capability, so the UI stops offering Attach for it.

Next steps