Docker Guide
This page installs and runs Archon with Docker Compose: on your own machine, or on a server with PostgreSQL and Caddy for automatic HTTPS. To prepare a VPS first (a user, SSH, the firewall and DNS), see Cloud Deployment.
The image includes the Claude Code binary from the Claude Agent SDK. On start, the entrypoint points CLAUDE_BIN_PATH at it unless you set CLAUDE_BIN_PATH yourself.
Cloud-init (fastest setup)
Section titled “Cloud-init (fastest setup)”deploy/cloud-init.yml prepares a new VPS when it first boots. Paste its contents into the provider’s User Data field when you create the server (Ubuntu 22.04+ or Debian 12+), add your SSH key, and point your domain’s A record at the server’s IP.
| Provider | Where to paste it |
|---|---|
| DigitalOcean | Create Droplet, Advanced Options, User Data |
| AWS EC2 | Launch Instance, Advanced Details, User Data |
| Linode | Create Linode, Add Tags, Metadata (User Data) |
| Hetzner | Create Server, Cloud config, User Data |
| Vultr | Deploy, Additional Features, Cloud-Init User-Data |
The script installs Docker, opens ports 22, 80 and 443 (TCP, plus UDP 443 for HTTP/3), adds a 2 GB swapfile, clones the repository to /opt/archon, copies .env.example to .env and Caddyfile.example to Caddyfile, and builds the image. It also creates an archon user with Docker access but no sudo, and copies your SSH key to it. Use the default cloud user or root for system maintenance.
Setup takes 5 to 8 minutes and writes /opt/archon/SETUP_COMPLETE when it finishes. Then:
ssh archon@your-server-ipnano /opt/archon/.env # see "Configure .env" belowcd /opt/archondocker compose --profile with-db --profile cloud up -dLocal Docker Desktop (Windows and macOS)
Section titled “Local Docker Desktop (Windows and macOS)”Run Archon on your own machine with SQLite and the Web UI. No domain or VPS is needed.
git clone https://github.com/coleam00/Archon.gitcd Archoncp .env.example .env # set a Claude or Codex credentialdocker compose up -dOpen http://localhost:3000. Add --profile with-db to use the PostgreSQL container instead of SQLite (see Profiles).
On Windows, build from a WSL terminal (for example in /mnt/c/Users/YourName/path/to/Archon), not PowerShell. Docker Desktop cannot follow Bun workspace symlinks from a Windows build context and fails with The file cannot be accessed by the system. If the container fails with exec docker-entrypoint.sh: no such file or directory, the checkout has CRLF line endings. .gitattributes forces LF for shell scripts, so re-clone the repository.
Manual server setup
Section titled “Manual server setup”Use this instead of cloud-init when you want each step under your control. Prepare the server with Cloud Deployment first.
-
Install Docker, then log out and back in so the group change applies:
Terminal window curl -fsSL https://get.docker.com | shsudo usermod -aG docker $USER -
Clone the repository and create the config files:
Terminal window git clone https://github.com/coleam00/Archon.gitcd Archoncp .env.example .envcp Caddyfile.example Caddyfile -
Edit
.envas described in Configure .env. -
Start the app, PostgreSQL and Caddy:
Terminal window docker compose --profile with-db --profile cloud up -d -
Check it:
Terminal window docker compose --profile with-db --profile cloud psdocker compose logs -f appcurl https://archon.example.com/api/health # from your machine
Pre-built image
Section titled “Pre-built image”To run ghcr.io/coleam00/archon:latest without building from source:
mkdir archon && cd archoncurl -O https://raw.githubusercontent.com/coleam00/Archon/main/deploy/docker-compose.ymlcurl -O https://raw.githubusercontent.com/coleam00/Archon/main/.env.examplecp .env.example .env # see "Configure .env" belowdocker compose up -dThis compose file has only the app service. To add PostgreSQL, uncomment the postgres service and the postgres_data volume, and set DATABASE_URL. It has no Caddy service.
Verify image attestations
Section titled “Verify image attestations”Published images carry BuildKit provenance and SPDX SBOM attestations. Resolve the tag to a digest, then inspect that digest so the image cannot change between inspection and deployment:
docker buildx imagetools inspect ghcr.io/coleam00/archon:latest# Copy the top-level Digest, not a platform manifest's digest.image='ghcr.io/coleam00/archon@sha256:<digest>'docker buildx imagetools inspect "$image" --format '{{ json .Provenance }}'docker buildx imagetools inspect "$image" --format '{{ json .SBOM }}'Both results must be non-empty: each platform has a SLSA provenance object and an SPDX SBOM object. In the provenance, check three things:
- The source is
https://github.com/coleam00/Archonand the revision is the release commit you intend to run. Current releases record them inbuildDefinition.externalParameters.request.argsaslabel:org.opencontainers.image.sourceandlabel:org.opencontainers.image.revision. Older BuildKit versions useinvocation.configSourceandinvocation.environment. - The workflow ref in
buildDefinition.internalParameters.github_workflow_refnames.github/workflows/publish.ymlat the expected ref. - The builder ID (
builder.idorrunDetails.builder.id) links to the GitHub Actions run.
The package inventory is under SPDX.packages. The unknown/unknown entries in the manifest list are the attestation manifests. The attestations are unsigned metadata, so they do not authenticate the publisher by themselves. See Docker’s provenance documentation.
Configure .env
Section titled “Configure .env”Docker Compose reads the repository’s .env. Edit it directly. Don’t run archon setup for a Docker install: the wizard writes Archon’s CLI env files, not this one. .env.example documents every variable.
AI credentials
Section titled “AI credentials”Set at least one provider:
# Claude: an OAuth token from `claude setup-token` on your own machineCLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-xxxxx# or an API key from console.anthropic.com# CLAUDE_API_KEY=sk-ant-xxxxx
# Codex: values from ~/.codex/auth.json after `codex login`# ARCHON_CODEX_ID_TOKEN=eyJhbGc...# ARCHON_CODEX_ACCESS_TOKEN=eyJhbGc...# ARCHON_CODEX_REFRESH_TOKEN=rt_...# ARCHON_CODEX_ACCOUNT_ID=6a6a7ba6-....env.example sets CLAUDE_USE_GLOBAL_AUTH=true. That flag only satisfies the server’s startup check: it tells Archon to rely on a claude /login session, and a fresh container has none. Set a token or key. When one is set, Archon uses it whatever the flag says. See AI Assistants for every provider.
Server, domain and database
Section titled “Server, domain and database”| Variable | Default in Docker | Purpose |
|---|---|---|
PORT | 3000 | App port, published on the host. Local development defaults to 3090. |
DOMAIN | none | Public hostname. Required for --profile cloud. |
DATABASE_URL | unset (SQLite) | PostgreSQL connection string. |
POSTGRES_PORT | 5432 | Host port for the PostgreSQL container, bound to 127.0.0.1. |
LOG_LEVEL | info | fatal, error, warn, info, debug or trace. |
For the PostgreSQL container, use the service name as the host:
DATABASE_URL=postgresql://postgres:postgres@postgres:5432/remote_coding_agentPlatform tokens (TELEGRAM_BOT_TOKEN, SLACK_BOT_TOKEN, GH_TOKEN, WEBHOOK_SECRET and so on) are covered in each adapter’s page under Adapters. For a GitHub webhook, the payload URL is https://archon.example.com/webhooks/github; see GitHub.
Profiles
Section titled “Profiles”Compose profiles add PostgreSQL, HTTPS or form login to the base app service:
| Command | What runs |
|---|---|
docker compose up -d | App with SQLite |
docker compose --profile with-db up -d | App and PostgreSQL 17 |
docker compose --profile cloud up -d | App and Caddy |
docker compose --profile with-db --profile cloud up -d | App, PostgreSQL and Caddy |
Add --profile auth for the form login sidecar. For an external database such as Supabase or Neon, set DATABASE_URL and use no database profile. There is no external-db profile.
- No profile: SQLite, stored in the data volume at
/.archon/archon.db. with-db: a PostgreSQL 17 container. The app creates the schema on first start and upgrades it when the Archon build changes. If you start this profile without settingDATABASE_URL, the app logs a warning and uses SQLite, and the container sits unused.cloud: Caddy in front of the app, with Let’s Encrypt certificates, HTTP to HTTPS redirects, HTTP/3 and unbuffered/api/stream/*for live updates. It needs aCaddyfile(copied fromCaddyfile.example),DOMAINset, the DNS A record in place, and ports 80 and 443 open. Caddy waits for the app’s health check before it starts.
Protect the Web UI
Section titled “Protect the Web UI”A Web UI on a public domain needs a login. Choose one of these:
- Better Auth (PostgreSQL only, recommended): per-user accounts, and the server rejects every
/api/*request without a session. SetBETTER_AUTH_SECRET; see Web UI login. Signup is closed by default: invite people withARCHON_AUTH_ALLOWED_EMAILS, or open it withARCHON_AUTH_OPEN_SIGNUP=true. With Better Auth on, you don’t need either Caddy option below; the Security reference explains how to retire them. - Caddy basic auth: the browser’s own login prompt, with no extra container.
- Form login sidecar: a styled login page and a session cookie, served by the
auth-servicecontainer.
Use one Caddy option at a time, not both. Caddy always leaves /webhooks/* and /api/health open, and webhooks verify their own signatures. Caddy answers /internal/* with a 404 and never forwards it.
Caddy basic auth
Section titled “Caddy basic auth”-
Generate a bcrypt hash. Never put a plaintext password in
.env.Terminal window docker run --rm caddy caddy hash-password --plaintext 'YOUR_PASSWORD' -
Set
CADDY_BASIC_AUTHin.env. Replaceadminwith your username and paste the complete hash unchanged:CADDY_BASIC_AUTH='basic_auth @protected {admin REPLACE_WITH_COMPLETE_HASH_OUTPUT}'This is a single-quoted multiline Compose value, so newlines and
$characters survive as written. Don’t double the dollar signs, and don’t source the file in a shell. See Compose interpolation and Caddy’s basic_auth. -
Recreate Caddy so it reads the new value:
Terminal window docker compose --profile cloud up -d --force-recreate caddy
To turn it off, leave CADDY_BASIC_AUTH empty or unset.
Form login sidecar
Section titled “Form login sidecar”-
Generate a bcrypt hash. The first run builds the
auth-serviceimage.Terminal window docker compose --profile auth run --rm auth-service \node -e "require('bcryptjs').hash('YOUR_PASSWORD', 12).then(h => console.log(h))" -
Generate a cookie signing secret:
Terminal window docker run --rm node:22-alpine \node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" -
Set them in
.env, writing every$in the hash as$$so Compose does not interpolate it:AUTH_USERNAME=adminAUTH_PASSWORD_HASH=$$2b$$12$$REPLACE_WITH_YOUR_HASHCOOKIE_SECRET=REPLACE_WITH_64_HEX_CHARS# COOKIE_MAX_AGE=86400 # session length in seconds -
In
Caddyfile, uncomment the Option A block (handle /login,handle /logoutand theforward_authhandle), and comment out the “No auth”handleblock below it. -
Start with the
authprofile:Terminal window docker compose --profile with-db --profile cloud --profile auth up -d
Your domain now redirects to /login. Visit /logout to end the session.
Data and home volumes
Section titled “Data and home volumes”The container keeps Archon’s data in /.archon: workspaces, worktrees, artifacts, logs, plugins and the SQLite database. The user’s home, /home/appuser, holds provider and tool state:
| Path | What it holds |
|---|---|
~/.claude/ | Claude Code skills, commands, agents, hooks, MCP config, sessions, memory and OAuth state |
~/.codex/ | Codex auth.json from codex login. With the ARCHON_CODEX_* variables set, startup overwrites it each time. |
~/.pi/agent/ | Pi auth.json from pi /login, models.json, settings.json and sessions |
~/.gitconfig | Git identity, signing config, aliases and safe.directory entries |
~/.config/gh/ | GitHub CLI login from gh auth login |
~/.bash_history | Shell history from docker compose exec app bash |
Both are Docker named volumes by default (archon_data and archon_user_home), so they survive restarts and rebuilds. To keep them at a host path instead, set ARCHON_DATA or ARCHON_USER_HOME in .env, and make the directory writable by UID 1001, the container user:
sudo mkdir -p /opt/archon-data /opt/archon-user-homesudo chown -R 1001:1001 /opt/archon-data /opt/archon-user-homeARCHON_DATA=/opt/archon-dataARCHON_USER_HOME=/opt/archon-user-homeOn every start the entrypoint fixes ownership of both paths, touching only files with the wrong owner.
ARCHON_HOMEhas no effect inside the container, which always uses/.archon. UseARCHON_DATAto choose where that lives on the host.- A bind-mounted home starts with an empty
~/.gitconfig, because Docker copies image content into new named volumes but never into bind mounts. The entrypoint still adds thesafe.directoryentries Archon needs. Set your Git identity withgit config --globalinside the container. safe.directoryentries added at runtime stay in the home volume, even after the checkout is gone. Archon never removes them, because concurrent setup may rely on the same entry. See Git directory trust.- To keep Pi’s data on the data volume, set
PI_CODING_AGENT_DIR=/.archon/pibefore the container starts. - To wipe the home volume:
docker compose down && docker volume rm archon_archon_user_home.
Root fallback for macOS bind mounts
Section titled “Root fallback for macOS bind mounts”On a macOS bind mount (VirtioFS), the ownership fix always fails: the host will not remap files to UID 1001. The entrypoint prints the chown error and exits 1, so the container restarts in a loop. Read-only mounts and SELinux or AppArmor denials on Linux fail the same way.
ARCHON_ALLOW_ROOT_FALLBACK=1 in .env makes the entrypoint print a warning and keep running as root instead. Any other value, or none, keeps the exit. The variable does nothing when the ownership fix succeeds.
GitHub credentials
Section titled “GitHub credentials”The container uses GH_TOKEN from .env. You can also log in inside the container, and the login lands on the home volume:
docker compose exec -u appuser -e HOME=/home/appuser app gh auth login- With
GH_TOKENset and GitHub App mode off, every start resets Git’shttps://github.comcredential helper to one that usesGH_TOKEN. A helper written bygh auth loginapplies only withoutGH_TOKEN. - In GitHub App mode (
GITHUB_APP_ID, a private key andWEBHOOK_SECRETset,GITHUB_TOKENunset), startup removes only the PAT helper that the entrypoint wrote earlier. An incomplete App configuration leaves it in place. Other helpers are yours and stay. - The entrypoint reads these variables from the container environment, not from
/.archon/.env. KeepGITHUB_APP_ID,GITHUB_APP_PRIVATE_KEYorGITHUB_APP_PRIVATE_KEY_PATH,WEBHOOK_SECRET,GITHUB_TOKENandGH_TOKENin the compose.env. If they are only in/.archon/.env, the server runs in App mode while clones keep using the old PAT. - With
ARCHON_SDLC_FORGE=gh, delete an emptyGH_TOKEN=line. The SDLC workflows refuse an emptyGH_TOKENwhenGITHUB_TOKENis unset, rather than letghfall back to the stored login.
Plugins
Section titled “Plugins”Install plugins inside the running container, as appuser so the server owns the files:
docker compose exec -u appuser app bun run cli plugin add coleam00/Archon/plugins/forge-githubdocker compose exec -u appuser app bun run cli plugin add Wirasm/archon-videoplugin update, plugin remove and plugin list work the same way. Plugins live in /.archon/plugins on the data volume, so they survive restarts and rebuilds. See Forge operations and Installed workflow packs.
The bundled SDLC workflows use gh by default. To use the forge plugin instead, set ARCHON_SDLC_FORGE=forge and install forge-github v0.13.0 or later; some pack steps still need gh. The plugin looks for GH_TOKEN, then GITHUB_TOKEN, then the container’s gh login. Your host’s gh login is not visible inside the container. See Use the forge path in the SDLC pack.
The image includes a verified Slack plugin outside the data volume. When SLACK_BOT_TOKEN is set, in the container environment or in /.archon/.env, the entrypoint installs it offline into /.archon/plugins before the server starts, and logs the release and commit. You don’t run plugin add for Slack. Slack still needs both SLACK_BOT_TOKEN and SLACK_APP_TOKEN to connect; see Slack.
- An installed, verified Slack plugin stays as it is, including a release you pinned from another source. The image does not update it.
- Missing or changed Slack executables, ownership conflicts, or a broken image receipt when a new install is needed stop provisioning with an error in the boot logs. Repair the install before restarting.
- To turn Slack off, remove its tokens from every env source, run
docker compose exec -u appuser app bun run cli plugin remove coleam00/Archon/plugins/chat-slack, and restart. Removing only the plugin reinstalls it on the next start. Removing only the tokens leaves it installed and reporting missing credentials.
The image has git and Bun, but not uv, Python, or tools a pack’s scripts call, such as ffmpeg. Add them with Dockerfile.user.
Container isolation is unavailable
Section titled “Container isolation is unavailable”archon workflow run ... --container starts a sibling Docker container for each run. Inside this compose stack it fails at preflight with “Cannot connect to the Docker daemon”: the image has no docker CLI, and the stack does not mount /var/run/docker.sock. Worktree isolation and in-place folder runs work normally.
Building the image
Section titled “Building the image”docker build -t archon .docker run --env-file .env -e ARCHON_DOCKER=true -p 3000:3000 archonThe Dockerfile builds in these stages:
manifestsandsourcesderive the workspace layout frompackages/, so a new package needs no Dockerfile edit.depsinstalls all dependencies, including the dev dependencies the web build needs.image-pluginsdownloads the pinned Slack release, checks its commit and checksum, and records a verified receipt.web-buildbuilds the Web UI with Vite.productionkeeps production dependencies and the built Web UI.
The production image runs Bun as the non-root appuser (UID 1001), which Claude Code requires. It includes git, curl, gh, postgresql-client, ripgrep, jq, Chromium and agent-browser, which drives the system Chromium for browser testing. It ships the source of every workspace package except docs-web, web (only the built UI ships) and chat-slack (shipped as the verified release under /opt/archon/image-plugins).
The Slack release is pinned separately from Archon’s version by the build args SLACK_PLUGIN_TAG (default v0.12.1) and SLACK_PLUGIN_COMMIT (default 5f2b4841aaca38180c0abbd32bc6345593292019). Override both together; the build rejects a tag that resolves to a different commit. Downloads happen only at build time.
Customizing the image
Section titled “Customizing the image”To add tools without editing the tracked Dockerfile:
- Copy
Dockerfile.user.exampletoDockerfile.user(usedeploy/Dockerfile.user.examplefor a server deploy) and edit it. - Copy
docker-compose.override.example.ymltodocker-compose.override.yml(ordeploy/docker-compose.override.example.yml). - Run
docker compose up -d. Compose merges the override file automatically.
Both files are gitignored, so your changes stay local.
Maintenance
Section titled “Maintenance”docker compose logs -f app # follow app logsdocker compose logs --tail=100 app # last 100 linesdocker compose restart appdocker compose down # stop, keep datadocker compose down -v # stop and delete volumes, including datadocker system df # Docker disk usageUpdate
Section titled “Update”git pulldocker compose --profile with-db --profile cloud up -d --buildUse the same profiles you deployed with. The app applies schema changes on startup: it runs the idempotent migrations/000_combined.sql under a PostgreSQL advisory lock, so there is no manual migration step.
Troubleshooting
Section titled “Troubleshooting”App exits with no_ai_credentials
Section titled “App exits with no_ai_credentials”The server found no Claude credential and no Codex credential. Set CLAUDE_CODE_OAUTH_TOKEN, CLAUDE_API_KEY, or ARCHON_CODEX_ID_TOKEN with ARCHON_CODEX_ACCESS_TOKEN. See AI credentials.
Caddy fails with “not a directory”
Section titled “Caddy fails with “not a directory””error mounting "Caddyfile": not a directoryCaddyfile did not exist, so Docker created a directory in its place:
rm -rf Caddyfilecp Caddyfile.example Caddyfiledocker compose --profile cloud up -dCaddy gets no certificate
Section titled “Caddy gets no certificate”Check that dig archon.example.com returns the server’s IP, that sudo ufw status shows 80 and 443 open, and that DOMAIN in .env is spelled right. Then read docker compose logs caddy. DNS changes can take up to an hour to propagate.
Health check fails
Section titled “Health check fails”The container health check calls /api/health on PORT, not /health:
curl http://localhost:3000/api/healthPostgreSQL connection refused
Section titled “PostgreSQL connection refused”With --profile with-db, DATABASE_URL must use the service name postgres as the host, not localhost. Check the container with docker compose ps postgres.
Permission errors in /.archon
Section titled “Permission errors in /.archon”The entrypoint exits 1 with the chown error when it cannot give /.archon or /home/appuser to UID 1001. On Linux with a bind mount, run sudo chown -R 1001:1001 /path/to/archon-data on the host. On a macOS bind mount, chown on the host does not help; see Root fallback for macOS bind mounts.
Port already in use
Section titled “Port already in use”Set another PORT in .env, such as PORT=3001.
Container keeps restarting
Section titled “Container keeps restarting”Run docker compose ps and docker compose logs --tail=50 app. The usual causes are a missing .env, an invalid credential or an unreachable database.
