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 desktop host target selection (#2982)

Francesco Bonaccie296dca1a825
diff --git a/docs/content/docs/how-to-guides/driver/expose-mcp-from-desktop-app.mdx b/docs/content/docs/how-to-guides/driver/expose-mcp-from-desktop-app.mdx
index 96c2e574b7..ab053065e2 100644
--- a/docs/content/docs/how-to-guides/driver/expose-mcp-from-desktop-app.mdx
+++ b/docs/content/docs/how-to-guides/driver/expose-mcp-from-desktop-app.mdx
@@ -38,6 +38,29 @@ Screen Recording permission. A gateway, terminal, `open`, or `NSWorkspace`
changes the TCC responsibility chain and cannot lend the app's grants to the
child.
+## Pass MCP configuration to a backend
+
+If the desktop app has a separate Node backend, keep `EmbeddedCuaDriverHost` in
+the Electron main process. Pass the returned MCP configuration through the
+backend's existing bootstrap or IPC channel:
+
+```ts
+const connection = await host.start();
+
+backend.send({
+ type: 'bootstrap',
+ cuaMcp: connection.mcp,
+});
+```
+
+The backend must launch the exact `cuaMcp.command` with `cuaMcp.args` and
+`cuaMcp.environment`. It may pass those values to an agent runtime such as
+Codex. It must not start another embedded host.
+
+After `host.restart()`, send the replacement `connection.mcp` before accepting
+new agent work. Stop old MCP proxies because their private endpoint belongs to
+the previous generation.
+
## Shut down in dependency order
Stop accepting new work, end active sessions, close MCP clients, then tear down
diff --git a/docs/content/docs/reference/cua-driver/embedding.mdx b/docs/content/docs/reference/cua-driver/embedding.mdx
index 08b5e1b8ce..b9db50b1a9 100644
--- a/docs/content/docs/reference/cua-driver/embedding.mdx
+++ b/docs/content/docs/reference/cua-driver/embedding.mdx
@@ -16,6 +16,33 @@ stdio MCP traffic to that daemon; it never executes tools itself.
A complete macOS reference host and demo live in the repo at `libs/cua-driver/rust/examples/embedded-host-macos`.
+## Target forms
+
+Cua Driver integrations have three target forms. Each form has a distinct
+owner and lifecycle:
+
+| Target | Connection contract | Owner |
+| --- | --- | --- |
+| Existing MCP configuration | Launch its configured `command`, `args`, and environment unchanged | The MCP client or user configuration |
+| Existing daemon | `CuaDriver.connect(socketPath)` or `cua-driver mcp --socket <path>` | The process that started the daemon |
+| App-hosted daemon | Start `EmbeddedCuaDriverHost` with an absolute binary path and use the returned `connection` | The permission-owning host app |
+
+The SDK does not scan `PATH`, search installation directories, or choose among
+these targets. The embedding application must select an explicit target. An
+app that starts an embedded host must use the `connection.mcp.command`,
+`connection.mcp.args`, and `connection.mcp.environment` values returned by that
+host instead of reconstructing the proxy invocation.
+
+`EmbeddedDriverHostOptions.binaryPath` / `binary_path` may point to any absolute
+executable path. The path does not determine macOS permission ownership. The
+process that calls `start()` determines the responsibility chain. Packaged
+applications normally keep the executable in their signed resources so the
+nested binary is covered by packaging, signing, and notarization.
+
+An embedded connection belongs to one host generation. After `restart()`, the
+host must replace every SDK client, MCP proxy, and copied MCP configuration
+with values from the new connection.
+
## Launch embedded
The supported SDK host generates a private endpoint, clears unsafe ambient
@@ -133,6 +160,11 @@ gateway / node daemon YourApp.app
└─ cua-driver mcp --socket <private>
```
+An Electron app may pass the returned MCP configuration to a separate backend
+over its existing bootstrap or IPC channel. That backend may launch the MCP
+proxy, but it must not construct `EmbeddedCuaDriverHost` or start the embedded
+daemon on the app's behalf.
+
## What changes
| Behavior | Standalone | Embedded |