# Run agents in a sandbox
Spin up an isolated Buddy sandbox, fetch your repo, connect over SSH, and run your AI coding agent in a clean cloud environment.
Buddy sandboxes are fully isolated cloud environments - a clean Ubuntu box preloaded with Node 24, Docker, Go, Python 3, git, and the Buddy CLI. Running an AI agent inside a sandbox keeps it off your machine: it gets its own throwaway workspace with your repo fetched in, and full freedom to install packages, run commands, and deploy - without touching your local setup.
Prefer code over the CLI? Manage sandboxes programmatically with the [Buddy Sandbox SDK](https://github.com/buddy/sandbox-sdk) ([npm](https://www.npmjs.com/package/@buddy-works/sandbox-sdk)). For a full self-hosted agent setup, follow the [Claude Managed Agents on Buddy Sandboxes](/docs/ai-agents/claude-managed-agents.md) guide.
## Quick start
```bash
npm install -g bdy
```
```bash
bdy login
```
Run this in your project directory:
```bash
bdy proj link
```
You'll be walked through creating or picking a project:
```text
? PROJECT Create new
? Provide project name: f1
✔ Project created
✔ Project linked to https://app.buddy.works/myplayground/f1-2
? INITIALIZE GIT REPOSITORY No
→ TRY NOW
$ bdy tunnel http 3000 - Expose localhost:3000 to the internet
$ bdy artifact publish . --create - Publish an artifact from the current project
$ bdy sandbox create --run "npm start" - Spin up a cloud sandbox and run your app
```
```bash
bdy sandbox create
```
The sandbox boots on Ubuntu 24.04 with Node 24, Docker, Go, Python 3, git, curl, wget, jq, rsync, ripgrep, unzip, nano, and bdy already installed.
Copy the SSH address from the sandbox **Settings → TUNNELS**, then connect as the `buddy` user:
```bash
ssh buddy@
```
Authentication uses the SSH key from your Buddy profile - see [SSH keys](/docs/git-hosting/ssh-keys.md) to add one, and [Endpoints](/docs/sandboxes/endpoints.md) for connection details.
AI coding agents come pre-installed in the sandbox - just start the one you want, and it works in a fully isolated environment:
```bash
claude
```
## Programmatic access with the SDK
Prefer to manage sandboxes from code instead of the CLI? The [Buddy Sandbox SDK](https://github.com/buddy/sandbox-sdk) is a TypeScript library for creating and driving sandboxes programmatically - ideal for building your own agent orchestration.
```bash
npm install @buddy-works/sandbox-sdk
```
```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: "/workspace/hello",
}],
});
await sandbox.start();
await sandbox.runCommand({ command: "npm test" });
await sandbox.stop();
```
The SDK covers the full lifecycle - create, start and stop, run commands, manage long-running apps, fetch repositories and artifacts, and create or restore snapshots - with regional configuration for US, EU, and AP. See the [source on GitHub](https://github.com/buddy/sandbox-sdk) and the [package on npm](https://www.npmjs.com/package/@buddy-works/sandbox-sdk).
## Fetch your repo into the sandbox
Use `--fetch` to pull code in at creation time, so the agent starts with your project ready to go:
```bash
# project repository, default branch, into the working directory
bdy sandbox create --fetch
# a specific branch
bdy sandbox create --fetch feature-branch
# an external public repository, into a chosen path
bdy sandbox create --fetch "path=/home/buddy/repo,url=https://github.com/acme/app,ref=main"
# fetch a branch and build it on boot
bdy sandbox create --fetch "path=/home/buddy/repo,ref=main,build=npm install && npm run build"
```
### Repository access
By default, sandboxes get **read-only** access to the project repository - enough for the agent to fetch and read the code.
To let the agent push changes back, grant **read-write** access: open the **Project repository** target, go to the **Permissions** tab, and add the sandbox with RW rights. You can also change the default so that all sandboxes get RW access to the repository.
## The agent can edit its own sandbox
Once inside, the agent isn't just a passenger - it can reshape the sandbox it's running in through the `this` command. `this` mirrors `bdy sandbox`, but every command is scoped to the current sandbox, so the agent never needs to know its own identifier.
```bash
this --help
```
The subcommands match `bdy sandbox`:
- `this get` / `this status` / `this yaml` - inspect the current sandbox
- `this update` - edit the sandbox definition
- `this endpoint` - expose ports and manage endpoints
- `this app` - manage running apps
- `this exec` / `this cp` / `this logs` - run commands, copy files, read setup logs
- `this snapshot` - snapshot the current state
- `this start` / `this stop` / `this restart` / `this destroy` - control the lifecycle
This lets the agent do things like expose the dev server it just started, install an app, or snapshot a known-good state - all from inside, mid-task. Run `this --help` for the exact options.
## More use cases
Run setup on boot and keep the app running:
```bash
bdy sandbox create --boot-command "npm install" --app-command "npm start" --app-dir /home/buddy/repo --wait-for-configured
```
Pick larger resources (CPUxRAM) for heavier agent work:
```bash
bdy sandbox create --resources 4x8
```
Run a one-off command in a sandbox (runs as `buddy` with passwordless sudo):
```bash
bdy sb exec command "npm test" --wait
```
Copy local files into a sandbox:
```bash
bdy sb cp ./local-dir :/home/buddy/
```
Manage the lifecycle:
```bash
bdy sb list
bdy sb get
bdy sb stop
bdy sb start
bdy sb destroy
```
Inspect the setup log (boot commands and fetch steps):
```bash
bdy sb logs
```
---
Original source: https://buddy.works/docs/ai-agents/sandboxes