> ## Documentation Index
> Fetch the complete documentation index at: https://hyperbrowser.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating Sandboxes

> Create and configure Hyperbrowser sandboxes

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.

<Tip>
  Get started instantly with common use cases covered by [Base Images](/sandboxes/base-images).
  For more custom use cases, learn how to
  [Build And Upload A Custom Image](/sandboxes/custom-images).
</Tip>

## Quick Start

Create a sandbox from an image:

<CodeGroup>
  ```typescript Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  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}")
  ```

  ```bash CLI theme={null}
  hx --json create node
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.hyperbrowser.ai/api/sandbox \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "imageName": "node"
    }'
  ```
</CodeGroup>

<Note>
  Provide exactly one start source when creating a sandbox:
  `imageName` or `snapshotName`.
</Note>

## Start From a Snapshot

Start a new sandbox from a memory snapshot:

<CodeGroup>
  ```typescript Node.js theme={null}
  const sandbox = await client.sandboxes.create({
    snapshotName: "my-node-snapshot",
    snapshotId: "your-snapshot-id", // optional but recommended
  });
  ```

  ```python Python theme={null}
  from hyperbrowser.models import CreateSandboxParams

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

  ```bash CLI theme={null}
  hx --json create snapshot:my-node-snapshot --snapshot-id your-snapshot-id
  ```

  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

## Configuration Options

Customize the sandbox region, timeout, and recording settings:

<CodeGroup>
  ```typescript Node.js theme={null}
  const sandbox = await client.sandboxes.create({
    imageName: "node",
    region: "us-west",
    timeoutMinutes: 30,
    enableRecording: true,
  });
  ```

  ```python Python theme={null}
  from hyperbrowser.models import CreateSandboxParams

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

  ```bash CLI theme={null}
  hx --json create node --region us-west --timeout-minutes 30 --enable-recording
  ```

  ```bash cURL theme={null}
  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
    }'
  ```
</CodeGroup>

## Resource Configuration

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

<CodeGroup>
  ```typescript Node.js theme={null}
  const sandbox = await client.sandboxes.create({
    imageName: "node",
    cpu: 4,
    memoryMiB: 4096,
    diskMiB: 8192,
  });
  ```

  ```python Python theme={null}
  from hyperbrowser.models import CreateSandboxParams

  sandbox = client.sandboxes.create(
      CreateSandboxParams(
          image_name="python",
          cpu=4,
          memory_mib=4096,
          disk_mib=8192,
      )
  )
  ```

  ```bash CLI theme={null}
  hx --json create node --cpu 4 --memory 4096 --disk 8192
  ```

  ```bash cURL theme={null}
  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": 4,
      "memMiB": 4096,
      "diskSizeMiB": 8192
    }'
  ```
</CodeGroup>

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

<Note>
  Resource configuration is only supported when started from an image.
  Snapshot launches use the snapshot's saved resource baseline.
</Note>

## Mount Volumes

Attach persistent volumes at sandbox launch using the `mounts` field.

<CodeGroup>
  ```typescript Node.js theme={null}
  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",
      },
    },
  });
  ```

  ```python Python theme={null}
  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",
              ),
          },
      )
  )
  ```

  ```bash CLI theme={null}
  hx create node --mount <volume-id>:/mnt/workspace
  hx create node --mount <volume-id>:/mnt/cache:ro
  hx create node --mount source=<volume-id>,target=/mnt/workspace
  hx create node --mount source=<volume-id>,target=/mnt/cache,readonly
  ```

  ```bash cURL theme={null}
  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"
        }
      }
    }'
  ```
</CodeGroup>

<Note>
  See [Managing Volumes](/sandboxes/volumes/managing) and
  [Mounting Volumes](/sandboxes/volumes/mounting) for API details and mount
  constraints.
</Note>

### Common Parameters

<ParamField path="imageName" type="string">
  Name of the sandbox image to start from. Provide this or `snapshotName`.
  See [Base Images](/sandboxes/base-images) for built-in values.
</ParamField>

<ParamField path="imageId" type="string">
  Optional specific image ID. Requires `imageName`.
</ParamField>

<ParamField path="cpu" type="number">
  Requested vCPU count for image launches. In the raw API, this field is
  `vcpus`.
</ParamField>

<ParamField path="memoryMiB" type="number">
  Requested memory in MiB for image launches. In the raw API, this field is
  `memMiB`.
</ParamField>

<ParamField path="diskMiB" type="number">
  Requested disk size in MiB for image launches. In the raw API, this field is
  `diskSizeMiB`.
</ParamField>

<ParamField path="snapshotName" type="string">
  Name of the snapshot to restore from. Provide this or `imageName`.
</ParamField>

<ParamField path="snapshotId" type="string">
  Optional specific snapshot ID. Requires `snapshotName`.
</ParamField>

<ParamField path="region" type="string" default="us">
  Region where the sandbox should start.
</ParamField>

<ParamField path="timeoutMinutes" type="number">
  Maximum sandbox lifetime in minutes.
</ParamField>

<ParamField path="enableRecording" type="boolean" default={false}>
  Enable sandbox recording.
</ParamField>

<ParamField path="mounts" type="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.
</ParamField>

## Sandbox Response

The create API returns a detailed sandbox object:

```json theme={null}
{
  "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"
}
```

<ResponseField name="id" type="string">
  Unique sandbox identifier.
</ResponseField>

<ResponseField name="status" type="string">
  Current sandbox status.
</ResponseField>

<ResponseField name="region" type="string">
  Region where the sandbox is running.
</ResponseField>

<ResponseField name="sessionUrl" type="string">
  Dashboard URL for the sandbox.
</ResponseField>

<ResponseField name="runtime" type="object">
  Runtime target used for direct runtime operations. Includes `transport`,
  `host`, and `baseUrl`.
</ResponseField>

<ResponseField name="token" type="string | null">
  Sandbox runtime bearer token.
</ResponseField>

<ResponseField name="tokenExpiresAt" type="string | null">
  Token expiration time in ISO 8601 format.
</ResponseField>

## Explore Sandbox Features

<AccordionGroup>
  <Accordion title="Lifecycle" icon="server">
    Manage running sandboxes, refresh handles, reconnect, and stop them cleanly
    with [Sandbox Lifecycle](/sandboxes/lifecycle).
  </Accordion>

  <Accordion title="Runtime URLs and Exposed Ports" icon="globe">
    Expose HTTP services, understand how sandbox URLs route to ports, and use
    authenticated browser access with
    [Sandbox Runtime URLs](/sandboxes/runtime).
  </Accordion>

  <Accordion title="Processes" icon="square-terminal">
    Run one-shot commands, start background work, stream output, and manage
    process state with [Sandbox Processes](/sandboxes/processes).
  </Accordion>

  <Accordion title="Local Filesystem" icon="folder">
    Read, write, watch, upload, download, and presign file transfers with
    [Local Filesystem](/sandboxes/filesystem/overview).
  </Accordion>

  <Accordion title="Volumes" icon="database">
    Create persistent volumes and mount them at launch with
    [Volumes](/sandboxes/volumes).
  </Accordion>

  <Accordion title="Snapshots" icon="camera">
    Capture memory state and restore new sandboxes from it with
    [Sandbox Snapshots](/sandboxes/snapshots).
  </Accordion>
</AccordionGroup>