Creating sandboxes

Create an isolated environment to run commands, work with files, and serve applications. A sandbox starts from an image, a saved CPU sandbox snapshot, or a persistent macOS disk.

Start with a base image for a CPU sandbox, or build a custom image with your application’s dependencies.

Requests without a GPU or macOS option create CPU sandboxes. For CUDA workloads, see GPU sandboxes; setting gpu selects the runtime automatically. For a Mac desktop and persistent disk, see macOS sandboxes (Beta). Contact us at info@hyperbrowser.ai or through support chat to enable GPU or macOS access for your team.

Quick Start

Create a sandbox from an image:

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const sandbox = await client.sandboxes.create({
  imageName: "node",
});

console.log("Sandbox ID:", sandbox.id);
console.log("Status:", sandbox.status);
console.log("Runtime URL:", sandbox.runtime.baseUrl);
console.log("Session URL:", sandbox.sessionUrl);

import os
from dotenv import load_dotenv

from hyperbrowser import Hyperbrowser

load_dotenv()

client = Hyperbrowser(api_key=os.environ["HYPERBROWSER_API_KEY"])

sandbox = client.sandboxes.create({"image_name": "python"})

print(f"Sandbox ID: {sandbox.id}")
print(f"Status: {sandbox.status}")
print(f"Runtime URL: {sandbox.runtime.base_url}")
print(f"Session URL: {sandbox.session_url}")

import os
from dotenv import load_dotenv

from hyperbrowser import Hyperbrowser
from hyperbrowser.models import CreateSandboxParams

load_dotenv()

client = Hyperbrowser(api_key=os.environ["HYPERBROWSER_API_KEY"])

sandbox = client.sandboxes.create(CreateSandboxParams(image_name="python"))

print(f"Sandbox ID: {sandbox.id}")
print(f"Status: {sandbox.status}")
print(f"Runtime URL: {sandbox.runtime.base_url}")
print(f"Session URL: {sandbox.session_url}")

hx --json vm create node

curl -X POST https://api.hyperbrowser.ai/api/sandbox \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "imageName": "node"
  }'

Provide exactly one start source when creating a sandbox: imageName, snapshotName (CPU sandboxes), or diskId (macOS). GPU sandboxes require a GPU-ready image built by your team and initially return status: "provisioning". Follow the GPU guide to wait for the runtime before running commands.

Start From a Snapshot

Start a new sandbox from a memory snapshot:

const sandbox = await client.sandboxes.create({
  snapshotName: "my-node-snapshot",
  snapshotId: "your-snapshot-id", // optional but recommended
});

sandbox = client.sandboxes.create(
    {
        "snapshot_name": "my-python-snapshot",
        "snapshot_id": "your-snapshot-id",  # optional but recommended
    }
)

from hyperbrowser.models import CreateSandboxParams

sandbox = client.sandboxes.create(
    CreateSandboxParams(
        snapshot_name="my-python-snapshot",
        snapshot_id="your-snapshot-id",  # optional but recommended
    )
)

hx --json vm create snapshot:my-node-snapshot --snapshot-id your-snapshot-id

curl -X POST https://api.hyperbrowser.ai/api/sandbox \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "snapshotName": "my-node-snapshot",
    "snapshotId": "your-snapshot-id"
  }'

Configuration Options

Customize the sandbox region, timeout, and recording settings:

const sandbox = await client.sandboxes.create({
  imageName: "node",
  region: "us-west",
  timeoutMinutes: 30,
  enableRecording: true,
});

sandbox = client.sandboxes.create(
    {
        "image_name": "python",
        "region": "us-west",
        "timeout_minutes": 30,
        "enable_recording": True,
    }
)

from hyperbrowser.models import CreateSandboxParams

sandbox = client.sandboxes.create(
    CreateSandboxParams(
        image_name="python",
        region="us-west",
        timeout_minutes=30,
        enable_recording=True,
    )
)

hx --json vm create node --region us-west --timeout-minutes 30 --enable-recording

curl -X POST https://api.hyperbrowser.ai/api/sandbox \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "imageName": "node",
    "region": "us-west",
    "timeoutMinutes": 30,
    "enableRecording": true
  }'

Resource Configuration

Set vCPU, memory, and disk size when launching from an image:

const sandbox = await client.sandboxes.create({
  imageName: "node",
  cpu: 2,
  memoryMiB: 2048,
  diskMiB: 8192,
});

sandbox = client.sandboxes.create(
    {
        "image_name": "python",
        "cpu": 2,
        "memory_mib": 2048,
        "disk_mib": 8192,
    }
)

from hyperbrowser.models import CreateSandboxParams

sandbox = client.sandboxes.create(
    CreateSandboxParams(
        image_name="python",
        cpu=2,
        memory_mib=2048,
        disk_mib=8192,
    )
)

hx --json vm create node --cpu 2 --memory 2048 --disk 8192

curl -X POST https://api.hyperbrowser.ai/api/sandbox \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "imageName": "node",
    "vcpus": 2,
    "memMiB": 2048,
    "diskSizeMiB": 8192
  }'

For image launches, the default resource configuration is 2 vCPUs, 2048 MiB of memory, and 8192 MiB of disk if you omit these fields.

Resource configuration is only supported when started from an image. Snapshot launches use the snapshot’s saved resource baseline.

Mount Volumes

Attach persistent volumes at sandbox launch using the mounts field.

const sandbox = await client.sandboxes.create({
  imageName: "node",
  mounts: {
    "/mnt/workspace": {
      id: "550e8400-e29b-41d4-a716-446655440000",
      type: "rw",
    },
    "/mnt/cache": {
      id: "660e8400-e29b-41d4-a716-446655440000",
      type: "ro",
    },
  },
});

sandbox = client.sandboxes.create(
    {
        "image_name": "node",
        "mounts": {
            "/mnt/workspace": {
                "id": "550e8400-e29b-41d4-a716-446655440000",
                "type": "rw",
            },
            "/mnt/cache": {
                "id": "660e8400-e29b-41d4-a716-446655440000",
                "type": "ro",
            },
        },
    }
)

from hyperbrowser.models import CreateSandboxParams, SandboxVolumeMount

sandbox = client.sandboxes.create(
    CreateSandboxParams(
        image_name="node",
        mounts={
            "/mnt/workspace": SandboxVolumeMount(
                id="550e8400-e29b-41d4-a716-446655440000",
                type="rw",
            ),
            "/mnt/cache": SandboxVolumeMount(
                id="660e8400-e29b-41d4-a716-446655440000",
                type="ro",
            ),
        },
    )
)

hx vm create node --mount <volume-id>:/mnt/workspace
hx vm create node --mount <volume-id>:/mnt/cache:ro
hx vm create node --mount source=<volume-id>,target=/mnt/workspace
hx vm create node --mount source=<volume-id>,target=/mnt/cache,readonly

curl -X POST https://api.hyperbrowser.ai/api/sandbox \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "imageName": "node",
    "mounts": {
      "/mnt/workspace": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "type": "rw"
      },
      "/mnt/cache": {
        "id": "660e8400-e29b-41d4-a716-446655440000",
        "type": "ro"
      }
    }
  }'

See Managing Volumes and Mounting Volumes for API details and mount constraints.

Common Parameters

string

Name of the sandbox image to start from. Provide this or snapshotName. See Base Images for built-in values.

string

Optional specific image ID. Requires imageName.

number

Requested vCPU count for image launches. In the raw API, this field is vcpus.

number

Requested memory in MiB for image launches. In the raw API, this field is memMiB.

number

Requested disk size in MiB for image launches. In the raw API, this field is diskSizeMiB.

string

Name of the snapshot to restore from. Provide this or imageName.

string

Optional specific snapshot ID. Requires snapshotName.

string

default:"us"

Region where the sandbox should start. The asia-south region is only available on Enterprise and Select plans. Get in touch to learn more.

number

Maximum sandbox lifetime in minutes.

boolean

default:false

Enable sandbox recording.

object

Optional raw-API map of mount path to volume reference. Each key is the mount path inside the sandbox (for example /mnt/workspace). Each value includes: id (volume UUID), type (rw or ro, default rw), and optional shared (currently reserved). This is available in the SDKs, via REST, and via CLI mount flags.

boolean

default:true

Sets the fallback for outbound destinations that do not match an allow or deny rule. Set it to false for a default-deny policy.

string[]

IPv4 addresses, IPv4 CIDRs, exact domains, or wildcard domains to allow.

string[]

IPv4 addresses or IPv4 CIDRs to deny. See Network Policies for precedence and domain rules.

Sandbox Response

The create API returns a detailed sandbox object:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "active",
  "region": "us",
  "sessionUrl": "https://app.hyperbrowser.ai/sandboxes/550e8400-e29b-41d4-a716-446655440000",
  "runtime": {
    "transport": "regional_proxy",
    "host": "https://<regional-runtime-host>",
    "baseUrl": "https://<regional-runtime-host>/sandbox/<sandbox-id>"
  },
  "network": {
    "allowInternetAccess": true,
    "allowOut": [],
    "denyOut": []
  },
  "token": "eyJ...",
  "tokenExpiresAt": "2026-03-12T21:14:00.000Z"
}

string

Unique sandbox identifier.

string

Current sandbox status.

string

Region where the sandbox is running.

string

Dashboard URL for the sandbox.

object

Runtime target used for direct runtime operations. Includes transport, host, and baseUrl.

object

Effective outbound network policy. Includes allowInternetAccess, allowOut, and denyOut.

string | null

Sandbox runtime bearer token.

string | null

Token expiration time in ISO 8601 format.

Explore Sandbox Features

Lifecycle

Manage running sandboxes, refresh handles, reconnect, and stop them cleanly with Sandbox Lifecycle.

Runtime URLs and Exposed Ports

Expose HTTP services, understand how sandbox URLs route to ports, and use authenticated browser access with Sandbox Runtime URLs.

Network Policies

Restrict outbound traffic with IPv4, CIDR, and domain rules using Network Policies.

Processes

Run one-shot commands, start background work, stream output, and manage process state with Sandbox Processes.

Local Filesystem

Read, write, watch, upload, download, and presign file transfers with Local Filesystem.

Volumes

Create persistent volumes and mount them at launch with Volumes.

Snapshots

Capture memory state and restore new sandboxes from it with Sandbox Snapshots.

Get Started

Sandbox

Base Images

Custom Images

Volumes

Local Filesystem

Quick Start

Start From a Snapshot

Configuration Options

Resource Configuration

Mount Volumes

Common Parameters

Sandbox Response

Explore Sandbox Features

​Quick Start

​Start From a Snapshot

​Configuration Options

​Resource Configuration

​Mount Volumes

​Common Parameters

​Sandbox Response

​Explore Sandbox Features

Quick Start

Start From a Snapshot

Configuration Options

Resource Configuration

Mount Volumes

Common Parameters

Sandbox Response

Explore Sandbox Features