> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bead.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox TypeScript SDK

> Find async methods in the sandbox TypeScript SDK for machines, commands, files, snapshots, fleets, and swarms.

Import the sandbox TypeScript SDK package `@beadrun/sdk` for async machine, command, file and account objects. Start with the [quickstart](https://docs.bead.run/sdks/typescript/quickstart.md).

## Machines and options

| Method or property | Purpose |
| - | - |
| `Sandbox.create(options, client)` | Create a machine. |
| `Sandbox.connect(id, client)` | Connect to an existing machine. |
| `Sandbox.fromGolden(golden, options, client)` | Create from a ready snapshot or template ID. |
| `sb.id`, `sb.sandboxId`, `sb.info` | Identity and machine metadata. |
| `sb.pause()`, `sb.resume(timeout)` | Pause or resume. |
| `sb.kill()` | Delete the machine. |
| `sb.cost()` | Read observed cost. |
| `sb.snapshot(options)` | Capture a ready `Golden`. |
| `sb.fork(n, timeout)` | Create independent memory copies. |

Create options include `template` (default `base`), `size`, `timeout` (default 300), `env`, `region`, `credentialProfile`, `kind`, `idle_timeout`, `autoPause` and `idempotencyKey`. Size accepts a name or `{ vcpus, memoryMiB }`. Memory restores require the source shape.

Client options include `apiKey`, `apiUrl`, `sandboxUrl`, `requestTimeout`, `operationTimeout`, `retries`, `retryDelay`, `pollInterval` and `fetch`. Timeouts use seconds; polling defaults to one second. Region validates the deployment catalog; choose deployment through the API origin.

## Commands

```typescript theme={null}
import { Sandbox } from '@beadrun/sdk';

const sb = await Sandbox.create({ size: 'small' });
try {
  const result = await sb.run('pwd', { cwd: '/tmp', timeout: 30 });
  console.log(result.exitCode, result.stdout, result.stderr);
  for await (const event of sb.run('echo stream', { stream: true })) {
    if (event.type === 'stdout' || event.type === 'stderr') console.log(event.data);
    if (event.type === 'exit') console.log(event.exitCode);
  }
} finally {
  await sb.kill();
}
```

`sb.commands.run` is also available. Options include `cwd`, `env`, `timeout`, `onStdout` and `onStderr`. A nonzero exit is a result. Breaking a stream cancels reading, not necessarily remote execution.

## Files and ports

| Method | Result |
| - | - |
| `sb.files.read(path)` | UTF-8 text. |
| `sb.files.write(path, textOrBytes)` | Write a string or `Uint8Array`. |
| `sb.files.list(path)` | Directory entries. |
| `sb.files.upload(path, bytes)` | Upload `Uint8Array` bytes. |
| `sb.files.download(path)` | Download a `Uint8Array`. |
| `sb.ports.url(port)` | Application URL. |

Local filesystem access stays with your application. Port URLs use the server domain and may require `sb.info.trafficAccessToken` in `e2b-traffic-access-token`; the URL alone grants no access. Reserved ports are rejected.

## Snapshots and parallel work

`sb.snapshot({ name, retentionSeconds, inheritCredentials })` returns a `Golden` with `id`, `info`, `wait()` and `delete()`. Retained storage has its own lifetime.

```typescript theme={null}
import { Fleet, Swarm } from '@beadrun/sdk';

await using fleet = await Fleet.create(2, { size: 'small' });
console.log(await Promise.all([...fleet].map(sb => sb.run('echo fleet'))));

const swarm = await Swarm.run({ cmd: 'echo swarm', inputs: [1, 2], size: 'small' });
for await (const result of swarm) console.log(result);
```

`Fleet.kill()` deletes members. `swarm.status()` inspects the job and `swarm.cancel()` cancels it. A wait timeout keeps the job inspectable. `BatchError.results` preserves per-member typed errors and successful `sandbox` objects for explicit cleanup.

## Account and agent resources

`pricing.estimate(...)` reads a cost estimate; `limits()` reads limits. `new Bead().profiles` exposes `list()`, `put(id, name, material)`, `revoke(id)` and `delete(id)`.

`sb.agent.prompt(...)` yields runner events fetched through cursor pages; `status()` reads conversation state and `interrupt(turnId)` interrupts a turn. `sb.desktop.screenshot()` returns bytes. `sb.browser.command(args)` invokes the browser helper. Use supported templates and configured credentials; see [coding agent runners](https://docs.bead.run/agents/runners.md).

## Errors and retries

`AuthenticationError`, `NotFoundError`, `TimeoutError`, `ProtocolError`, `LimitError`, `RateLimitError`, `PaymentRequiredError` and `BatchError` extend `BeadError`. Preserve `status`, `code` and `requestId`. Limit errors expose `limit`; payment errors expose `purchaseUrl`.

Creates, connects, pauses, resumes, sandbox deletions, snapshots, fleets and forks generate idempotency keys and retry selected transient failures. Reads also retry with bounded backoff. Snapshot deletion through `Golden.delete()` does not generate an idempotency key or automatically retry. Commands and prompts are not automatically replayed. Supply `idempotencyKey` on create for cross-process recovery.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.