> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agno.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AgentOS on Railway

> AgentOS template for teams that develop locally with Docker and deploy with Postgres on Railway.

**The [agentos-railway](https://github.com/agno-agi/agentos-railway) template is for teams that develop locally with Docker and deploy with Postgres on Railway.**

It includes:

* **Agent Builder**, which creates agents, teams, and workflows.
* **Platform Manager**, which inspects and explains the platform, eval history, deployment checks, and schedules.
* **Eight [skills](/deploy/coding-agents)** for setting up, building, testing, reviewing, and deploying the project with a coding agent.

Coding agents can use these skills with the AgentOS API, evals, traces, and container logs to inspect and improve the platform.

## Get started

Copy the prompt below into Claude Code, Cursor, or Codex to clone, configure, and start the platform.

<Snippet file="setup-prompt-railway.mdx" />

Prefer to drive yourself? Follow the manual steps below.

## Manual setup

**Prerequisites:** [Docker](https://www.docker.com/get-started/) installed and running. An [OpenAI API key](https://platform.openai.com).

<Steps>
  <Step title="Clone and configure">
    ```bash theme={null}
    git clone https://github.com/agno-agi/agentos-railway.git agentos
    cd agentos

    cp example.env .env
    ```

    Edit `.env` and set `OPENAI_API_KEY`.
  </Step>

  <Step title="Start the platform">
    ```bash theme={null}
    docker compose up -d --build
    ```

    The first build takes a few minutes. Confirm the API is available at [localhost:8000/docs](http://localhost:8000/docs).
  </Step>

  <Step title="Verify end to end">
    ```bash theme={null}
    ./scripts/mcp_check.sh
    ```

    Prints `MCP OK` with the tool count and a real agent answer through the MCP endpoint.
  </Step>

  <Step title="Connect the AgentOS UI">
    1. Open [os.agno.com](https://os.agno.com) and sign in.
    2. Click **Connect OS**, enter `http://localhost:8000`, and name it **Local AgentOS**.
  </Step>

  <Step title="Build your first agent">
    1. Chat with **Agent Builder**: "Build an agent that tracks AI news and writes a daily brief". Go through the agent development process.
    2. Once created, click **Refresh** on the top right, pick the new agent from the **Agents** dropdown, and ask: "What's new with Anthropic?"
    3. Ask **Platform Manager**: "How healthy is the platform?" It answers from eval history, deployment checks, schedules, and the agent you just built.
  </Step>
</Steps>

<Check>At this point, your AgentOS is running locally.</Check>

## Connect your frontends

| Frontend                    | How                                                                                                                                                                                                                 |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| MCP clients on your machine | `uvx agno connect` auto-detects Claude Code, Claude Desktop, Codex, and Cursor and registers `http://localhost:8000/mcp`. Verify from the app: "can you access my agentos mcp?"                                     |
| AgentOS UI                  | [os.agno.com](https://os.agno.com) → **Connect OS** → `http://localhost:8000`.                                                                                                                                      |
| claude.ai and ChatGPT       | Hosted sessions can't reach localhost. Deploy to production first, then add `https://<railway-domain>/mcp` as a custom connector and approve the consent page with the `MCP_CONNECT_SECRET` that `up.sh` generates. |
| Slack                       | Set `SLACK_BOT_TOKEN` and `SLACK_SIGNING_SECRET`. See [Slack setup](/agent-os/interfaces/slack/setup).                                                                                                              |
| Your product                | Call the AgentOS REST API with 80+ endpoints. Browse them at `/docs`.                                                                                                                                               |

## Deploy to production

**Prerequisites:** [Railway CLI](https://docs.railway.com/cli#installing-the-cli) installed and `railway login` completed.

<Steps>
  <Step title="Create a production env">
    ```bash theme={null}
    cp .env .env.production
    ```

    Edit `.env.production` with production values: a different OpenAI key, production-only credentials, a different Slack workspace.
  </Step>

  <Step title="Deploy">
    ```bash theme={null}
    ./scripts/railway/up.sh
    ```

    Provisions the AgentOS service and PostgreSQL on the same private network, creates your public domain, and sets `AGENTOS_URL` to it so scheduled jobs reach the platform.
  </Step>

  <Step title="Configure JWT verification">
    The script pauses for a `JWT_VERIFICATION_KEY`. Token-Based Authorization is on by default. Production startup requires that verification key or a readable JWKS file at the container path in `JWT_JWKS_FILE`; otherwise the process exits.

    1. Open [os.agno.com](https://os.agno.com), click **Connect OS** → **Live**, and enter your Railway domain.
    2. Name it **Live AgentOS**, turn on **Token-Based Authorization (JWT)** on the connection panel, and connect. The UI generates the public key. If the OS is already connected, enable the setting under **Settings** → **OS & Security**.
    3. Copy the public key and paste the full PEM into the `up.sh` prompt. The script saves it to your env file and deploys.

    If you skip the prompt, add `JWT_VERIFICATION_KEY` to `.env.production` later and run `./scripts/railway/env-sync.sh`. For JWKS, add the file to the image build context and rebuild, or configure a mount. Set `JWT_JWKS_FILE` to its container path, then redeploy the service. The scripts only forward the path.

    <Note>Live AgentOS connections are a paid feature. Use code `PLATFORM30` for one month off.</Note>
  </Step>

  <Step title="Connect your MCP clients">
    Re-run `uvx agno connect`, this time pointed at your deployed domain:

    ```bash theme={null}
    uvx agno connect --url https://<railway-domain>
    ```

    For claude.ai and ChatGPT on the web: add `https://<railway-domain>/mcp` as a custom connector in the chat app's connector settings. Leave the form's optional OAuth fields (client ID / client secret) empty. Click **Connect** and, on the consent page, enter the `MCP_CONNECT_SECRET` that `up.sh` generated during deploy (saved in `.env.production`).
  </Step>

  <Step title="Confirm it's live">
    ```bash theme={null}
    railway logs --service agent-os
    ```

    Open `https://<railway-domain>/docs` to confirm the API is serving.
  </Step>
</Steps>

<Check>Your AgentOS is live on Railway.</Check>

### Redeploy after code changes

```bash theme={null}
./scripts/railway/redeploy.sh
```

### Sync environment variables

```bash theme={null}
./scripts/railway/env-sync.sh
```

### Tear down

```bash theme={null}
./scripts/railway/down.sh
```

<Warning>
  Deletes the Railway project: the `agent-os` service, the pgvector database, and its volume, including all data. It also comments out the stale `AGENTOS_URL` in your env file so a future `up.sh` derives it fresh.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Build with coding agents" icon="wand-magic-sparkles" href="/deploy/coding-agents">
    Skills to create → improve → evaluate your platform using coding agents.
  </Card>

  <Card title="Railway reference" icon="book" href="/deploy/templates/railway/reference">
    Commands, environment variables, troubleshooting.
  </Card>
</CardGroup>