Installation

Install Cua Driver with the command for your platform. macOS and Windows are the official install targets; Linux is available as a pre-release backend while platform testing is still in progress.

macOS / Linux pre-release

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh)"

Windows (PowerShell)

irm https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.ps1 | iex

On macOS, the installer drops CuaDriver.app into /Applications and symlinks the binary at ~/.local/bin/cua-driver. The bundle is signed under com.trycua.driver, so TCC grants survive every release.

On Linux, the pre-release backend installer downloads the release into ~/.cua-driver/packages/releases/, retargets ~/.cua-driver/packages/current, and symlinks ~/.local/bin/cua-driver.

On Windows, the installer downloads the release into %USERPROFILE%\.cua-driver\packages\releases\, retargets the current junction, and exposes cua-driver.exe through %LOCALAPPDATA%\Programs\Cua\cua-driver\bin.

The install runs without sudo/admin. On macOS and Linux the CLI symlink lives under $HOME; on Windows the script updates the User-scope Path. If ~/.local/bin is not on your PATH, the shell installer detects your shell (zsh / bash / fish) and appends an export PATH=... line to the right rc file. Reload with source ~/.zshrc (or restart your terminal).

/bin/bash -c "$(curl -fsSL .../install.sh)" -- --bin-dir=/usr/local/bin    # legacy system path (needs sudo)
/bin/bash -c "$(curl -fsSL .../install.sh)" -- --no-modify-path            # don't touch shell rc

Both canonical installers live under libs/cua-driver/scripts/. The shell installer covers macOS and the Linux pre-release backend; install.ps1 covers Windows.

The Windows installer auto-detects host architecture (x64 / arm64) via [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture and downloads the matching cua-driver-rs-<v>-windows-{x86_64,arm64}.zip from GitHub Releases.

It runs without admin and without Developer Mode.

It also appends %LOCALAPPDATA%\Programs\Cua\cua-driver\bin to your User-scope Path so cua-driver --version resolves in any new PowerShell window. (v0.2.13 and earlier used Programs\trycua\cua-driver-rs\bin; the v0.2.14 installer auto-migrates the legacy layout.) The write is idempotent (re-running the installer never duplicates the entry) and falls back to printing manual [Environment]::SetEnvironmentVariable(...) instructions if the registry write is blocked (group policy, locked-down account). Pass -NoPathUpdate to suppress the auto-add — useful when you manage Path out-of-band via chezmoi / dotfiles / GPO:

# Fetch + invoke explicitly so we can pass the switch:
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.ps1))) -NoPathUpdate

The install layout is wired with NTFS directory junctions (IO_REPARSE_TAG_MOUNT_POINT), which any unprivileged user can create — no elevated symlink privilege required.

Versioned-dirs install layout

Linux and Windows installs land in a three-tier layout that makes upgrades and rollbacks an atomic retarget of one link, never a file overwrite. The macOS install intentionally stays on a different layout (/Applications/CuaDriver.app) — see the macOS asymmetry note below.

Linux

$CUA_DRIVER_RS_HOME/                          (default: ~/.cua-driver)
  packages/
    releases/
      0.2.0-x86_64-unknown-linux-gnu/cua-driver   (real binary, immutable)
      0.2.1-x86_64-unknown-linux-gnu/cua-driver   (real binary, immutable)
    current -> releases/0.2.1-x86_64-unknown-linux-gnu   (symlink — active version)
    current/cua-driver                                    (= the binary inside the target dir)
$CUA_DRIVER_RS_INSTALL_DIR/cua-driver -> $CUA_DRIVER_RS_HOME/packages/current/cua-driver
                                       (default: ~/.local/bin/cua-driver)

Windows

%USERPROFILE%\.cua-driver\                  ($env:CUA_DRIVER_RS_HOME)
  packages\
    releases\
      0.2.14-x86_64-pc-windows-msvc\cua-driver.exe      (real binary, immutable)
      0.2.15-x86_64-pc-windows-msvc\cua-driver.exe      (real binary, immutable)
    current\                                            (directory junction → releases\0.2.15-...)
%LOCALAPPDATA%\Programs\Cua\cua-driver\bin\             ($env:CUA_DRIVER_RS_INSTALL_DIR)
                                                        (directory junction → packages\current)

v0.2.13 and earlier used %LOCALAPPDATA%\Programs\trycua\cua-driver-rs\bin\ and %USERPROFILE%\.cua-driver-rs\. The v0.2.14+ installer detects the legacy layout and migrates transparently — stop any running daemon, delete the legacy task / junctions / package home, prune the legacy PATH entry, then install at the new path.

Both junctions are NTFS reparse points (IO_REPARSE_TAG_MOUNT_POINT), so the whole PATH-resolution chain bin\ → current\ → releases\<v>\cua-driver.exe is two filesystem hops transparently served from whichever release the inner junction currently points at.

Atomic upgrades and rollback

Both platforms ship every release into its own per-version directory under packages/releases/. Older versions are kept on disk so you can roll back without re-downloading. The active version is whichever directory packages/current points at.

Linux — roll back to a specific version

# The symlink target is RELATIVE to ~/.cua-driver/packages/, so just
# "releases/<v>-<target>" (no leading "../") — matches what install.sh writes.
ln -sfn releases/0.2.0-x86_64-unknown-linux-gnu ~/.cua-driver/packages/.current.tmp
mv -Tf ~/.cua-driver/packages/.current.tmp ~/.cua-driver/packages/current
cua-driver --version    # → 0.2.0

The mv -Tf is the rename(2) idiom: a concurrent cua-driver lookup sees either the old or new target, never an absent path.

Windows — roll back to a specific version

Re-run the install one-liner with $env:CUA_DRIVER_RS_VERSION pinned to the version you want active. The installer notices the per-version dir is already on disk, skips the download, and just retargets the current junction — so the round-trip is a single junction retarget under the hood.

$env:CUA_DRIVER_RS_VERSION = "0.2.0"
irm https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.ps1 | iex
cua-driver --version    # → 0.2.0

Clear $env:CUA_DRIVER_RS_VERSION and re-run to roll forward to the newest release.

Env-var overrides

# Keep more (or fewer) versions on disk
CUA_DRIVER_RS_KEEP_VERSIONS=10 bash install.sh   # keep 10 most recent
CUA_DRIVER_RS_KEEP_VERSIONS=0  bash install.sh   # disable GC entirely

==> another cua-driver-rs install is already in progress (lock at
    ~/.cua-driver/packages/.install.lock.d); waiting...

cat ~/.cua-driver/packages/.install.lock.d/info
# pid=43210
# started=2026-05-17T09:14:22Z
# argv=install.sh

Get-Content $env:CUA_DRIVER_RS_HOME\install.lock
# pid=43210
# started=2026-05-17T09:14:22.123Z
# invocation=install.ps1 -Release latest

Verify it worked

cua-driver --version
# cua-driver 0.1.0

cua-driver --help
# OVERVIEW: macOS Accessibility-driven computer-use agent — MCP stdio server.

For a structured environment + install report on any platform, run:

cua-driver doctor
# [ok  ] binary: cua-driver 0.2.1 (aarch64-macos)
# [ok  ] install dir: /Users/you/.local/bin/cua-driver
# [ok  ] home dir: /Users/you/.cua-driver (3 release dirs cached)
# [ok  ] telemetry: enabled (install-id present)
# ...

doctor runs version + install-layout + telemetry checks on every platform, plus platform-specific probes (legacy LaunchAgent / updater cleanup on macOS, UI Automation + interactive desktop session on Windows, X11/Wayland + AT-SPI on Linux). For the detailed macOS TCC + cdhash report, run cua-driver diagnose — doctor only surfaces a pointer to it. Pass --json for a scripting-friendly shape. Exit code is 0 when every probe is [ok] / [warn], non-zero only on [err] (e.g. the binary cannot resolve its own install dir).

Windows: interactive-session requirements

Window-driving tools — list_windows, click, type_text, screenshot, get_window_state — all bottom out in Win32 APIs (EnumWindows, GetForegroundWindow, PrintWindow) that are scoped to the calling process's WindowStation + Desktop. A process without an attached interactive desktop sees zero windows even when the user's logged-in desktop has plenty.

Windows session model in one paragraph. Every Windows process runs inside a numbered session. Session 0 is reserved for services and has no interactive desktop attached. Sessions 1, 2, ... are interactive logons — one per console / RDP user. SSH-launched processes (OpenSSH server) default to Session 0 unless the SSH server is explicitly configured to spawn the shell inside the interactive session. The same applies to most Windows service hosts, scheduled tasks running under SYSTEM, and background invocations from CI agents.

If cua-driver lands in Session 0, the window tools will silently return empty arrays and "no windows found" — that's the APIs working as designed against a session with no desktop, not a Cua Driver bug.

Diagnose with cua-driver doctor. The Windows session probe surfaces this directly:

[warn] interactive session: running in Session 0 (services); window-driving
       tools (list_windows, click, type_text, screenshot, get_window_state)
       will return empty results — these APIs need an attached interactive
       desktop.
         re-run cua-driver from an interactive logon (RDP, console, or a
         scheduled task in the user's session) for the GUI tools to function.

A healthy interactive logon reports the inverse:

[ok  ] interactive session: session 2 has an attached interactive desktop
       (WinSta0 + foreground window)

Common fixes for "all my tools return empty arrays on Windows".

• Run from RDP or the local console — the simplest fix; both put your shell in your own interactive session, not Session 0.
• Run from a Windows Terminal / PowerShell launched by your logged-in user — same effect.
• Register a logon Scheduled Task (recommended, equivalent to macOS LaunchAgent) — see Auto-start at logon below, or the Autostart concept page for the cua-driver autostart enable one-liner.
• Driving over SSH? Register the autostart task once from an interactive session, then cua-driver mcp and cua-driver call over SSH proxy through the running daemon automatically. See Running Cua Driver under SSH on Windows for the full workflow.
• Use a session-launcher utility — if you must invoke from a service / SSH context without the daemon-proxy path, run the binary through a launcher that spawns it inside an explicit interactive session id rather than inheriting Session 0.

Run cua-driver doctor after switching contexts to confirm the warning has cleared.

Auto-start at logon (Windows)

The Windows-native equivalent of macOS's LaunchAgent is a Scheduled Task triggered at logon, running as your user, with Run only when user is logged on (i.e. LogonType: Interactive). Once registered, cua-driver serve starts automatically every time you sign in via RDP or the console — no more pasting a startup one-liner.

install.ps1 prints the exact one-shot registration block on a successful install. To register it manually (substitute your install path if you built from source):

$exe       = "$env:LOCALAPPDATA\Programs\Cua\cua-driver\bin\cua-driver.exe"
$user      = "$env:COMPUTERNAME\$env:USERNAME"
$action    = New-ScheduledTaskAction -Execute $exe -Argument 'serve' -WorkingDirectory $env:USERPROFILE
$trigger   = New-ScheduledTaskTrigger -AtLogOn -User $user
$principal = New-ScheduledTaskPrincipal -UserId $user -LogonType Interactive -RunLevel Limited
$settings  = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries `
                -StartWhenAvailable -RestartCount 3 -RestartInterval (New-TimeSpan -Minutes 1) `
                -ExecutionTimeLimit (New-TimeSpan -Hours 0)
Register-ScheduledTask -TaskName 'cua-driver-serve' -Action $action -Trigger $trigger `
    -Principal $principal -Settings $settings

Useful follow-ups:

schtasks /Run    /TN cua-driver-serve         # start it now without re-logging
schtasks /Query  /TN cua-driver-serve /V /FO LIST
schtasks /Delete /TN cua-driver-serve /F      # remove

Notes:

• LogonType: Interactive is load-bearing — it pins the task to a Session 1+ logon. The alternative (S4U or Password) would land you in Session 0 again, undoing the point.
• -ExecutionTimeLimit (New-TimeSpan -Hours 0) means "no time limit"; without it Windows kills the task after 72h by default.
• Set CUA_DRIVER_RS_TELEMETRY_ENABLED=0 in your User environment if you want to disable telemetry persistently: [Environment]::SetEnvironmentVariable('CUA_DRIVER_RS_TELEMETRY_ENABLED', '0', 'User').

Grant TCC permissions

Cua Driver needs two permissions:

• Accessibility — to walk AX trees and dispatch AXUIElementPerformAction.
• Screen Recording — to capture per-window screenshots via ScreenCaptureKit.

Start the daemon first so TCC attributes the subsequent requests to CuaDriver.app rather than to whatever shell parent launched the CLI:

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

Then trigger the prompts:

cua-driver check_permissions

macOS raises the Accessibility and Screen Recording system dialogs. Grant both, then re-run the command to confirm:

cua-driver check_permissions
# ✅ Accessibility: granted.
# ✅ Screen Recording: granted.

If a grant still reads NOT granted after granting in the dialog, open System Settings → Privacy & Security, find CuaDriver.app under Accessibility and Screen Recording, and flip the toggle.

CUA_DRIVER_RS_PERMISSIONS_PANEL=1 cua-driver serve

# As a flag …
cua-driver serve --no-permissions-gate

# … or as an env-var.
CUA_DRIVER_RS_PERMISSIONS_GATE=0 cua-driver serve

✨ cua-driver v0.1.4 is available (you have v0.1.3).
   Update with: cua-driver update
   Release notes: https://github.com/trycua/cua/releases/tag/cua-driver-rs-v0.1.4

CUA_DRIVER_RS_UPDATE_CHECK=false cua-driver serve

cua-driver config set update_check_enabled false

Requirements

Plan for roughly 50 MB for the app bundle or package directory, plus any retained old versions on Linux / Windows.

Run the daemon

Most workflows benefit from a persistent daemon. Element-indexed workflows require one: the per-pid element cache lives in-process, so one-shot CLI invocations lose it between calls.

macOS

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

Linux pre-release

cua-driver serve &

Windows

cua-driver autostart enable
cua-driver autostart kick

Confirm it is up:

cua-driver status
# Cua Driver daemon is running
#   socket: /Users/you/Library/Caches/cua-driver/cua-driver.sock
#   pid: 12345

Stop it cleanly when done:

cua-driver stop

On macOS, open -n -g -a CuaDriver --args serve is the recommended form because LaunchServices attributes the process to CuaDriver.app's bundle id, which is what the user actually granted TCC against. cua-driver serve & also works and auto-relaunches itself via open when it detects the wrong TCC context.

Register with an MCP client (optional)

The MCP server is one of two ways to use Cua Driver — skip this section if you only want the CLI (cua-driver list_apps, etc.). You can register both later, MCP and CLI work side-by-side.

Cua Driver speaks MCP over stdio. Use cua-driver mcp-config --client <name> to print the right command for your client, or copy one of the snippets below directly:

Clients with a CLI add command

# Claude Code (add --scope project|global as needed)
claude mcp add --transport stdio cua-driver -- ~/.local/bin/cua-driver mcp

# Claude Code computer-use compatibility mode
claude mcp add --transport stdio cua-computer-use -- ~/.local/bin/cua-driver mcp --claude-code-computer-use-compat

# Codex (OpenAI)
codex mcp add cua-driver -- ~/.local/bin/cua-driver mcp

# OpenClaw
cua-driver mcp-config --client openclaw | sh

The Claude Code compatibility mode keeps CuaDriver's normal MCP tools, but replaces screenshot with a window-only screenshot shim that requires pid and window_id. Use it when you want Claude Code's vision/computer-use-style flow to ground on CuaDriver window captures.

Use MCP for that Claude Code vision/computer-use-style path. Shelling out to cua-driver screenshot can capture a window, but it does not expose the mcp__cua-computer-use__screenshot tool name that Claude Code appears to use as the image-grounding cue.

Clients configured via a config file

Cursor, OpenCode, and Hermes all configure MCP servers via files. Use mcp-config to print the exact snippet, paste it into the right path:

# Cursor — paste into ~/.cursor/mcp.json (or .cursor/mcp.json for project scope)
cua-driver mcp-config --client cursor | pbcopy

# OpenCode (sst/opencode) — paste into opencode.json at the project root
cua-driver mcp-config --client opencode | pbcopy

# Hermes (NousResearch) — paste into ~/.hermes/config.yaml,
# then run `/reload-mcp` inside Hermes
cua-driver mcp-config --client hermes | pbcopy

For any other client that accepts the standard mcpServers JSON shape:

cua-driver mcp-config | pbcopy

The client spawns cua-driver mcp on demand once registered.

Agent skills (optional)

The installer does not modify agent instruction directories by default. To fetch the matching Anthropic-format skill pack and link it into detected agents, run:

cua-driver skills install

skills install never overwrites an existing user-managed cua-driver link or directory. Use cua-driver skills status, cua-driver skills update, and cua-driver skills uninstall to inspect, refresh, or remove the pack.

Agents without a SKILL.md auto-loader

Cursor, Hermes, and Pi each use a single-file system prompt (different format) instead of a skills directory. We don't auto-wire these because:

• Cursor (~/.cursor/rules/*.mdc): rules expect a different frontmatter shape (description/globs/alwaysApply), not Anthropic's name/description. Symlinking the SKILL.md as .mdc works but the frontmatter renders as a noisy comment block.
• Hermes (~/.hermes/SOUL.md) and Pi (~/.pi/agent/SYSTEM.md): replace the entire system prompt — symlinking would clobber any custom prompt you've set.

For these, install the skill pack and paste its content manually into whatever instructions file the agent uses:

cua-driver skills install
cat "$(cua-driver skills path)/SKILL.md" | pbcopy

Uninstall

One canonical uninstall URL per platform mirrors the install side:

uninstall.sh removes the Rust implementation by default on macOS and Linux. A legacy --backend=swift path remains for users explicitly removing an old Swift install.

uninstall.ps1 self-elevates via UAC when it detects an -AutoStart install — the cua-driver-serve Scheduled Task is registered at RunLevel=Highest (see Autostart), so the daemon spawned by it runs at High IL and a non-elevated process (even the same user that installed it) can't terminate it or delete the task. The script detects either condition upfront and re-spawns itself elevated; the in-place path runs without UAC when no autostart artifacts are present.

What each uninstall removes

# Both Swift and Rust drivers share bundle id `com.trycua.driver`
# (the Rust port took over Swift's identity in cua-driver-rs ≥ 0.2.4).
tccutil reset Accessibility com.trycua.driver
tccutil reset ScreenCapture com.trycua.driver

tccutil reset Accessibility com.trycua.cuadriverrs 2>/dev/null
tccutil reset ScreenCapture com.trycua.cuadriverrs 2>/dev/null

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/uninstall.ps1))) -Force

Troubleshooting

cua-driver: command not found — ~/.local/bin isn't on your PATH. Add it and reload (see the first-time install callout above).

Permissions dialogs reappear after every launch — macOS is attributing the process to a different bundle id than the one you granted. Run cua-driver diagnose and paste the output when filing an issue; it reports cdhash, team id, and which bundle TCC is checking against.

Daemon won't start — another daemon may already be bound to the socket. Check with cua-driver status and stop it with cua-driver stop. For stale lock files after a crash, the daemon's own probe detects those and proceeds.

Ready to drive an app? Head to the Quickstart.

After install, see Updating for how to check for and apply new releases.