Quickstart

Install Cua Driver, connect your agent, and have it compute 6 × 7 in a desktop calculator.

Install Cua Driver on your computer and let your agent operate the calculator app in the background. By the end, the agent opens Calculator, computes 6 × 7, and reports 42 from the app itself.

Before you start#

• macOS 14+, Windows 10/11, or an x86_64 Linux desktop (X11 or XWayland, with AT-SPI 2)
• An agent that supports MCP or skills, such as Claude Code or Codex
• A desktop calculator app. On Linux, use your distribution's, such as GNOME Calculator.

Run every step in the desktop session you want the agent to drive.

1. Install and start Cua Driver#

No administrator access is needed. The installer picks the right path for your platform.

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

cua-driver permissions status

The daemon starts in the default standard permission mode, which is right for this walkthrough. Before a real workload, read Permissions to decide whether it should be bounded. If macOS grants look stale, see Troubleshoot.

2. Check that it sees your apps#

Run these in a second terminal. First confirm the daemon is reachable. You should see Cua Driver daemon is running:

cua-driver status

Then check the environment. Read the whole report, warnings included: a zero exit code does not prove the desktop is ready.

cua-driver doctor

Then list the GUI apps the driver can reach:

cua-driver call list_apps

The list should include an app you recognize. An empty list means the driver cannot reach the desktop: open Calculator in that session and retry, and fix any permission or display error doctor reports before you go on.

3. Connect your agent#

Pick one way in. A skill teaches the agent to run the Cua Driver CLI. An MCP registration exposes Cua Driver as a tool server. mcp-config prints the registration command, which you run, and installs the skill for that agent (add --no-skills to skip it). It uses the paths on your machine, not the example paths below.

To set up every agent on the machine at once (skill and MCP server), run curl -fsSL https://cua.ai/install.sh | sh -s -- --select cua-driver instead. It also installs the cua CLI.

cua-driver skills install
cua-driver skills status

cua-driver mcp-config --client claude

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

4. Ask your agent#

Start a fresh agent session and send this prompt. It asks the agent to read the calculator's display after acting, so the agent checks the app 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.

Name the setup you chose in place of "the Cua Driver skill":

The app name, the controls, and the steps differ by platform and calculator. The agent finds them from fresh state, and element indices from another run do not carry over. If no calculator is installed, install one from your platform's app store or package manager, then send the prompt again.

5. Check the result#

The calculator shows 42, and the agent reports that value from its last read of the app. A correct answer alone does not prove the agent operated the app.

Your own window, keyboard focus, and pointer should have stayed where they were. The moving cursor is the agent's overlay, not your pointer. Watch for this yourself: do not infer it from the answer. Cua Driver delivers input in the background where the operating system allows it, and a few cases still need the foreground: some apps accept only foreground input, launching an app can raise its window, and native Wayland depends on the compositor. See Platform mechanisms and Known limits.

Clean up#

cua-driver stop

Approve macOS permissions on managed Macs, CI hosts and VMs#

Step 1 needs someone at the Mac to approve two prompts: Accessibility and Screen Recording. Use the first option that fits.

1. Managed Macs: push an MDM profile with a Privacy Preferences Policy Control (PPPC) payload for com.trycua.driver. It pre-approves Accessibility. macOS does not let MDM grant Screen Recording silently, so set ScreenCapture to AllowStandardUserToSetSystemService: a standard user can then switch CuaDriver on without an administrator password.
2. Hosts you operate (dev boxes, CI hosts, VMs): when you tell your agent in the task that it may approve Cua Driver's prompts on this host, it runs cua-driver permissions grant and clicks Allow through the host's own VNC or Screen Sharing server. It clicks only prompts that name CuaDriver, and it logs each approval.
3. Everyone else: run cua-driver permissions grant and click through the prompts yourself, as in step 1.

Your agent never approves a prompt for another app, never does this without your explicit authorization in the task, and never does it on a machine you do not own or run. Approvals survive signed updates, so you approve once per Mac. The Cua Driver skill has the example profile, the VNC helper and the exact steps: see Install and approve permissions.

Next#

• Recipes: real workflows with prompts and checks, such as building a map and redacting a PDF. These runs use foreground input, so run them on a spare desktop or in a VM.
• Connect your agent: every supported harness, agent SDKs, and local models.
• Use the SDK: drive apps from Python or TypeScript inside your own program.
• Keep Cua Driver running: autostart, permission modes, and updates.
• How Cua Driver works: how it avoids stealing your focus and cursor.