Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/trycua/cua/llms.txt

Use this file to discover all available pages before exploring further.

Cua Driver is a background computer-use driver for macOS, Windows, and Linux. It lets AI agents click, type, scroll, and verify inside native desktop applications without stealing focus, moving the user’s cursor, or raising windows to the foreground. This page explains how the driver’s architecture — Rust native runtime, UniFFI language bindings, MCP over stdio, permission modes, and daemon topology — fits together.

​
The typed contract and language bindings

The public CuaDriver SDK contract is canonical. All language bindings and the MCP server are generated from the same Rust contract: 
private platform implementations
              |
              v
public typed CuaDriver SDK contract
       |          |          |
       v          v          v
   Rust apps   UniFFI      MCP server adapter
              /    \             |
          Python  TypeScript   agents and CLI
The MCP server is downstream of the same public SDK contract as an application. It does not maintain a separate implementation of desktop tools — it is an adapter over the typed Rust runtime. This means Python, TypeScript, Rust, and MCP callers all share the same tool behavior and authorization logic. Language bindings for Python (cua_driver) and TypeScript (@trycua/cua-driver) are generated by UniFFI. The stable native boundary is declared in rust/include/cua_driver_abi.h.

​
MCP over stdio

Cua Driver speaks MCP (Model Context Protocol) over stdio. Agent harnesses such as Claude Code, Codex, Cursor, and Prime Agent connect to the driver by spawning cua-driver mcp as a child process and exchanging JSON-RPC messages over stdin/stdout. The standard registration (all platforms): 
claude mcp add --transport stdio cua-driver -- cua-driver mcp
For the Claude Code computer-use compatibility mode (window-scoped screenshots): 
claude mcp add --transport stdio cua-computer-use -- cua-driver mcp --claude-code-computer-use-compat
Because stdio MCP is transport-neutral, the same cua-driver mcp command works with any harness that implements the MCP client side.

​
The tool catalog

Cua Driver exposes a cross-platform catalog of tools. The core tools available on macOS, Windows, and Linux include:
ToolSurfaceDescription
clickNativeClick at coordinates or accessibility element (supports left, right, double-click via button and count parameters)
dragNativeClick-drag from one point to another
type_textNativeType text into the focused or targeted control
press_keyNativePress a named key or key combination
hotkeyNativeSend a hotkey (e.g., Cmd+C)
scrollNativeScroll at coordinates
move_cursorNativeMove the agent cursor to coordinates
get_desktop_stateObservationCapture screenshot and accessibility tree
get_screen_sizeObservationCurrent screen dimensions
get_cursor_positionObservationCurrent cursor coordinates
verify_stateVerificationAssert a condition about current desktop state
invoke_menuNativeInvoke a named menu item
set_window_frameNativeResize or reposition a window
clipboard_readClipboardRead the system clipboard
clipboard_writeClipboardWrite to the system clipboard
start_sessionSessionBegin a scoped automation session
end_sessionSessionEnd a scoped session
The complete tool list — including platform-specific tools and session utilities — is declared in the driver contract manifest.

​
Permission modes

The permission mode belongs to the process that owns the runtime and is fixed at launch. A running daemon must be restarted to change its mode.
​
standard
mode
The default. Admits the full reviewed built-in operation set. No user confirmation is required for individual tool calls. Appropriate for trusted workloads on machines you control.
​
bounded
mode
Narrows the allowed calls to a reviewed manifest. Only tools and resources listed in the manifest are admitted. Use bounded when you want an agent to work only within a declared scope — for example, only in specific applications or only reading (no clipboard writes).
​
unrestricted
mode
Removes Cua’s runtime restrictions. Requires the explicit flag --dangerously-bypass-approvals at launch. No managed or user policy ceiling can be widened by this mode — it only removes Cua’s own layer.
Set the mode via environment variables when spawning the MCP process: 
CUA_DRIVER_PERMISSION_MODE=bounded \
CUA_DRIVER_SESSION_POLICY_FILE=/path/to/manifest.yaml \
cua-driver mcp
The permission policy engine is deny-by-default. A tool not explicitly mentioned in the policy is blocked. Adding a new tool to the driver does not automatically expose it to agents.

​
The no-foreground contract

Cua Driver’s default path operates applications in the background — without raising their windows, moving the real cursor, or switching the user’s active app. This works through platform-specific mechanisms:
  • macOS: Accessibility API for button presses and value reads without foreground activation; ScreenCaptureKit for window-specific capture without requiring the window to be raised.
  • Windows: UI Automation by window handle while another app is active; message posting to target windows.
  • Linux: AT-SPI for semantic element actions; X11 window-addressable input and capture on X11/XWayland. On Wayland, synthetic input is constrained by the compositor, so the background path relies more heavily on AT-SPI.
When a background path is unavailable (some SwiftUI windows, game/canvas surfaces, or Wayland apps that reject synthetic input), the driver reports the limit and lets the caller choose a foreground escalation for that specific action. The agent cursor is a synthetic overlay rendered by Cua Driver to show where the agent is acting. It is not the real pointer — the user’s cursor stays where they left it.

​
Daemon architecture

Cua Driver supports three execution topologies:
TopologyDescriptionWhen to use
Same processCuaDriver.create() loads the runtime inside the importing appApplications embedding Cua Driver directly
Private workercreate_private_worker() spawns a supervised child over inherited pipesPer-host process isolation without a listener
DaemonLong-lived process with stable OS identityStandalone macOS (CuaDriver.app) or shared service
On macOS, Accessibility and Screen Recording grants attach to an application identity. The standalone CuaDriver.app daemon keeps that identity stable across CLI and agent reconnects. The recommended macOS launch sequence is: 
# Start the daemon through the app bundle (attributes TCC grants correctly)
open -n -g -a CuaDriver --args serve

# Then connect agents via stdio MCP
cua-driver mcp
On Windows and Linux, bare cua-driver mcp now owns its runtime directly in the same process and shuts it down on stdin EOF. There is no automatic discovery or joining of an existing daemon. Use cua-driver mcp --socket <endpoint> when an agent must share a daemon’s sessions and resources.

​
Security hardening

  • The optional loopback HTTP MCP listener is disabled by default. Enable it with CUA_DRIVER_RS_MCP_HTTP_PORT; CUA_DRIVER_RS_MCP_HTTP_TOKEN is also required (32–4096 non-whitespace characters).
  • Windows daemon named pipes grant access only to the daemon owner’s user SID. Clients running as a different user or security principal are rejected.
  • The policy engine hashes each immutable policy snapshot and includes those hashes in authorization-host requests and status output.

​
Further reading

Drive your first app

Install Cua Driver, connect Claude Code, and drive a real desktop app step by step.

Permission modes reference

Full reference for standard, bounded, and unrestricted modes, including YAML and Rego policy syntax.

Process model

Platform-specific details on process identity, TCC grants, and service topology.

What is computer use?

The broader model behind computer-use automation and where Cua Driver fits.

Build docs developers (and LLMs) love

Get started for freeTalk to us