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): document the macOS permission grant flow (#2878)

Francesco Bonacci8d172980785e
diff --git a/docs/content/docs/how-to-guides/driver/install.mdx b/docs/content/docs/how-to-guides/driver/install.mdx
index 99e9f3c38e..17afe2e8a3 100644
--- a/docs/content/docs/how-to-guides/driver/install.mdx
+++ b/docs/content/docs/how-to-guides/driver/install.mdx
@@ -105,7 +105,34 @@ Then grant both permissions:
cua-driver permissions grant
```
-That command launches CuaDriver through LaunchServices and waits while you approve Accessibility and Screen Recording in the macOS dialogs.
+That command launches CuaDriver through LaunchServices so macOS attributes the prompts to the app, then waits.
+
+macOS prompts once for Accessibility. Note that it offers **Open System Settings**, not **Allow** — the dialog alone grants nothing:
+
+![The macOS Accessibility Access prompt: “CuaDriver” would like to control this computer using accessibility features, with Open System Settings and Deny buttons](/img/cua-driver/permissions/accessibility-prompt.png)
+
+Clicking **Open System Settings** adds CuaDriver to the Accessibility list, still switched off. Toggle it on:
+
+![CuaDriver listed under Accessibility in System Settings with its toggle switched off](/img/cua-driver/permissions/accessibility-settings.png)
+
+Screen Recording prompts separately, in the same shape:
+
+![The macOS Screen Recording prompt: “CuaDriver” would like to record this computer’s screen and audio, with Open System Settings and Deny buttons](/img/cua-driver/permissions/screen-recording-prompt.png)
+
+Toggle CuaDriver on under **Screen & System Audio Recording** too:
+
+![CuaDriver listed under Screen & System Audio Recording in System Settings with its toggle switched off](/img/cua-driver/permissions/screen-recording-settings.png)
+
+The prompt only registers the app; the toggle is what grants access. macOS may offer to quit and reopen CuaDriver when you flip one — accept, because a changed grant takes effect only after the responsible app fully relaunches. If the daemon does not come back, rerun `open -n -g -a CuaDriver --args serve`.
+
+macOS does not always raise both prompts in one pass. Confirm what landed with `cua-driver permissions status`, and if only one of the two appeared, run the pair again to prompt for the other:
+
+```bash
+open -n -g -a CuaDriver --args serve
+cua-driver permissions grant
+```
+
+If CuaDriver is missing from either list, add it with **+** and pick `/Applications/CuaDriver.app` — see [macOS permissions](/reference/cua-driver/macos-permissions) for recovering a stale registration.
You can also trigger the prompts yourself:
diff --git a/docs/content/docs/tutorials/drive-your-first-app.mdx b/docs/content/docs/tutorials/drive-your-first-app.mdx
index dca326f14c..610ab4436f 100644
--- a/docs/content/docs/tutorials/drive-your-first-app.mdx
+++ b/docs/content/docs/tutorials/drive-your-first-app.mdx
@@ -47,6 +47,35 @@ Use the same one-line installer on every platform; it picks the right path for t
```bash
cua-driver permissions grant
```
+
+ macOS prompts once for each permission. Neither prompt grants anything on its own — both offer **Open System Settings**, not **Allow**:
+
+ ![The macOS Accessibility Access prompt for CuaDriver, offering Open System Settings or Deny](/img/cua-driver/permissions/accessibility-prompt.png)
+
+ ![The macOS Screen Recording prompt for CuaDriver, offering Open System Settings or Deny](/img/cua-driver/permissions/screen-recording-prompt.png)
+
+ Clicking **Open System Settings** adds CuaDriver to that permission's list for you — switched off. Toggling it on is what actually grants access:
+
+ ![CuaDriver listed under Accessibility in System Settings with its toggle switched off](/img/cua-driver/permissions/accessibility-settings.png)
+
+ ![CuaDriver listed under Screen & System Audio Recording in System Settings with its toggle switched off](/img/cua-driver/permissions/screen-recording-settings.png)
+
+ <Callout type="warn">
+ Do this for both **Accessibility** and **Screen & System Audio Recording**; choosing **Deny** leaves the driver unable to see or drive your desktop. macOS may offer to quit and reopen CuaDriver when you flip a toggle — accept, because the driver only picks up a changed grant after a full relaunch. If the daemon does not come back, start it again with `open -n -g -a CuaDriver --args serve`.
+ </Callout>
+
+ macOS does not always raise both prompts in one pass. Check what actually landed:
+
+ ```bash
+ cua-driver permissions status
+ ```
+
+ If one is still missing, run the pair again to prompt for it:
+
+ ```bash
+ open -n -g -a CuaDriver --args serve
+ cua-driver permissions grant
+ ```
</Tab>
<Tab value="Windows">
Requires Windows 10/11 with an interactive desktop session and PowerShell.
diff --git a/docs/next.config.mjs b/docs/next.config.mjs
index fb70a9fa84..fd815ef4ea 100644
--- a/docs/next.config.mjs
+++ b/docs/next.config.mjs
@@ -1,5 +1,5 @@
import { createMDX } from 'fumadocs-mdx/next';
-import { networkInterfaces } from 'node:os';
+import { hostname, networkInterfaces } from 'node:os';
const withMDX = createMDX();
@@ -10,6 +10,14 @@ const localDevOrigins = [
.flat()
.filter((address) => address && !address.internal)
.map((address) => address.address),
+ // networkInterfaces() yields addresses only, so reaching the preview by name
+ // — a Tailscale MagicDNS host, a .local name — otherwise 403s on /_next/*
+ // and the page loads unhydrated: server-rendered HTML, no working sidebar.
+ hostname(),
+ // `**` matches any depth; a plain `*` matches a single segment and so would
+ // miss MagicDNS names like <host>.<tailnet>.ts.net.
+ '**.ts.net',
+ '*.local',
];
/** @type {import('next').NextConfig} */
diff --git a/docs/public/img/cua-driver/permissions/accessibility-prompt.png b/docs/public/img/cua-driver/permissions/accessibility-prompt.png
new file mode 100644
index 0000000000..099c65fbf1
Binary files /dev/null and b/docs/public/img/cua-driver/permissions/accessibility-prompt.png differ
diff --git a/docs/public/img/cua-driver/permissions/accessibility-settings.png b/docs/public/img/cua-driver/permissions/accessibility-settings.png
new file mode 100644
index 0000000000..e915d69cdd
Binary files /dev/null and b/docs/public/img/cua-driver/permissions/accessibility-settings.png differ
diff --git a/docs/public/img/cua-driver/permissions/screen-recording-prompt.png b/docs/public/img/cua-driver/permissions/screen-recording-prompt.png
new file mode 100644
index 0000000000..8a0d572ae9
Binary files /dev/null and b/docs/public/img/cua-driver/permissions/screen-recording-prompt.png differ
diff --git a/docs/public/img/cua-driver/permissions/screen-recording-settings.png b/docs/public/img/cua-driver/permissions/screen-recording-settings.png
new file mode 100644
index 0000000000..1c2593a7e8
Binary files /dev/null and b/docs/public/img/cua-driver/permissions/screen-recording-settings.png differ