Drive your first app with Cua Driver

Install Cua Driver, connect your agent, and verify a result in a desktop app on macOS, Windows, or Linux.

By the end of this walkthrough, your agent will open Calculator, compute 6 × 7, and report 42 through Cua Driver. You will install the driver, connect your agent, and run a prompt that matches its integration on macOS, Windows, or Linux. Have an agent installed and a desktop calculator available before you begin. On Linux, use your distribution's calculator, such as GNOME Calculator.

New to agents that operate applications? How Cua Driver works explains the model behind the workflow.

This walkthrough connects an existing agent to Cua Driver. To embed Cua Driver in your own program instead, see Use the SDK. To try it without touching your own desktop, run it in a sandbox.

Drive a legacy postal app with Cua Driver

Cua Driver fills shipment details and prints receipts in a Windows desktop app with no API. 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

The daemon you just started runs in the default standard permission mode, which is the right choice for this walkthrough. Once you move past Calculator, read Permissions to decide whether a real workload should be bounded instead. Stale macOS grants? See Troubleshoot.

2. Verify it is working#

First confirm that the daemon is reachable:

cua-driver status

Expect Cua Driver daemon is running. If it is not running, repeat your platform's startup step above. Then check the environment:

cua-driver doctor

Then list the running GUI apps the driver can reach:

cua-driver call list_apps

Read the doctor report, including warnings: a zero exit code does not prove desktop readiness. On macOS, also confirm both grants with cua-driver permissions status. Continue when the required permissions and desktop services are available, and list_apps includes a GUI app you recognize. An empty list is not a successful desktop check: open Calculator in that session and retry. Resolve permission or display errors before connecting the agent.

3. Connect your agent#

Choose one integration for your agent. A skill teaches the agent to use the Cua Driver CLI; MCP registration exposes Cua Driver as a tool server. mcp-config only prints setup instructions: you must run the registration command it prints. Use the output from your machine, not the illustrative paths below.

Install the Cua Driver skill for Claude Code:

cua-driver skills install
cua-driver skills status

Confirm that the status includes a Claude Code skill link, then start a fresh Claude Code session. If the link is missing, follow Install the agent skill.

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, Antigravity, OpenCode, Pi, a local model or another harness? See Connect your agent.

4. Ask your agent#

Use the prompt that matches the setup you chose. Ask the agent to read the calculator's displayed result after acting, so it verifies the GUI instead of answering the arithmetic from memory.

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 chose MCP registration instead, replace “Cua Driver skill” with “cua-computer-use MCP server.”

The app name, controls, and action sequence vary by platform and calculator. The agent must discover them from fresh state; element indices from another run are not reusable. If no calculator is installed, install one through your platform's normal app or package manager, then repeat the prompt.

To understand how the driver observes and acts, see How Cua Driver works.

5. Confirm what happened#

Confirm that the calculator displays 42 and that the agent's final observation reports that value. A correct answer alone does not prove that the agent operated the app.

Cua Driver uses best-effort background delivery. Observe whether your active app, keyboard focus, and real pointer stay unchanged during the interaction; do not infer this from the answer. The visible agent cursor is a separate overlay. macOS and Windows accessibility actions can operate supported controls in the background, but some apps require explicit foreground delivery. Linux AT-SPI actions and X11 routes can also work in the background; native Wayland depends on compositor support and has raw-keyboard limits. Launching an app can itself raise a window. See Platform mechanisms for these differences and Known limits for apps that need the foreground.

Clean up#

Stop the daemon when you are done:

cua-driver stop

What you did#

You installed Cua Driver, checked its daemon and desktop access, connected your agent, and verified a result computed inside a desktop app.

Try a real workflow#

Use a bounded task to connect app actions with a saved result. These macOS examples include edited recordings, fictional starter files, and output checks:

Build and inspect a map: load spatial data, prepare a print layout, and inspect the exported PDF.
Redact and annotate a PDF: prepare a review copy in Preview and check the saved redactions.
Prepare an exhibition panel: crop an archive image and edit a panel across GIMP and Inkscape.

These runs include foreground desktop input. Use a separate desktop, a sandbox or a VM when you need to keep working during the task.

Next steps#

Connect your agent: every supported harness, agent SDKs and local models.
Use the SDK: drive apps from Python or TypeScript and verify each action.
Keep Cua Driver running and updated: autostart, permission modes and updates.
How Cua Driver works: how it avoids focus and cursor disruption when the target app supports it.