Self-hosting
Requirements
What the server and each agent machine need.
AgentDock has two kinds of hosts: one server for the control plane, and one or more agent machines, each running a runner. They can be the same machine. This page lists what each needs.
Control plane
The control plane is four services: the API, the web app, PostgreSQL 16 and Redis 7.4. The supported way to run it on a server is Docker Compose.
| Need | Details |
|---|---|
| Docker | Docker Engine with the Compose plugin (docker compose). The images are built from the repository on the same host, so you also need git to clone it. |
| CPU architecture | Whatever Docker supports for node:24-bookworm-slim, postgres:16.5-alpine and redis:7.4.11-alpine (amd64 and arm64 both work). |
| Memory | The reference stack caps the containers at about 2.5 GB in total: API 1 GB, web 512 MB, PostgreSQL 512 MB, Redis 256 MB, proxy and tunnel 128 MB each. Building the images needs more headroom than running them. |
| Disk | The PostgreSQL volume grows with sessions, events and history. Plan a few GB to start and watch it. |
| A domain and TLS | A hostname that serves the web app and the API on one origin, through a reverse proxy or a tunnel. See Reverse proxy and tunnels. |
To run from source instead (development, or a quick local try), you need Bun 1.4.0 or newer, Node.js 24 or newer, and Docker for PostgreSQL and Redis. See Quick start.
Network
- Inbound: browsers and runners reach the control plane over HTTPS. Runners need WebSockets to pass through your proxy.
- Outbound, optional:
api.github.comif you register the GitHub App, andapi.telegram.orgif you set up the Telegram bot (long polling, so no inbound webhook is needed). Outbound webhooks go to URLs an admin configures. - Nothing has to be public except, optionally, the GitHub App webhook and inbound triggers. A control plane on a home server or a private network works.
Agent machines
Each machine that holds repositories runs one agentdock-runner. The runner is a prebuilt single binary.
| Need | Details |
|---|---|
| OS and architecture | macOS or Linux, on arm64 or x64 (darwin-arm64, darwin-x64, linux-arm64, linux-x64). Windows is not supported. |
tmux | Every orchestrator, slot and skill run gets its own tmux session. Version 3.2 or newer for terminal attach and for the Code Sentinel orchestrator. |
git | Every slot and skill run gets its own worktree. The Code Sentinel orchestrator needs 2.31 or newer. |
gh | The GitHub CLI, signed in with gh auth login. The runner uses it for issues, pull requests and checks, with the machine's own credentials. |
| Claude Code and/or Codex | The agent CLIs (claude, codex), signed in. The orchestrator and skill runs need Claude Code. |
| Code Sentinel | The plugin installed in the Claude Code profile the orchestrator runs with. Its orchestrator also needs python3 on PATH. See Code Sentinel overview. |
The runner reports what it found as capabilities on Admin → Runners, so a missing tool shows up there.
Network
- Outbound only. The runner dials the API over HTTPS and a WebSocket (
wss://). No inbound port is needed, so a laptop behind NAT works. - It also reaches GitHub through
gh,https://skills.shwhen someone searches the skills catalog, andhttps://github.comto clone skills for inspection. - The OTLP receiver for live token data listens on
127.0.0.1:4318and refuses anything but loopback.
Projects
A project must be a GitHub repository (origin on GitHub) connected by the absolute path of its main checkout. Other forges are refused with unsupported_forge.
AgentDock never sees your Anthropic, OpenAI or GitHub credentials. Runtime profiles point at config directories by path, and the agent CLIs and gh talk to their providers directly.