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

# Darkbloom agent sandboxes

> Run Linux and macOS virtual machines on Apple silicon Macs in Darkbloom's fleet. SSH in, run a coding agent, open a desktop, and pay per second.

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

An agent sandbox is a Linux VM (or, experimentally, a macOS VM) on an Apple
silicon Mac in Darkbloom's community fleet, for you or your coding agent: SSH
in, run Codex or another agent, open its desktop, stop it, and resume it later
on the same workspace. You pay per second while it runs, from the same
Darkbloom balance that Darkbloom inference uses.

> [card] [Quickstart](https://docs.darkbloom.dev/sandboxes/quickstart.md)
>
> From a new account to parallel builds: install, create, connect, and push code.

> [card] [Create and connect](https://docs.darkbloom.dev/sandboxes/create-and-connect.md)
>
> Sizes and prices, create flags, egress allowlists, SSH, files, and VNC.

> [card] [Coding agents](https://docs.darkbloom.dev/sandboxes/agents-and-mcp.md)
>
> Run Codex, drive the desktop with computer use, or expose sandboxes over MCP.

> [card] [Limits and billing](https://docs.darkbloom.dev/sandboxes/limits-and-billing.md)
>
> Per-account limits, billing holds, and what each charge covers.

## What you can do with a sandbox

* **Work over SSH.** Open an interactive shell, run one command, or copy files
  with `scp` and `rsync`.
* **Keep a workspace.** Your files, their owners and permissions, links, git
  repositories, and Codex's login and sessions survive a stop and resume.
* **Run several in parallel.** Each sandbox is independent, so builds and tests
  fan out instead of queueing.
* **Open a desktop.** A VNC desktop is available on either platform when you
  create the sandbox with one.
* **Let a coding agent drive it.** The built-in MCP server, the `codex`
  command, and computer use let an agent create sandboxes, run commands, and
  read and write files.

## Linux and macOS

| | Linux | macOS |
| - | - | - |
| Platform name | `linux_arm64` (the default) | `macos_arm64` |
| Image | Ubuntu with git, a C and C++ toolchain, Python and Node | Xcode and Homebrew |
| SSH login | `agent` | `runner` |
| Workspace | `/workspace` | `~/workspace` |
| Sizes | `c4-m8`, `c8-m16`, … | `mac-c4-m8`, `mac-c8-m16`, … |
| Status | Available | Experimental: the desktop and heavy disk writes may be slow. |

On current Linux images, `~/workspace` is a link to `/workspace`, so the same
path works on both platforms: `readlink ~/workspace` prints `/workspace`.

Sandboxes are arm64 only. There are no virtual machines inside a sandbox, and
no GPU on Linux.

## Pricing

Billing is per second from the moment a sandbox is ready until its VM is gone,
with a one-minute minimum per charge. Starting up and stopped sandboxes are
free.

`darkbloom-sandbox-cli sizes` reads the 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: `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; the full
table is in [sandbox pricing](https://docs.darkbloom.dev/sandboxes/pricing.md). The largest
sizes need the biggest Macs and may wait for capacity.

See [limits and billing](https://docs.darkbloom.dev/sandboxes/limits-and-billing.md) for holds, what the
console shows, and what happens when your balance cannot cover a boot.

## How you reach a sandbox

A sandbox has no inbound ports and no public address: you reach it only
through `darkbloom-sandbox-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, so point package managers at HTTPS mirrors.

The CLI verifies a boot's attestation before it connects to it and pins the
host key that boot attests. See [security](https://docs.darkbloom.dev/sandboxes/security.md).

## Who can use agent sandboxes

Access is by invitation, and a grant of one platform does not cover the other.
Send the Account ID the console shows under **Settings** and the platforms you
need (`linux_arm64`, `macos_arm64`, or both) to your Darkbloom contact. Until
you are granted, the sandbox API answers as if it did not exist. The
[troubleshooting page](https://docs.darkbloom.dev/sandboxes/troubleshooting.md) shows the message the CLI
prints.

You need a funded Darkbloom 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.

## Next steps

Start with the [quickstart](https://docs.darkbloom.dev/sandboxes/quickstart.md) to create and connect to
your first sandbox, then read [create and connect](https://docs.darkbloom.dev/sandboxes/create-and-connect.md)
for sizes, network policy, and the desktop.


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