Archon

English | 中文

Quick start: https://archon.diy/docs/deployment/docker.

This service deploys Archon, an open-source workflow engine for AI coding agents. The stack uses the official pre-built web UI + API image, persists Archon's working state in Docker volumes, defaults to SQLite for zero-config startup, and offers an optional with-db profile for local PostgreSQL.

Services

archon: Archon web UI and API server.
postgres: Optional PostgreSQL 17 backend for shared or heavier workflow usage.

Quick Start

Copy .env.example to .env:
```
cp .env.example .env
```
Set at least one AI credential in .env.

For Docker deployments, prefer CLAUDE_CODE_OAUTH_TOKEN or CLAUDE_API_KEY. If you use GitHub repositories or webhooks, set both GH_TOKEN and GITHUB_TOKEN to the same personal access token.
Start Archon:
```
docker compose up -d
```
Open http://localhost:3000.

Optional Local PostgreSQL

If you want a local PostgreSQL backend instead of SQLite, set this in .env:

DATABASE_URL=postgresql://postgres:postgres@postgres:5432/remote_coding_agent

Then start the optional profile:

docker compose --profile with-db up -d

Core Environment Variables

Variable	Description	Default
`ARCHON_VERSION`	Archon image tag	`latest`
`ARCHON_PORT_OVERRIDE`	Host port for the Archon web UI and API	`3000`
`CLAUDE_CODE_OAUTH_TOKEN`	Claude Code OAuth token for Docker deployments	placeholder
`CLAUDE_API_KEY`	Anthropic API key as an alternative to OAuth	(empty)
`DEFAULT_AI_ASSISTANT`	Default assistant for new conversations	`claude`
`DATABASE_URL`	PostgreSQL connection string; leave empty to use SQLite	(empty)
`GH_TOKEN`	GitHub personal access token for cloning private repos and GitHub CLI usage	(empty)
`GITHUB_TOKEN`	Same GitHub token reused by the GitHub adapter	(empty)
`ARCHON_DATA`	Optional host path for `/.archon`; leave empty for a named volume	Docker-managed volume
`ARCHON_USER_HOME`	Optional host path for `/home/appuser`; leave empty for a named volume	Docker-managed volume
`POSTGRES_PASSWORD`	Password for the optional local PostgreSQL container	`postgres`

Volumes

archon_data: SQLite database, registered codebases, workspaces, worktrees, and other Archon-managed data under /.archon.
archon_user_home: Persisted /home/appuser state, including Claude/Codex auth, ~/.gitconfig, shell history, and user-installed Archon assets.
archon_postgres_data: PostgreSQL data when the with-db profile is enabled.

Ports

3000: Archon web UI and API
5432: Optional local PostgreSQL, bound to 127.0.0.1 only when the with-db profile is enabled

Resource Requirements

Service	CPU Limit	Memory Limit
archon	2	4 GB
postgres	1	1 GB

The Archon image includes Chromium and Git tooling. Plan for 4+ GB RAM and 2+ CPU cores, and allocate more if you run concurrent workflows or browser-driven validation.

Notes

Default startup stores data in SQLite at /.archon/archon.db; use DATABASE_URL only when you need PostgreSQL.
The bundled PostgreSQL bootstrap mounts the current 000_combined.sql schema for fresh installs. If a future upstream release adds incremental PostgreSQL migrations, apply the newer SQL files from the Archon repository before upgrading an existing PostgreSQL data volume.
If you expose Archon beyond localhost, put it behind an authenticated reverse proxy.

4.5 KiB Raw Blame History