# Cloud sandbox reference



Cloud sandboxes run as isolated Firecracker microVMs on Clusterbase-managed
infrastructure. Each one boots from the VM template named by the environment's
[`template_id`](/docs/agents/environments#templates), and everything listed here
is on the image already — the agent can use it without an installation step.

These specifications apply to `cloud` environments, the only environment type
in v1.

## Templates [#templates]

| Template      | Operating system   | vCPU | Memory | Disk  | Use it for                                                     |
| ------------- | ------------------ | ---- | ------ | ----- | -------------------------------------------------------------- |
| `development` | Debian 13 (trixie) | 4    | 4 GB   | 10 GB | General-purpose development. The default.                      |
| `workspace`   | Debian 13 (trixie) | 2    | 1 GB   | 8 GB  | Document and data work, with the skills repo at `/mnt/skills`. |
| `browser`     | Ubuntu 24.04 LTS   | 4    | 4 GB   | 15 GB | Browser automation with Chrome and `agent-browser`.            |
| `desktop`     | Ubuntu 24.04 LTS   | 4    | 4 GB   | 10 GB | A graphical Xfce desktop with a visible browser.               |

`GET /v1/environment-templates` returns the same list. Saved environments accept
all four; an [on-demand run](/docs/agents/runs) accepts `development` and
`workspace`.

## Programming languages [#programming-languages]

| Language | Version                        | Package manager                             | Templates                             |
| -------- | ------------------------------ | ------------------------------------------- | ------------------------------------- |
| Python   | Distribution `python3`         | pip, uv 0.11.21                             | All (uv is not on `desktop`)          |
| Node.js  | 24.16.0 (22.17.1 on `desktop`) | npm                                         | All                                   |
| Bun      | 1.3.14                         | bun                                         | `development`, `workspace`, `desktop` |
| Go       | 1.26.4                         | go modules                                  | `development`                         |
| Rust     | 1.96.0 (rustup)                | cargo                                       | `development`                         |
| C/C++    | GCC (`build-essential`)        | make; cmake and pkg-config on `development` | `development`, `workspace`, `desktop` |

On `development`, `workspace`, and `browser`, `pip install` and `pip uninstall`
are routed through `uv pip`. Call `python3 -m pip` to reach pip directly.

Java, Ruby, PHP, and Deno are not installed. The images are Debian and Ubuntu,
so `apt-get install` adds them for the life of the sandbox.

### Pre-installed libraries [#pre-installed-libraries]

The `workspace` template carries the libraries its bundled skills depend on:

* **Python**: `anthropic`, `mcp`, `numpy`, `pandas`, `openpyxl`, `lxml`,
  `defusedxml`, `pypdf`, `pdfplumber`, `pdf2image`, `reportlab`, `Pillow`,
  `imageio`, `imageio-ffmpeg`, `pytesseract`, `PyYAML`, `markitdown[pptx]`
* **Node.js**: `docx`, `pptxgenjs`, `sharp`, `react`, `react-dom`, `react-icons`

`development` installs no pip Python libraries, but does carry `Pillow` via the
system `python3-pil` package, and only `esbuild` globally from npm. `desktop`
adds `esbuild` and `typescript`.

## Databases [#databases]

No database server or client is installed on any template. Install one with
`apt-get` when a session needs it, or connect to a
[managed database](/docs/ccp/database) over the network.

## Utilities [#utilities]

### System tools [#system-tools]

* `git` — Version control
* `curl`, `wget` — HTTP clients
* `unzip` — Archive extraction
* `ripgrep` (`rg`) — Fast file search
* `file` — File type detection (`development`, `workspace`, `desktop`; not `browser`)
* `vim` — Text editor (not on `desktop`)
* `net-tools`, `lsof` — Network and process inspection (`lsof` is not on `desktop`)

### Development tools [#development-tools]

* `make`, `gcc`, `g++` — Build toolchain
* `cmake`, `pkg-config`, `protobuf-compiler` — `development` only
* `nginx` — `development` and `workspace`
* `gh` 2.99.0 — GitHub CLI, `development` only
* `ccp` — Clusterbase CLI, on every template except `browser`
* `forge` — Forge CLI, `development` only

### Image tools [#image-tools]

`development`, `workspace`, and `desktop` (not `browser`) carry basic image
inspection and conversion tools:

* ImageMagick (`magick`) — image inspection and conversion
* `webp` (`cwebp`) — WebP encoding

### Document processing [#document-processing]

Installed on `workspace`:

* LibreOffice — Office document conversion
* `pandoc` — Document conversion
* Poppler utilities (`pdftotext`, `pdftoppm`) — PDF processing
* `tesseract` — Optical character recognition

### Browser automation [#browser-automation]

* `agent-browser` 0.31.1 with Chrome for Testing — `browser`
* A visible browser on an Xfce desktop (1440×900), with `xdotool`, `xclip`, and
  `scrot` — `desktop`

`jq`, `ffmpeg`, `tmux`, and `docker` are not installed.

## Sandbox specifications [#sandbox-specifications]

| Property          | Value                                                                                                                  |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Isolation         | Firecracker microVM                                                                                                    |
| Architecture      | x86\_64 (amd64)                                                                                                        |
| Init system       | systemd                                                                                                                |
| User              | `root`                                                                                                                 |
| Working directory | `/home/user` — [git repos](/docs/agents/environments#git-repos) clone here                                             |
| Skills            | `/mnt/skills` — the full repo on `workspace` and `desktop`, the `ccp` skill only on `development`, absent on `browser` |
| Compute and disk  | Fixed by the template — see [Templates](#templates)                                                                    |
| DNS               | `8.8.8.8`, `8.8.4.4`                                                                                                   |
| Network           | `unrestricted` — see [Networking](#networking)                                                                         |

## Idle behavior [#idle-behavior]

A `development` sandbox pauses after 15 minutes without tool calls or traffic to
its preview port. A `desktop` sandbox pauses after 15 minutes with no connected
viewer, control lease, or computer-use activity — see
[Sandboxes](/docs/ccp/sandboxes). Pausing snapshots memory to disk and frees the
VM; the next tool call or connection resumes the same VM with its files,
uncommitted git work, and processes intact.
Compute is not billed while paused. A detached background process does not count
as activity.

## Networking [#networking]

Outbound traffic to the public internet is unrestricted. Private address ranges
(`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `100.64.0.0/10`) and the cloud
metadata endpoint are blocked from inside the sandbox.

Inbound, only ports a template declares are published, each at an
`https://sbx-….` hostname; every other port and the VM's own address stay
private. `development` publishes port `8000` as a public preview. The `desktop`
ports require a short-lived access token.