.claude/skills/darkbloom-sandboxes/SKILL.md. The YAML
frontmatter is part of the skill file and must be kept.
---
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.

