Deploy and Host Agent Zero on Railway

Built for an LLM agent to deploy and use. There is no setup form and nothing to fill in: the login secret and the API-key seed are generated at deploy time, and the contract below lists every address, variable name and one script that proves the login and the API key work.

Agent Zero is an open source, general purpose AI agent framework. It runs a multi-agent system in its own Linux container: it writes and executes code, browses the web, keeps persistent memory and can create tools as it works. You drive it from a web UI or from its HTTP API.

About Hosting Agent Zero

This template runs one service: the official agent0ai/agent-zero v2.15 image, pinned by digest, with a volume on /a0/usr that holds memory, knowledge, projects, uploads, scheduler tasks and settings. The image hardcodes its UI port to 80; the start command moves it to Railway's injected PORT so the healthcheck and the public domain reach it.

The UI is behind a login. The user name is admin and the secret is AUTH_PASSWORD, generated per deploy and stable across redeploys. The API key for the external API is derived from three values you already have: A0_PERSISTENT_RUNTIME_ID, the user name and AUTH_PASSWORD. If you change the login secret inside the UI, the new value is stored on the volume and wins over the variable, and the key changes with it (Settings, External Services shows the current key).

Agent Zero needs a language model before it can answer. Add the provider key as a variable on the agent-zero service, for example API_KEY_OPENROUTER, API_KEY_ANTHROPIC or API_KEY_OPENAI, then choose the model under Settings. Until then the UI, login, API authentication and health all work, and a chat request returns the provider's authentication error.

Agent contract

Public URL: A0_PUBLIC_URL (https:// plus the service's RAILWAY_PUBLIC_DOMAIN). The web UI is at /.
Private URL: http://agent-zero.railway.internal:8080, exposed as A0_PRIVATE_URL.
Credentials: AUTH_PASSWORD (UI login secret, user name admin) and A0_PERSISTENT_RUNTIME_ID (seed for the API key).
Auth: the UI needs the login form (POST /login with username and password fields). The external API under /api/api_* needs the header X-API-KEY, whose value is the first 16 characters of the URL-safe base64 of sha256("RUNTIME_ID:admin:PASSWORD"), with RUNTIME_ID the value of A0_PERSISTENT_RUNTIME_ID and PASSWORD the value of AUTH_PASSWORD, without padding; the script below computes it.
Health: GET /api/health returns 200 without credentials.
API: POST /api/api_message (send a task, returns the reply and a context_id), GET /api/api_log_get, POST /api/api_reset_chat, POST /api/api_terminate_chat, GET /api/api_files_get.

# run with A0_PUBLIC_URL, AUTH_PASSWORD and A0_PERSISTENT_RUNTIME_ID set
KEY=$(printf '%s' "$A0_PERSISTENT_RUNTIME_ID:admin:$AUTH_PASSWORD" | openssl dgst -sha256 -binary | base64 | tr '+/' '-_' | tr -d '=' | cut -c1-16)
curl -s -o /dev/null -w "health: %{http_code}\n" "$A0_PUBLIC_URL/api/health"
curl -s -o /dev/null -w "ui without login: %{http_code}\n" "$A0_PUBLIC_URL/"
curl -s -o /dev/null -w "login: %{http_code}\n" -X POST "$A0_PUBLIC_URL/login" --data-urlencode "username=admin" --data-urlencode "password=$AUTH_PASSWORD"
curl -s -o /dev/null -w "api with wrong key: %{http_code}\n" -H "X-API-KEY: wrong" "$A0_PUBLIC_URL/api/api_log_get?context_id=x"
curl -s -o /dev/null -w "api with key: %{http_code}\n" -H "X-API-KEY: $KEY" "$A0_PUBLIC_URL/api/api_log_get?context_id=x"

A fresh deploy prints health: 200, ui without login: 302, login: 302, api with wrong key: 401 and api with key: 404 (the key was accepted; the 404 only says that chat context x does not exist). To run a task, add a model provider key as described above, then POST /api/api_message with the same header and a JSON body such as {"message": "list the files in /a0/usr"}.

Why Deploy Agent Zero 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 Agent Zero 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.

Agent-ready - generated login secret, API-key seed, contract block and one working script; no setup form.
Login on from the first request - the UI is never public and unauthenticated.
State survives redeploys - memory, knowledge, projects and settings live on a volume.
A working port - the image's hardcoded port 80 is moved to Railway's injected port, so the healthcheck passes.
Always on - the agent keeps its scheduled tasks running while you are away.

Common Use Cases

A coding and ops agent you can reach from anywhere - give it a task from the browser or over the API and read the result later.
An agent that other agents call - one service posts a task to /api/api_message and reads back the answer.
Scheduled research and monitoring - use the built-in scheduler for recurring web research or checks.

Dependencies for Agent Zero Hosting

One Railway volume on /a0/usr, created by the template.
A language model provider key, added by you after deploy.

Deployment Dependencies

Implementation Details

Variable	Purpose
`AUTH_PASSWORD`	Login secret for the web UI (user `admin`) and part of the API key, generated per deploy.
`A0_PERSISTENT_RUNTIME_ID`	Per-deploy seed for the API key, written to the volume at boot.
`A0_PUBLIC_URL`	HTTPS address for clients outside Railway.
`A0_PRIVATE_URL`	Address on the private network, for services in the same project.

The start command sets the user name to admin, moves the UI to Railway's injected PORT and then runs the image's own init. The container also runs an SSH server and a local SearXNG search engine; neither is exposed.