Deploy and Host Archon on Railway

Archon is an open-source remote coding agent. It runs Claude Code on a server you control and puts a web UI in front of it, so you can start a task from a browser, watch it work, and review the pull request it opens, instead of keeping a terminal open on your laptop.

About Hosting Archon

This template runs two services: Postgres and the Archon container, with a volume for cloned repositories and worktrees. Postgres is not optional here. Archon defaults to SQLite, but its per-user login is Postgres-only, so a SQLite deploy could not offer accounts at all. There are no migrations to run: the app converges its own schema on every boot under an advisory lock.

First boot is slow. The image carries bun, the Claude Code binary, the GitHub CLI and a browser-automation binary, so allow several minutes before the healthcheck passes. Signup is invite-gated by the email you supply, so the deploy is not reachable by anyone else even briefly.

Common Use Cases

Kicking off a coding task from a phone or tablet and reading the resulting pull request, with no laptop involved
Running long refactors or test-coverage sweeps on a server, so they survive your machine sleeping
Giving a small team one shared, logged-in place to run agent workflows against the same set of repositories

Dependencies for Archon Hosting

A Claude Code token (required). Archon cannot run an agent without a key. Run claude setup-token locally and paste the result into CLAUDE_CODE_OAUTH_TOKEN. An Anthropic API key works too, via CLAUDE_API_KEY.
Your email address (required). ARCHON_AUTH_ALLOWED_EMAILS is the signup allowlist. Signup is disabled when it is empty, so without it nobody, including you, can create the first account.
A volume, provisioned automatically at /.archon, holding cloned repositories, worktrees and workspaces.
A GitHub token (optional). Needed only for private repositories and for opening pull requests.

Deployment Dependencies

Implementation Details

The identity header is randomised, and that is the security model. Archon resolves a request's identity from a login session first, then falls back to a trusted header, X-Archon-User by default, which it takes at face value. That fallback exists for deployments sitting behind a proxy that authenticates and sets it. On a public URL with nothing stripping it, anyone can send that header and walk straight through the login gate, and the account it creates gets the default admin role. Upstream says so directly in resolveAuthContext: "the proxy MUST still strip that header, otherwise a client can forge it."

This template sets ARCHON_WEB_AUTH_HEADER to a 32-character value generated per deploy, so the header Archon trusts is one only your deployment knows and the default name is inert. Verified on a live deploy: X-Archon-User: attacker returns 401, while the generated name returns 200.

That is also why there is no reverse proxy in this template. A Caddy sidecar whose only job is request_header -X-Archon-User would be a third service to pay for, and it would still fail open the moment someone attached a domain directly to the app service, which Railway makes a two-click operation. Randomising the name closes the hole wherever the traffic enters.

Login is on, not merely available. Web auth activates only when DATABASE_URL and BETTER_AUTH_SECRET are both set, and both are wired here. ARCHON_WEB_AUTH_REQUIRED keeps every /api/* route behind a session, leaving only the login and health endpoints public. WEB_UI_ORIGIN is pinned to the deployment's own domain, because upstream defaults it to *.

Ports are pinned. Railway probes the healthcheck on the canonical PORT, and getPort() honours the same variable, so both agree on 3000.

One volume, not two. Upstream's compose mounts /.archon and /home/appuser. A Railway service takes one volume, so /.archon wins: it holds the cloned repositories and worktrees. Claude authentication arrives as a variable rather than a logged-in home directory, and the entrypoint rebuilds ~/.gitconfig on every boot, so nothing of value lives in the second mount. The volume mounts root-owned, which suits the image: given RAILWAY_RUN_UID=0, its entrypoint chowns the mount and re-drops to appuser with gosu.

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 are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.