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 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.mdxindex 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 thechild.+## 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 orderStop accepting new work, end active sessions, close MCP clients, then tear downdiff --git a/docs/content/docs/reference/cua-driver/embedding.mdx b/docs/content/docs/reference/cua-driver/embedding.mdxindex 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 embeddedThe 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 |