The Problem

Deploying long‑lived, stateful agents at scale is hard: each sandbox costs memory, incurs cold‑start latency, and duplicates storage. Teams need a way to run hundreds of thousands of agents per node while keeping startup times under a few milliseconds and per‑agent memory below 100 KB.

What This Does

rivet is an orchestrator that runs agents as lightweight Actors.

  • Fast start‑ups – the Rust core built from Cargo.toml launches an actor in ~5 ms.
  • Low memory – each actor shares the node process; the engine keeps only 72 KB per actor.
  • Persistent state – SQLite databases are stored in S3 and accessed through the engine/packages/api-builder/src/lib.rs runtime.
  • WebSocket support – actors expose real‑time channels via the peer layer in engine/packages/api-peer/src/lib.rs.
  • Scalable allocation – the alloc-count crate (engine/packages/alloc-count/src/lib.rs) tracks worker counts and prevents over‑provisioning.

The example in examples/minimal-agent/server.ts shows how a TypeScript agent is wired to the orchestrator via the rivetkit SDK.

How It Is Wired

Entry point – cargo run -p engine (or the Docker image built by docker/engine/Dockerfile).

  1. Cargo.toml pulls in api-builder, api-peer, and alloc-count.
  2. api-builder registers HTTP routes that forward requests to actors.
  3. Each request is routed by api-peer to the appropriate actor process, creating it if needed.
  4. Actor state lives in a per‑actor SQLite file stored on S3; the S3 client is instantiated in api-builder during initialization.
  5. When an actor terminates, alloc-count updates the global allocation counter.

The call graph is a single linear path: main.rs → api-builder → api-peer → actor code. No cycles are present, so changes to api-builder propagate linearly to the runtime.

How To Use It

# 1) Clone
git clone https://github.com/moses-y/rivet

# 2) Build the engine
cd rivet/engine
cargo build --release

# 3) Run the engine
./target/release/rivet-engine  # or use the Docker image

# 4) Start an example agent
cd examples/minimal-agent
npm install
npm start

The example starts a TypeScript server that connects to the orchestrator over WebSockets. No additional env vars are required for the minimal demo; the engine defaults to 127.0.0.1:3000.

Real‑World Use

A game backend can spin up one actor per player session. Each actor persists chat history in its own SQLite database on S3, allowing instant recovery after a node restart. The actor streams real‑time updates via WebSockets to all clients, keeping state in sync.

Code Health & Issues

  • Tests – 112 Rust test files in engine/.
  • CI – GitHub Actions (.github/workflows/*) run Rust, Swift, and Docker builds.
  • License – MIT (LICENSE).
  • No structural red flags – Cargo.lock, .gitignore, and deny.toml are present.
  • Missing – no automated linting for TypeScript; the README lacks a complete Docker‑Compose example.

The Bottom Line

rivet delivers a lean, Rust‑based orchestrator that keeps agents lightweight and fast. Its modular crate architecture makes it easy to extend, but the current lack of end‑to‑end CI for the TypeScript side may slow new language integrations. Teams needing high‑density, stateful agents with low cold‑start latency will find this a solid foundation.