Cua Driver Setup: Let Claude Code or Codex Use Your Desktop

Cua (the repo is trycua/cua) is an open source toolkit for computer-use agents: software that lets an AI model see a desktop and operate it the way a person would, clicking buttons, typing into fields and reading what appears on screen. Its centrepiece for individual developers is Cua Driver, a Rust daemon for macOS, Windows and Linux that exposes those actions to Claude Code, Codex, Cursor and a dozen other agents over MCP or a plain CLI, with the daemon, not the model, deciding what an agent is allowed to touch. The project is trending on GitHub today with roughly 1,000 new stars on top of about 25,000, sits under the MIT licence, and ships new Driver releases every few days (the latest, cua-driver-rs-v0.28.2, landed on 15 September 2026). Getting from nothing to an agent that opens Calculator, computes 6 x 7 and reads back 42 takes about 10 minutes: one install line, a doctor check, start the daemon, register it with your agent, run the prompt.

• Cua is five products in one repo: Cua Driver (local desktop control), Cua Fleets (paid cloud desktops at run.cua.ai), Lume (macOS and Linux VMs on Apple Silicon), Cua Bench (task creation and agent evaluation) and CUA-S1 (small form-filling models on Hugging Face). This guide sets up Driver, then Bench.
• Driver installs with one line per platform and no administrator access: a bash script on macOS and Linux, a PowerShell script on Windows. The 0.28.2 release binaries are 29 MB for Windows x64, 31 MB for Linux x64 and 70 MB for Apple Silicon.
• Every agent action is authorised by the daemon in one of three fixed modes, standard, bounded or unrestricted, chosen at launch and impossible to change from a tool call. The default standard mode allows input against every app on the desktop, so read the permission section before pointing an unattended agent at your real machine.
• You bring the model. Cua provides the computer and the tools; Claude Code, Codex, Cursor, Antigravity, OpenCode, Qwen Code and others connect through cua-driver mcp-config --client <name>.

The exact steps, start to finish

1. Step 1. Check what you already have.

   # Cua Driver needs macOS 14 Sonoma or later, Windows, or a Linux desktop session (X11 or Wayland).
   # Cua Bench (Step 8) additionally needs Python 3.12 or 3.13 and uv.
   sw_vers        # macOS: ProductVersion must be 14 or higher
   winver         # Windows: opens the version dialog
   echo $XDG_SESSION_TYPE   # Linux: x11 or wayland
   python --version
   uv --version
   claude --version   # or: codex --version, whichever agent you will connect

   Driver itself has no runtime dependency; it is a single native binary. You do need an agent already installed and a desktop calculator available, because that is the first thing you will ask it to drive.
2. Step 2. Install Cua Driver with the one-line installer. These are the README's exact lines; the script picks the right build for your CPU and does not ask for sudo or an administrator prompt.

   # macOS or Linux
   /bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"
   
   # Windows (PowerShell)
   irm https://cua.ai/driver/install.ps1 | iex

   On macOS it places CuaDriver.app in /Applications and a ~/.local/bin/cua-driver symlink, adding ~/.local/bin to your shell rc file if it is missing. On Windows the binary lands in %LOCALAPPDATA%\Programs\Cua\cua-driver\bin, cached releases live in %USERPROFILE%\.cua-driver, and the script registers a logon Scheduled Task that starts the daemon automatically (pass -NoAutoStart to the script if you would rather start it by hand). Open a new terminal afterwards so PATH picks it up.
3. Step 3. Verify the binary and the desktop environment.

   cua-driver --version
   cua-driver doctor

   On our Windows 10 test machine the doctor report came back all green: [ok ] binary: cua-driver 0.22.0 (x86_64-windows), [ok ] interactive session: session 1 has an attached interactive desktop, [ok ] UI Automation: CoCreateInstance(CUIAutomation) succeeded and [ok ] EnumWindows visible: 10 windows. The docs are explicit that a zero exit code does not prove desktop readiness; read the warnings. It also prints a telemetry notice on first use; cua-driver telemetry disable turns the content-free product telemetry off permanently.
4. Step 4. Start the daemon (platform specific). Decide the permission mode first, because it is fixed for the life of the process. Plain serve is standard mode.

   # macOS: launch through the app bundle so permission prompts attach to CuaDriver.app
   open -n -g -a CuaDriver --args serve
   cua-driver permissions grant
   cua-driver permissions status
   
   # Linux: run this inside your graphical session and leave the terminal open
   cua-driver serve
   
   # Windows: the installer's Scheduled Task normally starts it; otherwise, in a desktop terminal
   cua-driver serve

   macOS prompts for Accessibility and Screen Recording, but the dialog only offers Open System Settings: you must flip the CuaDriver toggle on in both lists yourself, then let the app relaunch. Our Windows run printed Cua Driver daemon listening on \\.\pipe\cua-driver immediately.
5. Step 5. Confirm the daemon is reachable and can see apps. From a second terminal:

   cua-driver status
   cua-driver call list_apps
   cua-driver list-tools

   status should say Cua Driver daemon is running along with the socket path, pid and permission mode: standard (built_in_default). list_apps returned a JSON array of 201 apps on our machine, 10 of them running, each with a pid, launch_path and windows list. An empty list is a failure: open an app in the same desktop session and retry. list-tools listed 57 MCP tools, from click, type_text and hotkey to get_window_state (a UI Automation tree of one app), browser_navigate, start_recording and verify_state.
6. Step 6. Connect your agent. Pick one path. For Claude Code the skill route is the recommended one:

   cua-driver skills install
   cua-driver skills status

   Prefer plain MCP? The driver prints the exact registration command for your install path:

   cua-driver mcp-config --client claude

   On our machine that printed claude mcp add-json --scope user cua-computer-use '{"args":["mcp"],"command":"C:/Users/you/AppData/Local/Programs/Cua/cua-driver/bin/cua-driver.exe"}'; run whatever it prints for you, not that line. The repo README also documents the plain stdio form, claude mcp add --transport stdio cua-driver -- cua-driver mcp. For Codex, cua-driver mcp-config --client codex emits codex mcp add cua-driver -- /path/to/cua-driver mcp; for Cursor, --client cursor prints JSON to paste into ~/.cursor/mcp.json. Start a fresh agent session after registering.
7. Step 7. First real use: drive Calculator. Paste the prompt from the official tutorial into your agent:

   Using the Cua Driver skill, open the installed calculator app,
   compute 6 × 7, and read the displayed result back from a fresh snapshot.

   If you registered MCP instead of the skill, say "cua-computer-use MCP server" instead of "Cua Driver skill". Watch two things: the calculator should display 42, and your active window, keyboard focus and pointer should stay where they were, because Driver uses best-effort background delivery through accessibility APIs where the app supports it. No agent handy? The same flow works from the CLI, which is how we verified it: cua-driver call launch_app with {"name":"Calculator"} opened Calculator hidden without stealing focus, cua-driver call get_window_state returned its 39-element UI Automation tree with an element_token per button, four cua-driver call click calls on the Six, Multiply by, Seven and Equals tokens each came back route: accessibility, delivery: background, and a final get_window_state read Display is 42. Two details from that run: PowerShell 5.1 strips the quotes out of multi-field JSON, so pipe the JSON into cua-driver call through stdin as the error hint suggests, and kill_app on the calculator was refused with foreign_process_termination_denied even in standard mode, so close apps through their own Close button.
8. Step 8. Optional: install Cua Bench and verify a simulated task. This part needs no VM, Docker or API key.

   uv tool install 'cua-bench[browser]'
   uv tool run --from 'cua-bench[browser]' playwright install chromium
   cb --help
   
   mkdir cua-bench-tutorial
   cd cua-bench-tutorial
   cb task create first-task
   cb task info first-task
   cb interact first-task --variant-id 0 --oracle --no-wait

   The scaffolder asks for an author name, a description (the docs use "Click the Submit button"), a difficulty and tags. The final interact run opens a simulated desktop window, clicks the button with the reference solution and should end with Evaluation result: [1.0]. On our Windows machine cua-bench 0.2.11 crashed on its own Braille-art banner with a UnicodeEncodeError until we set PYTHONUTF8=1 in the environment; after that, cb task info reported the simulated provider with setup, solve and evaluate ticks, and the oracle run printed Executing action: ClickAction(x=250, y=237) followed by Evaluation result: [1.0]. Note that the CLI's own quick-commands output says --task-id 0 where the tutorial says --variant-id 0; both are accepted today.

What is Cua and why is it trending?

Cua AI, Inc. started the repo on 31 January 2025 as a way to run macOS VMs for agents on Apple Silicon (that part survives as Lume). Over 2026 it has grown into a full stack around what the team calls Computer-Use 2.0: an agent that moves between code, APIs and graphical interfaces inside one task rather than being confined to a browser tab. The pieces are Cua Driver for the machine you are sitting at, Cua Fleets for isolated cloud desktops you claim from a pool at run.cua.ai, Lume for local VMs, Cua Bench for building tasks and scoring agents on them, and CUA-S1, a family of small specialised models (the first, CUA-S1-FORMS, scores which value belongs in which form field rather than generating tokens). The immediate trigger for this week's spike is a run of 0.2x Driver releases: 0.28.0 added support for the MCP 2026-07-28 protocol revision so modern clients can discover the driver and read its embedded skill without an initialize handshake, 0.24.0 shipped qualified isolated input for Hyprland and Omarchy desktops, and the README now leads with a 50-second demo of two Driver sessions selecting cells in LibreOffice Calc and objects in Inkscape while a terminal stays in front.

RelatedBrowserSkill Setup: Give Claude Code Your Logged-In Browser

What makes Driver different from the computer-use tools built into agent products is where the control lives. Anthropic's computer-use tool and OpenAI's Operator-style agents send screenshots to a model and execute whatever coordinates come back. Cua Driver instead reads the operating system's accessibility tree (UI Automation on Windows, AX on macOS, AT-SPI on Linux), gives the agent structured elements to act on, delivers input in the background where the toolkit allows it, and refuses with a structured error where it does not. The platform-support page is unusually honest about that boundary: Windows and macOS are Supported with canonical coverage of Electron, Tauri, WPF, WinUI 3, AppKit and SwiftUI apps; Linux X11 and Sway are Supported with limits; Hyprland and KDE are Experimental.

How do you install Cua Driver on Windows?

Open PowerShell (not as administrator; the script does not need it) and run the README's line:

irm https://cua.ai/driver/install.ps1 | iex

The 1,700-line script downloads the cua-driver-rs-0.28.2-windows-x86_64.zip (29 MB) or the arm64 build, unpacks it under %USERPROFILE%\.cua-driver\packages\releases, points a junction at it from %LOCALAPPDATA%\Programs\Cua\cua-driver\bin, appends that directory to your user PATH, and registers a logon Scheduled Task that runs cua-driver serve. Then, in a new terminal:

cua-driver --version
cua-driver doctor
cua-driver status
cua-driver call list_apps

Our machine already had 0.22.0 from an earlier install, and cua-driver check-update reported Current: 0.22.0 / Latest: 0.28.2 / Update available. Run cua-driver update --apply to install. That is the documented upgrade path; cua-driver channel set nightly followed by the same update --apply switches you to nightly builds. If status says the daemon is not running and cua-driver autostart status prints not-registered, run cua-driver serve in a desktop terminal and use a second one for the checks.

How do you install Cua Driver on macOS and Linux?

/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"

macOS needs 14 Sonoma or later. The bundle uses the com.trycua.driver signing identity so the Accessibility and Screen Recording grants stick across upgrades, which is also why the docs insist you start the daemon through open -n -g -a CuaDriver --args serve rather than running the bare binary: macOS attributes permissions to the responsible app, and a daemon spawned from Terminal has no stable identity. After cua-driver permissions grant, cua-driver permissions status should print granted for both. If it reports unknown, the daemon is not running.

On Linux, cua-driver serve must run inside the graphical session so it shares the display and accessibility bus with the apps it will drive. GNOME needs the bundled WinRects Shell helper and one Shell restart for authoritative window geometry; Sway is the reference Wayland lane; Hyprland ships a discovery-only plugin by default. If you want the same install on Apple Silicon in a throwaway VM instead, Lume installs with /bin/bash -c "$(curl -fsSL https://cua.ai/lume/install.sh)" and can create a vanilla macOS Tahoe VM from an Apple restore image.

RelatedECC Setup: Install the Claude Code Agent Harness in 10 Minutes

How does Cua Driver compare with Browser Use, Playwright MCP and the vendor computer-use tools?

What are the gotchas before you rely on it?

Standard mode is broad. The default runtime allows observation, input, isolated browser use and recording against every application on the desktop without prompts. That is fine for a supervised Calculator test; it is not what you want under an unattended agent. For that the docs describe bounded mode, where cua-driver serve --permission-mode bounded --capability-manifest ~/cua-session.yaml --approve-capability-manifest restricts the runtime to a reviewed list of tools, apps, browser origins and directories, and everything else is denied. On Windows and Linux, bare cua-driver mcp owns its own runtime and has no permission flag; set CUA_DRIVER_PERMISSION_MODE in the client's env block or point the client at a bounded serve daemon with --socket. Attaching to your already-logged-in Chrome profile is a separate explicit grant (cua-driver mcp --grant existing-profile) even in standard mode.

Telemetry is on by default, content-free but with an install id; cua-driver telemetry disable persists across upgrades. Windows autostart means the daemon comes back at every logon; cua-driver autostart disable removes the task. macOS permission prompts are confusing: the dialog does not grant anything, only the toggle in System Settings does, and the driver only sees a changed grant after a full relaunch. Wayland is not one thing: raw input cannot generally be sent to an occluded surface, and the Hyprland input plugin is limited to a qualified list of apps (LibreOffice Calc and Inkscape at specific package versions) with a matching compositor ABI. Cua Bench on Windows needs UTF-8: the CLI prints a Unicode banner before every command and dies with UnicodeEncodeError: 'charmap' codec can't encode on a default cp1252 console; $env:PYTHONUTF8=1 in PowerShell (or set PYTHONUTF8=1 in cmd) fixes it, and uv tool install into the Roaming tools directory hit os error 32 file locks twice on our machine until we pointed UV_TOOL_DIR at a local folder. Releases move fast: five Driver versions shipped between 7 and 15 September, and the CLI reference is documented against 0.28.2, so a months-old install like our 0.22.0 will be missing commands the docs describe. Finally, the wider repo carries third-party licences you should know about if you redistribute anything: OmniParser under CC-BY-4.0 and, in the optional cua-agent[omni] extra, ultralytics under AGPL-3.0.

Our take

Most computer-use demos are screenshot loops with a very expensive model in the middle, and they fall over the moment a dialog appears where the model did not expect it. Cua Driver is the first open project we have set up that treats the desktop as a structured system instead: it reads the accessibility tree, delivers input in the background where the platform allows, tells you exactly which toolkits are proven, and gates every action behind a mode that the agent cannot loosen from inside a tool call. That last part is the reason to try it, and also the reason to be careful. The default standard mode is the right one for the Calculator test on a machine you are watching; if you leave a coding agent running overnight with Driver attached, write the manifest first. The other honest caveat is churn: five releases in nine days is great for features and bad for tutorials, so treat the mcp-config output from your own binary as the source of truth over any pasted command, including ours.

Original analysis by GenZTech. Tool documentation: trycua/cua on GitHub.