Skip to main content
Sign In

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 nodes run your code.

BACKENDClientsBrowsers, appsActor nodesYour codeControl planeSchedule, route, persistObject storageS3, GCS or Azure

Nodes

A 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 SQLite database. Storage is tiered: recent data lives on SSDs in the control plane, and all data is offloaded to object storage such as S3.

Rivet ActorSQLiteYour ActorAZ 1AZ 2AZ 3Durable on disk in 3 availability zonesS3, offloaded later
  • Writes: A write goes to disk in three availability zones and is acknowledged once two of them have it. Object storage is never on the write path. Durable writes take 1.07 ms at p99.
  • Offloading: In the background, the control plane batches data into object storage. Batching keeps object storage requests few, and object storage has no size limit.
  • Reads: Hot pages are served from SSD, and cold pages are fetched from object storage on demand. The first read after a Rivet Actor wakes takes 1.36 ms at p99.
  • Sleep and wake: An Actor can sleep, release its memory, and wake on another node with its saved data.

All numbers come from the benchmark, which describes the setup and method. 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 Node Pool Configuration.

Questions?

Join our Discord to ask questions about the architecture and talk with the team.