Skip to main content
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.

Create and resume

sandbox_create takes allow_hosts and allow_sets (the sets of 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.