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

Add an agent

Create agents/my_agent.py:

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:

from agents.my_agent import my_agent

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

Redeploy: ./scripts/railway/redeploy.sh

Add tools

Agno includes 100+ tool integrations. See the full list.

from agno.tools.slack import SlackTools
from agno.tools.google_calendar import GoogleCalendarTools

my_agent = Agent(
    tools=[
        SlackTools(),
        GoogleCalendarTools(),
    ],
)

Use a different model

Add your API key to .env.production and update your agent:

from agno.models.anthropic import Claude

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

Add anthropic to pyproject.toml and redeploy:

./scripts/generate_requirements.sh upgrade
./scripts/railway/env-sync.sh
./scripts/railway/redeploy.sh

Add dependencies

1. Edit pyproject.toml
2. Regenerate requirements: ./scripts/generate_requirements.sh upgrade
3. Redeploy: ./scripts/railway/redeploy.sh

Enable Slack

Set both variables in .env.production:

SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=...

Sync and redeploy:

./scripts/railway/env-sync.sh

The interface activates automatically. See Slack setup for creating the Slack app.

Local Development

Run without Docker for faster iteration:

# 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

'railway: command not found'

Install: brew install railway (Mac) or npm install -g @railway/cli

First deploy fails (JWT)

Expected. Get your verification key from os.agno.com, add to .env.production, then run ./scripts/railway/env-sync.sh.

Database timeout

PostgreSQL takes ~30s to start. Check: railway logs --service pgvector

502 error

Container is still starting. Wait 1-2 min. Check: railway logs --service agent-os