Deploy to Railway

Ship Scout to Railway with JWT verification and a Git-backed wiki.

Scout ships with three Railway scripts. One provisions the project, one syncs env vars, one redeploys. Any cloud provider works, but Railway is the fastest path to a deployed Scout.

Prerequisites

• Scout set up locally (setup)
• A Railway account
• The Railway CLI installed and authenticated (railway login)

Step 1: Provision the project

Use .env.production to keep production credentials separate from local dev:

cp .env .env.production

Don’t set DB_* in .env.production. The deploy script points Scout at the Railway Postgres service automatically. Setting DB_HOST here would break the deploy when env vars sync.

Then run:

./scripts/railway/up.sh

This script:

1. Creates a Railway project called scout.
2. Adds a pgvector service with a persistent volume at /var/lib/postgresql.
3. Creates the scout application service and forwards a starter set of env vars.
4. Deploys and assigns a public domain.

The script prints the URL right away. The domain takes a few minutes to start resolving.

Step 2: Your first deploy will fail. That’s expected.

Production endpoints require RBAC authorization by default. Scout enables it whenever RUNTIME_ENV=prd. Without a JWT_VERIFICATION_KEY, Scout refuses to serve traffic. That’s deliberate. Scout’s job is to keep your company data off the public web.

The fix is to generate a key from AgentOS:

1. Open os.agno.com, click Add OS → Live, and enter your Railway domain.
2. Enable Token Based Authorization.
3. Paste the public key into .env.production (the full PEM block, no surrounding quotes):

JWT_VERIFICATION_KEY=-----BEGIN PUBLIC KEY-----
MIIBIjANBgkq...
-----END PUBLIC KEY-----

The Agno control plane handles JWT issuance, session management, traces, metrics, and the web UI. Scout just verifies the JWTs it sees. See the AgentOS security docs for the full picture.

Opting out is not recommended. If you must run production without auth (e.g. inside a private VPC behind another auth layer), flip authorization=False in app/main.py before deploying. Without it, anyone who guesses your Railway domain can query your CRM, wiki, and connected sources.

Step 3: Sync env vars and redeploy

Push everything in .env.production (JWT key, Slack credentials, MCP secrets):

./scripts/railway/env.sh

The script handles multiline values like PEM keys correctly. Railway auto-redeploys when values change. To trigger a redeploy manually:

./scripts/railway/redeploy.sh

Step 4: Verify

Once the domain resolves:

curl https://your-scout.up.railway.app/health
# {"status":"ok"}

curl https://your-scout.up.railway.app/contexts | jq
# Lists every registered context with its current status.

The OS you added in Step 2 should now show as connected at os.agno.com.

Use GitHub for the knowledge wiki

The filesystem wiki backend resets on every container restart. For production, swap to GitBackend so wiki pages persist with an audit trail and reviewers can comment on what Scout has filed.

1. Create a private wiki repo:

   gh repo create your-org/your-wiki --private --add-readme
   

2. Mint a fine-grained PAT scoped to that one repo (Settings → Developer settings → Fine-grained tokens). Grant Contents: Read and write.

3. Add to .env.production:

   WIKI_REPO_URL=https://github.com/your-org/your-wiki.git
   WIKI_GITHUB_TOKEN=github_pat_***
   

4. Sync and redeploy:

   ./scripts/railway/env.sh
   

Scout detects both env vars on startup and switches the knowledge wiki to GitBackend automatically. On boot you’ll see Knowledge wiki: GitBackend (<repo_url>) in the logs. The voice wiki stays filesystem-backed (voice rules are code-managed by design).

Every update_knowledge call commits with an LLM-summarised one-line message and pushes. git log -p wiki/knowledge/ is your audit trail. Full setup: WIKI_GIT.md.

Point Slack at production

If you set up Slack against an ngrok URL, swap it for your Railway domain:

1. Open your Slack app at api.slack.com/apps.
2. Go to Event Subscriptions.
3. Update the Request URL to https://your-scout.up.railway.app/slack/events.
4. Wait for the green Verified check, then Save Changes.

Stop ngrok. Slack delivers all events to Railway.

Auto-deploy on push

By default, code changes need ./scripts/railway/redeploy.sh. To auto-deploy on every push to main:

1. Open the Railway dashboard → your project → the scout service → Settings.
2. Under Source, click Connect Repo and pick the repo where Scout lives.
3. Set the deploy branch to main, then save.

Every push to main now triggers a fresh build and rolling deploy. ./scripts/railway/env.sh is still how you sync .env.production changes.

What you get

Resource	Purpose
scout service	The Scout app, FastAPI on port 8000, 2 replicas by default
pgvector service	Postgres with the pgvector extension (CRM context, agent memory)
/var/lib/postgresql volume	Persistent database storage
Railway-issued domain	Public HTTPS endpoint

Scale CPU, memory, or replicas in railway.json.

Operations

Task	Command
Tail logs	railway logs --service scout
Open the dashboard	railway open
Run a command in the container	railway ssh --service scout
Sync env var changes	./scripts/railway/env.sh
Redeploy code	./scripts/railway/redeploy.sh

Roadmap

The pieces landing next, built and verified on a side branch, shipping once tested with real tokens:

• Scheduled tasks. Daily cron over scout_followups WHERE due_at <= NOW() AND status='pending' so pending items surface every morning.
• Proactive provider actions. update_slack, update_github running on cron, not just on demand.
• GitHub, Gmail, Calendar providers. Each as its own service-account identity.