Architecture

How object storage, the control plane, and nodes work together to run Rivet Actors.

Rivet has three parts: object storage keeps Actor data, the control plane schedules Actors and routes requests, and actor nodes run your code.

Actor nodes

An actor node is a process running your app with the Rivet SDK, started with registry.start(). It opens an outbound connection to the control plane and hosts the Actors assigned to it. Nodes need no public URL or inbound port for Actor traffic. Add nodes when you need more capacity.

Control plane

The control plane chooses a node for each Actor, wakes sleeping Actors on demand, and forwards HTTP and WebSocket requests to the node hosting the target Actor. An Actor keeps the same address when it moves between nodes.

RivetKit starts a local control plane during development. In production, use Rivet Cloud or self-host the control plane.

Storage

Each Actor has a volume for its state, SQLite database, and key-value data. The control plane writes to replicated disks and moves data to object storage in the background. An Actor can sleep, release its memory, and wake on another node with its saved data.

For replication settings and disk requirements, see Storage.

Namespaces

A namespace separates Actors, keys, and node pools. For example, use production and staging on the same control plane. A namespace is identified by its slug, such as production, in endpoint URLs and API requests. See Namespaces.

Node pools

A node pool groups nodes by name within a namespace. Configure a pool before connecting nodes to it. A node joins the pool selected by RIVET_POOL, which defaults to default. For example, create a gpu pool for Actors that need GPUs alongside a default pool for the rest. See Nodes & Node Pools.