diff --git a/docs/content/docs/cua-driver/guide/getting-started/autostart.mdx b/docs/content/docs/cua-driver/guide/getting-started/autostart.mdx index a2fd7c9617..13789762b9 100644 --- a/docs/content/docs/cua-driver/guide/getting-started/autostart.mdx +++ b/docs/content/docs/cua-driver/guide/getting-started/autostart.mdx @@ -19,8 +19,20 @@ cua-driver autostart disable # remove the entry | Platform | Mechanism | Where it lives | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | Windows | Scheduled Task `cua-driver-serve` with `LogonType: Interactive` | Task Scheduler (`schtasks /Query /TN cua-driver-serve`) | -| macOS | Not yet implemented in the Rust port — use the manual `LaunchAgent` recipe ([`scripts/install-local.sh --autostart`](https://github.com/trycua/cua/blob/main/libs/cua-driver/scripts/install-local.sh)) | `~/Library/LaunchAgents/com.trycua.cua-driver-rs.plist` | -| Linux | Not yet implemented in the Rust port — use the manual `systemd --user` unit ([`scripts/install-local.sh --autostart`](https://github.com/trycua/cua/blob/main/libs/cua-driver/scripts/install-local.sh)) | `~/.config/systemd/user/cua-driver-rs.service` | +| macOS | Not yet in the `cua-driver autostart` verb — use `install-local.sh --autostart`, which writes a `RunAtLoad` + `KeepAlive` LaunchAgent running `cua-driver serve` ([`scripts/install-local.sh`](https://github.com/trycua/cua/blob/main/libs/cua-driver/scripts/install-local.sh)) | `~/Library/LaunchAgents/com.trycua.cua-driver.plist` | +| Linux | Not yet in the `cua-driver autostart` verb — use `install-local.sh --autostart`, which writes a `systemd --user` unit ([`scripts/install-local.sh`](https://github.com/trycua/cua/blob/main/libs/cua-driver/scripts/install-local.sh)) | `~/.config/systemd/user/cua-driver-rs.service` | + + + **macOS bonus — autostart fixes TCC attribution.** A LaunchAgent daemon is started by `launchd`, + so it's attributed to `com.trycua.driver` (not the terminal that would otherwise spawn it). That + means permission prompts say "Cua Driver", you grant **Accessibility + Screen Recording once**, + and the grants persist across reboots — every `cua-driver call` / `mcp` then routes through the + always-on, correctly-attributed daemon. Without autostart, a prompt raised from a terminal + attributes to the terminal and the grant never applies to the driver — run + `cua-driver permissions status` to see which identity your grants belong to, or + `cua-driver permissions grant` to grant correctly without autostart. Autostart stays opt-in + because a standing computer-control daemon with these grants is a deliberate choice, not a default. + **Platform parity status.** `cua-driver autostart` is currently a Windows-only verb in the Rust diff --git a/libs/cua-driver/scripts/_install-local-rust.sh b/libs/cua-driver/scripts/_install-local-rust.sh index 719fdd3fd8..a0c523b427 100755 --- a/libs/cua-driver/scripts/_install-local-rust.sh +++ b/libs/cua-driver/scripts/_install-local-rust.sh @@ -100,6 +100,10 @@ while [ "$#" -gt 0 ]; do echo " --autostart Also register a logon-time daemon:" echo " macOS: LaunchAgent under ~/Library/LaunchAgents" echo " Linux: systemd --user unit" + echo " On macOS this also fixes TCC: a launchd-started daemon" + echo " is attributed to com.trycua.driver (not your terminal)," + echo " so you grant Accessibility + Screen Recording once and" + echo " every cua-driver call/mcp routes through it correctly." echo " --help Show this help." echo "" echo "Examples:" @@ -426,7 +430,11 @@ fi if [ "$INSTALL_AUTOSTART" != true ]; then echo "" if [ "$OS" = "Darwin" ]; then - echo "Auto-start (optional): re-run with --autostart to register a LaunchAgent." + echo "Auto-start (recommended on macOS): re-run with --autostart to register a LaunchAgent." + echo " A launchd-started daemon is attributed to com.trycua.driver (not your terminal)," + echo " so permission prompts say \"Cua Driver\" and grants stick — grant Accessibility +" + echo " Screen Recording once and every cua-driver call/mcp routes through it correctly." + echo " (Without it, a prompt raised from a terminal attributes to the terminal instead.)" else echo "Auto-start (optional): re-run with --autostart to register a systemd user unit." fi