Deploy and Host Archon on Railway

Archon is an open-source harness builder for AI coding. You describe a development process as a YAML workflow (plan, implement, validate, review, open a pull request) and Archon runs it with Claude Code, Codex or Pi in isolated git worktrees, from a web dashboard, Slack, Telegram, Discord or GitHub.

About Hosting Archon

This template runs the official ghcr.io/coleam00/archon:0.14.0 image with PostgreSQL and a small Caddy gateway. Postgres is not optional here: Archon's built-in login (Better Auth) only works on Postgres, and with it every /api/* request needs a session. Signup is invite only. You enter the email addresses that may register in ARCHON_AUTH_ALLOWED_EMAILS when you deploy, and everyone else is refused.

Archon also trusts an X-Archon-User request header as a logged in identity, which is meant for reverse proxies. That is why the Archon service has no public domain. The gateway is the only public service: it removes that header from every request, answers /internal/* with 404, and streams /api/stream/* unbuffered.

Archon's data (cloned repositories, worktrees, artifacts, logs, plugins) lives on a volume at /.archon. Conversations, workflow runs, accounts and encrypted provider keys live in Postgres.

What's Included

archon-gateway (caddy:2.11-alpine): the public entry point. Strips the trusted identity header and blocks /internal/*.
Archon (ghcr.io/coleam00/archon:0.14.0): web UI, API, workflow engine and the bundled Claude Code, Codex and Pi runtimes. Private, with a volume at /.archon.
Postgres (postgres-ssl:17): application data and login accounts, with its own volume.

First Steps After Deploy

Open the public URL of the archon-gateway service.
Choose sign up and register with one of the addresses you put in ARCHON_AUTH_ALLOWED_EMAILS. There is no email verification, so do this right after the deploy.
Open Settings and connect an AI provider: paste an Anthropic or OpenAI API key, or set a shared CLAUDE_CODE_OAUTH_TOKEN, CLAUDE_API_KEY or CODEX_API_KEY on the Archon service.
Set GH_TOKEN on the Archon service if your workflows need private repositories or pull requests.
Add a project by its repository URL and start a workflow from the chat.

Once everyone has an account you can clear ARCHON_AUTH_ALLOWED_EMAILS and redeploy. Signup is then closed and existing accounts keep working.

Common Use Cases

Repeatable AI coding: the same plan, implement, validate, review sequence on every task
Issue to pull request: hand a GitHub issue to a workflow and review the finished PR
Parallel work: several runs at once, each in its own git worktree
Team harness: one hosted place where the team's workflows and run history live
Human approval gates: pause a run for review before it continues

Dependencies for Archon Hosting

Railway Hobby plan or higher is recommended. The image is about 1.2 GB compressed and each run starts coding agent processes and can start Chromium.
PostgreSQL: included, required for login
An AI provider credential: not needed to boot, needed to run anything. Claude, Codex or any Pi backend.
A GitHub token: optional, for private repositories and pull requests

Deployment Dependencies

Implementation Details

# Archon
PORT=3000
ARCHON_DOCKER=true
DEFAULT_AI_ASSISTANT=claude
DATABASE_URL=${{Postgres.DATABASE_PRIVATE_URL}}
BETTER_AUTH_SECRET=${{secret(48)}}
BETTER_AUTH_URL=https://${{archon-gateway.RAILWAY_PUBLIC_DOMAIN}}
ARCHON_AUTH_ALLOWED_EMAILS=          # required, you fill this in
TOKEN_ENCRYPTION_KEY=${{secret(64,"abcdef0123456789")}}

# archon-gateway
UPSTREAM=${{Archon.RAILWAY_PRIVATE_DOMAIN}}:3000
IDENTITY_HEADER=X-Archon-User

Key points:

Never give the Archon service its own public domain. Anyone could then send X-Archon-User and skip the login.
If you attach a custom domain, attach it to archon-gateway and update BETTER_AUTH_URL and WEB_UI_ORIGIN on Archon.
Do not rotate TOKEN_ENCRYPTION_KEY. Saved provider keys would become unreadable.
Only /.archon is persisted. The container home (/home/appuser) resets on every deploy, so use tokens in variables or keys saved in Settings instead of claude /login or gh auth login inside the container.
Webhooks (/webhooks/*) pass through the gateway and are verified by their own signatures. GitHub App mode is not preconfigured: it needs ARCHON_ALLOW_INTERNAL_ON_PUBLIC_BIND=1, which is safe here only because the gateway blocks /internal/*.

Why Deploy Archon on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Archon on Railway, you get a login protected AI coding harness with Postgres, generated secrets, health checks, managed SSL and private networking between the gateway, the app and the database.