API Reference

About This API

Agent Sandboxes is OpenSandbox running on Nirvana’s NKS with a custom, performance-tuned configuration.

The API is built on OpenSandbox, but we manage a fully customized deployment with:

Custom NKS Configuration — Optimized cluster setup tuned for your workload requirements
Integrated Storage Solution — Custom storage backend through the extensions field (not available in vanilla OpenSandbox)
Per-Customer Performance Tuning — Your sandbox cluster is configured specifically for your performance and reliability needs

The endpoints documented here cover the most common operations. For additional OpenSandbox endpoints and advanced options, see the OpenSandbox documentation.

Coming Soon: Nirvana-specific endpoints and enhanced management features tailored to your infrastructure.

Authentication

All API requests require the OPEN-SANDBOX-API-KEY header:

-H "OPEN-SANDBOX-API-KEY: YOUR_API_KEY"

Base URLs

API Server: {API_ENDPOINT} (provided by Nirvana Labs)
Gateway: {GATEWAY_ENDPOINT} (provided by Nirvana Labs)

Replace {API_ENDPOINT} and {GATEWAY_ENDPOINT} with the actual URLs provided when you receive your sandbox credentials.

Sandboxes

Create Sandbox

Request:

POST /sandboxes
Content-Type: application/json
OPEN-SANDBOX-API-KEY: YOUR_API_KEY

Body:

{
  "image": {
    "uri": "python:3.12-slim"
  },
  "entrypoint": ["/bin/sh", "-c", "command"],
  "resourceLimits": {
    "cpu": "2",
    "memory": "2Gi"
  },
  "extensions": {
    "persistence": "true",
    "storageClass": "local-path",
    "storageSize": "50Gi"
  }
}

Response:

{
  "id": "sandbox-id-uuid",
  "image": {
    "uri": "python:3.12-slim"
  },
  "status": {
    "state": "Running",
    "reason": "DependenciesReady",
    "message": "Pod is Ready; Service Exists",
    "lastTransitionAt": "2026-07-02T10:37:23Z"
  },
  "createdAt": "2026-07-02T10:37:16Z"
}

Get Sandbox

Request:

GET /sandboxes/{sandbox_id}
OPEN-SANDBOX-API-KEY: YOUR_API_KEY

Response: Returns the full sandbox object with current status.

List Sandboxes

Request:

GET /sandboxes
OPEN-SANDBOX-API-KEY: YOUR_API_KEY

Response:

{
  "items": [
    { /* sandbox object */ },
    { /* sandbox object */ }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20
  }
}

Pause Sandbox

Request:

POST /sandboxes/{sandbox_id}/pause
OPEN-SANDBOX-API-KEY: YOUR_API_KEY

Details:

Pod is deleted, PVC is retained
Instant operation
State preserved if persistence enabled

Resume Sandbox

Request:

POST /sandboxes/{sandbox_id}/resume
OPEN-SANDBOX-API-KEY: YOUR_API_KEY

Details:

Creates new pod with same /workspace PVC
Instant operation
Agent continues from checkpoint

Delete Sandbox

Request:

DELETE /sandboxes/{sandbox_id}
OPEN-SANDBOX-API-KEY: YOUR_API_KEY

Details:

Sandbox is terminated and resources are cleaned up
Instant operation

Endpoints & Access

Get Service Endpoint

Request:

GET /sandboxes/{sandbox_id}/endpoints/{port}
OPEN-SANDBOX-API-KEY: YOUR_API_KEY

Response:

{
  "endpoint": "{GATEWAY_ENDPOINT}",
  "headers": {
    "OpenSandbox-Ingress-To": "{sandbox_id}-{port}"
  }
}

Usage:

curl -H "OpenSandbox-Ingress-To: {sandbox_id}-{port}" \
  $GATEWAY_ENDPOINT/path

Proxy Endpoint (via API Server)

Request:

GET /sandboxes/{sandbox_id}/proxy/{port}/{path}
OPEN-SANDBOX-API-KEY: YOUR_API_KEY

Example:

curl $API_ENDPOINT/sandboxes/abc123/proxy/8000/state.json \
  -H "OPEN-SANDBOX-API-KEY: YOUR_API_KEY"

Details:

Routes through API server (simpler, no custom headers needed)
Suitable for JSON/API requests
Lower throughput than gateway for large files

Diagnostics

Get Sandbox Logs

Request:

GET /sandboxes/{sandbox_id}/diagnostics/logs
OPEN-SANDBOX-API-KEY: YOUR_API_KEY

Get Sandbox Events

Request:

GET /sandboxes/{sandbox_id}/diagnostics/events
OPEN-SANDBOX-API-KEY: YOUR_API_KEY

Inspect Sandbox

Request:

GET /sandboxes/{sandbox_id}/diagnostics/inspect
OPEN-SANDBOX-API-KEY: YOUR_API_KEY

Returns detailed pod and resource information.

Status States

Running — Sandbox is active and ready
Paused — Pod deleted, PVC retained
Pending — Creating pod, waiting for resources
Failed — Sandbox failed to start or crashed
Terminated — Sandbox deleted

Error Responses

All errors include a detail field with error information:

{
  "code": "ERROR_CODE",
  "message": "Human-readable error message",
  "detail": "Additional context"
}

Common errors:

MISSING_API_KEY — API key header missing
INVALID_API_KEY — API key incorrect
POD_READY_TIMEOUT — Sandbox failed to start within timeout
SANDBOX_NOT_FOUND — Sandbox ID doesn’t exist