Skip to main content
REFERENCE

Self-host

Run Rungate on your own infrastructure. Apache 2.0, no usage limits, no telemetry. One Node.js process, one SQLite file. Optional Redis for distributed rate limiting.

Rungate is Apache 2.0 open source. The full server runs as one Node.js process backed by a single SQLite file. No external services required for a basic deployment.

Source access during early access. The repository is currently private. Email [email protected] to request access; the snippets below show the standard setup once the repo URL is shared with you.

Install

Docker Compose

# Clone + run (repo URL provided after early-access onboarding)
git clone <rungate-repo-url>
cd rungate
cp .env.example .env

# Edit .env:
#   RUNGATE_MASTER_KEY (generate 32 random bytes — used for AES-256-GCM at rest)
#   RUNGATE_PORT (default 4000)
#   ...

docker compose up -d

# Bootstrap the first admin token
docker compose exec rungate npx tsx src/cli.ts tokens create \
  --name "bootstrap" --scope admin

npm

npm install -g rungate

# Start a local server
rungate start --port 4000

# Create a bootstrap admin token
rungate tokens create --name "bootstrap" --scope admin

# Create your first agent + policy
rungate agents create --name "my-agent"
rungate policies create --name "default" \
  --budget 1.00 --allowed-models gpt-4,claude-sonnet-4
rungate agents update my-agent --policy default

# Point your provider SDK at your local Rungate:
#   base_url = http://localhost:4000/v1
#   api_key  = rg_agt_...  (from agents create output)

From source

git clone <rungate-repo-url>     # repo URL provided after early-access onboarding
cd rungate
npm install
npm run build
# Configure env vars (see Configuration below)
npm start

Configuration

Configuration is via environment variables. The minimum required:

VariablePurpose
RUNGATE_MASTER_KEY32-byte base64 key for encrypting provider API keys at rest. Generate once, store securely. Required.
RUNGATE_PORTHTTP port. Default 4000.
RUNGATE_DB_PATHSQLite file path. Default ./data/rungate.db.
NODE_ENVSet to production on production deployments.

Optional:

VariablePurpose
RESEND_API_KEYFor magic-link auth emails.
RESEND_FROM_EMAILFrom address for outbound mail.
RUNGATE_ORIGINPublic origin (e.g. https://app.rungate.dev) used in magic-link URLs.
SIGNUP_NOTIFY_EMAILOperator email for new-signup notifications. Empty string disables.
REDIS_URLFor distributed rate limiting across multiple Rungate instances. Optional — local rate limiting is in-memory.

See .env.example in the repository for the full list.

Production deployment

A typical production deployment:

  • Container or process manager (Railway, Fly, Docker, systemd) — one Rungate instance is enough for low-to-moderate traffic.
  • Persistent volume mounted at the SQLite path. Never run Rungate against an ephemeral filesystem — your run history and tokens live there.
  • TLS at the edge (CDN, load balancer, or reverse proxy). Rungate itself listens HTTP; terminate TLS in front of it.
  • Optional: continuous SQLite backup with Litestream to an S3-compatible bucket.
  • Optional: Redis for rate-limit coordination if you scale to multiple instances.

Bootstrapping

First-run setup uses the CLI to create an initial admin token, then everything else is API-driven (or via the dashboard at /dashboard). The CLI is bundled with the server install: 

# Generate the master encryption key (one-time)
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

# Initialize the database
rungate init

# Create a bootstrap admin token (scope: admin)
rungate tokens create --name "bootstrap" --scope admin
# → outputs the rg_adm_* token. Save it; you can't retrieve it later.

# Use the admin token to create everything else via API or dashboard.

Backups

SQLite is the canonical store. Two recommended approaches:

  • Litestream. Continuous WAL streaming to an S3-compatible bucket. Recovery is "download the latest snapshot and replay WAL." See docs/guides/setup on the server for the exact config we use in production.
  • Periodic dumps. Cron a sqlite3 .backup dump to a backup volume, rotate with your usual policy.

Upgrading

Run the migration script after pulling a new version: 

git pull
npm install
npm run build
npm run migrate     # safe, idempotent — applies any new migrations
npm start

Migrations are forward-only. Each release notes any breaking schema changes in the changelog.

Operations

A few things worth knowing for production operators:

  • Logs. Pino structured logs to stdout. Pipe to your usual aggregator. Every component logs entry/exit and governance decisions.
  • Health. GET /health returns 200 when the server is up and the database is reachable.
  • Metrics. Prometheus-compatible metrics endpoint on /metrics. Standard process metrics plus Rungate-specific counters (requests by status, governance decisions, queue depth).
  • Tracing. OTLP-compatible trace export. Set OTEL_EXPORTER_OTLP_ENDPOINT and Rungate emits spans for every run, model call, tool call, and governance event.

License & support