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. Protected application routes. AgentOS routes require a valid token. The operational and documentation routes /, /health, /info, /docs, /redoc, /openapi.json, and /docs/oauth2-redirect remain public.
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-new-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],
)

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. Scheduled evals are off by default (ENABLE_SCHEDULED_EVALS=False) because they use model calls. Both workflows stay runnable on demand regardless.

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.
ENABLE_SCHEDULED_EVALS	No	False	Daily run-evals cron. Uses model calls.
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. Mint the key at os.agno.com: connect your OS (Connect OS → Live, enter your Railway domain), then turn on Token-Based Authorization (JWT) under Settings → OS & Security and paste the full PEM. 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.