Cua Docs

Drive your first app with Cua Driver

Install Cua Driver, connect your agent, and ask it in plain English to drive a desktop app in the background on macOS, Windows, or Linux.

By the end of this tutorial, your agent will open Calculator, compute 6 × 7, and report 42 through Cua Driver. You will install the driver, connect Claude Code, Codex, or Hermes, and run the same prompt on macOS, Windows, or Linux.

New to agents that operate applications? Start with What is computer use? for the model behind the workflow, then return here to build one.

Preview: agents play a Windows piano app

Cua Driver coordinates several agent cursors to play a Windows piano app at Microsoft Build. You will start with a smaller Calculator task below.

View the original post on X

1. Install Cua Driver#

Use the same one-line installer on every platform; it picks the right path for the host and needs no administrator access.

Requires macOS 14 (Sonoma) or later.

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

Start the daemon through the app bundle so macOS attributes permission prompts to CuaDriver.app. This is what makes the TCC grant stick to the driver:

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

Then grant Accessibility and Screen Recording:

cua-driver permissions grant

macOS prompts once for each permission. Neither prompt grants anything on its own — both offer Open System Settings, not Allow:

The macOS Accessibility Access prompt for CuaDriver, offering Open System Settings or Deny

The macOS Screen Recording prompt for CuaDriver, offering Open System Settings or Deny

Clicking Open System Settings adds CuaDriver to that permission's list for you — switched off. Toggling it on is what actually grants access:

CuaDriver listed under Accessibility in System Settings with its toggle switched off

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

Do this for both Accessibility and Screen & System Audio Recording; choosing Deny leaves the driver unable to see or drive your desktop. macOS may offer to quit and reopen CuaDriver when you flip a toggle — accept, because the driver only picks up a changed grant after a full relaunch. If the daemon does not come back, start it again with open -n -g -a CuaDriver --args serve.

macOS does not always raise both prompts in one pass. Check what actually landed:

cua-driver permissions status

If one is still missing, run the pair again to prompt for it:

open -n -g -a CuaDriver --args serve
cua-driver permissions grant

Full install steps, PATH setup, and permission details live in the install guide. See Install Cua Driver. The daemon you just started runs in the default standard authorization mode, which is the right choice for this tutorial; once you move past Calculator, read Permission modes to decide whether a real workload should be bounded instead.

2. Verify it is working#

Before you hand control to an agent, confirm the driver can see your desktop. Run the cross-platform probe:

cua-driver doctor

Then list the running GUI apps the driver can reach:

cua-driver call list_apps

If you see your running apps listed, the plumbing works. That is the only CLI you run by hand; from here the agent does the driving.

3. Connect your agent#

Register Cua Driver with your agent harness once.

Install the Claude Code skill. This is turnkey: the skill teaches Claude Code how to drive apps through Cua Driver, and you then ask in plain English.

cua-driver skills install

Prefer plain MCP instead of the skill? Print the Claude Code registration command:

cua-driver mcp-config --client claude

It prints a command you run to register the server (paths will be specific to your install):

claude mcp add-json --scope user cua-computer-use '{"args":["mcp"],"command":"/Users/you/.local/bin/cua-driver"}'

Using Cursor, Gemini/Antigravity, OpenCode, or Pi instead? See Connect your agent.

4. Ask your agent#

You can now prompt your agent in plain English, and it will drive Cua Driver for you.

> Using the cua-computer-use MCP, open the Calculator, compute 6 × 7, and tell me the result.
 
→ launch_app Calculator
→ get_window_state
→ click 7 [element_index=12]
→ click × [element_index=20]
→ click 6 [element_index=11]
→ click = [element_index=22]
→ get_window_state
✓ The result is 42.

Everything runs in the background, and the agent picks the right calculator for your OS (Calculator on macOS and Windows, the system calculator on Linux), so the same prompt works on all three platforms.

To understand capture and delivery modes, see Capture and delivery modalities.

5. Confirm what happened#

The agent reports 42. Cua Driver kept the calculator in the background the whole time. It never stole your keyboard focus and never moved your cursor. That is best-effort background: the agent drives the app while you keep working. See Best-effort background.

What you did#

You installed Cua Driver, verified it could see your desktop, connected your agent harness, and asked in plain English for a result computed inside a real desktop app. The agent did the driving through Cua Driver, in the background, on your platform.

Next steps#