Skip to main content
Running Workloads

Namespaces

Separate production, staging, or tenants with namespace slugs.

A namespace separates Actors, Actor keys, and node pools on one control plane. Each namespace has a unique slug, such as production or staging. Use that slug in endpoints and API requests.

Quickstart

Create a namespace

Use your control plane’s admin token:

curl -X POST "$RIVET_API/namespaces" \
  -H "Authorization: Bearer $RIVET_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"staging"}'
{"namespace":{"name":"staging","create_ts":1790000000000}}

Configure a node pool

Create a pool in the namespace before connecting nodes:

curl -X PUT "$RIVET_API/pools/default?namespace=staging" \
  -H "Authorization: Bearer $RIVET_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"metadata":{"environment":"staging"}}'

See Node Pool Configuration for pool settings.

Connect your app

Set the namespace slug in the node’s private endpoint and start the registry with registry.start():

RIVET_ENDPOINT=https://staging:<private-token>@rivet.mycompany.com

Use a scoped token for applications. The admin token can access every namespace.

List namespaces

curl "$RIVET_API/namespaces?limit=100" \
  -H "Authorization: Bearer $RIVET_ADMIN_TOKEN"

The response contains namespaces and pagination.cursor. Pass the cursor as cursor on the next request. Filter a single namespace with ?name=staging.

Fork a namespace

Pass fork_from to create a namespace that starts with a copy of another namespace’s Actors, with the same Actor IDs, keys, and databases. The copy shares the parent’s data instead of copying it. Node pools are not copied, so configure them in the new namespace before its Actors can run:

curl -X POST "$RIVET_API/namespaces?wait=settled" \
  -H "Authorization: Bearer $RIVET_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"staging-copy","fork_from":"production"}'

See Namespace Forks for what a fork includes and how Actors can tell they are in a copy.

Choose a namespace

An endpoint can include the slug, as above, or you can set RIVET_NAMESPACE=staging separately. Management API requests use ?namespace=staging.

The default namespace is provided for local development. On a shared control plane, create a namespace for each environment before connecting nodes or creating Actors.

Last updated November 16, 2026