Skip to content
Nirvana Labs Docs
Directory SDKs API Sign In

Create a Sandbox

This guide shows you how to create an Agent Sandbox using the REST API.

Prerequisites

Section titled “Prerequisites”
  • API endpoint and gateway endpoint (provided by Nirvana Labs)
  • OPEN-SANDBOX-API-KEY authentication key
  • curl or HTTP client

Create an Ephemeral Sandbox

Section titled “Create an Ephemeral Sandbox”

Ephemeral sandboxes are stateless and don’t require persistence configuration. Send a POST request to /sandboxes with your container image, entrypoint, and resource limits. The sandbox will be ready within seconds.

Terminal window
curl -X POST {API_ENDPOINT}/sandboxes \
  -H "Content-Type: application/json" \
  -H "OPEN-SANDBOX-API-KEY: YOUR_API_KEY" \
  -d '{
    "image": {"uri": "python:3.12-slim"},
    "entrypoint": ["/bin/sh", "-c", "python3 -m http.server 8000"],
    "resourceLimits": {"cpu": "1", "memory": "1Gi"}
  }'

Create a Persistent Sandbox

Section titled “Create a Persistent Sandbox”

Persistent sandboxes have /workspace storage that survives pause/resume cycles. Add the extensions field with persistence settings to enable this feature.

Terminal window
curl -X POST {API_ENDPOINT}/sandboxes \
  -H "Content-Type: application/json" \
  -H "OPEN-SANDBOX-API-KEY: YOUR_API_KEY" \
  -d '{
    "image": {"uri": "python:3.12-slim"},
    "entrypoint": ["/bin/sh", "-c", "python3 -m http.server 8000"],
    "resourceLimits": {"cpu": "2", "memory": "2Gi"},
    "extensions": {
      "persistence": "true",
      "storageClass": "local-path",
      "storageSize": "50Gi"
    }
  }'

See the Configuration Options section below for details on how to configure persistent storage.

Configuration Options

Section titled “Configuration Options”

Image

Section titled “Image”

Container image to run. Specify as a URI (e.g., python:3.12-slim, node:18-alpine).

Entrypoint

Section titled “Entrypoint”

Command to execute when the sandbox starts. This is typically a shell command or service startup script.

Resource Limits

Section titled “Resource Limits”

Specify CPU and memory allocation:

  • CPU: Cores as a string (e.g., "1", "2", or "2000m")
  • Memory: RAM in Kubernetes format (e.g., "512Mi", "1Gi", "2Gi")

Persistence (Optional)

Section titled “Persistence (Optional)”

To enable persistent /workspace storage that survives pause/resume:

  • persistence: "true" to enable, "false" to disable
  • storageClass: Kubernetes StorageClass name (e.g., "local-path" for development, "abs" for production)
  • storageSize: Storage size in Kubernetes format (e.g., "50Gi")

For detailed storage configuration, see Persistence & Storage.

Next Steps

Section titled “Next Steps”