# SDK

Create and drive Buddy Sandboxes from code with @buddy-works/sandbox-sdk - the full lifecycle, commands, files, apps, and snapshots from TypeScript.

The Sandbox SDK is a TypeScript library for creating and driving Sandboxes programmatically. Use it when Sandboxes are part of your product rather than part of your workflow - an agent orchestrator, a code-execution backend, a per-customer environment provisioner.

```bash
npm install @buddy-works/sandbox-sdk
```

The SDK requires Node.js 20 or newer. It is published before 1.0 - pin the exact version in `package.json`, as the API may still change between releases.

## Authentication

The SDK authenticates with a [personal access token](/docs/api/getting-started/oauth2/personal-access-token.md) and reads the workspace and project from the environment:

```bash
export BUDDY_TOKEN="your-personal-access-token"
export BUDDY_WORKSPACE="your-workspace"
export BUDDY_PROJECT="your-project"
export BUDDY_REGION="US"   # optional, US by default, EU and AS available
```

The token needs the `SANDBOX_INFO` and `SANDBOX_MANAGE` scopes. Every value can also be passed per call in a `connection` object, which is how you reach a different workspace or region from the same process.

## Creating and using a Sandbox

```typescript
import { Sandbox } from "@buddy-works/sandbox-sdk";

const sandbox = await Sandbox.create({
  identifier: "my-sandbox",
  os: "ubuntu:24.04",
  fetch: [{
    type: "PUBLIC_REPO",
    repository: "https://github.com/octocat/Hello-World",
    ref: "master",
    path: "/buddy/hello",
  }],
});

const command = await sandbox.runCommand({ command: "cat /buddy/hello/README" });
console.log(await command.output());

await sandbox.stop();
```

`runCommand` blocks until the command finishes and streams to `process.stdout` as it goes. Pass `detached: true` to get control back immediately, and read the result with `output()`, `stdout()`, or `stderr()`.

## What it covers

- the full lifecycle: create, clone, start, stop, restart, destroy
- commands, with output collected or streamed
- files, through `sandbox.fs`
- long-running apps
- snapshots
- configuration changes in place, through `sandbox.update()`

Endpoints, variables, and tags are set through `update()` rather than through their own methods. Terminal access, SSH, and custom domains stay on the UI and CLI side.

## Where to find it

- Source: [github.com/buddy/sandbox-sdk](https://github.com/buddy/sandbox-sdk)
- Package: [@buddy-works/sandbox-sdk on npm](https://www.npmjs.com/package/@buddy-works/sandbox-sdk)

## Other languages

There is no official SDK for other languages yet. Until there is, the [REST API](/docs/api/sandboxes.md) exposes the same operations and works from any stack.

## Next

- [CLI](/docs/sandboxes/cli.md) - the same operations from a terminal
- [AI agents](/docs/sandboxes/ai-agents.md) - patterns for agent orchestration
- [REST API](/docs/api/sandboxes.md) - full endpoint reference


---
Original source: https://buddy.works/docs/sandboxes/sdk