Skip to main content
A sandbox is useful to a coding agent only if the agent can create it, run commands in it, and clean it up. Darkbloom provides three ways to do that: an MCP server any MCP client can launch, a codex command that runs Codex inside the sandbox, and computer use for macOS desktops.

The MCP server

darkbloom-sandbox-cli mcp is a Model Context Protocol server on standard input and output. It uses your login and 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. Claude Desktop (claude_desktop_config.json), or any MCP client that runs a command:
Codex (~/.codex/config.toml):
The server exposes sandbox_create, sandbox_sizes, sandbox_list, sandbox_status, sandbox_exec, sandbox_read, sandbox_write, sandbox_keepalive, sandbox_extend, sandbox_stop, sandbox_resume, and sandbox_destroy. MCP server tools describes each one, its defaults, and its limits.

Run Codex in a sandbox

codex attests the boot (once per boot), then runs codex app-server in the guest over the same SSH channel and drives it with your task. There is no network port: prompts and approvals stay on your terminal, and a humanCommand checkpoint is never auto-approved. --json emits one JSON event per item on stdout while prompts stay on stderr. Useful options include --cwd PATH for the working directory, --model NAME for the model, --approval-policy (untrusted, on-request, or never), --thread ID to continue a session, and --max-wall SECONDS and --max-steps N to bound a run.

Computer use

For a macOS desktop, cua run drives the sandbox with OpenAI’s computer tool until the task completes:
It prints one line per action batch, keeps screenshots in a private temporary directory (--screenshot-dir DIR keeps them elsewhere), writes a JSONL transcript (--transcript PATH), and enforces hard step, wall-clock, token, and cost limits. It asks for confirmation before typing (unless you pass --allow-typing-secrets) and before quitting or closing an application. --create makes a sandbox and stops it if the run is cancelled or fails; it needs --platform macos_arm64, because computer use does. --sandbox sbx-… uses one this client created and leaves it running on success (--ephemeral stops it on success too). The API key comes from --api-key-file or OPENAI_API_KEY; --api-base defaults to https://api.openai.com/v1 (OPENAI_BASE_URL). mcp-cua sbx-… exposes the same computer-use control to an MCP client: it attests the boot (once per boot), then serves the Model Context Protocol on standard input and output for the guest’s computer-use agent, over an SSH stream-local forward. There is no TCP listener: the local end is a Unix socket, and MCP itself is stdio. On macOS, the desktop locks after 20 minutes without input unless a CLI connection has turned the lock off earlier in the boot. vnc, cua run, and mcp-cua tell you when the screen is locked already; see the desktop (VNC).

Teach the agent when to use a sandbox

The MCP tools say what an agent can do. The sandbox skill says when offloading pays off, how to push code without putting a token in a sandbox, what keeps a long build alive, and to stop what it started. Install it as .claude/skills/darkbloom-sandboxes/SKILL.md.