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

# AgentOS on Railway

> Run AgentOS on Railway.

This template runs AgentOS and PostgreSQL with pgvector on Railway. It includes example agents ready to use after deployment, automatic HTTPS (handled by Railway) and
public domain (your-app.up.railway.app).

## Prerequisites

* [Docker Desktop](https://docker.com/desktop)
* [uv](https://docs.astral.sh/uv) (Python package manager)
* [OpenAI API key](https://platform.openai.com)
* [Railway account](https://railway.app) (free tier works)
* Install Railway CLI:
  <CodeGroup>
    `bash Mac brew install railway ` `bash Windows/Linux npm install -g
        @railway/cli `
  </CodeGroup>

## Step-by-Step Guide

<Steps>
  <Step title="Set up Python environment">
    ```bash theme={null}
    uv venv --python 3.12
    source .venv/bin/activate
    ```
  </Step>

  <Step title="Install Agno">
    ```bash theme={null}
    uv pip install -U 'agno[infra]'
    ```
  </Step>

  <Step title="Create project codebase from template">
    ```bash theme={null}
    ag infra create --template agentos-railway --name my-agentos
    cd my-agentos
    ```

    The template includes the following agents ready to use after deployment:

    <CardGroup cols={3}>
      <Card title="Pal" icon="graduation-cap">
        Personal assistant that learns from you. Stores notes, bookmarks, and
        research findings.
      </Card>

      <Card title="Knowledge Agent" icon="book">
        RAG agent that answers questions from your documents. Pre-loaded with Agno
        docs.
      </Card>

      <Card title="MCP Agent" icon="plug">
        Connects to external tools via MCP. Extensible with any MCP-compatible
        service.
      </Card>
    </CardGroup>
  </Step>

  <Step title="Set your API key">
    ```bash theme={null}
    export OPENAI_API_KEY=sk-***
    ```
  </Step>

  <Step title="Login and deploy to Railway">
    ```bash theme={null}
    railway login
    ./scripts/railway_up.sh
    ```

    It takes \~2 min and creates the project, provisions PostgreSQL with pgvector, and deploys your AgentOS.
  </Step>

  <Step title="Get your domain">
    ```bash theme={null}
    railway open
    ```

    Find your URL in the dashboard (e.g., `my-agentos.up.railway.app`). Navigate to `<railway-domain>/docs` to see your AgentOS API.
  </Step>

  <Step title="Connect to your AgentOS Control Plane">
    1. Go to [os.agno.com](https://os.agno.com)
    2. Click "Connect OS" → Select "Live"
    3. Paste your Railway domain

    <Frame>
      <img className="block dark:hidden" src="https://mintcdn.com/agno-v2-docs-whatsapp-interface-documentation/P2C2FvFdUFM-bIli/images/agent-os-connection-railway-light.png?fit=max&auto=format&n=P2C2FvFdUFM-bIli&q=85&s=815db667ce8bd736abf1a6b9a20e1634" alt="AgentOS connection dialog" width="1232" height="1478" data-path="images/agent-os-connection-railway-light.png" />

      <img className="hidden dark:block" src="https://mintcdn.com/agno-v2-docs-whatsapp-interface-documentation/P2C2FvFdUFM-bIli/images/agent-os-connection-railway.png?fit=max&auto=format&n=P2C2FvFdUFM-bIli&q=85&s=39b25e40dbdd15b029837b7142dbe96f" alt="AgentOS connection dialog" width="1232" height="1464" data-path="images/agent-os-connection-railway.png" />
    </Frame>
  </Step>
</Steps>

<Check>Your AgentOS is live on Railway! Manage it from os.agno.com</Check>

## Tips

<AccordionGroup>
  <Accordion title="Customizing Template">
    You can customize the agents included in the template codebase with additional capabilities.

    <CardGroup cols={2}>
      <Card title="Build Custom Agents" icon="robot" href="/agents/building-agents">
        Create agents with your own tools and prompts.
      </Card>

      <Card title="Add Tools" icon="wrench" href="/tools/overview">
        Slack, GitHub, databases, and 100+ integrations.
      </Card>

      <Card title="Add Knowledge" icon="database" href="/knowledge/overview">
        Load documents, websites, and databases for RAG.
      </Card>

      <Card title="Add Interfaces" icon="comments" href="/production/interfaces/overview">
        Deploy to Slack, Discord, WhatsApp, or expose via MCP.
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Manage AgentOS on Railway">
    | Task             | Command                                               |
    | ---------------- | ----------------------------------------------------- |
    | Deploy updates   | `railway up --service agent_os -d`                    |
    | View logs        | `railway logs --service agent_os`                     |
    | Open dashboard   | `railway open`                                        |
    | Set env variable | `railway variables set KEY=value`                     |
    | Stop service     | `railway down --service agent_os`                     |
    | Scale replicas   | Edit `railway.json`: `{"deploy": {"numReplicas": 2}}` |
    | Switch model     | `railway variables set ANTHROPIC_API_KEY=sk-ant-***`  |
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="'railway: command not found'">
    Install: `brew install railway` (Mac) or `npm install -g @railway/cli`
  </Accordion>

  <Accordion title="Deployment fails">
    Run `railway init` first, then `./scripts/railway_up.sh` again.
  </Accordion>

  <Accordion title="Database timeout">
    PostgreSQL takes \~30s. Check: `railway logs --service pgvector`
  </Accordion>

  <Accordion title="502 error">
    Container starting. Wait 1-2 min. Check: `railway logs --service agent_os`
  </Accordion>
</AccordionGroup>