Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/trycua/cua/llms.txt

Use this file to discover all available pages before exploring further.

Cua Driver runs as a background daemon that lets agents drive native apps on your desktop without stealing focus or interrupting your work. The same one-line installer works on macOS, Windows, and Linux and does not require administrator access.
Cua Driver sends content-free product telemetry by default. The installer shows this notice before the first event. Run cua-driver telemetry disable at any time to stop it; the preference persists across upgrades.

​
Install the daemon

Requirements: macOS 14 (Sonoma) or later on Apple Silicon or Intel.
/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"
The installer places CuaDriver.app in /Applications and creates the ~/.local/bin/cua-driver symlink. The app bundle uses the com.trycua.driver signing identity so macOS TCC grants for Accessibility and Screen Recording remain attached across upgrades.If ~/.local/bin is missing from your PATH, the installer detects your shell (zsh, bash, or fish) and adds the matching export PATH=… line to your rc file. Reload your shell with source ~/.zshrc or open a new terminal window after installation completes.

​
Verify the install

cua-driver --version
# cua-driver 0.13.0
For a full environment and install report: 
cua-driver doctor
# [ok  ] binary: cua-driver 0.13.0 (aarch64-macos)
# [ok  ] install dir: /Users/you/.local/bin/cua-driver
# [ok  ] home dir: /Users/you/.cua-driver (3 release dirs cached)
# ...
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.

​
Start the daemon

The daemon owns the permission policy, element cache, macOS TCC attribution, and Windows interactive-session context. Start it before connecting an agent.
On macOS the daemon must start from inside CuaDriver.app so that TCC grants are attributed to the app bundle, not to your terminal:
open -n -g -a CuaDriver --args serve

​
Grant TCC permissions (macOS only)

macOS requires explicit grants for Accessibility and Screen Recording. Start the daemon first so macOS attributes the prompts to CuaDriver.app rather than your terminal, then run: 
cua-driver permissions grant
1

Grant Accessibility

macOS shows a prompt: “CuaDriver” would like to control this computer using accessibility features. Click Open System Settings. This adds CuaDriver to the Accessibility list with its toggle off — flip the toggle on.
2

Grant Screen Recording

A second prompt appears for Screen Recording. Click Open System Settings and toggle CuaDriver on under Screen & System Audio Recording. If macOS asks you to quit and reopen CuaDriver after flipping the toggle, accept — the grant takes effect only after the app fully relaunches.
3

Confirm both grants

cua-driver permissions status
# ✅ Accessibility: granted.
# ✅ Screen Recording: granted.
If only one prompt appeared, run the grant command again. If CuaDriver is missing from either list, click + and add /Applications/CuaDriver.app manually.
cua-driver permissions status reads grant state through the daemon. When no daemon is running it reports ❓ unknown rather than your terminal’s grants.

​
Choose a permission mode

The permission mode is fixed when the runtime starts. An agent cannot change it, and neither can you change it on a running daemon — you stop the daemon and restart it with different flags. Decide before starting the daemon.
ModeUse it when
standardNormal local CLI and MCP use. Observation, input, isolated browser use, recording, and validated file transfer run without prompts.
boundedAn unattended agent must stay inside a reviewed manifest of tools, applications, browser origins, and directories. Anything outside the manifest is denied.
unrestrictedThe machine is disposable or fully trusted and you accept every capability the built-in, managed, and user policy ceilings allow.
standard is the default — plain cua-driver serve needs no flags. For bounded, supply a manifest and the review acknowledgement: 
cua-driver serve \
  --permission-mode bounded \
  --session-policy ~/cua-session.yaml \
  --approve-session-policy
For unrestricted, pass the dangerous acknowledgement explicitly (--permission-mode unrestricted on its own fails closed): 
cua-driver serve --dangerously-bypass-approvals
On macOS, put those flags after serve in the open command so TCC attribution stays with CuaDriver.app: 
open -n -g -a CuaDriver --args serve \
  --permission-mode bounded \
  --session-policy ~/cua-session.yaml \
  --approve-session-policy
The manifest path must be absolute. 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.

​
Update Cua Driver

cua-driver update
This downloads the latest release and updates the symlink. The daemon must be restarted to pick up the new binary.

​
Next steps

Connect an Agent

Register cua-driver as an MCP server with Claude Code, Codex, Cursor, and other clients.

Permission Modes

Understand what standard allows, and how bounded and unrestricted modes differ.

Background Delivery

Learn how agents click and type without stealing focus or moving your cursor.

Windows & Linux

Platform-specific setup for Windows SSH mode and Linux X11/Wayland.

Build docs developers (and LLMs) love

Get started for freeTalk to us