Run on Railway

Deploy your agent platform to Railway with JWT auth on.

Your company probably has a set way of running software. Follow that. If you're looking for a place to test this out without going through the full DevOps process, Railway is a good option, and the template includes scripts to:

  • Deploy to Railway: ./scripts/railway/up.sh
  • Sync environment variables: ./scripts/railway/env-sync.sh
  • Redeploy the app: ./scripts/railway/redeploy.sh

Prerequisites

Why JWT is on by default

Token-Based Authorization is ON by default. Without a JWT_VERIFICATION_KEY (or JWT_JWKS_FILE), the app refuses to serve traffic in production. This is why the deploy script stops and asks you for a key.

Token-Based Auth gives you three things:

  • Protected application routes. Requests to agent, team, workflow, and data routes require a valid token.
  • Per-request identity. Middleware parses the token and exposes user_id, session_id, and custom claims to protected routes.
  • Granular permissions. A user token can be scoped to run a single agent. An admin token can read all sessions and test any agent.

AgentOS leaves its operational and API-documentation routes public: /, /health, /info, /docs, /redoc, /openapi.json, and /docs/oauth2-redirect.

Deploy your agent platform to Railway

Configure your production environment

The deploy and sync scripts read .env.production. This keeps local and production values separate: different OpenAI keys with different budgets, production-only credentials, a different Slack workspace.

cp .env .env.production

Edit .env.production with a production OpenAI key.

Provision and deploy

./scripts/railway/up.sh

This script:

  1. Creates a Railway project for your agent platform.
  2. Provisions a Postgres service (with pgvector) and a persistent volume.
  3. Creates the agent-os service and forwards the database connection vars.
  4. Issues your public Railway domain and sets AGENTOS_URL to it, on Railway and in .env.production.
  5. Pauses and asks for a JWT verification key.
  6. Builds and deploys from the current directory.

The domain takes a few minutes to start resolving after the first deploy.

Mint your verification key

os.agno.com can generate the keypair while the script waits:

  1. Click Connect OS → Live and enter your Railway domain.
  2. Name it Live Agent Platform, turn on Token-Based Authorization (JWT) on the connection panel, and connect. The UI generates an RSA keypair, keeps the private key, and shows you the public key. If the OS is already connected, enable the setting under Settings → OS & Security.
  3. Paste the public key into the script prompt. The script saves it to .env.production and sets it on Railway, then deploys.

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

You can also bring your own keypair. Generate an RSA keypair, sign tokens with the private key in your own auth service, and put the matching public key in JWT_VERIFICATION_KEY. The middleware verifies RS256 by default. For another algorithm, set algorithm in authorization_config.

Confirm it's live

railway logs --service agent-os

Once you see successful requests, open https://<your-app>.up.railway.app/docs and you're live.

Auto-deploys from GitHub

By default every code update needs ./scripts/railway/redeploy.sh. To auto-deploy on every push to main:

  1. Open the Railway dashboard → your project → the agent-os service → Settings.
  2. Under Source, click Connect Repo and pick your repo.
  3. Set the deploy branch to main.

Push to main now triggers a build and deploy. ./scripts/railway/env-sync.sh is still how you push env changes.

If you must run production without auth (inside a private VPC behind another auth layer), set authorization=False in app/main.py and redeploy. Keep authorization on for any deploy holding real data. Without it, anyone who guesses your Railway domain can read your sessions and run your agents.

Scaling

The template sets numReplicas: 1 in railway.json. It does not set CPU or memory limits there. Review resource allocation in your Railway service and plan settings. Before increasing replicas, configure shared runtime state and check scheduler and background-task behavior for the Agno version pinned by your template. See multiple replicas.

Operations

TaskCommand
Tail logsrailway logs --service agent-os
Open the Railway dashboardrailway open
Run a command with production env varsrailway run --service agent-os <command>
Push env changes./scripts/railway/env-sync.sh
Redeploy without git push./scripts/railway/redeploy.sh
Tear everything downDelete the project in the Railway dashboard

Deleting the Railway project removes the app, the database, and all data.

Next

Lock in behavior with evals