> ## Documentation Index
> Fetch the complete documentation index at: https://opensandbox-oc-s-762ac928075c46d2828bcb22.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox

> Create, connect, and manage sandbox lifecycle

## Class Methods

### `await Sandbox.create(...)`

Create a new sandbox. [HTTP API →](/api-reference/sandboxes/create)

<ParamField body="template" type="str" default="base">
  Template name
</ParamField>

<ParamField body="timeout" type="int" default="0">
  Idle timeout in seconds. `0` (the default) means persistent — the sandbox never auto-hibernates.
</ParamField>

<ParamField body="api_key" type="str">
  API key (falls back to `OPENCOMPUTER_API_KEY` env var)
</ParamField>

<ParamField body="api_url" type="str">
  API URL (falls back to `OPENCOMPUTER_API_URL` env var)
</ParamField>

<ParamField body="envs" type="dict[str, str]">
  Environment variables
</ParamField>

<ParamField body="metadata" type="dict[str, str]">
  Arbitrary metadata
</ParamField>

<ParamField body="burst" type="bool">
  Create a [Burst Sandbox](/sandboxes/burst-sandboxes). Disk is preserved across infrastructure restarts; processes may restart.
</ParamField>

<ParamField body="image" type="Image">
  Declarative image definition (see [Image](/reference/python-sdk/image))
</ParamField>

<ParamField body="snapshot" type="str">
  Name of a pre-built snapshot
</ParamField>

<ParamField body="on_build_log" type="Callable[[str], None]">
  Build log callback (when using `image`)
</ParamField>

**Returns:** `Sandbox`

```python theme={null}
sandbox = await Sandbox.create(template="my-stack", timeout=600)
```

Create a Burst Sandbox:

```python theme={null}
sandbox = await Sandbox.create(
    burst=True,
    timeout=300,
)
```

<Note>
  Burst Sandboxes are alpha. They preserve filesystem state across
  infrastructure restarts, may restart running processes, and are priced roughly
  2x cheaper than on-demand sandboxes.
</Note>

***

### `await Sandbox.connect(sandbox_id, ...)`

Connect to an existing sandbox. [HTTP API →](/api-reference/sandboxes/get)

<ParamField body="sandbox_id" type="str" required>
  Sandbox ID
</ParamField>

**Returns:** `Sandbox`

```python theme={null}
sandbox = await Sandbox.connect("sb-abc123")
```

***

### `await Sandbox.create_from_checkpoint(checkpoint_id, ...)`

Create a new sandbox from a checkpoint. [HTTP API →](/api-reference/checkpoints/fork)

<ParamField body="checkpoint_id" type="str" required>
  Checkpoint ID
</ParamField>

<ParamField body="timeout" type="int" default="0">
  Idle timeout
</ParamField>

**Returns:** `Sandbox`

```python theme={null}
forked = await Sandbox.create_from_checkpoint("cp-abc123")
```

***

### `await Sandbox.create_checkpoint_patch(checkpoint_id, script, ...)`

[HTTP API →](/api-reference/patches/create)

<ParamField body="checkpoint_id" type="str" required>
  Target checkpoint
</ParamField>

<ParamField body="script" type="str" required>
  Bash script
</ParamField>

<ParamField body="description" type="str">
  Description
</ParamField>

**Returns:** `dict`

***

### `await Sandbox.list_checkpoint_patches(checkpoint_id, ...)`

[HTTP API →](/api-reference/patches/list) — **Returns:** `list[dict]`

### `await Sandbox.delete_checkpoint_patch(checkpoint_id, patch_id, ...)`

[HTTP API →](/api-reference/patches/delete) — **Returns:** `None`

***

## Context Manager

Auto-kills the sandbox on exit:

```python theme={null}
async with await Sandbox.create() as sandbox:
    result = await sandbox.exec.run("echo hello")
    print(result.stdout)
# sandbox.kill() called automatically
```

***

## Instance Methods

### `await sandbox.kill()`

Terminate the sandbox. [HTTP API →](/api-reference/sandboxes/delete)

**Returns:** `None`

### `await sandbox.is_running()`

Check if the sandbox is running.

**Returns:** `bool`

### `await sandbox.set_timeout(timeout)`

Update idle timeout. [HTTP API →](/api-reference/sandboxes/set-timeout)

<ParamField body="timeout" type="int" required>
  New timeout in seconds
</ParamField>

**Returns:** `None`

### `await sandbox.create_checkpoint(name)`

Create a named checkpoint. [HTTP API →](/api-reference/checkpoints/create)

**Returns:** `dict`

### `await sandbox.list_checkpoints()`

[HTTP API →](/api-reference/checkpoints/list) — **Returns:** `list[dict]`

### `await sandbox.restore_checkpoint(checkpoint_id)`

Revert in-place to a checkpoint. [HTTP API →](/api-reference/checkpoints/restore)

**Returns:** `None`

### `await sandbox.delete_checkpoint(checkpoint_id)`

[HTTP API →](/api-reference/checkpoints/delete) — **Returns:** `None`

### `await sandbox.download_url(path, *, expires_in=3600)`

Generate a signed download URL. [HTTP API →](/api-reference/files/generate-download-url) · [Guide →](/sandboxes/signed-urls)

<ParamField body="path" type="str" required>
  Absolute path to the file
</ParamField>

<ParamField body="expires_in" type="int" default="3600">
  URL lifetime in seconds (max: 86400)
</ParamField>

**Returns:** `str`

### `await sandbox.upload_url(path, *, expires_in=3600)`

Generate a signed upload URL. [HTTP API →](/api-reference/files/generate-upload-url) · [Guide →](/sandboxes/signed-urls)

<ParamField body="path" type="str" required>
  Absolute path for the destination file
</ParamField>

<ParamField body="expires_in" type="int" default="3600">
  URL lifetime in seconds (max: 86400)
</ParamField>

**Returns:** `str`

### `await sandbox.create_preview_url(port, domain?, auth_config?)`

[HTTP API →](/api-reference/preview/create)

<ParamField body="port" type="int" required>
  Container port (1–65535)
</ParamField>

<ParamField body="domain" type="str">
  Custom domain
</ParamField>

<ParamField body="auth_config" type="dict">
  Auth configuration
</ParamField>

**Returns:** `dict`

### `await sandbox.list_preview_urls()`

[HTTP API →](/api-reference/preview/list) — **Returns:** `list[dict]`

### `await sandbox.delete_preview_url(port)`

[HTTP API →](/api-reference/preview/delete) — **Returns:** `None`

### `await sandbox.get_allowed_hosts()`

Return the egress allowlist + per-secret allowed hosts the sandbox's secrets proxy enforces. Useful for debugging "why is my outbound HTTP call being blocked" without having to cross-reference the [secret store](/sandboxes/secrets) config separately.

Sandboxes created without a `secret_store` option return an empty allowlist with `secretStore` omitted — the sandbox has no per-store egress restriction.

**Returns:** `dict` with the shape:

```python theme={null}
{
    "sandboxID": "sb-...",
    "secretStore": "my-store",                   # omitted if no store
    "baseSecretStore": "parent-store",           # omitted unless this is a layered fork
    "egressAllowlist": ["api.openai.com", ...],
    "perSecretAllowedHosts": {
        "OPENAI_API_KEY": ["api.openai.com"],
    },
}
```

For forks that layered an additional `secret_store` on top of an inherited one, `egressAllowlist` is the **union** of both stores' allowlists (matches what the runtime proxy enforces) and `baseSecretStore` is populated with the inherited parent's name. For sandboxes with a single store (or none), `baseSecretStore` is omitted.

```python theme={null}
info = await sandbox.get_allowed_hosts()
print(info["egressAllowlist"])          # ['api.openai.com', 'api.anthropic.com']
print(info["perSecretAllowedHosts"])    # {'OPENAI_API_KEY': ['api.openai.com']}
```

### `await sandbox.close()`

Close HTTP clients. Called automatically by the context manager.

***

## Not Available in Python

These features are TypeScript-only. Use the [HTTP API](/api-reference/overview) directly:

* `hibernate()` / `wake()`
* `cpuCount` / `memoryMB` on create

***

## Properties

<ParamField body="sandbox_id" type="str">
  Sandbox ID
</ParamField>

<ParamField body="status" type="str">
  Current status
</ParamField>

<ParamField body="agent" type="Agent">
  [Agent sessions](/reference/python-sdk/agent)
</ParamField>

<ParamField body="exec" type="Exec">
  [Command execution](/reference/python-sdk/exec)
</ParamField>

<ParamField body="files" type="Filesystem">
  [File operations](/reference/python-sdk/filesystem)
</ParamField>

<ParamField body="pty" type="Pty">
  [Terminal sessions](/reference/python-sdk/pty)
</ParamField>

<ParamField body="commands" type="Exec">
  **Deprecated** — alias for `exec`
</ParamField>