> ## 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.

# Agent sandboxes quickstart

> Go from a new Darkbloom account to builds running in parallel on Linux and macOS agent sandboxes, with your code pushed from your own machine.

> [!WARNING]
>
> Agent sandboxes are **experimental** and open by invitation. Expect rough
> edges and breaking changes.

This page takes you from a new account to builds running in parallel on
Darkbloom's Linux and macOS sandboxes, with your code pushed from your own
machine. [Create and connect](https://docs.darkbloom.dev/sandboxes/create-and-connect.md) covers every
create flag, network policy, and connection method; [troubleshooting](https://docs.darkbloom.dev/sandboxes/troubleshooting.md)
lists every error and what to do.

## Before you start

* **Your machine:** a Mac with Apple silicon, or Linux, with OpenSSH (`ssh` and
  `ssh-keygen`).
* **A funded account:** sign up at [https://console.darkbloom.dev](https://console.darkbloom.dev) and add funds
  there. Sandboxes draw on the same balance as Darkbloom inference.
* **Access:** sign in at [https://api-sandbox.darkbloom.dev](https://api-sandbox.darkbloom.dev) with the same
  account, open **Settings**, and send the **Account ID** to your Darkbloom
  contact. Say which platforms you need: `linux_arm64`, `macos_arm64`, or both.

A grant of one platform does not cover the other. Until you are granted, the
sandbox API answers as if it did not exist.

![Sandbox console Settings page showing the account's email and Account ID above its API keys](https://mintcdn.com/eigenlabs-f49d2e97/2TtlNanikOmTAJr5/images/console/settings.png?fit=max\&auto=format\&n=2TtlNanikOmTAJr5\&q=85\&s=48d05c26623664a5baddcfc8a7c91afc)

Settings in the sandbox console, where you find your Account ID and API keys. Example data.

## Install the CLI and sign in

Your Darkbloom contact sends you the release build of
`darkbloom-sandbox-cli` until the installer is served. Put it on your `PATH`.
If it reached you through a browser or a chat app, macOS quarantines it, so
clear that first:

```sh theme={null}
mkdir -p ~/.local/bin && mv ~/Downloads/darkbloom-sandbox-cli ~/.local/bin/
chmod 755 ~/.local/bin/darkbloom-sandbox-cli
xattr -d com.apple.quarantine ~/.local/bin/darkbloom-sandbox-cli 2>/dev/null
export PATH="$HOME/.local/bin:$PATH"   # also add this line to your shell profile
darkbloom-sandbox-cli --version        # release build, default plane https://api-sandbox.darkbloom.dev
```

When the service serves CLI releases, one command installs the current release
for Apple silicon Macs, Linux x86\_64, or Linux arm64 into `~/.local/bin`:

```sh theme={null}
curl -fsSL https://api-sandbox.darkbloom.dev/cli/install.sh | sh
```

While releases are served to invited accounts only, the installer needs an API
key from the console (**Settings** → **API keys**), saved in a file only you
can read. The installer refuses a key file others can read:

```sh theme={null}
chmod 600 ~/.dbx-key
curl -fsSL https://api-sandbox.darkbloom.dev/cli/install.sh |
  DARKBLOOM_SANDBOX_TOKEN_FILE=~/.dbx-key sh
```

A key an earlier `darkbloom-sandbox-cli login` stored is used by itself.
`sh -s -- --dir DIR` installs elsewhere. Later,
`darkbloom-sandbox-cli self-update` installs the service's current release in
place. It keeps the binary it replaced as
`darkbloom-sandbox-cli.previous` beside it, and refuses an older release unless
you pass `--force`; `--check` only says what is available.

Sign in, then list what you may run:

```sh theme={null}
darkbloom-sandbox-cli login   # opens a page in your browser: check the code, then approve
darkbloom-sandbox-cli sizes   # each size's vCPUs, memory, workspace, price per hour and platforms
```

![Command-line login page in the sandbox console showing the code, the device name, the account and what approving does](https://mintcdn.com/eigenlabs-f49d2e97/2TtlNanikOmTAJr5/images/console/cli-login-approve.png?fit=max\&auto=format\&n=2TtlNanikOmTAJr5\&q=85\&s=bafcebaf856052deacc381551d59df91)

The browser page that approves darkbloom-sandbox-cli login: check the code and approve it. Example data.

`login` stores an API key (`dbx_sk_…`, valid 90 days by default, revocable in
the console's settings) owner-only (mode 0600) in
`~/.config/darkbloom-sandbox/`, for that service only. `login --paste` or
`login --token-file PATH` stores a key you created in the console instead, and
`DARKBLOOM_SANDBOX_TOKEN` passes one to automation. `logout` revokes the stored
key and forgets it.

## Create sandboxes

A Linux sandbox for builds. The default network policy reaches GitHub and the
main package registries:

```sh theme={null}
darkbloom-sandbox-cli create --size c16-m32 --idle-minutes 60 --max-minutes 480 --wait
```

A macOS sandbox for Xcode builds, with Homebrew. `--display vnc` lets you open
its screen later with `darkbloom-sandbox-cli vnc sbx-…`:

```sh theme={null}
darkbloom-sandbox-cli create --platform macos_arm64 --size mac-c8-m32 \
  --egress allowlist --allow-set dev --allow-set homebrew \
  --display vnc --idle-minutes 60 --max-minutes 480 --wait
```

`create` prints the sandbox's ID (`sbx-…`). `darkbloom-sandbox-cli list` and
`status sbx-…` show each sandbox's state, time left, and cost so far.

![Sandbox console Sandboxes page listing sandboxes with state, size, image, egress, cost and ready time](https://mintcdn.com/eigenlabs-f49d2e97/2TtlNanikOmTAJr5/images/console/sandboxes-list.png?fit=max\&auto=format\&n=2TtlNanikOmTAJr5\&q=85\&s=0c076849639657a930eac9660ca0d78a)

The Sandboxes page in the sandbox console: each sandbox's state, size, egress, cost so far and readiness. Example data.

Network access is HTTPS (port 443) only, through a proxy that the sandbox
already sets in `HTTPS_PROXY`. To reach a host outside the default, create the
sandbox with an allowlist:

* `--egress allowlist`, plus the hosts you need.
* `--allow-set NAME` adds a named set of hosts.
* `--allow-host HOST` adds one host.

The [egress sets table](https://docs.darkbloom.dev/sandboxes/create-and-connect.md#network-and-egress)
lists every set. `darkbloom-builds`, for example, adds Zig, Go, Rust, and PyPI
downloads. The allowlist is fixed when the sandbox is created.

The largest sizes need the biggest Macs and may wait for capacity. If a create
fails with `no_capacity`, retry, pick a smaller size, and keep work that does
not need macOS on Linux.

## Connect

```sh theme={null}
darkbloom-sandbox-cli ssh sbx-…              # a shell: user agent on Linux, runner on macOS
darkbloom-sandbox-cli ssh sbx-… -- uname -a  # one command
```

For plain `ssh`, `scp`, `rsync`, `git`, and editors' remote SSH, write an SSH
config entry for each sandbox:

```sh theme={null}
darkbloom-sandbox-cli ssh-config --all > ~/.ssh/darkbloom-sandbox.conf
# Make this the FIRST line of ~/.ssh/config:
#   Include ~/.ssh/darkbloom-sandbox.conf
```

* Each sandbox becomes a host named `darkbloom-` followed by 12 characters of
  its ID.
* Run `ssh-config --all` again after you create or delete sandboxes.
* Linux sandboxes allow port forwards (`ssh -N -L 8080:127.0.0.1:8080
  darkbloom-…`). macOS sandboxes allow none.

## Bring your code

Push from your machine over SSH. This works for private repositories, and no
credential goes into the sandbox:

```sh theme={null}
H=darkbloom-xxxxxxxxxxxx   # a host name from ssh-config
W=/workspace               # on macOS: W=workspace (the workspace is in the login's home)
ssh "$H" "git init -q --bare $W/app.git"
git remote add sandbox "$H:$W/app.git"
git push sandbox HEAD:main
ssh "$H" "git clone -q $W/app.git $W/app"
# Later: git push sandbox HEAD:main && ssh "$H" "cd $W/app && git pull -q"
```

To copy a working tree that is not committed:

```sh theme={null}
rsync -a --exclude .git ./ "$H:/workspace/app/"
```

To clone from GitHub inside the sandbox instead:

1. Send a fine-grained, read-only token with
   `darkbloom-sandbox-cli secret set sbx-… GH_TOKEN < token-file`.
2. Point a git credential helper at the secret's file.

The secret is sealed to that boot and lasts until the sandbox stops. See
[secrets](https://docs.darkbloom.dev/sandboxes/security.md#secrets).

## Keep tools in the workspace

Only the workspace survives a stop:

* `/workspace` on Linux.
* `~/workspace` on macOS.

Everything else, your home directory included, starts fresh at every boot.
Install toolchains the image lacks, and point caches, into the workspace.

For example, Zig on Linux:

```sh theme={null}
cd /workspace
ZIG=0.15.2   # your version
curl -fsSL "$(curl -fsSL https://ziglang.org/download/index.json \
  | jq -r --arg v "$ZIG" '.[$v]["aarch64-linux"].tarball')" | tar -xJ
mv zig-*-"$ZIG" zig
printf 'export PATH=/workspace/zig:$PATH\nexport ZIG_GLOBAL_CACHE_DIR=/workspace/.cache/zig\n' > env.sh
```

This download needs `--allow-set darkbloom-builds`, which includes
`ziglang.org`. Run `source /workspace/env.sh` in each new login.

On macOS:

* `brew install` (with the `homebrew` set) installs into a directory that
  resets at every boot.
* Keep Xcode's build output in the workspace:
  `xcodebuild -scheme App -derivedDataPath ~/workspace/DerivedData build`.

## Run builds in parallel

Each sandbox is independent. Create several, then fan out from your machine:

```sh theme={null}
for H in darkbloom-aaaa darkbloom-bbbb darkbloom-cccc; do
  ssh "$H" 'cd /workspace/app && make test' > "$H.log" 2>&1 &
done
wait
```

A sandbox stops after `--idle-minutes` with no client attached and no network
traffic. **Work left running inside, in `tmux` or under `nohup`, does not keep
it alive.**

* Keep an SSH session open from your machine. The loop above does this.
* `darkbloom-sandbox-cli keepalive sbx-… 45m` holds off the idle stop, but only
  within the first hour of a boot.
* `darkbloom-sandbox-cli extend sbx-… 120` adds time before `--max-minutes`, up
  to 24 hours in total.

An account runs 2 sandboxes at a time unless Darkbloom set another limit for
you. See [limits](https://docs.darkbloom.dev/sandboxes/limits-and-billing.md#limits).

## Let a coding agent drive it

`darkbloom-sandbox-cli mcp` is an MCP server. With it, an agent such as Codex
or Claude can:

* create sandboxes
* run commands in them
* read and write files
* stop the sandboxes again

For Codex (`~/.codex/config.toml`):

```toml theme={null}
[mcp_servers.darkbloom-sandbox]
command = "darkbloom-sandbox-cli"
args = ["mcp"]
```

Other clients and the full tool list are in [coding agents](https://docs.darkbloom.dev/sandboxes/agents-and-mcp.md)
and [MCP server tools](https://docs.darkbloom.dev/sandboxes/mcp-tools.md).

**Teach the agent how to use the sandboxes.** The tools say what an agent can
do, not when to do it. Install the [sandbox skill](https://docs.darkbloom.dev/sandboxes/agent-skill.md) as
`.claude/skills/darkbloom-sandboxes/SKILL.md` so the agent knows 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.

## Stop or delete

```sh theme={null}
darkbloom-sandbox-cli stop sbx-…     # keeps the workspace; a stopped sandbox costs nothing
darkbloom-sandbox-cli resume sbx-…   # the same workspace, on the same Mac
darkbloom-sandbox-cli delete sbx-…   # erases the workspace
```

* **Billing:** per second from the moment a sandbox is ready, with a one-minute
  minimum. See [billing](https://docs.darkbloom.dev/sandboxes/limits-and-billing.md#billing).
* **Retention:** a sandbox stopped for 30 days is deleted.

## Before you rely on it

* **Only the machine that created a sandbox can reach it.** The CLI keeps each
  sandbox's keys in `~/.config/darkbloom-sandbox/`. Do not delete those
  records.
* **macOS capacity is small.** A create can fail with `no_capacity`: retry,
  pick a smaller size, and keep work that does not need macOS on Linux.
* **What the machines can't do:** sandboxes are arm64 only. There are no
  virtual machines inside a sandbox, and no GPU on Linux.
* **The network:** HTTPS only, through the proxy. There is no DNS inside, so a
  tool that ignores `HTTPS_PROXY` cannot connect.
* **Your workspace is encrypted on the Mac, but Darkbloom can decrypt it,** and
  a sandbox is not yet confidential from the Mac's owner. Keep production
  credentials out. See [security](https://docs.darkbloom.dev/sandboxes/security.md).
* **When a command fails,** [troubleshooting](https://docs.darkbloom.dev/sandboxes/troubleshooting.md) lists
  each error and what to do.


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