Connect to a Sandbox Cluster

Sandboxes are served by the Nirvana API at https://api.nirvanalabs.io/v1/sandboxes using the OpenSandbox Sandbox Lifecycle API, so OpenSandbox SDKs work unchanged. To use a sandbox cluster you need three things: an API key, the base URL and the cluster ID.

1. Get an API key

Create a Nirvana organization API key as described in Authentication. Give it the sandbox permission on the sandbox cluster’s project:

• read to list and get sandboxes.
• edit for everything else: creating and deleting sandboxes, getting endpoints, renewing expiration and updating metadata. A read-only key can’t reach a sandbox’s ports.

There is no separate sandbox key. Send the key in either header:

OPEN-SANDBOX-API-KEY: <key>
Authorization: Bearer <key>

OpenSandbox SDKs send OPEN-SANDBOX-API-KEY.

2. Set the base URL

Point the SDK or HTTP client at:

https://api.nirvanalabs.io/v1

3. Choose the cluster

Copy the cluster ID from the sandbox cluster’s page in the dashboard, or from the id field in the API. The cluster’s status must be ready.

When you create a sandbox, put the cluster ID in its extensions:

curl -X POST https://api.nirvanalabs.io/v1/sandboxes \
  -H "OPEN-SANDBOX-API-KEY: $NIRVANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": {"uri": "python:3.12-slim"},
    "entrypoint": ["python3", "-m", "http.server", "8000"],
    "resourceLimits": {"cpu": "1", "memory": "1Gi"},
    "extensions": {
      "nirvana.sandbox_cluster_id": "123e4567-e89b-12d3-a456-426614174000"
    }
  }'

With an SDK, pass the same key-value pair as the sandbox’s extensions.

Next steps

• Create a Sandbox
• Access Sandbox Endpoints
• Delete a Sandbox
• API Reference