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
• uv (Python package manager)
• OpenAI API key
• Railway account (free tier works)
• Install Railway CLI:
  bash Mac brew install railway  bash Windows/Linux npm install -g     @railway/cli

Step-by-Step Guide

1. Set up Python environment

   uv venv --python 3.12
   source .venv/bin/activate
   
2. Install Agno

   uv pip install -U 'agno[infra]'
   
3. Create project codebase from template

   ag infra create --template agentos-railway --name my-agentos
   cd my-agentos
   

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

   Pal

   Personal assistant that learns from you. Stores notes, bookmarks, and research findings.

   Knowledge Agent

   RAG agent that answers questions from your documents. Pre-loaded with Agno docs.

   MCP Agent

   Connects to external tools via MCP. Extensible with any MCP-compatible service.

4. Set your API key

   export OPENAI_API_KEY=sk-***
   
5. Login and deploy to Railway

   railway login
   ./scripts/railway_up.sh
   

   It takes ~2 min and creates the project, provisions PostgreSQL with pgvector, and deploys your AgentOS.

6. Get your domain

   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.

7. Connect to your AgentOS Control Plane

   1. Go to os.agno.com
   2. Click “Connect OS” → Select “Live”
   3. Paste your Railway domain

   

Your AgentOS is live on Railway! Manage it from os.agno.com

Tips

Customizing Template

You can customize the agents included in the template codebase with additional capabilities.

Build Custom Agents

Create agents with your own tools and prompts.

Add Tools

Slack, GitHub, databases, and 100+ integrations.

Add Knowledge

Load documents, websites, and databases for RAG.

Add Interfaces

Deploy to Slack, Discord, WhatsApp, or expose via MCP.

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-***

Troubleshooting

'railway: command not found'

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

Deployment fails

Run railway init first, then ./scripts/railway_up.sh again.

Database timeout

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

502 error

Container starting. Wait 1-2 min. Check: railway logs --service agent_os