Install AgentDock

This guide takes you from nothing to a running fleet: the control plane on a server, a runner on each machine that holds your repositories, a connected project and the first orchestrator round. Plan for about ten minutes on a machine that already has Docker and Claude Code.

What you need

On the server (it can be the same machine as your agents):

• Docker with Compose, for PostgreSQL 16 and Redis 7
• Bun 1.4 or newer and Node.js 24 or newer
• git

On each agent machine (macOS or Linux, arm64 or x64):

Run the control plane

1. 1

   Get the code

   git clone https://github.com/AndreyBegma/AgentDock && cd AgentDock
   bun install

2. 2

   Create the environment files

   The examples work as they are for a local install. The passwords in docker/.env must match DATABASE_URL and REDIS_URL in apps/api/.env, and the examples already agree.

   cp docker/.env.example docker/.env
   cp apps/api/.env.example apps/api/.env
   cp apps/web/.env.example apps/web/.env

3. 3

   Start the database

   This starts PostgreSQL on port 5421 and Redis on 6421 in Docker, waits for both, applies the migrations and seeds the price table.

   bun run db:setup

4. 4

   Create the first admin

   The seed creates no users and registration starts closed, so the first account comes from the command line.

   bun run admin:create

5. 5

   Start AgentDock

   bun run start:dev

   Open http://localhost:3517 and sign in. The API answers on port 8180:

   curl http://localhost:8180/health

Connect a machine

Each machine that holds repositories runs one agentdock-runner. It dials out to your server over a WebSocket, so the machine needs no open port.

1. 1

   Install the runner

   With Homebrew on macOS or Linux:

   brew install andreybegma/tap/agentdock-runner

   Or with npm (bun add -g agentdock-runner works too):

   npm i -g agentdock-runner

   Check it with agentdock-runner version, which prints the version and the target, for example 0.1.0 darwin-arm64.

2. 2

   Get a pairing code

   In AgentDock go to Admin → Runners → Add runner. The dialog shows a one-time code in the form XXXX-XXXX, valid for ten minutes, and the exact pair command for your server.

3. 3

   Pair

   --server is the address of the API, not of the web app: http://localhost:8180 for a local install, or https://<your-host>/api behind the reference proxy.

   agentdock-runner pair --server http://localhost:8180 --code XXXX-XXXX

   Pairing writes ~/.config/agentdock/runner.json (mode 0600) and detects your runtime profiles: ~/.claude, every directory in ~/.claude-profiles/, and Codex.

4. 4

   Keep it online

   Run it as a service so it survives logouts and reboots:

   brew services start agentdock-runner

   agentdock-runner install-service

   On Linux install-service writes a systemd user unit; on macOS a launchd agent. To try it in the foreground first, run agentdock-runner run. The Add runner dialog notices when the runner comes online.

Connect a project

1. 1

   Install Code Sentinel in your Claude profile

   AgentDock drives the Code Sentinel orchestrator, a Claude Code plugin. Inside Claude Code on the agent machine:

   /plugin marketplace add AndreyBegma/claude-code-plugin
   /plugin install code-sentinel@code-sentinel

2. 2

   Add an orchestrator block to the repository

   The orchestrator reads .code-analyzer-config.json at the repository root. A minimal one:

   {
     "orchestrator": {
       "base": "main",
       "maxSlots": 3,
       "readyLabel": "cs:ready",
       "checks": ["bun run lint", "bun run test", "bun run build"],
       "mergeMethod": "squash",
       "autoMerge": true
     }
   }

   Every key is optional. See the config reference.

3. 3

   Connect it in AgentDock

   Go to Projects → Connect, pick the online runner and enter the absolute path of the repository's main checkout (not a worktree). Click Inspect to preview what AgentDock detected, then Connect.

4. 4

   Pick a runtime profile

   In Project → Settings, choose the default runtime profile, and optionally the model, merge approval and a budget.

Run the first round

1. 1

   Queue some work

   Label a GitHub issue cs:ready, use Project → Queue → Create issue, or write a spec with /code-sentinel:spec and let it open the issue for you.

2. 2

   Start the orchestrator

   Open Project → Fleet → Start…, choose start, the profile, model and permission mode, and confirm. AgentDock launches /code-sentinel:orchestrator in a tmux session on the runner.

3. 3

   Watch and steer

   Slots appear as the orchestrator dispatches workers. Open one to read its brief and checkpoints, watch the live pane, send the worker a message or stop it. Merged pull requests, tokens and API-equivalent cost land in History and Usage.

Where to go next