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

# Give a coding agent the sandbox skill

> A ready-made skill that tells Claude, Codex, and other coding agents when to offload work to a Darkbloom agent sandbox, how to move code without leaking a token, and how to clean up.

The [MCP tools](https://docs.darkbloom.dev/sandboxes/mcp-tools.md) say what an agent can do. The skill says
when to do it: when offloading pays off, how to push code without putting a
token in a sandbox, what keeps a long build alive, and to stop what it started.

Save the text below as `.claude/skills/darkbloom-sandboxes/SKILL.md`. The YAML
frontmatter is part of the skill file and must be kept.

````markdown theme={null}
---
name: darkbloom-sandboxes
description: Offload builds, tests and long-running work to Darkbloom agent sandboxes (Linux and macOS VMs on Apple silicon Macs) over SSH, and run several in parallel. Use when the local machine is the bottleneck (slow builds, memory pressure, many parallel jobs), when a task needs macOS or Xcode, or when a task should run in a fresh, isolated machine. Not for CI (that is GitHub Actions routed to Darkbloom) and not for production data.
---

# Darkbloom agent sandboxes

A sandbox is a VM you reach over SSH with `darkbloom-sandbox-cli`. Linux
sandboxes are Ubuntu on arm64; macOS sandboxes have Xcode and Homebrew. You
pay per second while a sandbox runs, so create what the task needs, keep work
in the workspace, and stop it when the work is done.

Read `darkbloom-sandbox-cli help <command>` for exact flags. The full guide
is the customer page *Darkbloom agent sandboxes*.

## Preconditions

1. The CLI is installed and on `PATH`: `darkbloom-sandbox-cli --version`
   must print a release build and the plane `https://api-sandbox.darkbloom.dev`.
2. You are signed in: `darkbloom-sandbox-cli list`. If it fails with a 401,
   ask the human to run `darkbloom-sandbox-cli login`; it opens a browser and
   needs their approval. Never ask for their API key in chat.
3. If every call answers 404 `not_found`, the account is not allowlisted for
   sandboxes: stop and ask the human to get access. Do not retry in a loop.

## The loop for one task

```sh
darkbloom-sandbox-cli sizes        # what this account may create, and the price per hour
darkbloom-sandbox-cli create --size c8-m16 --idle-minutes 60 --max-minutes 240 --wait
darkbloom-sandbox-cli ssh sbx-… -- 'cd /workspace && uname -a'
darkbloom-sandbox-cli stop sbx-…   # keeps the workspace; costs nothing while stopped
darkbloom-sandbox-cli delete sbx-… # erases the workspace
```

`create` prints the ID (`sbx-…`). Keep it: every later command needs it, and
only the machine that created a sandbox can reach it.

## Choosing a platform and size

- **Linux** for anything that does not need macOS: it is cheaper and there is
  far more capacity. Sizes run from `c4-m8` to `c32-m128`.
- **macOS** only for Xcode, Swift, or a macOS app. It is scarce: expect
  `no_capacity` and retry or shrink. The largest macOS size is `mac-c8-m32`.
- Prefer the smallest size that fits. `--cpus N --memory G` picks the cheapest
  size that meets a need.
- `darkbloom-sandbox-cli sizes` is the authority on names and prices; do not
  assume one exists.

## Network: the allowlist is fixed at create

There is no DNS and no plain HTTP inside a sandbox. Every outbound request
goes through an HTTPS proxy that the login already sets in `HTTPS_PROXY`, on
port 443, to hosts chosen when the sandbox is created.

- Default (`--egress preset`): Darkbloom's developer list: GitHub, npm,
  crates.io, PyPI, Go, the Ubuntu mirrors and OpenAI.
- Anything else must be named at create:
  `--egress allowlist --allow-set dev --allow-set homebrew --allow-host example.com`.
  Named sets include `dev`, `homebrew`, `node`, `rust`, `ruby`, `go`, `vscode`,
  `anthropic` and `darkbloom-builds` (which adds Zig, Hugging Face, kubectl and
  PostgreSQL downloads).
- A blocked host fails with `CONNECT tunnel failed, response 403`. If a tool
  needs a new host, create a sandbox with that host; the allowlist cannot be
  changed on a running sandbox.

## Getting the code in

Push it, and leave credentials out of the sandbox:

```sh
H=darkbloom-xxxxxxxxxxxx      # from: darkbloom-sandbox-cli ssh-config --all
ssh "$H" 'git init -q --bare /workspace/work.git'
git push "$H:/workspace/work.git" HEAD:main
ssh "$H" 'git clone -q /workspace/work.git /workspace/work'
```

- This works for private repositories and needs no token inside the sandbox.
- To copy an uncommitted tree: `rsync -a --exclude .zig-cache ./ "$H:/workspace/work/"`.
- To clone from GitHub inside the sandbox instead, send a fine-grained,
  read-only token with `darkbloom-sandbox-cli secret set sbx-… GH_TOKEN < file`
  and have git read it with a credential helper. A secret lasts one boot:
  send it again after a `resume`.

## The workspace is the only thing that persists

- Linux: `/workspace`. macOS: `~/workspace`. Everything else, the home
  directory included, is reset at every boot.
- Put toolchains, caches and build output there, and export `PATH` and cache
  variables from a file in the workspace, for example
  `source /workspace/env.sh`.
- On macOS, point Xcode's output there too:
  `xcodebuild -derivedDataPath ~/workspace/DerivedData`.
- Do not write outside the workspace and expect it to survive.

## Long jobs and the idle stop

A sandbox stops itself in two ways, and neither cares that a build is running:

- **Idle** (`--idle-minutes`, 15 by default): no attached client and no
  network traffic. Work under `nohup` or in `tmux` does **not** count.
- **Maximum** (`--max-minutes`, 240 by default): however busy.

So while a job must run:

- Keep an SSH client attached. Run the job in the foreground of a command you
  are still waiting on, or hold `darkbloom-sandbox-cli ssh sbx-…` open.
- Or `darkbloom-sandbox-cli keepalive sbx-… 45m`, which only holds within the
  first hour of a boot.
- Raise the ceiling with `darkbloom-sandbox-cli extend sbx-… 120` (up to 24
  hours in total).
- Before reporting a long job as started, check
  `darkbloom-sandbox-cli status sbx-…` and say what keeps it running.

## Parallel work

Each sandbox is independent, so fan out rather than queueing:

```sh
for H in darkbloom-a darkbloom-b darkbloom-c; do
  ssh "$H" 'cd /workspace/work && make test' > "$H.log" 2>&1 &
done
wait
```

The account has a limit on running sandboxes (2 by default; the human can
raise it). More creates fail `409 limit_reached`. Stop the finished ones
before starting more. Starts are rate-limited too (about 10 at once, then one
a minute).

## Clean up, always

Sandboxes cost money until they are stopped, and an agent that forgets them
leaves a bill behind.

- `stop` when the task is done: the workspace is kept and costs nothing, and a
  `resume` brings it back on the same Mac.
- `delete` when the work is pushed out or no longer wanted. A sandbox stopped
  for 30 days is deleted automatically.
- At the end of a session, `darkbloom-sandbox-cli list` and report what is
  still running, with IDs and states.

## What not to do

- **Never put production credentials, customer data or regulated data in a
  sandbox.** The workspace is encrypted on the Mac, but Darkbloom can decrypt
  it, and the product does not yet claim confidentiality from the machine's
  owner. Treat a sandbox as a convenient isolated dev box, not a vault.
- **Never work around attestation.** `ssh` verifies the boot before it
  connects; do not disable it, edit `known_hosts`, or pass extra SSH options
  to skip host-key checks. Use `ssh-config` for anything the `ssh` wrapper
  refuses.
- **Do not create a sandbox per command.** One sandbox runs many commands.
- **Do not print secrets.** `secret set` reads the value from a file or stdin;
  keep it out of argv, out of logs, and out of your replies.

## When something fails

| Message | What it means |
|---|---|
| `unfunded` | The account's balance cannot cover the hold: tell the human. |
| `no_capacity` | No Mac fits right now: retry, or a smaller size or the other platform. |
| `boot_timeout` | It never started, and was not billed: create again. |
| `409 limit_reached` | Stop a running sandbox first. |
| `409 not_ready` | Still booting: `status` until `ready`, then retry. |
| `verification_failed` | Do not retry blindly: delete it, create a new sandbox, and report it. |
| `CONNECT tunnel failed, response 403` | The host is not in this sandbox's allowlist. |

A sandbox that stops with work unsaved loses that work; commit and push
inside the sandbox before long jobs, or keep the sandbox alive deliberately.
````


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