Skip to content
AgentDock

Getting started

Quick start

Run AgentDock locally, create the first admin and pair a runner in about ten minutes.

This page runs AgentDock from source on your own machine, creates the first admin, pairs a runner on the same machine and starts the orchestrator on one repository. It takes about ten minutes once the prerequisites are installed.

For a server deployment, use Docker Compose instead. The runner steps are the same.

Before you start

You need these on the machine:

  • Bun 1.4.0 or newer and Node.js 24 or newer, to run the control plane from source.
  • Docker, for PostgreSQL and Redis.
  • For the runner: tmux, git, the GitHub CLI gh signed in with gh auth login, and Claude Code. The full list is in Requirements.
  • For the orchestrator: the Code Sentinel plugin installed in your Claude Code profile, and a GitHub repository checked out locally.

Run the control plane

  1. Clone and install

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

  2. Copy the environment files

    The examples work as they are for local development.

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

    The passwords in docker/.env must match DATABASE_URL and REDIS_URL in apps/api/.env. Both examples use change-me, so they already agree. Every variable is described in the configuration reference.

  3. Start the database

    Terminal
    bun run db:setup

    This starts PostgreSQL on port 5421 and Redis on port 6421 with Docker Compose, waits for both, applies the migrations and runs the seed. The seed closes public registration and loads the first price table. It creates no users.

  4. Create the first admin

    Terminal
    bun run admin:create

    It asks for an email and a password. To run it without prompts, set ADMIN_EMAIL and ADMIN_PASSWORD (and optionally ADMIN_NAME) in apps/api/.env, run it, then remove them.

  5. Start the API and the web app

    Terminal
    bun run start:dev

    The API listens on http://localhost:8180 and the web app on http://localhost:3517. Check the API from another terminal:

    Terminal
    curl http://localhost:8180/health

  6. Sign in

    Open http://localhost:3517 and sign in as the admin. Overview shows a Getting started checklist. The next sections walk through it.

Pair a runner

The runner is the daemon that does the work on the machine with your repositories. Here it runs on the same machine as the control plane.

  1. Install the runner

    Terminal
    brew install andreybegma/tap/agentdock-runner
# or
npm i -g agentdock-runner

    Check it with agentdock-runner version, which prints something like 0.1.0 linux-x64. Other install methods are in Install and pair.

  2. Get a pairing code

    In the web app, go to Admin → Runners → Add runner. The dialog shows a one-time code in the form XXXX-XXXX. It is valid for 10 minutes and works once.

  3. Pair

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

    --server is the API origin, not the web app. Locally that is http://localhost:8180. Pairing writes ~/.config/agentdock/runner.json (mode 0600) and detects your runtime profiles: claude-default for ~/.claude, one profile per directory in ~/.claude-profiles/, and codex-default.

  4. Start it

    For a first try, run it in the foreground:

    Terminal
    agentdock-runner run

    To keep it running across logouts and reboots, use brew services start agentdock-runner (Homebrew) or agentdock-runner install-service (npm). The Add runner dialog notices when the runner comes online.

Connect a project

  1. Open the Connect dialog

    Go to Projects → Connect project. Pick the online runner and enter the absolute path of the repository's main checkout, for example /home/you/code/my-app. A git worktree is refused, with a suggestion for the main checkout. The repository's origin must be on GitHub.

  2. Inspect, then connect

    Click Inspect. The runner reads the repository and the dialog previews the owner/name, the base branch, the Code Sentinel config and where the docs live. Nothing is stored yet. Click Connect to add the project. The runner starts watching it.

  3. Choose a runtime profile

    Open the project's Settings → General and set Default runtime profile to the Claude profile that has the Code Sentinel plugin installed. You can also set a profile only for the orchestrator in Settings → Orchestrator.

Start the orchestrator

Open the project's Fleet page and click Start…. Choose the command (start begins a new round, next picks up the next queued issue), check the model (default opus) and the permission mode (default auto), and click Start.

The runner launches the orchestrator in a tmux session named agentdock-orch-<owner>-<repo>. From then on the orchestrator picks issues labelled cs:ready from GitHub and dispatches workers. Slots appear on the Fleet page as they start. Click one to see its brief, checkpoints and live pane.

Nothing to do?

If the queue is empty, the orchestrator has nothing to dispatch. Create an issue from Queue → Create issue, or add the cs:ready label to a well-specified issue on GitHub.

Start… is disabled with a reason when the runner is offline, no profile is set, the orchestrator is already running, or a budget with the stop action is exceeded.

Next steps

ConceptsWhat a round, a slot, a run and a profile are.Install and pairRunners on other machines, services and troubleshooting.Docker ComposeMove the control plane to a server.Code SentinelSet up the plugin the orchestrator comes from.