Skip to main content
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 covers every create flag, network policy, and connection method; troubleshooting 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 and add funds there. Sandboxes draw on the same balance as Darkbloom inference.
  • Access: sign in at 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

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:
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:
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:
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:
Command-line login page in the sandbox console showing the code, the device name, the account and what approving does

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:
A macOS sandbox for Xcode builds, with Homebrew. --display vnc lets you open its screen later with darkbloom-sandbox-cli vnc sbx-…:
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

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

For plain ssh, scp, rsync, git, and editors’ remote SSH, write an SSH config entry for each sandbox:
  • 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:
To copy a working tree that is not committed:
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.

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

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):
Other clients and the full tool list are in coding agents and MCP server tools. 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 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

  • Billing: per second from the moment a sandbox is ready, with a one-minute minimum. See 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.
  • When a command fails, troubleshooting lists each error and what to do.