Skip to main content
This page covers choosing a size, creating a sandbox, its outbound network policy, and every way to reach it. For the lifecycle after creation, see stop, resume, and retention.

Sizes and prices

sizes reads the service’s live list and is the price you pay. At the time of writing, Linux sizes cost $0.032 per vCPU-hour plus $0.008 per GiB-hour of memory, for example c4-m8 (4 vCPUs, 8 GiB, 32 GiB workspace) at $0.192 an hour and `c8-m16` (8 vCPUs, 16 GiB, 64 GiB workspace) at $0.384. macOS sizes cost $0.35 to $0.90 an hour. Each platform takes only its own sizes, and the full list is in sandbox pricing. The largest sizes need the biggest Macs and may wait for capacity. Instead of a size you can ask for resources: create --cpus 8 --memory 16 creates the cheapest size the service offers on the platform with at least that much, and says which.

Create a sandbox

create sends a fresh nonce (or the one you name with --nonce HEX, 64 hex characters, to repeat the same create) and your SSH public key (--key PUBKEY, else ~/.ssh/id_ed25519.pub, else a key it generates) and prints the sandbox ID (sbx-…). The CLI keeps a record of each sandbox, with the nonce and key, in ~/.config/darkbloom-sandbox/sessions/: only the machine that created a sandbox can verify and reach it, so do not delete those records. --wait returns once the sandbox is ready; without it, status shows its progress. A create is idempotent per nonce: if its answer is lost (a dropped connection, a timeout), the same create again, with the same nonce, answers the sandbox it made rather than a second one. A create that failed answers its failure again, so trying again means a new create (a new nonce). A sandbox whose answer never reached you still shows in darkbloom-sandbox-cli list (and the console); delete it if you do not need it. Billing starts only once it is ready, and with nothing attached it stops at its idle limit. Options worth knowing: create names no image: the service boots the agent image Darkbloom pins for the platform (Codex included), and the CLI records its digest so that it refuses to connect to a boot of any other image.

Scripting

With --json, a create that fails prints one JSON document on stdout, the sentence on stderr as ever, and exits 1 (2 for a usage error). The document has this shape:
With --wait, it prints the created sandbox on a first line once it has a Mac (or immediately when --image is given), and the ready sandbox (or that error document, with "sandbox" beside it) on a second. A create that gives up before it has a Mac prints the error document alone.

Network and egress

A sandbox has no inbound ports and no public address: you reach it only through the CLI. Outbound traffic goes through Darkbloom’s gateway, HTTPS on port 443 only, through a proxy that every login already has in HTTPS_PROXY (127.0.0.1:3128). Plain http:// URLs and other ports do not work: point package managers at HTTPS mirrors.
  • --egress preset (the default) allows Darkbloom’s codex+dev list of developer hosts (package registries, GitHub, model APIs Codex uses).
  • --egress allowlist --allow-host api.example.com --allow-host github.com allows exactly the hosts you name instead (1 to 64 exact lowercase hostnames, no wildcards). An allowlist replaces the preset: name every host your work needs, one by one or by set (--allow-set dev is the preset’s own hosts).
--allow-set NAME (repeatable, only with --egress allowlist) adds a named set of hosts. The sets are Darkbloom’s: the CLI asks the service for them when you name one, and create prints the hosts the allowlist came to and the sandbox’s egress policy digest (what its attestation must show; --json has the hosts in egress.allowlist). The sandbox may reach every set’s hosts and every --allow-host, 64 hosts at most together, fixed when it is created: A set names the hosts its tool’s own downloads use, not every host a build may reach: a Homebrew cask, or a formula built from source, downloads from its vendor’s host, a CocoaPods pod from its own repository, and a VS Code extension installed in the sandbox from its publisher’s host (PUBLISHER.gallerycdn.vsassets.io; VS Code can also download extensions on your machine and copy them over, its remote.downloadExtensionsLocally setting). Name those hosts with --allow-host. A service from before the sets were served leaves them to your CLI version’s own (every set above but darkbloom-builds, and dev as that version knows the preset), and create says so. A name the service has no set for creates nothing. The preset does not reach Homebrew’s formula list or the host its packages download from, so brew install fails under it. A macOS sandbox that installs with Homebrew:
A host outside the policy fails inside the guest: the proxy refuses it with HTTP 403 and says why (curl: (56) CONNECT tunnel failed, response 403, as git and most tools report it; curl -v shows the proxy’s header Sandbox-Refusal: policy; mode=…; host=…). A 502 from the proxy is every other failure to open the connection: the host is allowed but could not be reached just now, the URL names a port other than 443 or an IP address instead of a hostname, or the sandbox’s egress limits are used up. The 403 needs both the sandbox’s image and the service to carry this change: until both do, a host outside the policy answers 502 as well.

Connect over SSH

Before the first connection to each boot, ssh verifies the boot’s attestation and pins the host key it attests; it then takes a short-lived ingress capability from the service and runs your ssh (DARKBLOOM_SANDBOX_SSH, default ssh) through the gateway with only that key, as agent@sbx-… on Linux and runner@sbx-… on macOS. Your work lives in /workspace (Linux) or ~/workspace (macOS). On current Linux images, ~/workspace is a link to /workspace, so the same path works on both. On an older Linux image a ~/workspace you make is a directory in the home, which is memory and gone at the next stop; a stopped sandbox gets the link when it moves to the new image with resume --upgrade-image. See image upgrades. darkbloom-sandbox-cli codex sbx-… -- "task" runs Codex in the sandbox over the same channel. See coding agents.

Files

ssh … -- COMMAND connects its standard input and output, so copies are pipes:

Plain OpenSSH: scp, sftp, rsync, port forwards, editors

darkbloom-sandbox-cli ssh-config prints an OpenSSH host entry per sandbox that reaches it through the CLI, so every OpenSSH tool works, and editors’ remote servers that forward a port (VS Code Remote-SSH, JetBrains Gateway) work with Linux sandboxes (macOS sandboxes allow no forwarding):
ssh-config sbx-… prints one sandbox’s entry, --all every sandbox this CLI created; run it again after you create or delete sandboxes. Each entry is named darkbloom- and the first 12 characters of the ID after sbx- (the whole ID if two would collide), logs in as the sandbox’s user (agent or runner) with the SSH key you created it with, and trusts only the host key the CLI pinned from the boot’s attestation, checked strictly; it never forwards your SSH agent or X11 display into the sandbox. Its ProxyCommand is darkbloom-sandbox-cli proxy sbx-…: every connection verifies the boot exactly as ssh does (attesting it the first time after a create or resume) and takes a fresh short-lived capability from the service, so nothing in the entry expires and there is no token in it; the CLI reads your token from where login stored it (or DARKBLOOM_SANDBOX_TOKEN, which your shell passes on to ssh). Without the config, ssh passes forwarding flags placed after --:
It also accepts -R, -D, -T, -t, -C, -q, and -v; a second -- starts the remote command. It refuses options that would change how ssh reaches or trusts the sandbox (-o, -F, -J, -i, -p, …): use ssh-config for anything else. Linux sandboxes allow local forwards (-L, -D); macOS sandboxes allow none.

The desktop (VNC)

vnc verifies the boot’s attestation first (never skipped), turns on the guest’s display with a fresh random password sealed to the attested guest key, listens on 127.0.0.1 only (--port N, else any free port), and opens your viewer at vnc://127.0.0.1:<port> (macOS Screen Sharing, or any VNC viewer). A sandbox created without a display cannot get one later (409 display_not_enabled): create a new one with --vnc. End-to-end encrypted means the screen traffic travels inside the SSH channel to the attested guest, encrypted from your machine to the sandbox. Darkbloom’s gateway and the network relay it without seeing it, and the desktop listens only on the guest’s loopback, so nothing else on the network can reach it. This is not a claim of confidentiality from the Mac’s owner. See security. Slow links. The desktop sends only what changes, but a busy screen needs bandwidth: Darkbloom’s targets are a first frame within 2 seconds and under 8 Mbit/s at 1080p. On a slow link, use a smaller window or lower your viewer’s quality. macOS desktops are the newest part and may lag. The macOS screen lock. On today’s macOS images the desktop locks after 20 minutes without input, and a locked desktop shows only the wallpaper and takes no clicks or keys, from you or from a computer-use agent. No way to unlock it from inside the sandbox is known; a new boot starts unlocked, so stop it and resume it (the workspace is kept). The CLI prevents the lock: at its first connection to each boot of a macOS sandbox (ssh, vnc, codex, cua, the MCP servers, and plain ssh or an editor through ssh-config’s entries) it turns the lock off for that boot, which takes about five seconds once and says nothing. Connect within 20 minutes of a create or a resume if you will use the desktop later; vnc, cua run, and mcp-cua tell you when the screen is locked already (sbx-…'s screen is locked. …). A later image turns the lock off by itself; the CLI notices that at its first connection to a sandbox of such an image and makes no extra connection to that sandbox again.