Skip to main content
Sandboxes are isolated cloud environments built to scale with your agentic needs. Sandboxes have real runtime urls that you can call to run any kind of workflow you need. Batteries are included.
Get started instantly with common use cases covered by Base Images. For more custom use cases, learn how to Build And Upload A Custom Image.

​
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);
Provide exactly one start source when creating a sandbox: imageName or snapshotName.

​
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
});

​
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,
});

​
Resource Configuration

Set vCPU, memory, and disk size when launching from an image: 
const sandbox = await client.sandboxes.create({
  imageName: "node",
  cpu: 4,
  memoryMiB: 4096,
  diskMiB: 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",
    },
  },
});
See Managing Volumes and Mounting Volumes for API details and mount constraints.

​
Common Parameters

​
imageName
string
Name of the sandbox image to start from. Provide this or snapshotName. See Base Images for built-in values.
​
imageId
string
Optional specific image ID. Requires imageName.
​
cpu
number
Requested vCPU count for image launches. In the raw API, this field is vcpus.
​
memoryMiB
number
Requested memory in MiB for image launches. In the raw API, this field is memMiB.
​
diskMiB
number
Requested disk size in MiB for image launches. In the raw API, this field is diskSizeMiB.
​
snapshotName
string
Name of the snapshot to restore from. Provide this or imageName.
​
snapshotId
string
Optional specific snapshot ID. Requires snapshotName.
​
region
string
default:"us"
Region where the sandbox should start.
​
timeoutMinutes
number
Maximum sandbox lifetime in minutes.
​
enableRecording
boolean
default:false
Enable sandbox recording.
​
mounts
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.

​
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": "550e8400-e29b-41d4-a716-446655440000.us.example.hyperbrowser.ai",
    "baseUrl": "https://550e8400-e29b-41d4-a716-446655440000.us.example.hyperbrowser.ai"
  },
  "token": "eyJ...",
  "tokenExpiresAt": "2026-03-12T21:14:00.000Z"
}
​
id
string
Unique sandbox identifier.
​
status
string
Current sandbox status.
​
region
string
Region where the sandbox is running.
​
sessionUrl
string
Dashboard URL for the sandbox.
​
runtime
object
Runtime target used for direct runtime operations. Includes transport, host, and baseUrl.
​
token
string | null
Sandbox runtime bearer token.
​
tokenExpiresAt
string | null
Token expiration time in ISO 8601 format.

​
Explore Sandbox Features

Manage running sandboxes, refresh handles, reconnect, and stop them cleanly with Sandbox Lifecycle.
Expose HTTP services, understand how sandbox URLs route to ports, and use authenticated browser access with Sandbox Runtime URLs.
Run one-shot commands, start background work, stream output, and manage process state with Sandbox Processes.
Read, write, watch, upload, download, and presign file transfers with Local Filesystem.
Create persistent volumes and mount them at launch with Volumes.
Capture memory state and restore new sandboxes from it with Sandbox Snapshots.