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.
