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): point users to permission modes before daemon start (#2945)

Francesco Bonaccia24302305c75
diff --git a/docs/content/docs/how-to-guides/driver/connect-your-agent.mdx b/docs/content/docs/how-to-guides/driver/connect-your-agent.mdx
index bb9b14a28b..f601eeca20 100644
--- a/docs/content/docs/how-to-guides/driver/connect-your-agent.mdx
+++ b/docs/content/docs/how-to-guides/driver/connect-your-agent.mdx
@@ -28,6 +28,35 @@ cua-driver permissions status
See [Install Cua Driver](/how-to-guides/driver/install) and [macOS permissions](/reference/cua-driver/macos-permissions) for setup details.
+## Decide the permission mode first
+
+Registering the server does not choose an authorization
+[permission mode](/reference/cua-driver/permission-modes) — the process that owns
+the driver runtime does, at launch. Every config below therefore runs in the
+default `standard` mode unless you change that process.
+
+- **macOS:** `cua-driver mcp` proxies to the `CuaDriver.app` daemon to keep TCC
+ attribution with the app, so that daemon's launch flags decide the mode. Start
+ it in the mode you want before the client connects, and use
+ [autostart](/how-to-guides/driver/keep-running#pin-a-permission-mode) to make
+ that stick.
+- **Windows and Linux:** bare `cua-driver mcp` owns its own runtime and has no
+ `--permission-mode` flag. Either set `CUA_DRIVER_PERMISSION_MODE` — plus
+ `CUA_DRIVER_SESSION_POLICY_FILE` and `CUA_DRIVER_SESSION_POLICY_APPROVED` for
+ `bounded` — in the client's `env` block, or run a `cua-driver serve` daemon in
+ that mode and point the client at it with `--socket`.
+
+`--grant existing-profile` is the one authorization flag `cua-driver mcp` accepts
+directly, and it applies only to a runtime this command launches. An agent cannot
+widen any of this from a tool call.
+
+<Callout type="warn">
+ A `standard`-mode runtime allows input against every application on the
+ desktop. If an agent should reach only a reviewed set of apps, origins, and
+ directories, register it against a `bounded` runtime instead — see [Write a
+ bounded manifest](/how-to-guides/driver/write-a-bounded-manifest).
+</Callout>
+
## Generate the client config
Use `mcp-config` to print the registration command or JSON for a supported client:
diff --git a/docs/content/docs/how-to-guides/driver/install.mdx b/docs/content/docs/how-to-guides/driver/install.mdx
index 5968fc25cc..006b6d8154 100644
--- a/docs/content/docs/how-to-guides/driver/install.mdx
+++ b/docs/content/docs/how-to-guides/driver/install.mdx
@@ -91,6 +91,42 @@ cua-driver doctor
`doctor` checks the version, install layout, and telemetry setup on every platform. It also runs platform probes for TCC on macOS, the interactive session on Windows, and AT-SPI plus the display server on Linux.
+## Choose a permission mode
+
+Cua Driver authorizes every agent action inside the native runtime, and the mode is fixed when that runtime starts. An agent cannot change it, and neither can you change it on a running daemon — you restart the daemon with different flags. Decide which mode you want before starting the daemon below.
+
+| Mode | Use it when |
+| ---- | ----------- |
+| `standard` | Normal local CLI and MCP use. Observation, input, isolated browser use, recording, and validated file transfer run without prompts. Residual boundaries, such as attaching to an existing logged-in Chromium profile, still need an explicit grant. |
+| `bounded` | An unattended agent, gateway, or embedded application must stay inside a reviewed manifest of tools, applications, browser origins, and directories. Anything outside the manifest is denied. |
+| `unrestricted` | The machine is disposable or fully trusted and you accept every capability the built-in, managed, and user policy ceilings still allow. |
+
+`standard` is the default and is what the rest of this guide assumes, so plain `cua-driver serve` needs no flags. For `bounded`, pass a manifest plus the review acknowledgement:
+
+```bash
+cua-driver serve \
+ --permission-mode bounded \
+ --session-policy ~/cua-session.yaml \
+ --approve-session-policy
+```
+
+For `unrestricted`, pass the dangerous acknowledgement. `--permission-mode unrestricted` on its own fails closed:
+
+```bash
+cua-driver serve --dangerously-bypass-approvals
+```
+
+On macOS, put those flags after `serve` in the app-bundle launch so TCC attribution stays with `CuaDriver.app`. The manifest path must resolve on its own: your shell expands `~` before `open` sees it, but a relative path fails, because an app started by `open` does not inherit the shell's working directory.
+
+```bash
+open -n -g -a CuaDriver --args serve \
+ --permission-mode bounded \
+ --session-policy ~/cua-session.yaml \
+ --approve-session-policy
+```
+
+See [Permission modes](/reference/cua-driver/permission-modes) for exactly what each mode allows, and [Write a bounded manifest](/how-to-guides/driver/write-a-bounded-manifest) for a tested manifest. To keep a non-default mode across reboots, its flags belong in the autostart entry — see [Pin a permission mode](/how-to-guides/driver/keep-running#pin-a-permission-mode).
+
## Grant TCC permissions (macOS only)
**Start the daemon first** so macOS attributes the TCC request to `CuaDriver.app` instead of your terminal:
@@ -154,6 +190,7 @@ cua-driver permissions status
## Next steps
+- [Permission modes](/reference/cua-driver/permission-modes): what standard allows, and how bounded and unrestricted differ.
- [Install the Cua Driver agent skill](/how-to-guides/driver/install-agent-skill): add the cross-platform instructions from ClawHub or install them directly for another agent.
- [Keep Cua Driver running](/how-to-guides/driver/keep-running): configure autostart so the daemon comes back after reboots.
- [Connect Cua Driver to an MCP client](/how-to-guides/driver/connect-your-agent): register it with Claude Code, Cursor, Codex, and other clients.
diff --git a/docs/content/docs/how-to-guides/driver/keep-running.mdx b/docs/content/docs/how-to-guides/driver/keep-running.mdx
index 863bae3aaf..614e4341df 100644
--- a/docs/content/docs/how-to-guides/driver/keep-running.mdx
+++ b/docs/content/docs/how-to-guides/driver/keep-running.mdx
@@ -13,6 +13,12 @@ it running when you use those interfaces. Applications that import
`CuaDriver.create()` execute through the same-process SDK and do not need this
setup.
+Every entry below starts the daemon in the default `standard`
+[permission mode](/reference/cua-driver/permission-modes). The mode is fixed at
+launch, so a `bounded` or `unrestricted` daemon needs that configuration in the
+autostart entry itself — see [Pin a permission
+mode](#pin-a-permission-mode).
+
<Tabs items={['macOS', 'Windows', 'Linux']}>
<Tab value="macOS">
@@ -142,6 +148,93 @@ A headless box has no `graphical-session.target`, so on those machines also chan
</Tab>
</Tabs>
+## Pin a permission mode
+
+`--permission-mode`, `--session-policy`, `--approve-session-policy`, and
+`--dangerously-bypass-approvals` are read once, when the daemon starts. Put them
+in the autostart entry so an unattended restart comes back in the same mode
+instead of falling back to `standard`.
+
+<Tabs items={['macOS', 'Windows', 'Linux']}>
+ <Tab value="macOS">
+
+Add each flag as its own `<string>` inside `ProgramArguments`, after `serve`:
+
+```xml
+<key>ProgramArguments</key>
+<array>
+ <string>/Applications/CuaDriver.app/Contents/MacOS/cua-driver</string>
+ <string>serve</string>
+ <string>--permission-mode</string>
+ <string>bounded</string>
+ <string>--session-policy</string>
+ <string>/Users/you/cua-session.yaml</string>
+ <string>--approve-session-policy</string>
+</array>
+```
+
+`launchd` does not expand `~` or run a shell, so the manifest path must be
+absolute. Reload the agent after editing:
+
+```bash
+launchctl unload ~/Library/LaunchAgents/com.trycua.cua-driver.plist
+launchctl load ~/Library/LaunchAgents/com.trycua.cua-driver.plist
+```
+
+ </Tab>
+ <Tab value="Windows">
+
+`cua-driver autostart enable` always registers a bare `serve` command and has no
+mode flags, so configure the equivalent User-scope environment variables. The
+Scheduled Task inherits them at logon:
+
+```powershell
+setx CUA_DRIVER_PERMISSION_MODE bounded
+setx CUA_DRIVER_SESSION_POLICY_FILE "$env:USERPROFILE\cua-session.yaml"
+setx CUA_DRIVER_SESSION_POLICY_APPROVED 1
+```
+
+`setx` affects new processes only, so restart the daemon for the change to take
+effect:
+
+```powershell
+cua-driver stop
+cua-driver autostart kick
+```
+
+ </Tab>
+ <Tab value="Linux">
+
+Extend `ExecStart` in `~/.config/systemd/user/cua-driver.service`:
+
+```ini
+ExecStart=%h/.local/bin/cua-driver serve --permission-mode bounded --session-policy %h/cua-session.yaml --approve-session-policy
+```
+
+Then reload and restart the unit:
+
+```bash
+systemctl --user daemon-reload
+systemctl --user restart cua-driver.service
+```
+
+ </Tab>
+</Tabs>
+
+Every form is trusted launch configuration: anyone who can edit the plist, the
+Scheduled Task, the systemd unit, or those environment variables can change the
+mode the daemon comes back in. Bad configuration fails startup rather than
+silently downgrading to `standard` — a bounded daemon with no approved manifest,
+or `unrestricted` without its acknowledgement, does not bind its action socket
+at all. Confirm the daemon is up, then make one call your manifest does not
+allow and check that it is refused:
+
+```bash
+cua-driver status
+cua-driver call <a tool outside allow.tools> '{}'
+# Error: ...
+```
+
## Verify it's running
```bash
diff --git a/docs/content/docs/reference/cua-driver/permission-modes.mdx b/docs/content/docs/reference/cua-driver/permission-modes.mdx
index 75b0620e23..276052018e 100644
--- a/docs/content/docs/reference/cua-driver/permission-modes.mdx
+++ b/docs/content/docs/reference/cua-driver/permission-modes.mdx
@@ -52,6 +52,40 @@ Passing `--permission-mode unrestricted` without
remains a configuration alias for `unrestricted`. New integrations should use
the canonical names.
+## Configure a mode without CLI flags
+
+The mode is read once, when the runtime that owns the driver starts. Only
+`cua-driver serve` takes the flags above. A launcher that cannot pass them —
+`cua-driver mcp` owning its own runtime on Windows and Linux, a Windows
+Scheduled Task registered by `cua-driver autostart enable`, or an embedding
+host — uses the equivalent environment variables:
+
+| Flag | Environment variable |
+| --- | --- |
+| `--permission-mode <mode>` | `CUA_DRIVER_PERMISSION_MODE=<mode>` |
+| `--session-policy <path>` | `CUA_DRIVER_SESSION_POLICY_FILE=<path>` |
+| `--approve-session-policy` | `CUA_DRIVER_SESSION_POLICY_APPROVED=1` |
+| `--dangerously-bypass-approvals` | `CUA_DRIVER_DANGEROUSLY_BYPASS_APPROVALS=1` |
+
+The variables accept `1`, `true`, `yes`, or `on` for their boolean form. The CLI
+flag normalizes mode plus acknowledgement in one step; the environment form does
+not, so `unrestricted` requires `CUA_DRIVER_PERMISSION_MODE=unrestricted` **and**
+`CUA_DRIVER_DANGEROUSLY_BYPASS_APPROVALS=1`, and `bounded` requires both the
+policy file and its approval. Missing halves fail startup instead of downgrading
+to `standard`.
+
+`CUA_DRIVER_SESSION_POLICY_FILE` and `CUA_DRIVER_SESSION_POLICY_APPROVED` are
+rejected in `standard` and `unrestricted` mode, so a stale exported variable
+prevents startup rather than applying silently.
+
+These variables are trusted launch configuration on the same footing as the
+flags. Whoever can write them for the daemon's environment sets its mode, so
+treat them like the plist, unit file, or Scheduled Task that carries them. An
+agent tool call can never set them.
+
+A running daemon's mode cannot be changed. Stop it and start it again with the
+configuration you want.
+
## What standard allows
Standard mode is designed to preserve practical autonomous workflows. It does
diff --git a/docs/content/docs/tutorials/drive-your-first-app.mdx b/docs/content/docs/tutorials/drive-your-first-app.mdx
index df5c10c227..51ae4228b8 100644
--- a/docs/content/docs/tutorials/drive-your-first-app.mdx
+++ b/docs/content/docs/tutorials/drive-your-first-app.mdx
@@ -96,7 +96,7 @@ Use the same one-line installer on every platform; it picks the right path for t
</Tabs>
<Callout type="info">
- Full install steps, PATH setup, and permission details live in the install guide. See [Install Cua Driver](/how-to-guides/driver/install).
+ Full install steps, PATH setup, and permission details live in the install guide. See [Install Cua Driver](/how-to-guides/driver/install). The daemon you just started runs in the default `standard` authorization mode, which is the right choice for this tutorial; once you move past Calculator, read [Permission modes](/reference/cua-driver/permission-modes) to decide whether a real workload should be `bounded` instead.
</Callout>
## 2. Verify it is working
diff --git a/libs/cua-driver/README.md b/libs/cua-driver/README.md
index c0d9b8bba2..7860ff867d 100644
--- a/libs/cua-driver/README.md
+++ b/libs/cua-driver/README.md
@@ -26,6 +26,12 @@ runtime-neutral agent boundary.
only the tools and resources in a reviewed manifest. `unrestricted` requires
`--dangerously-bypass-approvals`.
+The mode belongs to the process that owns the runtime and is fixed at launch:
+`cua-driver serve` takes the flags, `cua-driver mcp` and embedding hosts use the
+matching `CUA_DRIVER_PERMISSION_MODE`, `CUA_DRIVER_SESSION_POLICY_FILE`, and
+`CUA_DRIVER_SESSION_POLICY_APPROVED` variables. Choose it before starting the
+daemon; a running daemon must be restarted to change it.
+
Attaching to an existing logged-in Chromium profile remains explicit:
```bash