AgentOS on Railway

The agentos-railway template is for teams that develop locally with Docker and deploy with Postgres on Railway.

It includes:

Agno, the team that coordinates platform work, also exposed as the agno MCP tool.
Platform Builder, which creates and updates agents, teams, and workflows through the runtime.
Platform Manager, which inspects the platform, eval history, deployment checks, and schedules.
Platform Engineer, which inspects the project’s source code.
Eight skills 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.

Help me set up my agent platform and build my first agent.

Clone https://github.com/agno-agi/agentos-railway into a folder called agent-platform, cd in, and run the setup-platform skill (in .agents/skills/).

Prefer to drive yourself? Follow the manual steps below.

Manual setup

Prerequisites: Docker installed and running. An OpenAI API key.

Clone and configure

git clone https://github.com/agno-agi/agentos-railway.git agentos
cd agentos

cp example.env .env

Edit .env and set OPENAI_API_KEY.

Start the platform

docker compose up -d --build

The first build takes a few minutes. Confirm the API is available at localhost:8000/docs.

Verify end to end

./scripts/mcp_check.sh

Prints MCP OK with the tool count and a real agent answer through the MCP endpoint.

Connect the AgentOS UI

Open os.agno.com and sign in.
Click Connect OS, enter http://localhost:8000, and name it Local AgentOS.

Build your first agent

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

At this point, your AgentOS is running locally.

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 → 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.
Your product	Call the AgentOS REST API with 80+ endpoints. Browse them at `/docs`.

Deploy to production

Prerequisites: Railway CLI installed, railway login completed, and OpenSSL available for generating the MCP OAuth secret.

Create a production env

cp .env .env.production

Edit .env.production with production values: a different OpenAI key, production-only credentials, a different Slack workspace.

Deploy

./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.

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.

Open os.agno.com, click Connect OS → Live, and enter your Railway domain.
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.
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.

Live AgentOS connections are a paid feature. Use code PLATFORM30 for one month off.

Connect your MCP clients

Re-run uvx agno connect, this time pointed at your deployed domain:

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).

Confirm it's live

railway logs --service agent-os

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

Your AgentOS is live on Railway.

Redeploy after code changes

./scripts/railway/redeploy.sh

Sync environment variables

./scripts/railway/env-sync.sh

Tear down

./scripts/railway/down.sh

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 and JWT_VERIFICATION_KEY in your env file so a future up.sh derives the URL and requests a verification key again.