SDK

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 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
• Package: @buddy-works/sandbox-sdk on npm

Other languages

There is no official SDK for other languages yet. Until there is, the REST API exposes the same operations and works from any stack.

Next

• CLI - the same operations from a terminal
• AI agents - patterns for agent orchestration
• REST API - full endpoint reference