# Headless agents

Run codex exec, claude -p and other agents with no one at the keyboard.

A headless agent runs with no one at the keyboard to sign in or approve a tool call. Sign in once interactively on the same machine first ([MCP server](/docs/mcp)); the app keeps that sign-in for headless runs.

## Codex (`codex exec`)

Headless Codex never asks for approval, so it refuses every box tool that can change something (clicks, typing, the shell). Approve box's tools for one run:

```bash
codex exec -c 'mcp_servers.box.default_tools_approval_mode="approve"' "Use box to take a screenshot"
```

To keep it, add `default_tools_approval_mode = "approve"` under `[mcp_servers.box]` in `~/.codex/config.toml`. Codex then runs every box tool without asking, also in interactive chats, and anything your AI reads on a web page can steer the box's browser and shell. Keep deleting or resetting a box behind a prompt:

```toml
[mcp_servers.box]
url = "https://mcp.box.simular.ai/mcp"
default_tools_approval_mode = "approve"

[mcp_servers.box.tools.box_delete]
approval_mode = "prompt"
```

Don't use `--dangerously-bypass-approvals-and-sandbox` for this: it also turns off Codex's sandbox on your own computer.

## Claude Code (`claude -p`)

Headless Claude Code can't ask for permission either, so allow box's tools for the run with `--allowedTools` and the server's prefix: `mcp__box` for a server you added in Claude Code as `box`, every tool of it, the shell included. Put the prompt right after `-p`: `--allowedTools` takes a list, and a prompt after it is read as one more tool name.

```bash
claude -p "Use box to take a screenshot" --allowedTools mcp__box
```

If you added box only as a connector on claude.ai, its tools are named `mcp__claude_ai_box__…`, so allow `mcp__claude_ai_box` instead.

If you added box both ways, Claude Code loads only the one you added in Claude Code and drops the claude.ai connector. A headless run can't open a browser to sign that one in, so sign it in interactively on the same machine first (`/mcp` in Claude Code).

## CI machines

On a CI machine where nobody can sign in, use a personal key from [https://box.simular.ai/keys](https://box.simular.ai/keys) in a config file, kept in an environment variable rather than in the file. For Claude Code:

```json
{
  "mcpServers": {
    "box": {
      "type": "http",
      "url": "https://mcp.box.simular.ai/mcp",
      "headers": { "Authorization": "Bearer ${BOX_TOKEN}" }
    }
  }
}
```

```bash
claude -p "Use box to take a screenshot" --strict-mcp-config --mcp-config box-mcp.json --allowedTools mcp__box
```

`--strict-mcp-config` uses only the servers in that file. Keep the key in your CI's secret store, and revoke it at [https://box.simular.ai/keys](https://box.simular.ai/keys) when the job no longer needs it.