Railway

Deploy the oversight server to Railway using the included railway.json configuration. Railway handles builds, deploys, health checks, and automatic restarts.

railway.json

The repository includes a railway.json that configures the build and deploy settings:

railway.json json
{
  "$schema": "https://railway.com/railway.schema.json",
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "BUILD_HASH=${RAILWAY_GIT_COMMIT_SHA:-dev} pnpm run build"
  },
  "deploy": {
    "startCommand": "node packages/server/dist/index.js",
    "healthcheckPath": "/api/health",
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 5
  }
}
Setting Value Purpose
builder NIXPACKS Automatic Node.js + pnpm detection
buildCommand BUILD_HASH=... pnpm run build Compiles all packages with the git commit SHA as the build hash
startCommand node packages/server/dist/index.js Starts the Fastify server
healthcheckPath /api/health Railway polls this endpoint to verify the service is healthy
restartPolicyType ON_FAILURE Auto-restart on crash, up to 5 retries

Quick Deploy

Deploy with Railway CLI bash
# Install the Railway CLI
npm install -g @railway/cli

# Login and link to your project
railway login
railway init

# Deploy from the repo root
railway up

Alternatively, connect your GitHub repository in the Railway dashboard and Railway will deploy automatically on every push to the configured branch.

Environment Variables

Set these in the Railway dashboard under your service's Variables tab. Railway injects them at both build time and runtime.

Variable Required Description
SUPABASE_URL Yes Supabase project URL (https://<ref>.supabase.co)
SUPABASE_SERVICE_ROLE_KEY Yes Supabase service role JWT
SUPABASE_ANON_KEY Yes Supabase anon/public JWT
VITE_SUPABASE_URL Yes Same as SUPABASE_URL (used at build time by Vite)
VITE_SUPABASE_ANON_KEY Yes Same as SUPABASE_ANON_KEY (used at build time by Vite)
PORT No Railway sets this automatically
Tip: Railway provides RAILWAY_GIT_COMMIT_SHA automatically during builds. This is used as the build hash for version tracking in the oversight UI.

Linking to Supabase

Oversight uses Supabase as its database and auth layer. To connect your Railway deployment:

  1. Create a Supabase project at supabase.com/dashboard
  2. Navigate to Settings > API to find your project URL, anon key, and service role key
  3. Paste these values into the Railway service variables as described above
  4. Redeploy the service — Railway will pick up the new variables automatically

Custom Domain

Railway generates a default *.up.railway.app domain for your service. To use a custom domain:

  1. Open your service in the Railway dashboard and go to Settings > Networking > Custom Domain
  2. Enter your domain (e.g. oversight.example.com)
  3. Add the CNAME record Railway provides to your DNS provider
  4. Railway automatically provisions a TLS certificate once the DNS record propagates

Runner Considerations

The oversight runner is a long-lived daemon that polls for tasks and executes them using the Claude CLI. Since the runner needs access to your local claude installation and plugins, it typically runs on your workstation rather than on Railway.

Run the runner locally while the server is deployed to Railway:

Local runner bash
# From the repo root (with .env configured)
pnpm runner

The runner connects to the same Supabase instance as the Railway-hosted server and picks up tasks assigned to its authenticated user.