Sandbox Lifecycle

Sandboxes launch with the configuration you need and run until you stop them or they time out. By default, this is based on your team’s default Session Timeout setting which you can change on the Settings page. You can also configure the timeout per sandbox during creation. timeoutMinutes is the sandbox’s total lifetime beginning when its VM starts, not a timeout applied separately to each SDK operation. For GPU sandboxes, the lifetime begins when provisioning finishes and the sandbox starts running.

Wait for a GPU sandbox

GPU creation returns 202 Accepted with status: "provisioning". At this point, runtime and token are null. Poll GET /api/sandbox/{id} until status is active before running commands. Stop polling if the sandbox enters a terminal state and inspect closeReason.

Status	Meaning
`provisioning`	GPU resources and the image are being prepared. Runtime calls are not available yet.
`active`	The GPU sandbox is running and runtime credentials are available.
`stopping`	The sandbox is shutting down.
`closed`, `error`, `close-error`	The sandbox has ended or failed. Inspect `closeReason` for details.

The CLI’s --wait-for-provisioning flag waits for an active GPU sandbox. Ending that wait does not stop the sandbox. To cancel, call the normal stop endpoint or use hx vm stop with its ID, even while it is still provisioning. Provisioning time is not billed. Once active, allocated GPU, CPU, and memory resources are billed until the sandbox ends, including time spent idle. See GPU pricing. GPU sandboxes can be interrupted and do not resume running processes after an interruption. Their disk is ephemeral: save checkpoints and results to external storage while the sandbox is running. See GPU limits.

Set a lifetime

macOS sandboxes (Beta) save disk changes asynchronously when stopped. Wait for the disk to become ready and detached before starting a new sandbox with its diskId. Running processes and memory are not preserved.

For example, set a custom session timeout when creating the sandbox:

const sandbox = await client.sandboxes.create({
  imageName: "node",
  timeoutMinutes: 30,
});

sandbox = client.sandboxes.create(
    {
        "image_name": "python",
        "timeout_minutes": 30,
    }
)

from hyperbrowser.models import CreateSandboxParams

sandbox = client.sandboxes.create(
    CreateSandboxParams(
        image_name="python",
        timeout_minutes=30,
    )
)

curl -X POST https://api.hyperbrowser.ai/api/sandbox \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "imageName": "node",
    "timeoutMinutes": 30
  }'

Getting a Sandbox

Fetch a detailed sandbox handle by ID:

const sandbox = await client.sandboxes.get(
  "550e8400-e29b-41d4-a716-446655440000",
);
const detail = sandbox.toJSON();

// Selected fields from detail:
// {
//   "id": "550e8400-e29b-41d4-a716-446655440000",
//   "teamId": "team-id",
//   "status": "active",
//   "endTime": null,
//   "startTime": 1775822400000,
//   "createdAt": "2026-04-10T12:00:00.000Z",
//   "updatedAt": "2026-04-10T12:00:00.000Z",
//   "region": "us-west",
//   "sessionUrl": "https://app.hyperbrowser.ai/sandboxes/550e8400-e29b-41d4-a716-446655440000",
//   "duration": 0,
//   "proxyBytesUsed": 0,
//   "cpu": 2,
//   "memoryMiB": 2048,
//   "diskMiB": 8192,
//   "timeoutMinutes": 30,
//   "runtime": {
//     "transport": "regional_proxy",
//     "host": "https://<regional-runtime-host>",
//     "baseUrl": "https://<regional-runtime-host>/sandbox/<sandbox-id>"
//   },
//   "exposedPorts": [
//     {
//       "port": 3000,
//       "auth": true,
//       "url": "https://<exposed-port-host>/",
//       "browserUrl": "https://<exposed-port-host>/_hb/auth?grant=<exposed-port-token>&next=%2F",
//       "browserUrlExpiresAt": "2026-04-11T12:00:00.000Z"
//     }
//   ],
//   "token": "sandbox-runtime-token",
//   "tokenExpiresAt": "2026-04-11T12:00:00.000Z"
// }

sandbox = client.sandboxes.get("550e8400-e29b-41d4-a716-446655440000")
detail = sandbox.to_dict()

# Selected fields from detail:
# {
#   "id": "550e8400-e29b-41d4-a716-446655440000",
#   "team_id": "team-id",
#   "status": "active",
#   "end_time": None,
#   "start_time": 1775822400000,
#   "created_at": "<datetime>",
#   "updated_at": "<datetime>",
#   "region": "us-west",
#   "session_url": "https://app.hyperbrowser.ai/sandboxes/550e8400-e29b-41d4-a716-446655440000",
#   "duration": 0,
#   "proxy_bytes_used": 0,
#   "cpu": 2,
#   "memory_mib": 2048,
#   "disk_mib": 8192,
#   "timeout_minutes": 30,
#   "runtime": {
#     "transport": "regional_proxy",
#     "host": "https://<regional-runtime-host>",
#     "base_url": "https://<regional-runtime-host>/sandbox/<sandbox-id>"
#   },
#   "exposed_ports": [
#     {
#       "port": 3000,
#       "auth": True,
#       "url": "https://<exposed-port-host>/",
#       "browser_url": "https://<exposed-port-host>/_hb/auth?grant=<exposed-port-token>&next=%2F",
#       "browser_url_expires_at": "<datetime>"
#     }
#   ],
#   "token": "sandbox-runtime-token",
#   "token_expires_at": "<datetime>"
# }

curl -X GET https://api.hyperbrowser.ai/api/sandbox/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: YOUR_API_KEY"

# Abbreviated REST response:
# {
#   "id": "550e8400-e29b-41d4-a716-446655440000",
#   "teamId": "team-id",
#   "status": "active",
#   "endTime": null,
#   "startTime": 1775822400000,
#   "createdAt": "2026-04-10T12:00:00.000Z",
#   "updatedAt": "2026-04-10T12:00:00.000Z",
#   "region": "us-west",
#   "sessionUrl": "https://app.hyperbrowser.ai/sandboxes/550e8400-e29b-41d4-a716-446655440000",
#   "duration": 0,
#   "proxyBytesUsed": 0,
#   "vcpus": 2,
#   "memMiB": 2048,
#   "diskSizeMiB": 8192,
#   "timeoutMinutes": 30,
#   "runtime": {
#     "transport": "regional_proxy",
#     "host": "https://<regional-runtime-host>",
#     "baseUrl": "https://<regional-runtime-host>/sandbox/<sandbox-id>"
#   },
#   "exposedPorts": [
#     {
#       "port": 3000,
#       "auth": true,
#       "url": "https://<exposed-port-host>/",
#       "browserUrl": "https://<exposed-port-host>/_hb/auth?grant=<exposed-port-token>&next=%2F",
#       "browserUrlExpiresAt": "2026-04-11T12:00:00.000Z"
#     }
#   ],
#   "token": "sandbox-runtime-token",
#   "tokenExpiresAt": "2026-04-11T12:00:00.000Z"
# }

The REST API returns VM sizing fields as vcpus, memMiB, and diskSizeMiB. The Node SDK exposes the same values as cpu, memoryMiB, and diskMiB; the Python SDK exposes them as cpu, memory_mib, and disk_mib. duration is the elapsed runtime in milliseconds after a sandbox ends, so it is 0 while the sandbox is active. timeoutMinutes is the configured total lifetime.

Listing Sandboxes

List your sandboxes with optional filtering:

const response = await client.sandboxes.list({
  status: "active",
  page: 1,
  limit: 20,
});

// Selected response fields:
// {
//   "totalCount": 1,
//   "page": 1,
//   "perPage": 20,
//   "sandboxes": [
//     {
//       "id": "sandbox-id",
//       "status": "active",
//       "region": "us-west"
//     }
//   ]
// }

response = client.sandboxes.list(
    {
        "status": "active",
        "page": 1,
        "limit": 20,
    }
)

# Selected fields from response.model_dump():
# {
#   "total_count": 1,
#   "page": 1,
#   "per_page": 20,
#   "sandboxes": [
#     {
#       "id": "sandbox-id",
#       "status": "active",
#       "region": "us-west"
#     }
#   ]
# }

from hyperbrowser.models import SandboxListParams

response = client.sandboxes.list(
    SandboxListParams(
        status="active",
        page=1,
        limit=20,
    )
)

# Selected fields from response.model_dump():
# {
#   "total_count": 1,
#   "page": 1,
#   "per_page": 20,
#   "sandboxes": [
#     {
#       "id": "sandbox-id",
#       "status": "active",
#       "region": "us-west"
#     }
#   ]
# }

curl -X GET "https://api.hyperbrowser.ai/api/sandboxes?status=active&page=1&limit=20" \
  -H "x-api-key: YOUR_API_KEY"

# Abbreviated REST response:
# {
#   "totalCount": 1,
#   "page": 1,
#   "perPage": 20,
#   "sandboxes": [
#     {
#       "id": "550e8400-e29b-41d4-a716-446655440000",
#       "status": "active",
#       "region": "us-west"
#     }
#   ]
# }

Refreshing and Connecting

Connect to an existing sandbox or refresh the runtime token.

Create and get responses for an active sandbox include a runtime token that is valid for 24 hours. The Node and Python SDKs automatically obtain a fresh token shortly before expiry and retry a replayable runtime HTTP request once with a fresh token after a 401. Call refresh() when you also want to refresh the handle’s cached sandbox metadata. For a more detailed guide to runtime tokens, see Sandbox Runtime URLs.

// Refresh an existing handle
await sandbox.refresh();

// Reconnect from an ID
const reattached = await client.sandboxes.connect(
  "550e8400-e29b-41d4-a716-446655440000",
);

// Selected fields from reattached.toJSON():
// {
//   "id": "550e8400-e29b-41d4-a716-446655440000",
//   "runtime": {
//     "baseUrl": "https://<regional-runtime-host>/sandbox/<sandbox-id>"
//   },
//   "tokenExpiresAt": "<24 hours after the reconnect request>"
// }

# Refresh an existing handle
sandbox.refresh()

# Reconnect from an ID
reattached = client.sandboxes.connect(
    "550e8400-e29b-41d4-a716-446655440000"
)

# Selected fields from reattached.to_dict():
# {
#   "id": "550e8400-e29b-41d4-a716-446655440000",
#   "runtime": {
#     "base_url": "https://<regional-runtime-host>/sandbox/<sandbox-id>"
#   },
#   "token_expires_at": "<datetime about 24 hours after reconnect>"
# }

Stopping a Sandbox

Always stop a sandbox when you are done with it:

const response = await sandbox.stop();

// {
//   "success": true
// }

response = sandbox.stop()

# response.model_dump()
# {
#   "success": True
# }

curl -X PUT https://api.hyperbrowser.ai/api/sandbox/SANDBOX_ID/stop \
  -H "x-api-key: YOUR_API_KEY"

# {
#   "success": true
# }

Stopping a sandbox is safe to call more than once.

Exposing Ports

Expose a port when you need a custom process to be accessible from outside from the sandbox. This provides a custom runtime URL for that exposed port.

const exposure = await sandbox.expose({
  port: 3000,
  auth: true,
});

// {
//   "port": 3000,
//   "auth": true,
//   "url": "https://<exposed-port-host>/",
//   "browserUrl": "https://<exposed-port-host>/_hb/auth?grant=<exposed-port-token>&next=%2F",
//   "browserUrlExpiresAt": "2026-04-11T12:00:00Z"
// }

// Helper for deriving the URL for an exposed port:
// sandbox.getExposedUrl(3000)

exposure = sandbox.expose(
    {
        "port": 3000,
        "auth": True,
    }
)

# exposure.model_dump(mode="json")
# {
#   "port": 3000,
#   "auth": True,
#   "url": "https://<exposed-port-host>/",
#   "browser_url": "https://<exposed-port-host>/_hb/auth?grant=<exposed-port-token>&next=%2F",
#   "browser_url_expires_at": "2026-04-11T12:00:00Z"
# }

# Helper for deriving the URL for an exposed port:
# sandbox.get_exposed_url(3000)

from hyperbrowser.models import SandboxExposeParams

exposure = sandbox.expose(
    SandboxExposeParams(
        port=3000,
        auth=True,
    )
)

# exposure.model_dump(mode="json")
# {
#   "port": 3000,
#   "auth": True,
#   "url": "https://<exposed-port-host>/",
#   "browser_url": "https://<exposed-port-host>/_hb/auth?grant=<exposed-port-token>&next=%2F",
#   "browser_url_expires_at": "2026-04-11T12:00:00Z"
# }

# Helper for deriving the URL for an exposed port:
# sandbox.get_exposed_url(3000)

curl -X POST https://api.hyperbrowser.ai/api/sandbox/SANDBOX_ID/expose \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "port": 3000,
    "auth": true
  }'

# {
#   "port": 3000,
#   "auth": true,
#   "url": "https://<exposed-port-host>/",
#   "browserUrl": "https://<exposed-port-host>/_hb/auth?grant=<exposed-port-token>&next=%2F",
#   "browserUrlExpiresAt": "2026-04-11T12:00:00Z"
# }

If auth is enabled, send the sandbox bearer token when calling the exposed URL:

const detail = await sandbox.info();
const healthUrl = new URL("health", exposure.url);
const response = await fetch(healthUrl, {
  headers: {
    Authorization: `Bearer ${detail.token}`,
  },
});

const body = await response.text();

console.log(response.status); // 200
console.log(body); // <service response>

import requests

detail = sandbox.info()
response = requests.get(
    f"{exposure.url.rstrip('/')}/health",
    headers={"Authorization": f"Bearer {detail.token}"},
    timeout=30,
)
response.raise_for_status()
body = response.text

print(response.status_code)  # 200
print(body)  # <service response>

curl "${EXPOSED_URL%/}/health" \
  -H "Authorization: Bearer $SANDBOX_TOKEN"

For a dedicated guide to runtime URLs, exposed service URLs, browser auth links, and end-to-end examples, see Sandbox Runtime URLs.

Port 4001 is reserved for the sandbox runtime API url and cannot be exposed.

Get Started

Sandbox

Base Images

Custom Images

Volumes

Local Filesystem

Wait for a GPU sandbox

Set a lifetime

Getting a Sandbox

Listing Sandboxes

Refreshing and Connecting

Stopping a Sandbox

Exposing Ports

​Wait for a GPU sandbox

​Set a lifetime

​Getting a Sandbox

​Listing Sandboxes

​Refreshing and Connecting

​Stopping a Sandbox

​Exposing Ports

Wait for a GPU sandbox

Set a lifetime

Getting a Sandbox

Listing Sandboxes

Refreshing and Connecting

Stopping a Sandbox

Exposing Ports