Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
docs(cua-driver): clarify macOS TCC launch modes (#2187)
injaneity740806ca01f9
diff --git a/docs/content/docs/reference/cua-driver/process-model.mdx b/docs/content/docs/reference/cua-driver/process-model.mdxindex 1a74caf4b5..9776b05c1c 100644--- a/docs/content/docs/reference/cua-driver/process-model.mdx+++ b/docs/content/docs/reference/cua-driver/process-model.mdx@@ -23,6 +23,15 @@ The **daemon-proxy pattern** separates the process that speaks to the caller froOn macOS, the root issue is **TCC**, Transparency Consent and Control. Accessibility and Screen Recording grants are attached to a specific app identity, represented by a bundle ID. Grants to `CuaDriver.app` do not automatically cover every subprocess named `cua-driver`.+## Supported macOS launch modes++Use one of two supported identities:++- **Standalone:** grant permissions to the installed `CuaDriver.app` and launch its daemon through LaunchServices. See [macOS permissions](/reference/cua-driver/macos-permissions).+- **Embedded:** have the macOS app that owns the grants spawn `cua-driver` directly with `CUA_DRIVER_EMBEDDED=1` or `--embedded`. See [Embedding](/reference/cua-driver/embedding).++A raw `cua-driver` binary launched outside `CuaDriver.app` without embedded mode has no stable TCC identity and is unsupported. Do not grant permissions to arbitrary binary paths or use that configuration in production.+If an IDE terminal starts `cua-driver` directly, macOS attributes that subprocess to the terminal app's bundle, not to `CuaDriver.app`. The binary is right, but the privacy identity is wrong.The daemon path fixes the attribution. The daemon is launched through LaunchServices with `open -n -g -a CuaDriver`, so macOS treats it as part of `CuaDriver.app`. The MCP stdio process remains where the assistant spawned it, but becomes a thin proxy: it forwards tool calls to the daemon over a Unix socket and returns the daemon's responses. There are two processes, but one tool surface.diff --git a/libs/cua-driver/README.md b/libs/cua-driver/README.mdindex 3fe6be4dfe..aec31a136b 100644--- a/libs/cua-driver/README.md+++ b/libs/cua-driver/README.md@@ -43,3 +43,12 @@ claude mcp add --transport stdio cua-computer-use -- cua-driver mcp --claude-codThis keeps CuaDriver's normal MCP tools and changes only `screenshot`, which requires `pid` and `window_id` and captures that window only.Use MCP for this Claude Code vision/computer-use-style path. CLI screenshots still work as CuaDriver calls, but they do not expose the `mcp__cua-computer-use__screenshot` tool name that Claude Code appears to use as the image-grounding cue.++## macOS process identity and permissions++macOS attributes Accessibility and Screen Recording grants to a responsible app identity, not simply to an executable path. Use one of these supported launch modes:++- **Standalone:** install `CuaDriver.app`, grant permissions to it, and start its daemon with `open -n -g -a CuaDriver --args serve`. The installed `cua-driver mcp` CLI may proxy through this daemon automatically.+- **Embedded:** have the macOS app that owns the grants spawn the driver directly with `CUA_DRIVER_EMBEDDED=1` (or `--embedded`). This keeps the driver in that app's responsibility chain, so it inherits the app's grants. A gateway, terminal, or unrelated helper must not spawn it on the app's behalf.++Directly spawning a raw `cua-driver` binary outside `CuaDriver.app` without embedded mode is unsupported: it has no stable bundle identity for TCC attribution. Do not grant permissions to arbitrary binary paths or rely on that configuration in production. See [`rust/Skills/cua-driver/EMBEDDING.md`](rust/Skills/cua-driver/EMBEDDING.md) for the embedding contract and examples.diff --git a/libs/cua-driver/rust/Skills/cua-driver/README.md b/libs/cua-driver/rust/Skills/cua-driver/README.mdindex 44615f8ffc..d75012c9ca 100644--- a/libs/cua-driver/rust/Skills/cua-driver/README.md+++ b/libs/cua-driver/rust/Skills/cua-driver/README.md@@ -79,6 +79,21 @@ forbidden-list / launch / click details.relevant panes of System Settings after first use; toggle it onthere.+ There are exactly two supported macOS identity models:+ - **Standalone:** launch the installed app daemon with+ `open -n -g -a CuaDriver --args serve`; grants belong to+ `CuaDriver.app` (`com.trycua.driver`). The installed CLI may+ auto-launch and proxy through this daemon.+ - **Embedded:** the app that owns the grants must spawn+ `cua-driver mcp` directly with `CUA_DRIVER_EMBEDDED=1` (or+ `--embedded`), so the child remains in that app's TCC+ responsibility chain. See `EMBEDDING.md`.++ A raw binary launched outside `CuaDriver.app` without embedded mode+ is unsupported because it has no stable bundle identity for TCC+ attribution. Do not grant permissions to arbitrary binary paths or+ use that configuration in production.+### Windows1. **Windows 10/11** (any edition with PowerShell 5.1+).