Skip to main content
Your company probably has a standard way to run software. Use it. If you want to deploy this platform without building the cloud infrastructure first, Railway is the quickest path through this guide. 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
  • Tear down the Railway project: ./scripts/railway/down.sh

​
Prerequisites

​
Why JWT is on by default

JWT authorization is enabled by default. Production startup requires a JWT_VERIFICATION_KEY or JWT_JWKS_FILE. During an interactive deploy, the script pauses for a verification key when neither value is configured. JWT authorization provides:
  • 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. Per-user data isolation is opt-in. Set authorization_config=AuthorizationConfig(user_isolation=True) to limit non-admin users to their own sessions, memories, traces, and runs. See User Isolation.

​
Deploy your agent platform to Railway

1

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, or a different Slack workspace.Create the file the first time you deploy:
Skip this command if .env.production already exists. Edit the file with a production OpenAI key.
2

Provision and deploy

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. Generates MCP_CONNECT_SECRET for hosted MCP clients and saves it to .env.production and Railway.
  6. Asks for a JWT verification key when neither JWT setting is configured.
  7. Builds and deploys from the current directory.
The domain takes a few minutes to start resolving after the first deploy.
3

Mint your verification key

os.agno.com can generate the keypair while the script waits:
  1. Click Connect OS → Live, enter your Railway domain, and name it Live Agent Platform.
  2. Go to Settings → OS & Security and turn on Token-Based Authorization (JWT). The UI generates an RSA keypair, keeps the private key, and shows you the public key.
  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.
4

Confirm it's live

The health check should succeed, and the protected /agents route should return 401 without a token. Open https://<your-app>.up.railway.app/docs to inspect the deployed API. Use railway logs --service agent-os if either check fails.
5

Connect MCP clients

Register the deployed AgentOS with supported local clients:
For ChatGPT or Claude on the web, add https://<your-app>.up.railway.app/mcp as a custom connector. Enter the MCP_CONNECT_SECRET stored in .env.production on the consent page.

​
Auto-deploys from GitHub

Until GitHub auto-deploy is connected, redeploy code changes with ./scripts/railway/redeploy.sh. To 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.

​
External authentication boundary

If a private network or trusted gateway already blocks unauthenticated traffic, set authorization=False in app/main.py. JWT middleware still validates tokens while JWT_VERIFICATION_KEY or JWT_JWKS_FILE remains configured. Remove those values from .env.production and the Railway agent-os service, then redeploy. MCP_CONNECT_SECRET controls the separate OAuth flow for MCP clients. Remove it from both places too if the gateway should protect /mcp. Keep AgentOS authorization enabled for internet-accessible deployments and services that hold user data. ./scripts/railway/env-sync.sh updates variables present in .env.production; it does not remove variables you deleted from the file.

​
Scaling

The starter is configured for one replica with 4 GiB of memory and 2 vCPU. Adjust the resource limits in railway.json as load grows. Validate schedules and long-lived MCP connections with your workload before increasing numReplicas.

​
Operations

Deleting the Railway project removes the app, the database, and all data.
See Railway Reference for environment variables, customization, and troubleshooting.

​
Next

Next steps →