Concepts

This page defines the words the rest of the docs use. Most of them come from two places: AgentDock's own architecture (control plane, runner, profile, project) and the Code Sentinel orchestrator it drives (round, slot, worktree, checkpoint).

The big picture

control plane (your server)
  web (Next.js) · API (NestJS) · PostgreSQL · Redis
        ▲
        │ WebSocket, opened by the runner
        │
agent machine
  agentdock-runner
    ├─ profiles: claude-default, claude-work, codex-default
    └─ project ~/code/my-app (main checkout)
         ├─ orchestrator   tmux agentdock-orch-acme-my-app
         ├─ slot i42       tmux cs-i42   worktree ../.wt-my-app-i42
         └─ slot i57       tmux cs-i57   worktree ../.wt-my-app-i57

Infrastructure

Control plane

The API, the web app, PostgreSQL and Redis. It stores accounts, projects, the fleet's state, history, sessions and cost, and serves the UI. It never touches a project's filesystem. Anything that reads a repository or starts a process is a command sent to a runner.

Runner

agentdock-runner, a daemon on each machine that holds repositories and runs agents. One runner per machine. It opens an outbound WebSocket to the API, so the machine needs no inbound port, and it works the same whether it sits next to the server or on a laptop behind NAT. It sends events up (tmux sessions, worktrees, orchestrator boards, transcripts, pull requests) and executes a typed allowlist of commands that come down. A runner is paired once with a one-time code, which gives it a token the server can revoke.

Runtime and runtime profile

A runtime is an agent CLI: claude (Claude Code) or codex. A runtime profile says how to launch a runtime on one runner: the binary, environment variables such as CLAUDE_CONFIG_DIR or CODEX_HOME, and extra arguments. Profiles let one machine run agents under different accounts or configurations. They live in the runner's config, not on the server. See Runtime profiles.

Project

A GitHub repository on a runner, connected by the absolute path of its main checkout. A project carries its settings: base branch, ready label, default runtime profile, merge approval, members and budget. Deleting a project in AgentDock never touches the disk.

The orchestrator's vocabulary

Orchestrator

A Claude Code session running /code-sentinel:orchestrator for one project. AgentDock starts it in a tmux session named agentdock-orch-<owner>-<repo> with start (begin a new round) or next (pick up the next queued issue). The orchestrator decides what to dispatch and which model each slot uses. AgentDock never picks an issue for it.

Ready label

The GitHub label that marks an issue as dispatchable. It is cs:ready by default and can be changed per project. GitHub issues with this label are the queue; AgentDock has no tracker of its own.

Round

One pass of the orchestrator over the queue. Each round writes a board file round-<HHMM>.md under the repository's git directory. AgentDock records rounds in its history.

Slot

One unit of dispatched work: one issue (or one part of an issue), named i<issue> or i<issue>-<part>. A slot has its own worktree and its own tmux session cs-<slot>. The session running in it is the worker (/code-sentinel:worker). Slot statuses in the UI are dispatched, running, idle, prompt, quota, stale and ended.

Worktree

A git worktree created next to the main checkout as .wt-<repo>-<slot>, so parallel workers never share a working directory. Stopping a slot from AgentDock kills its tmux session but leaves the worktree, branch and commits alone.

Brief and checkpoint

The brief (.orchestrator-brief.md) is a slot's assignment. A checkpoint is a report the worker writes into .orchestrator-reply.md as it progresses: picked up, plan ready, implementation done, pull request open, blocked or misclassified. The Fleet page shows the latest checkpoint per slot.

What AgentDock records

Run

One recorded execution with an outcome, a duration, an optional pull request, and tokens and cost. Kinds are orchestrator_slot, skill and schedule. Statuses are running, blocked, waiting_person, succeeded, failed and abandoned. Runs are what the History page lists.

Session

One agent CLI session, read from its transcript and, when telemetry is on, from OpenTelemetry logs sent to the runner. A session is a tree: turns, LLM requests, tool calls and subagents. Only metadata is stored (model, token counts, durations, tool names, stop reason), never prompt, response or tool text.

API-equivalent cost

What the recorded tokens would cost at public API prices, from a versioned price table, even when the agent runs on a subscription. AgentDock bills nothing and takes no payments; this number exists so you can compare and limit spend. A model that matches no price shows as unpriced, never as zero.

Budget

A spend limit in API-equivalent cost for a project or a user, per day, week or month. Thresholds (50, 80 and 100 percent by default) send notifications. With the stop action, an exceeded budget refuses new orchestrator starts and skill runs; it never kills a running agent.

Skill run and schedule

A skill run is a headless Claude Code session that runs one skill on one project in its own worktree and returns a report or a pull request. A schedule is a cron rule that starts a skill run or an orchestrator command.

Next steps