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

# Create and connect to an agent sandbox

> Choose a size and price, create a Linux or macOS sandbox, control its outbound network, and connect over SSH, scp, rsync, VS Code, or VNC.

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](https://docs.darkbloom.dev/sandboxes/lifecycle.md).

## Sizes and prices

```sh theme={null}
darkbloom-sandbox-cli sizes   # name, vCPUs, memory, workspace, price per hour, platforms you may boot it on
```

`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](https://docs.darkbloom.dev/sandboxes/pricing.md). 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

```sh theme={null}
darkbloom-sandbox-cli create --size c4-m8 --wait                          # Linux, persistent, preset egress
darkbloom-sandbox-cli create --platform macos_arm64 --size mac-c4-m8 --vnc  # macOS (experimental), straight to its desktop
```

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

| Option | Default | What it does |
| - | - | - |
| `--size`, `--cpus`, `--memory` | none | A named size, or the cheapest size that fits the resources you ask for. |
| `--platform` | `linux_arm64` | The OS: `linux_arm64` or `macos_arm64`. macOS is experimental: the desktop and heavy disk writes may be slow. |
| `--ephemeral` | persistent | An ephemeral sandbox cannot stop: its workspace is deleted when it ends (including an idle stop). A persistent one keeps its workspace across stops. |
| `--egress`, `--allow-host`, `--allow-set` | `preset` | Outbound network. See [network and egress](#network-and-egress). |
| `--display`, `--vnc` | `none` | A desktop you open with `vnc`; only a create chooses it, on either platform (every macOS image can serve one). |
| `--max-minutes N` | 240 (30–1440) | The longest each boot runs, however busy. |
| `--idle-minutes N` | 15 (5–120) | Stops a ready sandbox with nothing attached and no traffic for that long. |
| `--keep-alive DURATION` | none | Holds off the idle stop once ready. See [idle limit, keepalive, and maximum](https://docs.darkbloom.dev/sandboxes/lifecycle.md#idle-limit-keepalive-and-maximum). |
| `--key`, `--nonce` | `--key`: your default key or a generated one; `--nonce`: generated | Your SSH public key, and a 64-hex nonce that makes a repeated create answer the same sandbox. |
| `--json` | off | Machine-readable output for scripts. See [scripting](#scripting). |

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

```text theme={null}
{"error": {"status", "code", "message", "retryable", "outcome_unknown", "sandbox_id"}}
```

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:

| Set | Hosts | For |
| - | - | - |
| `dev` | the `codex+dev` preset's hosts | what `--egress preset` reaches |
| `homebrew` | `formulae.brew.sh`, `ghcr.io`, `pkg-containers.githubusercontent.com`, `github.com`, `raw.githubusercontent.com`, `release-assets.githubusercontent.com` | `brew install` on macOS |
| `node` | `nodejs.org`, `registry.npmjs.org`, `registry.yarnpkg.com`, `repo.yarnpkg.com` | Node.js downloads, npm, Yarn (Corepack's too) |
| `rust` | `sh.rustup.rs`, `static.rust-lang.org`, `crates.io`, `index.crates.io`, `static.crates.io` | rustup, Rust toolchains, crates |
| `ruby` | `rubygems.org`, `index.rubygems.org`, `cdn.cocoapods.org` | `gem install`, CocoaPods |
| `go` | `go.dev`, `dl.google.com`, `proxy.golang.org`, `sum.golang.org`, `storage.googleapis.com` | Go downloads and modules |
| `vscode` | `update.code.visualstudio.com`, `vscode.download.prss.microsoft.com`, `main.vscode-cdn.net`, `marketplace.visualstudio.com` | VS Code Remote-SSH's server |
| `anthropic` | `api.anthropic.com` | the Anthropic API (Claude Code) |
| `darkbloom-builds` | GitHub, npm, Go, Rust, PyPI, Hugging Face, Zig, kubectl, PostgreSQL and Ubuntu package downloads, and Playwright's browsers (31 hosts) | what Darkbloom's own builds download |

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:

```sh theme={null}
darkbloom-sandbox-cli create --platform macos_arm64 --size mac-c4-m8 \
  --egress allowlist --allow-set dev --allow-set 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

```sh theme={null}
darkbloom-sandbox-cli ssh sbx-…                       # an interactive shell
darkbloom-sandbox-cli ssh sbx-… -- uname -a           # one command, its output here
```

Before the first connection to each boot, `ssh` verifies the boot's
[attestation](https://docs.darkbloom.dev/sandboxes/security.md#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](https://docs.darkbloom.dev/sandboxes/lifecycle.md#image-upgrades).

`darkbloom-sandbox-cli codex sbx-… -- "task"` runs Codex in the sandbox over
the same channel. See [coding agents](https://docs.darkbloom.dev/sandboxes/agents-and-mcp.md).

### Files

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

```sh theme={null}
tar czf - ./myproject | darkbloom-sandbox-cli ssh sbx-… -- tar xzf - -C /workspace    # upload a tree (Linux)
darkbloom-sandbox-cli ssh sbx-… -- tar czf - -C /workspace myproject | tar xzf -     # download it
darkbloom-sandbox-cli ssh sbx-… -- 'cat > /workspace/notes.txt' < notes.txt          # one file
```

### 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):

```sh theme={null}
darkbloom-sandbox-cli ssh-config --all > ~/.ssh/darkbloom-sandbox.conf
# Make this the FIRST line of ~/.ssh/config (ssh keeps the first value it
# reads for each option, so a `Host *` above it would override it):
#   Include ~/.ssh/darkbloom-sandbox.conf
ssh darkbloom-2f7c9a410d3e                                # the Host name ssh-config printed
scp ./data.csv darkbloom-2f7c9a410d3e:/workspace/         # Linux; on macOS :workspace/ (sftp alike)
rsync -a -e ssh ./src/ darkbloom-2f7c9a410d3e:/workspace/src/
ssh -N -L 8080:127.0.0.1:8080 darkbloom-2f7c9a410d3e      # a server in the box on localhost:8080
```

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

```sh theme={null}
darkbloom-sandbox-cli ssh sbx-… -- -L 8080:127.0.0.1:8080 -N
```

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)

```sh theme={null}
darkbloom-sandbox-cli create --size c4-m8 --vnc        # create with a display, wait, open it
darkbloom-sandbox-cli vnc sbx-…                        # open the desktop of a sandbox created with one
```

`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](https://docs.darkbloom.dev/sandboxes/security.md#your-connection).

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


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