> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2-codex-homepage-20260719-015142.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Run on Railway

> Deploy AgentOS and Postgres to Railway with JWT authorization and MCP access.

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

* A [Railway](https://railway.com) account
* The [Railway CLI](https://docs.railway.com/cli#installing-the-cli) installed and authenticated (`railway login`)

## 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](/agent-os/security/authorization/user-isolation).

## Deploy your agent platform to Railway

<Steps>
  <Step title="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:

    ```bash theme={null}
    cp .env .env.production
    ```

    Skip this command if `.env.production` already exists. Edit the file with a production OpenAI key.
  </Step>

  <Step title="Provision and deploy">
    ```bash theme={null}
    ./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. 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.
  </Step>

  <Step title="Mint your verification key">
    [os.agno.com](https://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.

    <Note>
      Live AgentOS connections are a paid feature. Use code `PLATFORM30` for one month off.
    </Note>

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

  <Step title="Confirm it's live">
    ```bash theme={null}
    curl --fail https://<your-app>.up.railway.app/health
    curl --silent --output /dev/null --write-out "%{http_code}\n" https://<your-app>.up.railway.app/agents
    ```

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

  <Step title="Connect MCP clients">
    Register the deployed AgentOS with supported local clients:

    ```bash theme={null}
    uvx agno connect --url https://<your-app>.up.railway.app
    ```

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

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

| Task                                   | Command                                    |
| -------------------------------------- | ------------------------------------------ |
| Tail logs                              | `railway logs --service agent-os`          |
| Open the Railway dashboard             | `railway open`                             |
| Run a command with production env vars | `railway run --service agent-os <command>` |
| Push env changes                       | `./scripts/railway/env-sync.sh`            |
| Redeploy without git push              | `./scripts/railway/redeploy.sh`            |
| Tear everything down                   | `./scripts/railway/down.sh`                |

<Warning>
  Deleting the Railway project removes the app, the database, and all data.
</Warning>

See [Railway Reference](/deploy/templates/railway/reference) for environment variables, customization, and troubleshooting.

## Next

[Next steps →](/agent-platform/next-steps)