Skip to content

Control planes and namespaces

Everything a Rivet app has lives on a control plane: every instance’s data, every pool, and the record of which node runs what. A control plane is the boundary around a Rivet app. Nothing on one can reach anything on another, and each has its own admin token, its own storage and its own bill on the cloud it runs on.

A control plane is divided into namespaces. Each namespace has its own pools and its own instances, so the same class in two namespaces is two separate sets of instances.

A namespace for every stage

Section titled “A namespace for every stage”

A control plane Layer creates a namespace for the stage it’s deployed with, so alchemy deploy --stage dev and alchemy deploy --stage prod against the same control plane get separate namespaces:

src/cluster.ts
import * as RivetHetzner from "@alchemy.run/rivet/Hetzner";


export const Cluster = RivetHetzner.ServerControlPlane("Rivet");

Pools, classes and streams all go in the stage’s namespace, and callers reach only that namespace’s instances.

Rivet has no API to delete a namespace. Destroying a stage removes its pools and stops managing its namespace, which stays on the control plane, empty.

A control plane per environment

Section titled “A control plane per environment”

Namespaces separate stages, but they share a control plane: its engines, its storage and its admin token. A control plane is the stronger wall. Give production its own when you want its data, its capacity and its token apart from everything else.

The stage decides what is deployed, and the profile decides where it goes. Deploy the production stage with a profile that signs in to the production account:

Terminal window
pnpm alchemy profile create prod
pnpm alchemy deploy --stage prod --profile prod

Each stage that runs its own control plane deploys its own engines, on the cloud its profile signs in to.

A control plane you already run

Section titled “A control plane you already run”

A control plane that runs outside the Stack, Rivet Cloud or one you operate yourself, connects with its URL and admin token. A namespace is still created for the stage unless you name one:

src/cluster.ts
import * as Rivet from "@alchemy.run/rivet";
import * as Config from "effect/Config";


export const Cluster = Rivet.ControlPlane("Rivet", {
  endpoint: "https://rivet.example.com",
  token: Config.Redacted("RIVET_TOKEN"),
});

See Control Plane and Rivet Cloud.

Next, Tokens and networks: who can reach a control plane, and with what.