# Architecture 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. Your client Gateway routes to a specific Actor Control plane schedules, versions, persists worker protocol Worker your process, your code Actor Actor Actor … ## 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](/docs/deploy/cloud), inside your own account with [BYOC](/docs/deploy/byoc), or [self-host](/docs/deploy/self-host/control-plane) 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](/docs/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](/docs/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](/docs/versions). ## 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](/docs/workers) for running them and [Pool Configuration](/docs/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](/docs/connect) for the endpoint and [Management API](/docs/debugging) 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). Long-running worker architecture diagram 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 worker architecture diagram 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. | | Long-running | Serverless | | --- | --- | --- | | Process | Always on, connects out | Started by the control plane per request | | Public endpoint | Not required | Required | | Scaling | You manage it | Platform autoscaling, scale to zero | | Typical hosts | Kubernetes, Docker, VMs | Vercel, Cloudflare, Supabase, Lambda | See [Workers & Pools](/docs/workers) for starting a worker in either mode and [Deploy Workers](/docs/deploy/self-host/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](/docs/regions).