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.