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

# Coding agents: MCP, Codex, and computer use

> Give a coding agent access to agent sandboxes over the MCP server, run Codex inside a sandbox, and drive a macOS desktop with OpenAI's computer tool.

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:

```json theme={null}
{
  "mcpServers": {
    "darkbloom-sandbox": {
      "command": "darkbloom-sandbox-cli",
      "args": ["mcp"]
    }
  }
}
```

Codex (`~/.codex/config.toml`):

```toml theme={null}
[mcp_servers.darkbloom-sandbox]
command = "darkbloom-sandbox-cli"
args = ["mcp"]
```

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](https://docs.darkbloom.dev/sandboxes/mcp-tools.md) describes each
one, its defaults, and its limits.

## Run Codex in a sandbox

```sh theme={null}
darkbloom-sandbox-cli codex sbx-… -- "fix the failing test and run it"
```

`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:

```sh theme={null}
darkbloom-sandbox-cli cua run "TASK" --create --platform macos_arm64 --size mac-c4-m8
```

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)](https://docs.darkbloom.dev/sandboxes/create-and-connect.md#the-desktop-vnc).

## Teach the agent when to use a sandbox

The MCP tools say what an agent can do. The [sandbox skill](https://docs.darkbloom.dev/sandboxes/agent-skill.md)
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`.


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