Sandbox Clusters

A sandbox cluster is the compute your sandboxes run on, in one region. Nirvana provisions and manages it for you. It is a Nirvana API resource like a VM or a VPC, and you create and delete it yourself through the API.

Projects

Each sandbox cluster belongs to one of your projects. Access to it, and to the sandboxes on it, follows that project: an API key needs the cluster’s project in its scope to see or use it.

Limits

An organization can have any number of sandbox clusters, within its quotas. Each cluster counts against the organization’s quotas.

Sandbox clusters are not available in every region.

Permissions

Managing sandbox clusters needs the sandbox_cluster permission on the cluster’s project: read to list and get, edit to create, update and delete. Using the sandboxes on a cluster needs the separate sandbox permission, see Connect to a Sandbox Cluster. API keys are covered in Authentication.

Organization roles limit this further. Members can read sandbox clusters and sandboxes but can’t create, update or delete them. Owners and admins can.

Create a sandbox cluster

curl -X POST https://api.nirvanalabs.io/v1/sandbox_clusters \
  -H "Authorization: Bearer $NIRVANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "my-sandboxes",
    "tags": ["agents"],
    "region": "us-sva-2",
    "instance_type": "n1-standard-8",
    "node_count": 3
  }'

Field	Required	Description
`project_id`	Yes	Project the cluster belongs to.
`name`	Yes	Name of the cluster. Unique within the project. Must start with a lowercase letter, followed by lowercase letters, digits or hyphens; at most 63 characters; can’t end with a hyphen.
`tags`	No	Tags to attach to the cluster.
`region`	Yes	Region to create the cluster in.
`instance_type`	Yes	Instance type of the nodes sandboxes run on.
`node_count`	Yes	Number of nodes, from 1 to 100.

The request returns 202 with an operation. Provisioning takes a few minutes. Poll the cluster until its status is ready before creating sandboxes on it.

Get a sandbox cluster

curl https://api.nirvanalabs.io/v1/sandbox_clusters/{sandbox_cluster_id} \
  -H "Authorization: Bearer $NIRVANA_API_KEY"

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "my-sandboxes",
  "tags": ["agents"],
  "region": "us-sva-2",
  "status": "ready",
  "instance_type": "n1-standard-8",
  "node_count": 3,
  "project_id": "123e4567-e89b-12d3-a456-426614174000",
  "gateway_hostname": "gw.0123456789ab.nirvanacloud.net",
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T00:00:00Z"
}

Field	Description
`status`	Lifecycle status. Sandboxes can be created only when it is `ready`.
`gateway_hostname`	Hostname that sandbox endpoints are served on over HTTPS. Allow it in outbound firewalls if needed. `null` until assigned. A cluster that is deleted and recreated gets a new one.

List sandbox clusters

curl "https://api.nirvanalabs.io/v1/sandbox_clusters?project_id={project_id}" \
  -H "Authorization: Bearer $NIRVANA_API_KEY"

project_id is required. Optional filters:

region: only clusters in this region.
tags: only clusters carrying every given tag. Repeat the parameter for several tags.
name: only clusters whose name contains this text, ignoring case.

The usual limit, cursor and sort parameters apply.

Update a sandbox cluster

You can change a cluster’s name and tags. Send at least one of them.

curl -X PATCH https://api.nirvanalabs.io/v1/sandbox_clusters/{sandbox_cluster_id} \
  -H "Authorization: Bearer $NIRVANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "agents-prod", "tags": ["agents", "prod"]}'

The request returns 200 with the updated cluster.

Delete a sandbox cluster

curl -X DELETE https://api.nirvanalabs.io/v1/sandbox_clusters/{sandbox_cluster_id} \
  -H "Authorization: Bearer $NIRVANA_API_KEY"

The request returns 202 with an operation. Deleting a cluster also deletes every sandbox on it.

While a cluster is being created or deleted, the request fails with 409 and the SANDBOX_CLUSTER_NOT_DELETABLE error type. Wait for the current operation to finish and try again.