Railway Reference

Commands, customization, environment variables, and troubleshooting for the Railway template.

Manage

Task	Command
Deploy code changes	./scripts/railway/redeploy.sh
Sync env variables	./scripts/railway/env-sync.sh
Tail logs	railway logs --service agent-os
Open the dashboard	railway open
Tear down	./scripts/railway/down.sh (add --yes to skip the confirmation)

Auto-deploy on merge

Recommended: let Railway build and 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 and save.

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

Production auth

Token-Based Authorization is on by default. Production startup requires JWT_VERIFICATION_KEY or a readable JWKS file at the container path in JWT_JWKS_FILE; otherwise the process exits.

Token-Based Auth gives you three things:

1. No public access. The server rejects requests without a valid token.
2. Per-request identity. Middleware validates the token and exposes its user_id, optional session_id, scopes, and claims to the request.
3. Scope-based permissions. Token scopes control access to AgentOS routes and resources.

The templates do not enable per-user data isolation. To scope non-admin session, memory, trace, and run access to the JWT subject, pass authorization_config=AuthorizationConfig(user_isolation=True) to AgentOS. See User Isolation.

To opt out (not recommended), set authorization=False in app/main.py and redeploy. Use this only inside a private VPC behind another auth layer. Without it, anyone who guesses your Railway domain can access your platform.

Customize

Add an agent

Ask your coding agent to run /create-agent, or do it by hand. Create agents/my_agent.py:

from agno.agent import Agent

from app.settings import default_model
from db import get_postgres_db

INSTRUCTIONS = """\
What the agent does, which tools it uses, the rules to follow when answering.
"""

my_agent = Agent(
    id="my-agent",
    name="My Agent",
    model=default_model(),
    db=get_postgres_db(),
    instructions=INSTRUCTIONS,
    enable_agentic_memory=True,
    add_datetime_to_context=True,
    add_history_to_context=True,
    num_history_runs=5,
)

Register it in app/main.py:

from agents.my_agent import my_agent

agent_os = AgentOS(
    ...
    agents=[agent_builder, platform_manager, web_search, my_agent],
)

Add its UI metadata beneath the existing manifest: key in app/config.yaml:

  my-agent:
    description: "What the agent does."
    quick_prompts:
      - "First example prompt"
      - "Second example prompt"
      - "Third example prompt"

Local containers hot-reload on save. For production, run ./scripts/railway/redeploy.sh.

Change the model

app/settings.py defines default_model(), used by every agent. Change it in one place:

from agno.models.anthropic import Claude

def default_model():
    return Claude(id="claude-sonnet-5")

Add anthropic to pyproject.toml, set the provider key in your env, and regenerate pins:

./scripts/generate_requirements.sh

Rebuild locally with docker compose up -d --build. For production:

./scripts/railway/env-sync.sh
./scripts/railway/redeploy.sh

Add tools

Agno ships 100+ toolkits. See Toolkits.

from agno.tools.slack import SlackTools

my_agent = Agent(
    ...
    tools=[SlackTools()],
)

Add dependencies

1. Edit pyproject.toml.
2. Regenerate pins: ./scripts/generate_requirements.sh (add upgrade to refresh every pin).
3. Rebuild locally with docker compose up -d --build, or redeploy with ./scripts/railway/redeploy.sh.

Enable Slack

Set both variables in your env file:

SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=...

Sync with ./scripts/railway/env-sync.sh. The interface activates automatically and routes messages to Agent Builder; change the agent= argument in app/main.py to point at another agent. See Slack setup.

Toggle scheduled workflows

The deployment check runs daily by default (ENABLE_DEPLOY_CHECK=True); it is deterministic and free. The run-evals schedule is always registered but starts disabled because it uses model calls. Enable it from the AgentOS UI. Both workflows remain runnable on demand.

Format, validate, and run evals

The format, validate, and eval scripts run on the host and need a venv. Set it up once:

./scripts/venv_setup.sh
source .venv/bin/activate

Task	Command
Format	./scripts/format.sh
Lint and type-check	./scripts/validate.sh
Run smoke evals	python -m evals --tag smoke

./scripts/mcp_check.sh runs inside the container, so it needs no venv.

Environment variables

Variable	Required	Default	Description
OPENAI_API_KEY	Yes	-	Models and embeddings.
RUNTIME_ENV	No	prd	dev disables JWT. Compose sets it for local. Never put it in an env file that syncs to Railway, or production deploys unauthenticated.
JWT_VERIFICATION_KEY	Production	-	Public key from os.agno.com. Quote the value so the multi-line PEM parses as one variable.
JWT_JWKS_FILE	Production	-	Path inside the running container to a JWKS JSON file. The scripts set only this path. Add the file to the image build context, rebuild, and redeploy the image, or configure a platform mount and roll the service.
MCP_CONNECT_SECRET	No	generated by up.sh	OAuth consent secret (16+ chars) for connecting claude.ai and ChatGPT to /mcp. up.sh generates one on deploy and writes it to .env.production.
AGENTOS_MCP_SIGNING_KEY	No	generated	Optional high-entropy signing-key material (32+ chars) for OAuth tokens. Unset, a strong key is generated and persisted in the database. Rotating it invalidates outstanding tokens.
AGENTOS_URL	No	http://127.0.0.1:8000	Scheduler base URL. up.sh sets it to your Railway domain. Scheduled jobs never fire if it stays at the default in production. When MCP_CONNECT_SECRET is set, OAuth metadata also derives its public origin from this URL.
ENABLE_DEPLOY_CHECK	No	True	Daily deployment-check cron.
EVALS_TAG	No	smoke	Eval tag the run-evals workflow runs.
EVALS_CASE_TIMEOUT_SECONDS	No	90	Per-case timeout for run-evals runs.
EVALS_SUITE_TIMEOUT_SECONDS	No	900	Whole-suite timeout for run-evals runs.
PARALLEL_API_KEY	No	-	WebSearch uses the Parallel SDK when set, keyless MCP otherwise.
SLACK_BOT_TOKEN	No	-	Set with the signing secret to enable Slack.
SLACK_SIGNING_SECRET	No	-	Set with the bot token to enable Slack.
DB_HOST / DB_PORT / DB_USER / DB_PASS / DB_DATABASE	No	matches compose	Postgres connection.
DB_DRIVER	No	postgresql+psycopg	SQLAlchemy driver.
AGNO_DEBUG	No	False	Verbose Agno logs. Compose sets it for dev.
WAIT_FOR_DB	No	False	If True, the entrypoint blocks on the database before starting. Compose sets it.

Troubleshooting

railway: command not found

Install the CLI with brew install railway or npm install -g @railway/cli, then run railway login.

up.sh pauses asking for a JWT key

Expected. At os.agno.com, choose Connect OS → Live, 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. Paste the full PEM into the script prompt. To add a PEM later, set JWT_VERIFICATION_KEY and run ./scripts/railway/env-sync.sh. To use 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 or roll the service. Env sync alone only updates the path.

App fails to start in production

JWT auth is on whenever RUNTIME_ENV is not dev. Set JWT_VERIFICATION_KEY and sync. For JWKS, verify the file exists inside the container at JWT_JWKS_FILE; changing the variable alone does not deliver it. To opt out inside a private VPC behind another auth layer, set authorization=False in app/main.py.

502 right after deploy

The container is still starting. Wait 1-2 minutes and check railway logs --service agent-os.

Scheduled jobs never fire

AGENTOS_URL is still the localhost default. up.sh sets it to your Railway domain automatically; for a custom domain or tunnel, set it by hand and run ./scripts/railway/env-sync.sh.