Rivet

Rivet Actors are long-running, lightweight processes that combine in-memory state, automatic persistence, real-time WebSockets, durable queues, and scheduling into a single unified primitive. Instead of stitching together Redis, a message broker, a cron system, and a database, you define an actor once and the runtime handles state co-location, hibernation when idle, and global edge routing near your users.

The architecture is built for the workloads that break traditional serverless: AI agents that need persistent context across calls, collaborative documents where every edit must reach all connected clients instantly, per-tenant databases with zero-latency reads, and sandbox orchestration where lifecycle management is non-trivial. Each actor is its own isolated process — one per agent, per session, or per user — so state never bleeds between tenants.

Rivet ships as three deployment tiers. RivetKit is an npm library you install and run locally with no infrastructure. The self-hosted Rust engine (or Docker container) adds Postgres, FoundationDB, or filesystem persistence and scales horizontally by adding nodes. Rivet Cloud provides the fully managed global edge network with automatic regional routing, ~20ms cold starts, and $0 idle cost. All three tiers share the same TypeScript API, so local development and production behave identically.

Under the hood, the engine consists of Pegboard (actor orchestration and networking), Gasoline (durable workflow execution with full replay semantics), Guard (traffic routing proxy), and Epoxy (an EPaxos-based multi-region KV store). The built-in Inspector dashboard provides a SQLite viewer, workflow visualizer, event monitor, and interactive REPL for debugging actors in both development and production.

What You Get

• Actor runtime with in-memory state — State lives co-located with compute for 0ms read latency; automatically persisted to embedded SQLite, FoundationDB, or Postgres with no explicit save calls.
• Built-in WebSocket support — Real-time bidirectional streaming to any number of connected clients via c.broadcast() or targeted messages, with no external pub/sub infrastructure required.
• Durable queues — Typed message queues (c.queue.iter()) with guaranteed delivery for async workloads like AI tool call chains, chat message processing, and job pipelines.
• Scheduling and cron jobs — Native timers and cron expressions scoped to individual actors for automated retries, cleanup tasks, and periodic state syncs without an external scheduler.
• Workflow orchestration with replay — Multi-step operations backed by Gasoline, Rivet’s durable execution engine, with automatic retry on failure and full event-sourced replay semantics for crash recovery.
• Actor Inspector dashboard — Browser-based debugging UI with a real-time SQLite viewer, workflow step visualizer, event monitor showing every state change, and an interactive REPL for calling actor actions live.
• Multi-runtime SDKs — RivetKit libraries for TypeScript (Node.js, Bun, Deno), Rust, and Python, plus first-class integrations for React, Next.js, Hono, Express, Elysia, tRPC, and AI SDK.
• Zero-config local development — npm install rivetkit runs actors inside your existing process; no Docker, no infrastructure, no configuration — the same API works locally and in production.
• Global edge deployment — Rivet Cloud automatically spawns actors in the region nearest the user and handles cross-region routing, enabling legal jurisdiction compliance and low-latency access globally.
• Self-host with a single binary — The Rivet engine ships as a single Rust binary or Docker image deployable on any VPS, Kubernetes cluster, Railway, Render, or AWS, with Compose and K8s manifests included.

Common Use Cases

• AI agent with persistent memory — An AI coding assistant uses one actor per conversation to hold message history in-memory, stream tokens to the client via c.broadcast('token', delta), and queue follow-up tool calls durably so they survive process restarts.
• Real-time collaborative document editor — Each document is a Rivet Actor holding the current CRDT state in-memory; WebSocket connections from all editors receive every delta via broadcast, and SQLite persistence means no edit is ever lost on actor sleep.
• Per-tenant database isolation — A SaaS platform runs one actor per customer with tenant state in embedded SQLite; reads are 0ms because compute and data are co-located, and actors hibernate to $0 cost between business hours.
• Durable sandbox orchestration — A code execution platform uses one actor per workspace to manage sandbox lifecycle, queue submitted jobs, schedule automatic cleanup after 30 minutes of inactivity, and report status back via WebSocket.
• Chat room with history — Each chat room is an actor storing message history in SQLite; new users connecting get a replay of recent messages from state, while active users receive live updates via WebSocket broadcast.
• Multi-step workflow automation — A background job that calls three external APIs in sequence uses Rivet Workflows: each step is recorded, retried on transient failure, and the full execution tree is visible in the Inspector dashboard.

Under The Hood

Architecture

Rivet is a monorepo organized around a hard separation between the TypeScript developer-facing SDK (RivetKit) and the Rust orchestration engine. The engine itself is modular: Pegboard handles actor lifecycle, placement, and networking; Gasoline provides the durable workflow execution layer using event-sourced replay semantics comparable to Temporal; Guard is the traffic routing proxy that terminates WebSocket and HTTP connections and routes them to the correct actor; and Epoxy is a custom EPaxos implementation for multi-region KV consistency. This separation means the TypeScript API is decoupled from infrastructure concerns — the same actor definition runs in-process locally, against a single-node self-hosted engine, or across a global edge network, with no code changes. Data flows from client through Guard to the actor process where state is read directly from co-located SQLite or KV storage with no network hop.

Tech Stack

The engine is written in Rust using Axum and Tokio for async HTTP and WebSocket serving, with UniversalDB as an abstraction layer over SQLite (via rusqlite), FoundationDB, RocksDB, and Postgres. The TypeScript SDK targets ESM and CJS via tsup, integrates Drizzle ORM for typed SQLite access within actors, and uses Vitest for testing. Biome handles formatting and linting across the entire monorepo, while Lefthook enforces pre-commit checks and Turborepo orchestrates cross-package builds. The frontend Inspector is built on React 19 with Next.js, CodeMirror for live JSON editing, and WebSocket connections directly to the actor REPL endpoint. Infrastructure targets include Docker Compose, Kubernetes, Railway, Render, Vercel, and bare metal via the single Rust binary.

Code Quality

The TypeScript test suite uses Vitest with a driver matrix pattern that runs each test against multiple backends — in-process, local engine, and remote engine — ensuring consistent behavior across deployment modes. Tests cover actor lifecycle races, hibernation state, WebSocket acknowledgment, CBOR/JSON serialization compatibility, inspector versioning, and registry shutdown ordering. Rust code uses rstest for parameterized tests alongside testcontainers for Docker-based integration testing. Error handling is typed throughout: the TypeScript side uses structured RivetError and UserError classes with explicit group/code pairs; the Rust side uses the rivet-error crate with macro-generated error types. Biome import restrictions enforce clean module boundaries, preventing internal packages from being imported directly across layers.

What Makes It Unique

Rivet’s core differentiator is collapsing five infrastructure primitives — in-memory cache, persistent database, pub/sub, queue, and cron scheduler — into a single actor process with a sub-millisecond API. Unlike Cloudflare Durable Objects, which are limited to the Cloudflare runtime and have constrained compute, Rivet runs on any infrastructure including self-hosted bare metal. Unlike Temporal for durable workflows, Rivet’s Gasoline engine is embedded inside the same process as the stateful actor, so workflow state and business state share the same SQLite database. The driver matrix architecture means RivetKit can target Cloudflare Workers, Supabase Edge Functions, and Node.js with the same actor definitions, while Epoxy’s EPaxos implementation provides leaderless multi-region KV consistency without the single-leader bottleneck of Raft.

Self-Hosting

Rivet is licensed under Apache License 2.0, which is a permissive open-source license with no copyleft requirements. You can use it commercially, modify it freely, distribute it in proprietary products, and build SaaS offerings on top of it without publishing your own source code. The only obligations are to include the original license notice and attribute changes. This makes it one of the most self-hosting-friendly licenses available for infrastructure software.

Running the Rivet engine yourself requires meaningful operational maturity. The simplest path is a single Docker Compose deployment using the provided manifests in self-host/compose/, which bundles the Rust engine, Postgres, and NATS messaging. Production deployments targeting high availability should use the Kubernetes manifests in self-host/k8s/ and require a managed Postgres cluster, properly configured NATS, and optionally FoundationDB for the multi-region KV store. The engine is a compiled Rust binary that starts quickly and has a small memory footprint, but you are responsible for database backups, certificate management, node health, and version upgrades. There is no built-in automated upgrade path — upgrades require rolling restarts.

Rivet Cloud provides the fully managed alternative: global edge network, automatic actor placement near users, built-in observability, managed upgrades, and $0 idle cost with no cluster to maintain. Self-hosting gives you full control over data residency and avoids vendor lock-in, but you give up the global edge routing, managed database operations, SLA guarantees, and priority engineering support available through the Cloud tier. Community support is available via Discord and GitHub Discussions; enterprise support arrangements are handled through direct contact with the Rivet team.