Set permissions

Every call, from the CLI, MCP, the SDK, or a daemon, passes the same authorization check inside the runtime before it touches the desktop. The trusted launcher configures it at startup; an agent cannot change it from a tool call, and a running daemon cannot be reconfigured (restart it).

Every call must pass all of these layers, and each can only narrow:

1. Hard invariants, such as self-targeting and protected-host checks.
2. The built-in tool and risk map.
3. Administrator policy, CUA_DRIVER_MANAGED_POLICY_FILE.
4. User policy, CUA_DRIVER_POLICY_FILE.
5. The permission mode.
6. The capability manifest, when configured.
7. A launch grant or host decision for a residual boundary.

Choose a mode#

cua-driver serve \
  --permission-mode bounded \
  --capability-manifest ~/cua-session.yaml \
  --approve-capability-manifest

cua-driver serve --dangerously-bypass-approvals

--permission-mode unrestricted alone fails closed. Add the two manifest flags to standard or unrestricted to narrow them too. On macOS, pass the flags after serve in open -n -g -a CuaDriver --args serve … and use an absolute manifest path.

What standard allows:

Without CLI flags#

cua-driver mcp on Windows and Linux, the Windows autostart task, and embedding hosts read the same settings from the environment:

unrestricted needs both the mode and the bypass variable; bounded needs the manifest and its approval. A missing half fails startup instead of falling back to standard. Anyone who can set these variables sets the mode: protect them like the unit file or task that carries them. To keep a mode across reboots, see Pin a permission mode.

Write a capability manifest#

A manifest is deny by default: a tool must be in allow.tools and every resource it touches must match. It narrows any mode and never widens one.

version: 3
expires_after: 8h
idle_timeout: 30m
 
allow:
  tools:
    - start_session
    - end_session
    - launch_app
    - get_window_state
    - click
    - type_text
    - press_key
    - kill_app
 
resources:
  apps:
    - executable: /usr/bin/example-editor   # macOS: bundle_id: com.example.Editor
      launch: true
      windows: all
      terminate: driver_launched
 
  files:
    read:
      - dir: /data/input
        recursive: true
    write:
      - dir: /data/output
        recursive: true
 
  desktop:
    display: false

• Apps: bundle_id on macOS, an absolute executable on Windows and Linux. terminate: driver_launched only kills a process this runtime started.
• Files: roots are compared by canonical path component; recursive: false allows direct children only.
• desktop.display: true allows full-display capture and screen-coordinate input. Keep it false unless needed.
• expires_after and idle_timeout are optional, but required in bounded.
• Version 1 and 2 manifests still load; their ask.tools entries are denied.

A browser-only manifest:

version: 3
expires_after: 8h
idle_timeout: 30m
 
allow:
  tools:
    - start_session
    - end_session
    - launch_app
    - list_windows
    - browser_prepare
    - get_browser_state
    - browser_navigate
    - browser_click
    - browser_type
    - browser_download
 
resources:
  browser:
    profiles:
      - kind: isolated        # or existing_profile for a logged-in profile
    origins:
      - https://app.example.com
 
  desktop:
    display: false

Test it before unattended use: an allowed call succeeds silently, the same tool against another app, origin, or path returns bounded_resource_outside_manifest, and an unlisted tool returns permission_denied. To point an MCP client at the bounded daemon:

{
  "mcpServers": {
    "cua": {
      "command": "cua-driver",
      "args": ["mcp", "--socket", "/path/to/cua-driver.sock"]
    }
  }
}

Revoke#

cua-driver revoke --session research-1
cua-driver revoke --all

Ending a session removes its grants, browser bindings, recordings, and cursor; its label stays retired until start_session declares it again. revoke --all suspends the whole runtime (calls return authorization_suspended) until you restart it.

Restrict tools with a policy#

A policy file limits which tools an agent may call and with which arguments. It is deny by default once set, loaded once at startup, and a missing or invalid file stops the daemon from starting.

allow:
  tools:                       # allowed with any arguments
    - screenshot
    - get_window_state
    - list_apps
    - list_windows
    - click
    - press_key
    - wait
  rules:                       # allowed when every constraint passes
    - tool: type_text
      constraints:
        text:
          max_length: 500
          pattern: "^[\\x20-\\x7E\\n\\t]*$"
    - tool: scroll
      constraints:
        amount:
          min: -20
          max: 20
    - tool: launch_app
      constraints:
        bundle_id:
          allowed: ["com.apple.Safari", "com.google.Chrome"]
deny:
  tools:                       # checked first
    - shell_execute

Evaluation: deny.tools → allow.tools → any matching allow.rules entry → deny. Constraint checks are min, max, max_length, pattern (RE2 syntax), and allowed. allow and deny also accept a flat list of names. type_text_chars is normalized to type_text.

CUA_DRIVER_POLICY_FILE=~/.cua-driver/policy.yaml cua-driver serve

cua-driver call shell_execute '{"command":"echo hello"}'
# Error: tool 'shell_execute' is explicitly denied

For programmable rules, point the variable at a .rego file, or a directory of .rego files loaded in filename order. The rule data.cua.policy.allow must be a boolean; undefined denies. The input is {"server": "cua-driver", "tool": "<name>", "arguments": {…}}:

package cua.policy
 
import rego.v1
 
safe_tools := {"screenshot", "get_window_state", "list_apps", "list_windows", "click", "press_key", "wait"}
 
allow if {
    input.tool in safe_tools
}
 
allow if {
    input.tool == "type_text"
    count(input.arguments.text) <= 500
}

A managed policy (CUA_DRIVER_MANAGED_POLICY_FILE) uses the same formats; a call must pass both. cua-driver status shows a hash of each loaded policy. Policies decide which calls run. They do not filter responses, rate-limit, or authenticate callers, and code running inside the runtime's process can bypass them. A browser browser_navigate host allowlist also cannot stop a page from redirecting after a click.

Host authorization#

An embedding app can install a DriverAuthorizationHost callback to decide residual standard boundaries itself, and a DriverActivityObserver for content-free events (see Use the SDK). Without a grant or callback, a residual boundary returns authorization_required; Cua never shows its own modal. Same-user code and malware on the same desktop are outside this boundary.