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:
--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 inHTTPS_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’scodex+devlist of developer hosts (package registries, GitHub, model APIs Codex uses).--egress allowlist --allow-host api.example.com --allow-host github.comallows 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 devis 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:
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
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 --:
-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.
