Architecture

How namespaces, Actors, workers, pools, and the gateway fit together, and the difference between serverless and long-running workers.

Rivet separates the process that decides where work runs from the process that runs it. The control plane schedules, routes, and persists. Workers are your processes, running your code. Everything else in these docs is a detail of one of those two sides, or of the boundary between them.

Control Plane

The control plane is a single Rust binary. It tracks every Actor, decides which worker each one runs on, routes requests to it, and persists its state. It is the only stateful component you operate, and it never runs your code.

Use it on Rivet Cloud, inside your own account with BYOC, or self-host it. In local development, RivetKit starts one for you at http://localhost:6420 with no authentication.

Namespaces

A namespace is the tenancy boundary. Actor IDs and keys, worker names, pools, and tokens are all scoped to one namespace. Use namespaces to separate production from staging, or one customer from another. Every connection names a namespace, defaulting to default.

See Namespaces.

Actors

An Actor is one schedulable unit of work with its own durable state and its own address. The control plane’s view of every Actor is the same regardless of type: it has an ID, a key, a status, and the worker it is currently allocated to.

An Actor is created on demand, runs until it goes idle, hibernates with its state intact, and wakes on the next request. It does not move between regions. Workflows, agentOS, and Dynamic Apps are Actors with a job already built in.

See Actor Statuses for the lifecycle the control plane exposes.

Workers

A worker is a process you operate that has your code loaded and the Rivet SDK running inside it. It is the only place your code executes. Workers connect outbound to the control plane, so they need no public URL and no inbound firewall rule.

Each worker reports a version number. The control plane prefers the highest version it can see when allocating new Actors, which is what makes a rolling deploy work without coordination. See Versions & Upgrades.

Worker Pools

A pool is the set of workers registered under one name within a namespace. Pools route Actors to the right hardware: a gpu-workers pool and a default pool can serve the same application, and a client names the pool when it creates an Actor.

A pool’s kind matches how its workers attach. normal pools hold long-running workers that connect themselves. serverless pools are woken by the control plane over HTTP. Scaling, drain behavior, and eviction rate limits are set per pool.

See Workers & Pools for running them and Pool Configuration for the options.

Gateway

The gateway is the part of the control plane that accepts client traffic and proxies it to whichever worker currently holds the target Actor. It speaks plain HTTP and WebSocket:

{RIVET_ENDPOINT}/gateway/{actor_id}/{path}

Because it resolves the target on every request, a client never needs to know where an Actor is running, and an Actor that is rescheduled onto a different worker keeps the same address. See Connect for the endpoint and Management API for addressing Actors directly.

Serverless vs. Long-Running Workers

How a worker connects to the control plane is the biggest deployment decision. There are two options, and they can coexist in different pools of the same namespace.

Long-Running Workers

The worker starts as a normal process, opens a persistent connection to the control plane, and waits for work. When a client creates an Actor, the control plane sends a command over that connection to start it. This is the default mode, used for local development and for containers, VMs, and bare metal (Kubernetes, Railway, AWS ECS, Hetzner).

You control how many workers run and how they scale. Nothing needs to be publicly reachable.

Serverless Workers

There is no persistent process. When a client creates an Actor, the control plane calls GET /api/rivet/start on your serverless deployment, and that invocation becomes a worker for the length of the request. Use it for Vercel, Cloudflare Workers, Supabase, and AWS Lambda. Rivet Cloud deploys in this mode.

Serverless workers scale to zero, follow your platform’s autoscaling, and work with preview deployments. Function timeouts are handled by migrating Actors between invocations with their state intact, so you write code as if it runs forever.

See Workers & Pools for starting a worker in either mode and Deploy Workers for per-platform guides.

Regions

A datacenter is one control plane deployment with its own hostname. A multi-region deployment runs one per region over a shared database, and Actors are placed in a datacenter at creation and stay there. See Regions & Multi-Region.