Sandbox TypeScript SDK

Import the sandbox TypeScript SDK package @beadrun/sdk for async machine, command, file and account objects. Start with the quickstart.

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

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.

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.

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.

​Machines and options

​Commands

​Files and ports

​Snapshots and parallel work

​Account and agent resources

​Errors and retries