Configure coding agents

These options extend Run a coding agent in a sandbox. The examples are regions of examples/agents-in-sandboxes/tour.py.

Give the agent MCP servers#

Every run gets the sandbox's own MCP tools (cua-driver: screen, input, windows) unless sandbox_mcp=False or the harness cannot take them (Pi has no MCP client, Hermes and OpenClaw read MCP only from their own config; Antigravity is off by default, see the table). Add more with mcp_servers: a URL (streamable HTTP, as reachable from inside the sandbox) or a command (stdio, run in the sandbox). Header values may be secrets; they are handled like keys.

run = await agents.run(
    "openai-codex",
    "Use the docs server to look up our API style guide, then review api.py.",
    cua.AgentRunOptions(
        env_from_host=["OPENAI_API_KEY"],
        mcp_servers=[
            cua.AgentRunMcpServer(name="docs", url="https://mcp.example.com/mcp",
                                  headers={"Authorization": "Bearer <token>"}),
            cua.AgentRunMcpServer(name="fs", command="npx",
                                  args=["-y", "@modelcontextprotocol/server-filesystem", "/srv"]),
        ],
        exit_when_idle=True,
    ),
)

cua agent run local:dev openai-codex "Review api.py" --env-from-host OPENAI_API_KEY \
  --mcp docs=https://mcp.example.com/mcp --no-sandbox-mcp

Use a custom endpoint or proxy#

base_url points the harness at a gateway, proxy or compatible server; wire picks its format (anthropic, openai-responses, openai-chat, gemini) when it differs from the harness's own.

run = await agents.run(
    "claude-code",
    "Summarize the repository in five bullet points.",
    cua.AgentRunOptions(
        env={"ANTHROPIC_API_KEY": "<gateway key>"},
        base_url="https://llm-gateway.internal.example.com",
        model="claude-sonnet-4-5",
        exit_when_idle=True,
    ),
)

cua agent run local:dev claude-code "Summarize the repository" \
  --env-from-host ANTHROPIC_API_KEY --base-url https://llm-gateway.internal.example.com \
  --model <model-id>

Harnesses#

cua agent harnesses

import json
 
import cua
 
print([h["id"] for h in json.loads(cua.agent_harnesses())])
# ['claude-code', 'openai-codex', 'gemini-cli', 'google-antigravity', 'opencode', 'goose', 'pi', 'hermes', 'openclaw']

cua agent harnesses (or cua.agent_harnesses()) prints the full record: what each installs, its interactive CLI, and known limits.

Credentials#

• Keys reach a run only as explicit per-run env (env, env_from_host, --env-from-host). They are written with mode 0600 in the run's directory, redacted from its event log, and never passed in argv.
• Nothing is copied from your machine's agent config (~/.claude, ~/.codex, and so on).
• To use a signed-in session instead of a key, move it with teleport (claude-code is a built-in app), which shows what will move and asks for approval first.
• See also Pass secrets safely.

Event kinds#

Each event has seq, turn, kind, optional text and tool fields, a one-line line rendering, and json (the raw record, ACP payload included).