Sandboxes are isolated cloud environments with process, filesystem, terminal, snapshot, and port exposure APIs. You create a sandbox from either an image or a previously created snapshot.
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,
});
Common Parameters
Name of the sandbox image to start from. Provide this or snapshotName.
Optional specific image ID. Requires imageName.
Name of the snapshot to restore from. Provide this or imageName.
Optional specific snapshot ID. Requires snapshotName.
Region where the sandbox should start.
Maximum sandbox lifetime in minutes.
Enable sandbox recording.
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/features/sessions/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"
}
Unique sandbox identifier.
Region where the sandbox is running.
Dashboard URL for the sandbox.
Runtime target used for direct runtime operations. Includes transport,
host, and baseUrl.
Sandbox runtime bearer token.
Token expiration time in ISO 8601 format.
