Drive Your First Desktop App with Cua Driver on Any OS

Cua Driver lets an AI agent operate native desktop applications in the background — without stealing focus, moving your cursor, or raising windows. By the end of this tutorial, your agent will open Calculator, compute 6 × 7, and report 42, all while your desktop stays undisturbed. You will install the driver, connect Claude Code (or another harness), and run the same prompt on macOS, Windows, or Linux.

New to agents that operate applications? Read What is computer use? first, then return here.

Steps

Install Cua Driver

Use the one-line installer for your platform. It picks the right path automatically and requires no administrator access.

macOS
Windows
Linux

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 TCC grants stick to the driver:

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

Then prompt for Accessibility and Screen Recording permissions:

cua-driver permissions grant

Grant both Accessibility and Screen & System Audio Recording in System Settings. Clicking Open System Settings adds CuaDriver to the list but does not toggle access — you must flip the toggle yourself. If the daemon does not come back after you toggle, restart it with open -n -g -a CuaDriver --args serve.

Check what was actually granted:

cua-driver permissions status

If either permission is missing, run the grant pair again:

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

Requires Windows 10/11 with an interactive desktop session and PowerShell.

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

The installer registers Cua Driver to start automatically at sign-in. kick starts it immediately so you do not need to sign out or restart before continuing.

Requires an x86_64 Linux desktop session with X11 or XWayland, plus AT-SPI 2.

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

Full install steps, PATH setup, and permission details live in the Install Cua Driver guide. The daemon starts in standard authorization mode, which is the right default for this tutorial.

Verify it is working

Before handing control to an agent, confirm the driver can see your desktop:

cua-driver doctor

List the running GUI applications 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.

Connect your agent

Register Cua Driver with your agent harness once. The mcp-config command prints the exact registration command for your client.

Claude Code
Codex
Prime Agent
Hermes

Install the Claude Code skill — the turnkey path that teaches Claude Code how to drive apps through Cua Driver:

cua-driver skills install

Or register the MCP server directly:

cua-driver mcp-config --client claude

That command prints a registration command specific to your install path:

claude mcp add --transport stdio cua-driver -- cua-driver mcp

For the vision/computer-use compatibility mode (window-scoped screenshots):

claude mcp add --transport stdio cua-computer-use -- cua-driver mcp --claude-code-computer-use-compat

Print the Codex registration command:

cua-driver mcp-config --client codex

The printed command uses the absolute installed binary path:

codex mcp add cua-driver -- /Users/you/.local/bin/cua-driver mcp

Restart Codex or open a fresh session after registration.

Install the skill pack and print the Prime Agent config:

cua-driver skills install
cua-driver mcp-config --client prime-agent

Run /reload in Prime Agent or start a new session, then use /skill:cua-driver to load the skill explicitly.

Print the Hermes snippet:

cua-driver mcp-config --client hermes

Paste it under mcp_servers in ~/.hermes/config.yaml:

mcp_servers:
  cua-driver:
    command: "cua-driver"
    args: ["mcp"]

Then reload MCP servers inside Hermes with /reload-mcp.

Using Cursor, OpenCode, OpenClaw, or another harness? See Connect your agent for more options.

Ask your agent

Now prompt your agent in plain English. It will translate the request into Cua Driver tool calls automatically.

Claude Code
Codex
Prime Agent

> 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.

> Using the Cua Driver skill, open the Calculator, compute 6 × 7, and read the result back.

→ 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.

> Using the Cua Driver skill, open the Calculator, compute 6 × 7, and read the result back.

→ launch_app Calculator
→ get_window_state
→ click 7
→ click ×
→ click 6
→ click =
→ verify_state
✓ The result is 42.

Everything runs in the background. 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.

Confirm what happened

The agent reports 42. Cua Driver kept the calculator in the background the entire time — it never stole your keyboard focus and never moved your cursor. This is best-effort background: the agent drives the app while you keep working.To verify the driver’s background behavior, check the driver logs or run:

cua-driver call get_window_state

What you built

You installed Cua Driver, verified it could see your desktop, registered it with an agent harness via MCP, and prompted 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

Connect your agent

Use the SDK in-process

Embed the typed SDK directly in a Python or TypeScript application.

Permission modes

Decide whether your workload needs standard, bounded, or unrestricted mode.

How Cua Driver works

Understand MCP over stdio, the Rust native runtime, UniFFI bindings, and the daemon architecture.

Get Started

Concepts

Cua Driver

Cua Sandbox

Lume

Cua Bench

Use Cua With

Drive Your First Desktop App with Cua Driver on Any OS

Steps

What you built

Next steps

Connect your agent

Use the SDK in-process

Permission modes

How Cua Driver works

Build docs developers (and LLMs) love

Get Started

Concepts

Cua Driver

Cua Sandbox

Lume

Cua Bench

Use Cua With

Documentation Index

​Steps

​What you built

​Next steps

Connect your agent

Use the SDK in-process

Permission modes

How Cua Driver works

Build docs developers (and LLMs) love

Steps

What you built

Next steps