Skip to main content
POST
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

Provide exactly one start source: imageName (with optional imageId), snapshotName (Linux, with optional snapshotId), or diskId (macOS). macOS is in beta; contact info@hyperbrowser.ai to enable it for your team. Set runtimeClass to macos and use region us for Mac launches. CPU and memory can be set for image launches and macOS disk launches; memory snapshots restore their original resources. Mac disk resizing is not supported.

​
imageName
string
required

Image name to launch from (base image such as node, python, default, or a custom image). For macOS beta, use macos-base with runtimeClass macos; each image launch creates a new writable disk.

​
runtimeClass
enum<string>

Sandbox runtime. Ordinary requests default to firecracker (Linux); GPU requests select gvisor-cpu. Set macos explicitly for a Mac sandbox. macOS is in beta; contact info@hyperbrowser.ai to enable it for your team.

Available options:
firecracker,
gvisor-cpu,
macos
​
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

Linux memory snapshot name to restore from. 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.

​
mounts
object

Volume mounts, keyed by absolute mount path inside the sandbox. Shared volume mounts are not supported by macOS.

​
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

Memory in MiB for image launches or macOS disk launches. macOS requires at least 4096 MiB, in multiples of 1024 MiB.

Required range: 512 <= x <= 262144
​
diskSizeMiB
integer

Disk size in MiB (image launches only). For macOS, omit this field to use the source disk size; resizing is not supported.

Required range: 2048 <= x <= 32768
​
timeoutMinutes
integer

Maximum sandbox lifetime in minutes, measured from VM start.

Required range: 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

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.

Example:
​
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.

Response

200 - application/json

Sandbox created

​
id
string<uuid>
required
​
status
enum<string>
required

Current sandbox lifecycle status. macOS can report stopping while disk changes are being saved and the VM is being released.

Available options:
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
required

Connection details for the sandbox runtime API (process execution, files, terminals).

​
exposedPorts
object[]
required
​
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
number | null

Start timestamp in epoch milliseconds.

​
endTime
number | null

End timestamp in epoch milliseconds.

​
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.

​
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). Null when the sandbox is unavailable.

​
tokenExpiresAt
string<date-time> | null
​
startupSecrets
object[]

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