Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

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.mdx
index 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 fro
On 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.md
index 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-cod
This 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.md
index 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 on
there.
+ 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.
+
### Windows
1. **Windows 10/11** (any edition with PowerShell 5.1+).