Skip to content
AgentDock

Runners

Install and pair

Install agentdock-runner with Homebrew or npm, pair it and keep it online.

agentdock-runner is the daemon that does the work on each machine with repositories. It reads the fleet's state, runs the agents and executes AgentDock's commands. This page installs it, pairs it with your server and keeps it running.

Every AgentDock server also serves a public /install page (for example https://agentdock.example.com/install) with the same steps and the correct server address filled in.

Before you install

The runner runs on macOS or Linux, arm64 or x64. It looks for these on the machine and reports them as capabilities:

  • tmux (3.2 or newer for terminal attach and the Code Sentinel orchestrator)
  • git
  • gh, signed in with gh auth login
  • Claude Code (claude) and/or Codex (codex), signed in

A missing tool is not an install error. It shows up as a missing capability on Admin → Runners, and the features that need it are unavailable. The full list is in Requirements.

Install

Pick one. All of them install the same prebuilt binary for darwin-arm64, darwin-x64, linux-arm64 or linux-x64.

Homebrew

Works on macOS and Linux, and is the supported way on macOS.

Terminal
brew install andreybegma/tap/agentdock-runner

npm or Bun

The npm package is a thin wrapper that pulls the one binary for your platform through optional dependencies (agentdock-runner-darwin-arm64 and so on).

Terminal
npm i -g agentdock-runner
# or
bun add -g agentdock-runner

From source

Needs Bun. This builds every package, the runner included.

Terminal
git clone https://github.com/AndreyBegma/AgentDock && cd AgentDock
bun install && bun run build
apps/runner/dist/agentdock-runner version

Copy apps/runner/dist/agentdock-runner somewhere on your PATH, for example ~/.local/bin. Tarballs for each platform with SHA256SUMS are also attached to the GitHub releases tagged runner-v*.

Check the install

Terminal
agentdock-runner version
# 0.1.0 linux-x64

Pair

  1. Get a pairing code

    In the web app, an admin opens Admin → Runners → Add runner. The dialog shows a one-time code like K7QM-3XRP and the full pair command for this server. The code is valid for 10 minutes and works once.

  2. Run pair on the machine

    Terminal
    agentdock-runner pair --server https://agentdock.example.com/api --code XXXX-XXXX

    pair exchanges the code for a runner id and a token, writes them to ~/.config/agentdock/runner.json with mode 0600, and detects the machine's runtime profiles if the file has none yet. It prints each profile and whether it is authenticated. Add --no-detect to skip detection. See Runtime profiles.

  3. Start it and watch it come online

    Run it in the foreground once to see that it connects:

    Terminal
    agentdock-runner run

    The Add runner dialog notices when the runner comes online and offers to connect a project. Stop it with Ctrl+C and set it up as a service (next section).

Keep it online

Run the runner as a service so it survives logouts and reboots. Which command depends on how you installed it, not on the OS.

Installed with Homebrew

Terminal
brew services start agentdock-runner

Logs go to $(brew --prefix)/var/log/agentdock-runner.log.

Installed with npm, Bun or from source

Terminal
agentdock-runner install-service

On Linux it writes a systemd user unit to ~/.config/systemd/user/agentdock-runner.service and prints how to start it:

Terminal
systemctl --user daemon-reload && systemctl --user enable --now agentdock-runner
journalctl --user -u agentdock-runner -f

The unit restarts the runner 5 seconds after a failure, except after exit code 78 (see below). A systemd user service normally stops when you log out; on a server, run sudo loginctl enable-linger $USER so it keeps running without a session.

On macOS it writes a launchd agent to ~/Library/LaunchAgents/com.agentdock.runner.plist, logging to ~/Library/Logs/agentdock-runner.log, and prints how to load it:

Terminal
launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.agentdock.runner.plist

The launchd agent keeps the PATH that install-service ran with, so tools installed with Homebrew or in ~/.local/bin are found. Run install-service from a shell where tmux, gh and claude are on your PATH.

Run it as you

Install the runner as the same user who runs the agents. It has to see that user's tmux server, worktrees, gh login and Claude Code config. Do not run it as root or inside a container.

Verify

Terminal
agentdock-runner status
Output
config:   /home/you/.config/agentdock/runner.json
paired:   yes, as <runner id>
server:   https://agentdock.example.com/api
profiles: 3
spool:    1 segment(s), 2048 bytes, last seq 412, acked 412
reach:    reachable (HTTP 404)

reach only shows that the server answers; any HTTP status counts. In the web app, Admin → Runners shows the runner as online with its capabilities and profiles.

Troubleshooting

The runner shows offline

It is paired but not running, or it cannot connect. Start it as in Keep it online and read its log. Admin → Runners shows a remedy next to the status.

The pairing code expired or was already used

pair says the pairing code is invalid, expired or already used. Codes last 10 minutes and work once. Generate a new one in Admin → Runners.

Pairing fails with HTTP 404 or cannot reach the server

Check that --server is the API origin (see the callout above) and that the machine reaches it:

Terminal
curl https://agentdock.example.com/api/health

command not found

The install directory is not on your PATH. With npm, add the global bin directory: run npm prefix -g and add its bin subdirectory.

macOS refuses the binary

Install with Homebrew. That is the supported way on macOS.

The service stops and does not restart (exit code 78)

Exit code 78 means the server closed the connection for good: the runner was revoked by an admin, replaced by a newer pairing of the same machine, or speaks a protocol version the server does not accept. Restarting would only loop, so systemd does not restart it, and the launchd and Homebrew wrappers turn 78 into a clean exit. Fix the cause, then pair again (revoked or replaced) or upgrade the runner (protocol mismatch).

cannot take the lock

Another agentdock-runner run is already running on this machine, for example the service and a foreground copy. One daemon per machine; stop the extra one.

No profiles, or a profile is not authenticated

run warns no runtime profiles configured when the config has none. Run agentdock-runner profiles --detect --write. A profile marked not authenticated has no credentials on disk: sign in to Claude Code or Codex with that config directory. See Runtime profiles.

Next steps

Runtime profilesChoose which account and config each agent runs with.Runner referenceEvery command, runner.json key and state file.