> For the complete documentation index, see [llms.txt](https://docs.computesdk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.computesdk.com/providers/sandbox0.md).

# Sandbox0

Sandbox0 provides fast persistent cloud sandboxes with shell command execution and native filesystem operations.

## Installation & Setup

```bash
npm install computesdk @computesdk/sandbox0
```

Set a Sandbox0 team API key:

```bash
export SANDBOX0_TOKEN=your_sandbox0_token
```

`SANDBOX0_BASE_URL` is optional and defaults to `https://api.sandbox0.ai`. For automated team workloads, set it to the team's home-region endpoint so requests go directly to the regional gateway.

An interactive access token can also be used by setting both `SANDBOX0_TOKEN` and `SANDBOX0_TEAM_ID`.

## Usage

```typescript
import { compute } from 'computesdk';
import { sandbox0 } from '@computesdk/sandbox0';

compute.setConfig({
  provider: sandbox0({
    token: process.env.SANDBOX0_TOKEN,
    hardTtl: 600,
  }),
});

const sandbox = await compute.sandbox.create({
  templateId: 'coding-agent',
  memory: 256,
});

const result = await sandbox.runCommand('node --version');
console.log(result.stdout);

await sandbox.filesystem.writeFile('/tmp/result.txt', result.stdout);
console.log(await sandbox.filesystem.readFile('/tmp/result.txt'));

await sandbox.destroy();
```

## Configuration Options

```typescript
interface Sandbox0Config {
  token?: string;
  teamId?: string;
  baseUrl?: string;
  templateId?: string;
  ttl?: number;
  hardTtl?: number;
  memory?: number | string;
  envs?: Record<string, string>;
  commandTimeout?: number;
}
```

Numeric memory values are interpreted as MiB. `ttl` and `hardTtl` use seconds; `commandTimeout` uses milliseconds. When `templateId` is omitted, the provider uses `SANDBOX0_TEMPLATE` and then falls back to `coding-agent`.

Per-create `templateId`, `snapshotId`, `memory`, `envs`, `ttl`, `hardTtl`, and `autoResume` options override provider defaults where applicable.

## Supported Operations

| Method       | Supported | Notes                                                                                                                                                          |
| ------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create`     | ✅         | Claims a Sandbox0 sandbox from a template; supports snapshot restore and memory overrides.                                                                     |
| `getById`    | ✅         | Returns `null` for a missing sandbox.                                                                                                                          |
| `list`       | ✅         | Paginates through sandboxes visible to the team token.                                                                                                         |
| `destroy`    | ✅         | Idempotent, with bounded retry for throttling and server failures.                                                                                             |
| `runCommand` | ✅         | Uses `sh -lc`; foreground calls follow an asynchronous Context through WebSocket with API polling fallback. Supports `cwd`, env, timeout, and background mode. |
| `getInfo`    | ✅         | Uses lifecycle metadata already returned by Sandbox0 without adding a post-create request.                                                                     |
| `getUrl`     | ✅         | Returns the URL of an existing public Sandbox0 service for the requested port.                                                                                 |
| `filesystem` | ✅         | Native read, write, mkdir, list, stat, and delete operations.                                                                                                  |

For automated workloads, set `hardTtl` as a safety net in addition to calling `destroy`.

Foreground commands use the requested timeout as both a local deadline and the Sandbox0 Context TTL. If the WebSocket disconnects before a terminal event, the provider continues through the Context API. A timeout also triggers a best-effort Context deletion.

Use `sandbox.getInstance()` for Sandbox0-specific pause/resume, services, snapshots, volumes, and observability APIs.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.computesdk.com/providers/sandbox0.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.