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

# Railway Reference

> Manage, customize, and troubleshoot your Railway deployment.

## Manage

| Task                | Command                                               |
| :------------------ | :---------------------------------------------------- |
| Deploy updates      | `./scripts/railway/redeploy.sh`                       |
| View logs           | `railway logs --service agent-os`                     |
| Open dashboard      | `railway open`                                        |
| Sync env variables  | `./scripts/railway/env-sync.sh`                       |
| Set single variable | `railway variables set KEY=value`                     |
| Stop service        | `railway down --service agent-os`                     |
| Stop database       | `railway down --service pgvector`                     |
| Scale replicas      | Edit `railway.json`: `{"deploy": {"numReplicas": 2}}` |

## Customize

<AccordionGroup>
  <Accordion title="Add an agent">
    Create `agents/my_agent.py`:

    ```python theme={null}
    from agno.agent import Agent
    from agno.models.openai import OpenAIResponses
    from db import get_postgres_db

    my_agent = Agent(
        id="my-agent",
        name="My Agent",
        model=OpenAIResponses(id="gpt-5.5"),
        db=get_postgres_db(),
        instructions="You are a helpful assistant.",
    )
    ```

    Register in `app/main.py`:

    ```python theme={null}
    from agents.my_agent import my_agent

    agent_os = AgentOS(
        name="AgentOS",
        agents=[web_search, code_search, my_agent],
    )
    ```

    Redeploy: `./scripts/railway/redeploy.sh`
  </Accordion>

  <Accordion title="Add tools">
    Agno includes 100+ tool integrations. See the [full list](/tools/overview).

    ```python theme={null}
    from agno.tools.slack import SlackTools
    from agno.tools.google_calendar import GoogleCalendarTools

    my_agent = Agent(
        tools=[
            SlackTools(),
            GoogleCalendarTools(),
        ],
    )
    ```
  </Accordion>

  <Accordion title="Use a different model">
    Add your API key to `.env.production` and update your agent:

    ```python theme={null}
    from agno.models.anthropic import Claude

    my_agent = Agent(
        model=Claude(id="claude-sonnet-4-5"),
    )
    ```

    Add `anthropic` to `pyproject.toml` and redeploy:

    ```bash theme={null}
    ./scripts/generate_requirements.sh upgrade
    ./scripts/railway/env-sync.sh
    ./scripts/railway/redeploy.sh
    ```
  </Accordion>

  <Accordion title="Add dependencies">
    1. Edit `pyproject.toml`
    2. Regenerate requirements: `./scripts/generate_requirements.sh upgrade`
    3. Redeploy: `./scripts/railway/redeploy.sh`
  </Accordion>

  <Accordion title="Enable Slack">
    Set both variables in `.env.production`:

    ```bash theme={null}
    SLACK_BOT_TOKEN=xoxb-...
    SLACK_SIGNING_SECRET=...
    ```

    Sync and redeploy:

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

    The interface activates automatically. See [Slack setup](/deploy/interfaces/slack/overview) for creating the Slack app.
  </Accordion>
</AccordionGroup>

## Local Development

Run without Docker for faster iteration:

```bash theme={null}
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Set up environment
./scripts/venv_setup.sh
source .venv/bin/activate

# Start PostgreSQL (required)
docker compose up -d agentos-db

# Run AgentOS
python -m app.main
```

## Environment Variables

| Variable               | Required   | Default                 | Description                               |
| :--------------------- | :--------- | :---------------------- | :---------------------------------------- |
| `OPENAI_API_KEY`       | Yes        | —                       | OpenAI API key                            |
| `RUNTIME_ENV`          | No         | `prd`                   | `dev` enables hot-reload and disables JWT |
| `JWT_VERIFICATION_KEY` | Production | —                       | Public key from os.agno.com               |
| `AGENTOS_URL`          | No         | `http://127.0.0.1:8000` | Scheduler base URL                        |
| `SLACK_BOT_TOKEN`      | No         | —                       | Enable Slack interface                    |
| `SLACK_SIGNING_SECRET` | No         | —                       | Enable Slack interface                    |
| `PARALLEL_API_KEY`     | No         | —                       | Parallel SDK key for WebSearch            |
| `PORT`                 | No         | `8000`                  | API server port                           |
| `DB_HOST`              | No         | `localhost`             | Database host                             |
| `DB_PORT`              | No         | `5432`                  | Database port                             |
| `DB_USER`              | No         | `ai`                    | Database user                             |
| `DB_PASS`              | No         | `ai`                    | Database password                         |
| `DB_DATABASE`          | No         | `ai`                    | Database name                             |

## Troubleshooting

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

  <Accordion title="First deploy fails (JWT)">
    Expected. Get your verification key from os.agno.com, add to `.env.production`, then run `./scripts/railway/env-sync.sh`.
  </Accordion>

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

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