Install Cua Driver

Install Cua Driver on macOS, Windows, or Linux with a one-line script.

Cua Driver supports macOS, Windows, and Linux. Use the same one-line installer on each platform; the script selects the right install path for the host 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 telemetry; the preference persists across upgrades. See Telemetry and privacy for the exact event schema and identity controls.

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 permissions 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 the shell with source ~/.zshrc or open a new terminal window.

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.

Follow the nightly channel#

Stable is the default. To install the newest nightly and save that preference:

curl -fsSL https://cua.ai/driver/install.sh | bash -s -- --channel nightly

Later cua-driver check-update and cua-driver update --apply stay on nightly. Switch back without reinstalling immediately with:

cua-driver channel set stable
cua-driver update --apply

channel set saves intent only; update --apply performs the binary change.

Install an exact nightly#

Nightlies are immutable builds of exact main commits. Copy the full nightly-cua-driver-rs-v… tag from the component's GitHub release, then pin that tag during installation:

CUA_DRIVER_RS_VERSION=nightly-cua-driver-rs-v0.19.4-nightly.20260812.123456789 \
  /bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"

The pin is one-shot: it does not change the saved update channel. A machine without a saved preference therefore remains on stable; a machine following nightly keeps following nightly. Exact pins never fall back to another release when an asset is missing, and cannot be combined with --channel.

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:

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

For unrestricted, pass the dangerous acknowledgement. --permission-mode unrestricted on its own fails closed:

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.

open -n -g -a CuaDriver --args serve \
  --permission-mode bounded \
  --capability-manifest ~/cua-session.yaml \
  --approve-capability-manifest

See Permission modes for exactly what each profile allows, and Write a capability manifest for a tested manifest. To keep a non-default profile across reboots, its flags belong in the autostart entry — see 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:

open -n -g -a CuaDriver --args serve

Then grant both permissions:

cua-driver permissions grant

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

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

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

Toggle CuaDriver on under Screen & System Audio Recording too:

CuaDriver listed under Screen & System Audio Recording in System Settings with its toggle switched off

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:

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 for recovering a stale registration.

You can also trigger the prompts yourself:

cua-driver check_permissions

macOS opens the Accessibility and Screen Recording prompts. Grant both permissions, then run the check again:

cua-driver permissions status
# ✅ Accessibility: granted.
# ✅ Screen Recording: granted.

cua-driver permissions status reads the driver's actual grant state through the daemon. When no daemon is running, it reports ❓ unknown instead of reporting your terminal's grants, and it does not claim granted unless the driver has that permission.

Next steps#

Choose a Cua Driver integration: decide whether your agent or product should use MCP, the SDK, or an app-hosted service.
Permission modes: what standard allows, and how bounded and unrestricted differ.
Install the Cua Driver agent skill: add the cross-platform instructions from ClawHub or install them directly for another agent.
Keep Cua Driver running: configure autostart so the daemon comes back after reboots.
Connect Cua Driver to an MCP client: register it with Claude Code, Cursor, Codex, and other clients.
Update Cua Driver: check for new releases and apply them.