Create new sandbox

POST

api

sandbox

curl --request POST \
  --url https://api.hyperbrowser.ai/api/sandbox \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "imageName": "node"
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "provisioning",
  "region": "us",
  "runtime": {
    "transport": "regional_proxy",
    "host": "<string>",
    "baseUrl": "<string>"
  },
  "exposedPorts": [
    {
      "port": 32768,
      "auth": true,
      "url": "<string>",
      "browserUrl": "<string>",
      "browserUrlExpiresAt": "2023-11-07T05:31:56Z"
    }
  ],
  "runtimeClass": "firecracker",
  "diskId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "ready": true,
  "teamId": "<string>",
  "startTime": 123,
  "endTime": 123,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "closeReason": "<string>",
  "creditsUsed": 123,
  "vcpus": 123,
  "memMiB": 123,
  "diskSizeMiB": 123,
  "timeoutMinutes": 123,
  "network": {
    "allowInternetAccess": true,
    "allowOut": [
      "<string>"
    ],
    "denyOut": [
      "<string>"
    ]
  },
  "sessionUrl": "<string>",
  "duration": 123,
  "proxyBytesUsed": 123,
  "token": "<string>",
  "tokenExpiresAt": "2023-11-07T05:31:56Z",
  "gpuType": "<string>",
  "gpuCount": 123,
  "capabilities": {
    "commands": true,
    "files": true,
    "pty": true,
    "gpu": true,
    "snapshots": true,
    "volumes": true,
    "exposedPorts": true,
    "networkFiltering": true,
    "liveNetworkUpdates": true,
    "internetAccess": true,
    "desktop": true,
    "persistentDisks": true,
    "memorySnapshots": true,
    "writableStorage": "disk"
  },
  "startupSecrets": [
    {
      "env": "<string>",
      "source": {
        "type": "vault",
        "name": "<string>"
      },
      "name": "<string>",
      "secretId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "version": 123,
      "secretType": "totp",
      "reference": "<string>",
      "tokenSecret": "<string>",
      "overrides": [
        {
          "type": "vault",
          "name": "<string>"
        }
      ]
    }
  ]
}

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "provisioning",
  "region": "us",
  "runtime": {
    "transport": "regional_proxy",
    "host": "<string>",
    "baseUrl": "<string>"
  },
  "exposedPorts": [
    {
      "port": 32768,
      "auth": true,
      "url": "<string>",
      "browserUrl": "<string>",
      "browserUrlExpiresAt": "2023-11-07T05:31:56Z"
    }
  ],
  "runtimeClass": "firecracker",
  "diskId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "ready": true,
  "teamId": "<string>",
  "startTime": 123,
  "endTime": 123,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "closeReason": "<string>",
  "creditsUsed": 123,
  "vcpus": 123,
  "memMiB": 123,
  "diskSizeMiB": 123,
  "timeoutMinutes": 123,
  "network": {
    "allowInternetAccess": true,
    "allowOut": [
      "<string>"
    ],
    "denyOut": [
      "<string>"
    ]
  },
  "sessionUrl": "<string>",
  "duration": 123,
  "proxyBytesUsed": 123,
  "token": "<string>",
  "tokenExpiresAt": "2023-11-07T05:31:56Z",
  "gpuType": "<string>",
  "gpuCount": 123,
  "capabilities": {
    "commands": true,
    "files": true,
    "pty": true,
    "gpu": true,
    "snapshots": true,
    "volumes": true,
    "exposedPorts": true,
    "networkFiltering": true,
    "liveNetworkUpdates": true,
    "internetAccess": true,
    "desktop": true,
    "persistentDisks": true,
    "memorySnapshots": true,
    "writableStorage": "disk"
  },
  "startupSecrets": [
    {
      "env": "<string>",
      "source": {
        "type": "vault",
        "name": "<string>"
      },
      "name": "<string>",
      "secretId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "version": 123,
      "secretType": "totp",
      "reference": "<string>",
      "tokenSecret": "<string>",
      "overrides": [
        {
          "type": "vault",
          "name": "<string>"
        }
      ]
    }
  ]
}

For GPU creation, set gpu, use region: "us", and provide a GPU-ready image built by your team. Contact us at info@hyperbrowser.ai to enable GPU access. The API returns 202 with status: "provisioning"; poll the sandbox until it is active before using its runtime. See GPU sandboxes for a complete example.

macOS sandboxes are in beta. Reach out to us at info@hyperbrowser.ai to enable them for your team. See macOS sandboxes for API and CLI examples, desktop sharing, and disk reuse.

Authorizations

x-api-key

string

header

required

Body

application/json

Image launch
Snapshot restore
macOS disk launch (Beta)

Provide exactly one start source: imageName (with optional imageId), snapshotName (CPU sandboxes, with optional snapshotId), or diskId (macOS). GPU sandboxes require GPU access, a GPU-ready team image, and region us. Set gpu to select the GPU runtime automatically. macOS is in beta and requires runtimeClass macos and region us. Contact info@hyperbrowser.ai for GPU or macOS access. Memory snapshots restore their original resources; Mac disk resizing is not supported.

imageName

string

required

Image name to launch from. CPU sandboxes can use a base image such as node or python, or a custom image. GPU sandboxes require a GPU-ready image built by your team; wait for gpuImageReady on its build. For macOS, use macos-base with runtimeClass macos; each image launch creates a new writable disk.

runtimeClass

enum<string>

Runtime selection. Requests without GPU or macOS options create CPU sandboxes (firecracker). Setting gpu selects gvisor-cpu automatically; omit runtimeClass for GPU creation. Set macos explicitly for a Mac sandbox.

Available options:

firecracker,

gvisor-cpu,

macos

gpu

enum<string>

GPU product to allocate. Requires GPU access, region us, and a GPU-ready image built by your team. GPU sandboxes return HTTP 202 with status provisioning. Poll GET /api/sandbox/{id} until active before using the runtime. Availability depends on capacity and requested resources.

Available options:

L4,

A10G,

L40S,

A100-40GB,

A100-80GB,

RTX-PRO-6000,

H100,

H200,

B200,

B300

gpuCount

integer

default:1

Number of whole GPUs of the requested type, on one host. Requires gpu. Supported counts depend on the GPU product and available host sizes.

Required range: 1 <= x <= 8

diskId

string<uuid>

Existing persistent Mac disk to boot. Requires runtimeClass macos. Use instead of imageName or snapshotName. The disk must be ready and detached; each disk can run in only one sandbox at a time.

imageId

string<uuid>

Pin a specific image revision. Requires imageName.

snapshotName

string

CPU sandbox memory snapshot to restore. GPU sandboxes do not support snapshots; macOS uses diskId instead.

snapshotId

string<uuid>

Pin a specific snapshot revision. Requires snapshotName.

region

enum<string>

Region to run the session in. The asia-south region is only available on Enterprise and Select plans. Get in touch at https://calendly.com/shri-hyperbrowser/demo.

Available options:

us,

us-central,

us-west,

us-east,

asia-south,

europe-west

enableRecording

boolean

default:false

Enable recording. For macOS, captures an HLS desktop recording available in the dashboard Recording tab.

exposedPorts

object[]

Ports to expose at launch.

Show child attributes

mounts

object

Volume mounts, keyed by absolute mount path inside a CPU sandbox. GPU and macOS sandboxes do not support shared volume mounts.

Show child attributes

vcpus

integer

vCPU count for image launches or macOS disk launches. macOS requires at least 2 vCPUs; available sizes depend on your plan and host capacity.

Required range: 1 <= x <= 32

memMiB

integer

System memory (RAM) in MiB for image launches or macOS disk launches. For GPU sandboxes this is separate from GPU memory (VRAM), which is determined by gpu. macOS requires at least 4096 MiB, in multiples of 1024 MiB. Plan and host limits apply.

Required range: 512 <= x <= 262144

diskSizeMiB

integer

Disk size in MiB for image launches. GPU sandboxes default to and require at least 12288 MiB (12 GiB), with a maximum of 65536 MiB (64 GiB), subject to plan and host limits. GPU disk is ephemeral and files are deleted when the sandbox stops. For macOS, omit this field to use the source disk size; resizing is not supported.

Required range: 2048 <= x <= 65536

timeoutMinutes

integer

Maximum sandbox lifetime in minutes, measured from when it starts running. For GPU sandboxes, provisioning time is excluded.

Required range: 0 <= x <= 1440

allowInternetAccess

boolean

default:true

Outbound internet access policy.

allowOut

string[]

Outbound allow rules (IPv4 address, CIDR range, or domain). macOS supports IPv4 addresses and CIDRs only.

denyOut

string[]

Outbound deny rules (IPv4 address or CIDR range). macOS supports IPv4 addresses and CIDRs only.

secrets

object

CPU image launches only; GPU and macOS sandboxes do not support secret injection. Secrets to set as environment variables for the image's startup command only, merged over vault's variables; they aren't added to the sandbox's default environment. Supported for image launches of images that have a startup command; otherwise you get 400 SECRET_STARTUP_UNSUPPORTED (to run your own command with secrets, use POST /api/sandbox/{id}/processes). Requires secrets to be enabled for your team; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED), and, for restricted API keys, the secrets.use scope. If the startup command can't be started, the sandbox is stopped and you get the host's error with its own code, such as 422 SECRET_VALUE_INVALID or 501 SECRET_TOTP_UNSUPPORTED, with retryable true for 5xx statuses since a new sandbox may run on another host. You get 502 SECRET_STARTUP_FAILED instead (with causeCode when the host gave one) when the host couldn't be reached, the command may have started, or stopping the sandbox couldn't be confirmed, and 422 SECRET_STARTUP_COMMAND_FAILED with exitCode when the command exits with 126 or 127 right after starting. SECRET_STARTUP_FAILED and SECRET_STARTUP_COMMAND_FAILED include sandboxId when stopping the sandbox couldn't be confirmed, so you can stop it yourself.

Show child attributes

Example:

{
  "OPENAI_API_KEY": { "name": "openai-key" }
}

vault

string

Name of a vault whose variables to set for the image's startup command, before secrets. The same rules as secrets apply, and together with secrets and onePassword they set at most 32 variables.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$

onePassword

object

1Password fields to set as environment variables for the image's startup command, read from 1Password when it starts. The same rules as secrets apply. If 1Password can't provide a value, the sandbox is stopped and you get 422 SECRET_ONEPASSWORD_REFERENCE_FAILED or SECRET_ONEPASSWORD_AUTH_FAILED, 429 SECRET_ONEPASSWORD_RATE_LIMITED, or 502 or 503 SECRET_ONEPASSWORD_FAILED; all but the 422s are retryable.

Show child attributes

Response

Sandbox created

string<uuid>

required

status

enum<string>

required

Current sandbox lifecycle status. GPU sandboxes begin in provisioning with no runtime or token. Poll until active, or stop on a terminal status and inspect closeReason. macOS can report stopping while disk changes are saved.

Available options:

provisioning,

active,

stopping,

closed,

close-error,

error

region

enum<string>

required

Region to run the session in. The asia-south region is only available on Enterprise and Select plans. Get in touch at https://calendly.com/shri-hyperbrowser/demo.

Available options:

us,

us-central,

us-west,

us-east,

asia-south,

europe-west

runtime

object | null

required

Runtime API connection details. Null while a GPU sandbox is provisioning, or if it ended before acquiring a runtime. Wait for status active before using these URLs.

Show child attributes

exposedPorts

object[]

required

Show child attributes

runtimeClass

enum<string>

Runtime selected for this sandbox.

Available options:

firecracker,

gvisor-cpu,

macos

diskId

string<uuid>

Persistent disk ID, present for macOS sandboxes. Reuse it after the disk is ready and detached.

ready

boolean

Present for macOS. True when the sandbox is active and its runtime is ready for commands. If false, fetch the sandbox again and check status before retrying.

teamId

string

startTime

Start timestamp in epoch milliseconds, serialized as a number or numeric string. May be null.

endTime

End timestamp in epoch milliseconds, serialized as a number or numeric string. May be null.

createdAt

string<date-time>

updatedAt

string<date-time>

closeReason

string | null

creditsUsed

number | null

vcpus

integer | null

memMiB

integer | null

diskSizeMiB

integer | null

timeoutMinutes

integer | null

network

object

Effective outbound network policy for a sandbox.

Show child attributes

sessionUrl

string

Dashboard URL for this sandbox.

duration

number

Total runtime in milliseconds (0 while running).

proxyBytesUsed

number

token

string | null

Sandbox runtime session token (24h TTL). Send as Authorization: Bearer for runtime API calls. Null during GPU provisioning and when the sandbox is unavailable.

tokenExpiresAt

string<date-time> | null

gpuType

string | null

Allocated GPU product, present for GPU sandboxes. Corresponds to the gpu creation parameter.

gpuCount

integer | null

Number of allocated GPUs, present for GPU sandboxes.

capabilities

object

Capabilities reported for GPU and macOS sandboxes. Inspect these fields before using runtime-specific features. Fields depend on the runtime.

Show child attributes

startupSecrets

object[]

Each variable the startup command received. Present only when you passed secrets, vault or onePassword.

Show child attributes

⌘I

curl --request POST \
  --url https://api.hyperbrowser.ai/api/sandbox \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "imageName": "node"
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "provisioning",
  "region": "us",
  "runtime": {
    "transport": "regional_proxy",
    "host": "<string>",
    "baseUrl": "<string>"
  },
  "exposedPorts": [
    {
      "port": 32768,
      "auth": true,
      "url": "<string>",
      "browserUrl": "<string>",
      "browserUrlExpiresAt": "2023-11-07T05:31:56Z"
    }
  ],
  "runtimeClass": "firecracker",
  "diskId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "ready": true,
  "teamId": "<string>",
  "startTime": 123,
  "endTime": 123,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "closeReason": "<string>",
  "creditsUsed": 123,
  "vcpus": 123,
  "memMiB": 123,
  "diskSizeMiB": 123,
  "timeoutMinutes": 123,
  "network": {
    "allowInternetAccess": true,
    "allowOut": [
      "<string>"
    ],
    "denyOut": [
      "<string>"
    ]
  },
  "sessionUrl": "<string>",
  "duration": 123,
  "proxyBytesUsed": 123,
  "token": "<string>",
  "tokenExpiresAt": "2023-11-07T05:31:56Z",
  "gpuType": "<string>",
  "gpuCount": 123,
  "capabilities": {
    "commands": true,
    "files": true,
    "pty": true,
    "gpu": true,
    "snapshots": true,
    "volumes": true,
    "exposedPorts": true,
    "networkFiltering": true,
    "liveNetworkUpdates": true,
    "internetAccess": true,
    "desktop": true,
    "persistentDisks": true,
    "memorySnapshots": true,
    "writableStorage": "disk"
  },
  "startupSecrets": [
    {
      "env": "<string>",
      "source": {
        "type": "vault",
        "name": "<string>"
      },
      "name": "<string>",
      "secretId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "version": 123,
      "secretType": "totp",
      "reference": "<string>",
      "tokenSecret": "<string>",
      "overrides": [
        {
          "type": "vault",
          "name": "<string>"
        }
      ]
    }
  ]
}

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "provisioning",
  "region": "us",
  "runtime": {
    "transport": "regional_proxy",
    "host": "<string>",
    "baseUrl": "<string>"
  },
  "exposedPorts": [
    {
      "port": 32768,
      "auth": true,
      "url": "<string>",
      "browserUrl": "<string>",
      "browserUrlExpiresAt": "2023-11-07T05:31:56Z"
    }
  ],
  "runtimeClass": "firecracker",
  "diskId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "ready": true,
  "teamId": "<string>",
  "startTime": 123,
  "endTime": 123,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "closeReason": "<string>",
  "creditsUsed": 123,
  "vcpus": 123,
  "memMiB": 123,
  "diskSizeMiB": 123,
  "timeoutMinutes": 123,
  "network": {
    "allowInternetAccess": true,
    "allowOut": [
      "<string>"
    ],
    "denyOut": [
      "<string>"
    ]
  },
  "sessionUrl": "<string>",
  "duration": 123,
  "proxyBytesUsed": 123,
  "token": "<string>",
  "tokenExpiresAt": "2023-11-07T05:31:56Z",
  "gpuType": "<string>",
  "gpuCount": 123,
  "capabilities": {
    "commands": true,
    "files": true,
    "pty": true,
    "gpu": true,
    "snapshots": true,
    "volumes": true,
    "exposedPorts": true,
    "networkFiltering": true,
    "liveNetworkUpdates": true,
    "internetAccess": true,
    "desktop": true,
    "persistentDisks": true,
    "memorySnapshots": true,
    "writableStorage": "disk"
  },
  "startupSecrets": [
    {
      "env": "<string>",
      "source": {
        "type": "vault",
        "name": "<string>"
      },
      "name": "<string>",
      "secretId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "version": 123,
      "secretType": "totp",
      "reference": "<string>",
      "tokenSecret": "<string>",
      "overrides": [
        {
          "type": "vault",
          "name": "<string>"
        }
      ]
    }
  ]
}

Sessions

WebMCP

Profiles

Secrets

Vaults

Sandboxes

Sandbox Volumes

Sandbox Images

Sandbox Snapshots

Web API

Scrape

Crawl

Extract

Extensions

HyperAgent

BrowserUse

Claude Computer Use

Gemini Computer Use

Meta Computer Use

Grok Computer Use

Jev Computer Use

OpenAI CUA

X402

Authorizations

Body

Response