Deploying Rivet in a VPC or Air-Gapped Network
IMPORTANT: Before doing anything, you MUST read in this skill's directory. It contains essential guidance on debugging, error handling, state management, deployment, and project setup. Those rules and patterns apply to all RivetKit work. Everything below assumes you have already read and understood it.
Patterns for running self-hosted Rivet inside a private network: a VPC without internet egress, an on-premises rack, or a fully air-gapped environment. The engine is one service, the recommended single-node storage backend is the local file system, and the engine makes no outbound connections by default. Self-hosting is the only Rivet deployment model that supports air-gapped networks; see the
Self-Hosting Overview for the full comparison with BYOC.
What Runs Inside the Perimeter
A self-hosted deployment has three components, all of which live inside your network:
| Component | Role | Inside the perimeter |
|---|
| Your backend | Your application server, including the runner that executes actor code | Yes |
| Rivet Engine | Orchestration service that manages actor lifecycle, routes messages, and serves the dashboard and APIs | Yes |
| Storage | Persistence for actor state. Local file system for single-node, PostgreSQL or FoundationDB for multi-node | Yes |
There is no license server, no Rivet Cloud account, and no callback to
. Clients inside the perimeter reach actors through the engine's gateway over your private network. See
Architecture.
Single-Binary Install
The engine compiles to a single
binary. Build it from source outside the perimeter, then copy the binary across the boundary:
bash
git clone https://github.com/rivet-dev/rivet.git
cd rivet
cargo build --release -p rivet-engine
# Copy target/release/rivet-engine into the perimeter.
Prebuilt binaries are coming soon; see
Installing Rivet Engine for current options.
Run it with the file system backend, which stores everything on local disk and is the production-ready choice for single-node deployments. The
File System docs list air-gapped environments as a primary use case because it needs no database infrastructure:
bash
RIVET__database__file_system__path="/var/lib/rivet/data" ./rivet-engine
Configuration can also come from files. The engine discovers config at
on Linux (JSON, JSON5, JSONC, YAML, and YML are all supported), and
overrides the path. Environment variables use the
prefix with
as the separator. See
Configuration.
The engine serves its own dashboard on port
, so inspection and namespace management work with nothing but a browser inside the perimeter.
Docker Compose Deployment
For Docker hosts without registry access, move the engine image across the boundary the standard way:
bash
# Outside the perimeter.
docker pull rivetdev/engine:latest
docker save rivetdev/engine:latest -o rivet-engine.tar
# Inside the perimeter.
docker load -i rivet-engine.tar
Then run the engine and your app together in one Compose file:
yaml
services:
rivet-engine:
image: rivetdev/engine:latest
ports:
- "6420:6420"
volumes:
- rivet-data:/data
environment:
RIVET__FILE_SYSTEM__PATH: "/data"
restart: unless-stopped
my-app:
build: .
environment:
RIVET_ENDPOINT: "http://default:admin@rivet-engine:6420"
depends_on:
- rivet-engine
restart: unless-stopped
volumes:
rivet-data:
uses the format
http://namespace:token@host:port
and tells your app to connect to the engine as a runner instead of running standalone. After both services start, register your runner with the engine through the dashboard or its API. The full walkthrough, including PostgreSQL setup for multi-node deployments, is in
Docker Compose.
No Outbound Telemetry
The engine exports traces and metrics only when you opt in with OpenTelemetry. Export is disabled unless
is set, and the export target defaults to a local collector at
. With no configuration, nothing crosses the perimeter.
When you want observability, keep it inside the network:
- Set and point at a collector you run inside the perimeter.
- Adjust to control trace sampling.
- Use the engine's health endpoint for liveness and readiness probes.
See the
Production Checklist for monitoring guidance.
Embedding Rivet in a Customer's Environment
If you ship software that runs inside your customers' VPCs, the same setup turns Rivet into an internal component of your product rather than a service your customers must reach over the internet:
- Ship the engine next to your app. Add to the Compose file or chart you already deliver. Your app finds it over the private network via , so one artifact deploys the whole stack.
- One namespace per install. The endpoint URL carries the namespace and token (
http://namespace:token@host:port
- Generate a strong admin token per install. Replace the default token and keep it server-side. Never include the admin token in or anywhere clients can read it.
- Public endpoint only when needed. with a public () token is only required when browser clients connect to actors in serverless runtime mode. Backend-only deployments can skip it entirely.
- TLS at the customer's edge. Terminate TLS with the customer's reverse proxy or load balancer in front of the engine.
Scaling Past One Node
| Backend | Use when | Status |
|---|
| File System (RocksDB-based) | Single-node deployments, including air-gapped installs | Production-ready, single node only |
| PostgreSQL | Multi-node deployments | Recommended for multi-node today, but experimental |
| FoundationDB | Largest production deployments | Enterprise |
For multi-node deployments, run two or more engine nodes behind a load balancer and add NATS for pub/sub, which replaces the default PostgreSQL
/
path at high throughput. Neither is needed for a single-node file system install. See the
Production Checklist.
Perimeter Checklist
- Admin token: Generate a strong, random token for engine authentication and verify it is not exposed to clients.
- TLS termination: Encrypt connections to the engine via a reverse proxy or load balancer.
- No public exposure: Keep port reachable only from inside the perimeter unless clients outside it genuinely need access.
- Health checks: Configure liveness and readiness probes against the engine health endpoint.
- Telemetry: Leave OpenTelemetry export off, or point it at a collector inside the network.
- Backups: With the file system backend, back up the data directory. With PostgreSQL, configure automated backups and failover.
Full Configuration
- Self-Hosting Overview for architecture and the self-host vs BYOC comparison
- Installing Rivet Engine for Docker, binary, and source installs
- Docker Container and Docker Compose for container deployments
- Kubernetes for cluster deployments
- Configuration for every option and the full JSON schema
- Endpoints for connecting your backend and clients
- Production Checklist before going live
Reference Map
Actors
- Access Control
- Actions
- Actor Keys
- Actor Scheduling
- Actor Statuses
- AI and User-Generated Rivet Actors
- Authentication
- Communicating Between Actors
- Connections
- Custom Inspector Tabs
- Debugging
- Design Patterns
- Destroying Actors
- Errors
- Fetch and WebSocket Handler
- Helper Types
- Icons & Names
- Input Parameters
- Lifecycle
- Limits
- Low-Level HTTP Request Handler
- Low-Level KV Storage
- Low-Level WebSocket Handler
- Metadata
- Next.js Quickstart
- Node.js & Bun Quickstart
- Queues & Run Loops
- React Quickstart
- Realtime
- Rust Quickstart (Preview)
- Sandbox Actor
- Scaling & Concurrency
- Sharing and Joining State
- SQLite
- SQLite + Drizzle
- State & Storage
- Testing
- Troubleshooting
- Types
- Vanilla HTTP API
- Versions & Upgrades
- Workflows
Agent Os
- Agent-to-Agent Communication
- agentOS vs Sandbox
- Authentication
- Benchmarks
- Configuration
- Core Package
- Cron Jobs
- Deployment
- Embedded LLM Gateway
- Events
- Filesystem
- Limitations
- LLM Credentials
- Multiplayer
- Networking & Previews
- Overview
- Permissions
- Persistence & Sleep
- Pi
- Processes & Shell
- Queues
- Quickstart
- Sandbox Mounting
- Security & Auth
- Security Model
- Sessions
- Software
- SQLite
- System Prompt
- Tools
- Webhooks
- Workflow Automation
Clients
- Node.js & Bun
- React
- Swift
- SwiftUI
Connect
- Deploy To Amazon Web Services Lambda
- Deploying to AWS ECS
- Deploying to Cloudflare Workers
- Deploying to Freestyle
- Deploying to Google Cloud Run
- Deploying to Hetzner
- Deploying to Kubernetes
- Deploying to Railway
- Deploying to Rivet Compute
- Deploying to Supabase Functions
- Deploying to Vercel
- Deploying to VMs & Bare Metal
Cookbook
- AI Agent
- AI Agent Workspaces
- Chat Room
- Collaborative Text Editor
- Cron Jobs and Scheduled Tasks
- Database per Tenant
- Deploying Rivet in a VPC or Air-Gapped Network
- Live Cursors and Presence
- Multiplayer Game
General
- Actor Configuration
- Architecture
- Cross-Origin Resource Sharing
- Documentation for LLMs & AI
- Edge Networking
- Endpoints
- Environment Variables
- HTTP Server
- Logging
- Pool Configuration
- Production Checklist
- Registry Configuration
- Runtime Modes
Self Hosting
- Configuration
- Docker Compose
- Docker Container
- File System
- FoundationDB (Enterprise)
- Installing Rivet Engine
- Kubernetes
- Multi-Region
- PostgreSQL
- Production Checklist
- Railway Deployment
- Render Deployment
- TLS & Certificates