---
title: "Deploy Agent Zero · Quick Start"
description: "Open-source AI agent with its own Linux shell, memory and a secured web UI"
category: "AI/ML"
url: https://railway.com/deploy/agent-zero-quick-start
---

# Deploy Agent Zero · Quick Start

Open-source AI agent with its own Linux shell, memory and a secured web UI

**[Deploy Agent Zero · Quick Start on Railway](https://railway.com/template/agent-zero-quick-start)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/agent-zero-quick-start/manifest.json

- **Creator:** withSeismic
- **Category:** AI/ML

## Template content

### agent-zero

- **Image:** agent0ai/agent-zero:latest
- **Start command:** `/bin/sh -c 'P=/opt/venv-a0/bin/python; if ! $P -c "import scipy.special" 2>/dev/null; then echo "[railway-start] scipy.special fails to import (numpy 2 files left over in the image), removing them"; $P -c "import csv,glob,os,shutil,numpy as n;sp=os.path.dirname(os.path.dirname(n.__file__));rec=lambda d:{r[0] for r in csv.reader(open(d+\"/RECORD\")) if r};keep=set().union(*map(rec,glob.glob(sp+\"/numpy-1.*.dist-info\")));old=glob.glob(sp+\"/numpy-2.*.dist-info\") if keep else [];bad=[os.path.join(sp,f) for d in old for f in rec(d)-keep if f.startswith(\"numpy/\")];[os.remove(f) for f in bad if os.path.isfile(f)];[shutil.rmtree(d) for d in old];print(\"[railway-start] removed\",len(bad),\"files\")"; $P -c "import scipy.special" && echo "[railway-start] scipy.special ok" || echo "[railway-start] scipy.special still fails, memory features may not work"; fi; exec /exe/initialize.sh "${BRANCH:-main}"'`
- **Health check:** /api/health
- **Public domain:** Yes

## Documentation

# Deploy and Host Agent Zero on Railway

Agent Zero is an open-source, general-purpose AI agent. Instead of a fixed set of tools, it gets its own Linux environment: it writes and runs code, uses the terminal, searches and browses the web, keeps long-term memory, learns from documents you give it, and hands subtasks to subordinate agents. You work with it in a chat-style web UI or call it over HTTP, and it can connect to MCP servers and run scheduled tasks.

## About Hosting Agent Zero

This template deploys the latest official `agent0ai/agent-zero` image as one service with a volume. The agent can run shell commands as root inside its container, so the template locks the UI down before the first request:

- **Login from the first request.** `AUTH_LOGIN` and `AUTH_PASSWORD` are generated for each deploy. Without them, the UI and its API redirect to the login page. There is no default account.
- **Your data on a volume.** Everything Agent Zero keeps in `/a0/usr` (settings, saved API keys, memory, knowledge, chats, projects, the agent's work folder, uploads, skills and scheduled tasks) lives on a Railway volume and survives redeploys and upgrades.
- **Memory works on Railway.** The current image ships a broken numpy install (numpy 1.26.4 laid over leftovers of numpy 2.3.5), so the embedding model behind memory and knowledge fails to load with `All ufuncs must have type numpy.ufunc`. The start command removes the leftover files before Agent Zero starts. It only acts while that import is broken, so it does nothing once upstream fixes the image.
- **One public port.** Only the web UI gets a domain. The SSH server, the built-in SearXNG search engine and the tunnel API inside the container stay private.
- **Healthcheck.** Railway waits for `/api/health` before routing traffic to a new deployment.
- **No key needed to boot.** The LLM provider keys are optional. The UI, login, settings, knowledge import and memory all work before you add one.

### Getting started

1. Deploy. Optionally paste an OpenRouter, OpenAI or Anthropic API key into the matching variable first; you can also add keys later.
2. Wait for the agent-zero service to turn green. The image is large, so the first deploy takes a few minutes.
3. Open the service's **Variables** tab and copy `AUTH_LOGIN` and `AUTH_PASSWORD`.
4. Open the public URL and sign in.
5. Open **Settings**. Agent Zero's default model preset uses OpenRouter, so with `API_KEY_OPENROUTER` set you can start chatting right away. With an OpenAI or Anthropic key, choose a model from that provider for the chat and utility models. You can also paste keys into Settings instead of using variables.
6. Ask it for something real, such as "clone this repository and summarise how it handles auth" or "find this week's releases of my three favourite libraries and write a changelog to a file".
7. To give it reference material, use **Import knowledge** in the chat input. Files are stored on the volume and indexed into memory.

## Common Use Cases

- A coding and ops agent you can reach from any browser: it writes, runs and debugs code in its own sandboxed Linux environment
- Research tasks that search the web, read pages and documents, and save the findings to files or memory
- Scheduled jobs, such as daily monitoring, report generation or data clean-up, run by the built-in scheduler
- An agent other services call over HTTP (`POST /api/api_message` with the key from Settings, External Services) or over MCP and A2A

## Dependencies for Agent Zero Hosting

- `agent0ai/agent-zero:latest` (official image)
- A Railway volume at `/a0/usr`
- An API key from an LLM provider (OpenRouter, OpenAI, Anthropic or any other provider Agent Zero supports), or a model server you run yourself

### Deployment Dependencies

- [Agent Zero on GitHub](https://github.com/agent0ai/agent-zero)
- [Agent Zero documentation](https://github.com/agent0ai/agent-zero/tree/main/docs)
- [Agent Zero images on Docker Hub](https://hub.docker.com/r/agent0ai/agent-zero/tags)
- [OpenRouter API keys](https://openrouter.ai/keys)

### Implementation Details

Variables on the agent-zero service:

| Variable | Value | Why |
|---|---|---|
| `AUTH_LOGIN` | generated, `admin-` plus 8 characters | Web UI user name. Login is required while it is set |
| `AUTH_PASSWORD` | generated, 32 characters | Web UI password |
| `API_KEY_OPENROUTER` | optional | Used by the default model preset |
| `API_KEY_OPENAI`, `API_KEY_ANTHROPIC` | optional | For OpenAI or Anthropic models; Agent Zero reads any `API_KEY_{PROVIDER}` variable |
| `PORT` | `80` | The image hard-codes the UI to port 80; this points the domain and healthcheck at it |
| `RAILWAY_HEALTHCHECK_TIMEOUT_SEC` | `600` | Time allowed for the first boot |

Agent Zero also reads `/a0/usr/.env` on the volume, and values there win over service variables. Each time you save Settings, it writes the login and the API key fields to that file, including empty ones. After your first save, change the password and keys in Settings rather than in Railway variables; a variable you edit later is ignored while `/a0/usr/.env` has a line for it.

The start command runs the numpy repair described above, then the image's own `/exe/initialize.sh`, which starts Agent Zero, SSH, cron and SearXNG under supervisord.

Only `/a0/usr` persists. Tools the agent installs elsewhere in the container (with `apt` or `pip`, for example) are gone after a redeploy; ask the agent to keep scripts and virtual environments in its work folder if they need to last.

The image tracks `latest`. To upgrade, redeploy the agent-zero service. Avoid the in-app updater: it replaces program files outside the volume, so the next redeploy brings back the image's version anyway. To hold a version, set the image to a release [tag](https://hub.docker.com/r/agent0ai/agent-zero/tags) such as `v2.15`. The service runs as one replica because the volume attaches to one container. The UI session cookie is tied to the running process, so you sign in again after each redeploy.

## 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.


## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [Weaviate](https://railway.com/deploy/weaviate-1) — Vector database with hybrid search and an API key-protected API
- [Möbius Personal AI OS](https://railway.com/deploy/mobius-v01-personal-ai-os) — Self-hosted AI agent that builds and runs apps for you, with memory.

Open this page in a browser: https://railway.com/deploy/agent-zero-quick-start