Skip to content

docs(cua-driver-rs): sell --autostart's TCC benefit on macOS (grant once) #1766

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
f-trycua merged 1 commit into from
May 30, 2026
Merged

docs(cua-driver-rs): sell --autostart's TCC benefit on macOS (grant once) #1766

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 14 additions & 2 deletions docs/content/docs/cua-driver/guide/getting-started/autostart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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` |

<Callout type="info">
**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.
</Callout>

<Callout type="info">
**Platform parity status.** `cua-driver autostart` is currently a Windows-only verb in the Rust
Expand Down
10 changes: 9 additions & 1 deletion libs/cua-driver/scripts/_install-local-rust.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:"
Expand Down Expand Up @@ -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
Expand Down
Loading