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

# MCP server tools

> The twelve tools the Darkbloom sandbox MCP server exposes, with their defaults, output limits, workspace paths, and image-upgrade consent.

`darkbloom-sandbox-cli mcp` exposes these tools to an MCP client. It keeps your
keys, token, and sandbox records in its own process, no tool result contains a
secret, and `sandbox_exec` verifies the boot's attestation exactly as `ssh`
does.

| Tool | What it does |
| - | - |
| `sandbox_create` | Creates a sandbox and waits for it to be ready. |
| `sandbox_sizes` | Lists the sizes this account may create, with prices and platforms. |
| `sandbox_list` | Lists sandboxes and says how many ended ones it left out. |
| `sandbox_status` | Returns one sandbox's state, deadlines, and cost. |
| `sandbox_exec` | Runs a command in the workspace and returns its output. |
| `sandbox_read` | Reads a file. |
| `sandbox_write` | Writes a file. |
| `sandbox_keepalive` | Holds off the idle stop for a duration. |
| `sandbox_extend` | Adds minutes before the boot's maximum. |
| `sandbox_stop` | Stops a sandbox and keeps its workspace. |
| `sandbox_resume` | Boots a stopped sandbox on the same workspace. |
| `sandbox_destroy` | Deletes the sandbox and its workspace. |

## Create and resume

`sandbox_create` takes `allow_hosts` and `allow_sets` (the sets of [network and
egress](https://docs.darkbloom.dev/sandboxes/create-and-connect.md#network-and-egress)) for an allowlist,
and waits for the sandbox to be ready: 45 seconds by default, up to 900 with
`timeout_seconds`, or `wait: false` to return at once. A client that sends
`_meta.progressToken` gets progress while it waits. If the sandbox is still
starting, the tool returns its ID and state, so your agent polls with
`sandbox_status` instead of creating another.

`sandbox_resume` waits the same way. `sandbox_stop` keeps the workspace, and an
idle-stopped sandbox is resumed, not destroyed.

`sandbox_resume` never changes a sandbox's image by itself: when the service
needs an upgrade it explains it and shows the full 64-hex digest of the image
it would boot, and upgrades only when called again with `upgrade_image` set to
exactly that digest. A different or unverifiable digest is refused before
anything is sent.

## List and status

`sandbox_list` leaves ended sandboxes out and says how many
(`ended_omitted`); `include_ended: true` lists them too. `list_full: true` says
the service's list was full (100 sandboxes or more), so older ones may be in
neither.

## Commands and files

Commands and files live in the workspace. `sandbox_exec` starts each command in
the workspace (`/workspace` on Linux, `~/workspace` on macOS; `cwd` names
another directory), and `sandbox_read` and `sandbox_write` take a path that is
absolute, `~/…` (the login's home), or relative to the workspace. Only the
workspace survives a stop: a write outside it says so (the login's `~/.codex`
is a link into the workspace, so it is kept).

## Results sized for a model

`sandbox_exec` keeps 16 KiB of stdout and of stderr by default
(`max_output_bytes`, up to 1 MiB). Of a longer stream it returns the start and
the end, cut between characters, with a line between them that says how much
was left out. A command's output and a file's content are sent once, as JSON
text.

A command that outlives `timeout_seconds` (60 by default, 600 at most) is no
longer waited for but may still run: start long work with `nohup COMMAND > LOG
2>&1 &` and read the log.


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