> ## 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

## Static Methods

### `Sandbox.create(opts?)`

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

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

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

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

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

<ParamField body="envs" type="Record<string, string>">
  Environment variables
</ParamField>

<ParamField body="metadata" type="Record<string, string>">
  Arbitrary metadata
</ParamField>

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

<ParamField body="cpuCount" type="number">
  CPU cores
</ParamField>

<ParamField body="memoryMB" type="number">
  Memory in MB
</ParamField>

<ParamField body="secretStore" type="string">
  Secret store name — resolves encrypted secrets and egress allowlist
</ParamField>

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

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

<ParamField body="onBuildLog" type="(log: string) => void">
  Build log callback (when using `image`)
</ParamField>

**Returns:** `Promise<Sandbox>`

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

Create a Burst Sandbox:

```typescript theme={null}
const 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>

***

### `Sandbox.connect(sandboxId, opts?)`

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

<ParamField body="sandboxId" type="string" required>
  Sandbox ID
</ParamField>

<ParamField body="apiKey" type="string">
  API key
</ParamField>

<ParamField body="apiUrl" type="string">
  API URL
</ParamField>

**Returns:** `Promise<Sandbox>`

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

***

### `Sandbox.createFromCheckpoint(checkpointId, opts?)`

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

<ParamField body="checkpointId" type="string" required>
  Checkpoint ID
</ParamField>

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

**Returns:** `Promise<Sandbox>`

```typescript theme={null}
const forked = await Sandbox.createFromCheckpoint("cp-abc123");
```

***

### `Sandbox.createCheckpointPatch(checkpointId, opts)`

Create a patch for a checkpoint. [HTTP API →](/api-reference/patches/create)

<ParamField body="checkpointId" type="string" required>
  Target checkpoint
</ParamField>

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

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

**Returns:** `Promise<PatchResult>`

```typescript theme={null}
const result = await Sandbox.createCheckpointPatch("cp-abc", { script: "apt install -y curl" });
```

***

### `Sandbox.listCheckpointPatches(checkpointId, opts?)`

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

**Returns:** `Promise<PatchInfo[]>`

***

### `Sandbox.deleteCheckpointPatch(checkpointId, patchId, opts?)`

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

**Returns:** `Promise<void>`

***

## Instance Methods

### `sandbox.kill()`

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

**Returns:** `Promise<void>`

### `sandbox.isRunning()`

Check if the sandbox is running.

**Returns:** `Promise<boolean>`

### `sandbox.hibernate()`

Snapshot VM state and stop. No compute cost while hibernated. [HTTP API →](/api-reference/sandboxes/hibernate)

**Returns:** `Promise<void>`

### `sandbox.wake(opts?)`

Resume a hibernated sandbox. [HTTP API →](/api-reference/sandboxes/wake)

<ParamField body="timeout" type="number" default="0">
  Idle timeout after wake
</ParamField>

**Returns:** `Promise<void>`

### `sandbox.setTimeout(timeout)`

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

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

**Returns:** `Promise<void>`

### `sandbox.createCheckpoint(name)`

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

<ParamField body="name" type="string" required>
  Checkpoint name (unique per sandbox)
</ParamField>

**Returns:** `Promise<CheckpointInfo>`

### `sandbox.listCheckpoints()`

[HTTP API →](/api-reference/checkpoints/list) — **Returns:** `Promise<CheckpointInfo[]>`

### `sandbox.restoreCheckpoint(checkpointId)`

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

**Returns:** `Promise<void>`

### `sandbox.deleteCheckpoint(checkpointId)`

[HTTP API →](/api-reference/checkpoints/delete) — **Returns:** `Promise<void>`

### `sandbox.getPreviewDomain(port)`

Get the preview URL domain for a specific port. No API call — constructs the hostname locally.

<ParamField body="port" type="number" required>
  Port number
</ParamField>

**Returns:** `string` (e.g., `sb-abc123-p3000.workers.opencomputer.dev`)

```typescript theme={null}
const domain = sandbox.getPreviewDomain(3000);
console.log(`https://${domain}`);
```

***

### `sandbox.downloadUrl(path, opts?)`

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

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

<ParamField body="opts.expiresIn" type="number" default="3600">
  URL lifetime in seconds (max: 86400)
</ParamField>

**Returns:** `Promise<string>`

### `sandbox.uploadUrl(path, opts?)`

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

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

<ParamField body="opts.expiresIn" type="number" default="3600">
  URL lifetime in seconds (max: 86400)
</ParamField>

**Returns:** `Promise<string>`

### `sandbox.createPreviewURL(opts)`

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

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

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

<ParamField body="authConfig" type="Record<string, unknown>">
  Auth configuration
</ParamField>

**Returns:** `Promise<PreviewURLResult>`

### `sandbox.listPreviewURLs()`

[HTTP API →](/api-reference/preview/list) — **Returns:** `Promise<PreviewURLResult[]>`

### `sandbox.deletePreviewURL(port)`

[HTTP API →](/api-reference/preview/delete) — **Returns:** `Promise<void>`

***

### `sandbox.getAllowedHosts()`

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 `secretStore` option return an empty allowlist with `secretStore` undefined — the sandbox has no per-store egress restriction.

**Returns:** `Promise<AllowedHostsInfo>`

```typescript theme={null}
const info = await sandbox.getAllowedHosts();
console.log(info.egressAllowlist);          // ['api.openai.com', 'api.anthropic.com']
console.log(info.perSecretAllowedHosts);    // { 'OPENAI_API_KEY': ['api.openai.com'] }
```

The returned `AllowedHostsInfo`:

<ParamField body="sandboxID" type="string">
  Sandbox ID
</ParamField>

<ParamField body="secretStore" type="string">
  Name of the primary secret store the sandbox is bound to (the "winning" store on the row, whose secrets shadow the base store on env-name collisions). Empty when the sandbox was created without a `secretStore` option.
</ParamField>

<ParamField body="baseSecretStore" type="string">
  Name of the inherited parent store, present only when a fork layered an additional `secretStore` on top of an inherited one. Empty for sandboxes created from scratch and for forks without an override.
</ParamField>

<ParamField body="egressAllowlist" type="string[]">
  Hosts the sandbox can reach via the secrets proxy. For layered forks this is the **union** of every layered store's allowlist (base first, primary's additions appended, deduped) — matches what the runtime proxy actually enforces.
</ParamField>

<ParamField body="perSecretAllowedHosts" type="Record<string, string[]>">
  Optional per-secret restrictions. When the sandbox uses a listed secret in a request, only the listed hosts are reachable for that request. For layered forks, the primary store's secrets shadow the base on name collisions (matches runtime env-collision behavior).
</ParamField>

***

## Properties

<ParamField body="sandboxId" type="string">
  Sandbox ID (readonly)
</ParamField>

<ParamField body="status" type="string">
  Current status (readonly)
</ParamField>

<ParamField body="domain" type="string">
  Preview URL domain for port 80 (e.g., `sb-abc123-p80.workers.opencomputer.dev`). Returns empty string if sandbox domain is not configured.
</ParamField>

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

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

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

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

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

***

## Types

<Accordion title="SandboxOpts">
  ```typescript theme={null}
  interface SandboxOpts {
    template?: string;
    timeout?: number;
    apiKey?: string;
    apiUrl?: string;
    envs?: Record<string, string>;
    metadata?: Record<string, string>;
    cpuCount?: number;
    memoryMB?: number;
    secretStore?: string;
    image?: Image;
    snapshot?: string;
    onBuildLog?: (log: string) => void;
  }
  ```
</Accordion>

<Accordion title="CheckpointInfo">
  ```typescript theme={null}
  interface CheckpointInfo {
    id: string;
    sandboxId: string;
    orgId: string;
    name: string;
    sandboxConfig: object;
    status: string;       // "processing" | "ready" | "failed"
    sizeBytes: number;
    createdAt: string;
  }
  ```
</Accordion>

<Accordion title="PatchInfo / PatchResult">
  ```typescript theme={null}
  interface PatchInfo {
    id: string;
    checkpointId: string;
    sequence: number;
    script: string;
    description: string;
    strategy: string;     // "on_wake"
    createdAt: string;
  }

  interface PatchResult {
    patch: PatchInfo;
  }
  ```
</Accordion>

<Accordion title="PreviewURLResult">
  ```typescript theme={null}
  interface PreviewURLResult {
    id: string;
    sandboxId: string;
    orgId: string;
    hostname: string;
    customHostname?: string;
    port: number;
    cfHostnameId?: string;
    sslStatus: string;
    authConfig?: object;
    createdAt: string;
  }
  ```
</Accordion>