Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -148,11 +148,7 @@ Some apps (Calculator, Settings, older UWPs) host their top-level window as a `W

## Why not just `cua-driver serve &` over SSH?

A naively-spawned `cua-driver serve &` over SSH inherits the SSH session — which on Windows OpenSSH is **Session 0**, the non-interactive services session. The daemon comes up, but every GUI tool it answers (`list_windows`, `click`, `screenshot`, ...) bottoms out in Win32 APIs scoped to the calling session's WindowStation + Desktop, which Session 0 doesn't have. Tools silently return empty arrays.

`autostart enable && kick` sidesteps this by running the daemon under the user's interactive logon (Session 1+) instead of inheriting whatever session called `serve`. The daemon then has a real desktop attached and GUI tools work.

See [Running cua-driver under SSH on Windows](/cua-driver/guide/getting-started/windows-ssh) for the end-to-end SSH workflow.
A `cua-driver serve &` spawned over SSH inherits the SSH session — Session 0 on Windows OpenSSH — which has no interactive desktop, so every GUI tool returns empty. `autostart enable && kick` runs the daemon under the user's interactive logon (Session 1+) instead, so it has a real desktop attached. [Running cua-driver under SSH on Windows](/cua-driver/guide/getting-started/windows-ssh) has the full reasoning and the end-to-end workflow.

## Uninstall behaviour

Expand Down
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
---
title: Comparison
description: How Cua Driver compares to other macOS computer-use tools
description: How Cua Driver compares to other computer-use tools
---

import { Callout } from 'fumadocs-ui/components/callout';

This page compares Cua Driver with other macOS computer-use tools. All are quality projects. The best choice depends on your workload.
This page compares Cua Driver with other computer-use tools. The best choice depends on your workload. (Several of the alternatives below are macOS-specific; Cua Driver itself runs on macOS, Windows, and Linux.)

## Quick comparison

| Feature | Cua Driver | Codex Computer Use | Claude Computer Use | Lume |
| -------------------- | ----------------------- | -------------------- | -------------------- | ----------------------- |
| **License** | MIT | Closed source | Closed source | MIT |
| **Drives host Mac** | Yes | Yes | No (sandbox only) | No (hosts VMs) |
| **Drives host machine** | Yes | Yes | No (sandbox only) | No (hosts VMs) |
| **Sandbox / VM** | No | No | Yes (Cowork VM) | Yes (macOS + Linux VMs) |
| **Backgrounded** | Default | Default | N/A (sandbox) | N/A |
| **MCP server** | Yes (stdio) | No | No | Yes |
Expand Down Expand Up @@ -69,7 +69,7 @@ This is a different product shape. Cowork is sandbox-first: Claude operates an i

Cua Driver fits when all of these are true:

- You want an agent to drive real apps on your own Mac (not a VM).
- You want an agent to drive real apps on your own machine (not a VM).
- The user needs to keep working in another app while the agent operates.
- You're building against any MCP-capable agent, not locked to one vendor.
- MIT licensing matters.
Expand Down
18 changes: 9 additions & 9 deletions docs/content/docs/cua-driver/guide/getting-started/faq.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,10 @@ Two common causes:

```bash
# Populate the cache for this exact (pid, window_id).
cua-driver get_window_state '{"pid":844,"window_id":10725}'
cua-driver call get_window_state '{"pid":844,"window_id":10725}'

# Then act with the same window_id.
cua-driver click '{"pid":844,"window_id":10725,"element_index":14}'
cua-driver call click '{"pid":844,"window_id":10725,"element_index":14}'
```

If you're running one-shot CLI invocations without a daemon, the cache lives for one process lifetime. Start the daemon first:
Expand Down Expand Up @@ -107,8 +107,8 @@ A known Chromium renderer-IPC limit: the filter coerces synthetic right-click su
HTML5's click-to-play handler rejects some synthetic click paths. Use keyboard instead:

```bash
cua-driver press_key '{"pid":<pid>,"key":"k"}' # YouTube play/pause
cua-driver press_key '{"pid":<pid>,"key":"space"}' # generic video play/pause
cua-driver call press_key '{"pid":<pid>,"key":"k"}' # YouTube play/pause
cua-driver call press_key '{"pid":<pid>,"key":"space"}' # generic video play/pause
```

Keyboard events travel through a different auth envelope and reach the page.
Expand All @@ -118,7 +118,7 @@ Keyboard events travel through a different auth envelope and reach the page.
Pass the URL to `launch_app`:

```bash
cua-driver launch_app '{"bundle_id":"com.google.Chrome","urls":["https://trycua.com"]}'
cua-driver call launch_app '{"bundle_id":"com.google.Chrome","urls":["https://trycua.com"]}'
```

The URL opens in a new window via Chrome's `application(_:open:)` delegate. The driver's focus-restore guard catches Chrome's internal activation and clobbers the frontmost back to what it was before the call.
Expand All @@ -133,7 +133,7 @@ The URL opens in a new window via Chrome's `application(_:open:)` delegate. The
### How do I disable the visual cursor overlay?

```bash
cua-driver set_agent_cursor_enabled '{"enabled":false}'
cua-driver call set_agent_cursor_enabled '{"enabled":false}'
```

Or via config:
Expand All @@ -149,7 +149,7 @@ The overlay only renders when the driver has an AppKit run loop (inside `cua-dri
Tune the motion knobs:

```bash
cua-driver set_agent_cursor_motion '{"glide_duration_ms":300}'
cua-driver call set_agent_cursor_motion '{"glide_duration_ms":300}'
```

See `set_agent_cursor_motion` in the [MCP tools reference](/cua-driver/reference/mcp-tools) for every knob.
Expand All @@ -158,13 +158,13 @@ See `set_agent_cursor_motion` in the [MCP tools reference](/cua-driver/reference

### `check_permissions` says `NOT granted` but I granted both.

TCC checks the calling process, not `CuaDriver.app`. Inside IDE terminals (Claude Code, Cursor, VS Code, Conductor), the shell inherits the IDE's TCC responsibility chain. So running `cua-driver check_permissions` in one of those shells reads against the IDE's bundle, not `com.trycua.driver`.
TCC checks the calling process, not `CuaDriver.app`. Inside IDE terminals (Claude Code, Cursor, VS Code, Conductor), the shell inherits the IDE's TCC responsibility chain. So running `cua-driver call check_permissions` in one of those shells reads against the IDE's bundle, not `com.trycua.driver`.

Start the daemon first, which runs through LaunchServices under the CuaDriver bundle:

```bash
open -n -g -a CuaDriver --args serve
cua-driver check_permissions # forwards to the daemon — authoritative answer
cua-driver call check_permissions # forwards to the daemon — authoritative answer
```

### `cua-driver mcp` from an IDE terminal can't see Accessibility.
Expand Down
32 changes: 16 additions & 16 deletions docs/content/docs/cua-driver/guide/getting-started/installation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -69,10 +69,10 @@ irm https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/in
```

<Callout type="warn">
**Known issue on Windows PowerShell 5.1**: `install.ps1` currently fails to parse on stock Windows PowerShell 5.1 (the version shipped with Windows 10 / Server 2019 / Server 2025) due to backtick + ampersand escaping in the post-install hint block — see [#1626](https://github.com/trycua/cua/issues/1626). Workaround until that lands: manual zip install:
**If `install.ps1` fails to parse on stock Windows PowerShell 5.1** (the version shipped with Windows 10 / Server 2019 / Server 2025; see [#1626](https://github.com/trycua/cua/issues/1626)), fall back to a manual zip install:

```powershell
$version = "0.2.9"
$version = "0.3.2"
$arch = if ([System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture -eq 'Arm64') { 'arm64' } else { 'x86_64' }
$url = "https://github.com/trycua/cua/releases/download/cua-driver-rs-v$version/cua-driver-rs-$version-windows-$arch-binary.zip"
iwr $url -OutFile $env:TEMP\cua.zip -UseBasicParsing
Expand Down Expand Up @@ -171,9 +171,9 @@ Clear `$env:CUA_DRIVER_RS_VERSION` and re-run to roll forward to the newest rele
| Env var | Default (Linux/macOS) | Default (Windows) | What it controls |
|---|---|---|---|
| `CUA_DRIVER_RS_VERSION` | unset → use baked version | unset → use baked version | Pin a specific release (e.g. `0.2.0`). |
| `CUA_DRIVER_RS_INSTALL_DIR` | `~/.local/bin` | `%LOCALAPPDATA%\Programs\trycua\cua-driver-rs\bin` | The visible PATH-entry directory. On Windows this is itself a junction. |
| `CUA_DRIVER_RS_HOME` | `~/.cua-driver-rs` | `%USERPROFILE%\.cua-driver-rs` | Package home — holds `packages/releases/<v>/` and `packages/current`. |
| `CUA_DRIVER_RS_NO_MODIFY_PATH` *(Linux/macOS only)* | `0` | use `-NoPathUpdate` switch on `install.ps1` | Skip the PATH append. On Windows the installer appends `%LOCALAPPDATA%\Programs\trycua\cua-driver-rs\bin` to the User-scope `Path` by default; use the fetch+invoke form with `-NoPathUpdate` to opt out (see the Windows install section above for the exact one-liner). |
| `CUA_DRIVER_RS_INSTALL_DIR` | `~/.local/bin` | `%LOCALAPPDATA%\Programs\Cua\cua-driver\bin` | The visible PATH-entry directory. On Windows this is itself a junction. |
| `CUA_DRIVER_RS_HOME` | `~/.cua-driver-rs` | `%USERPROFILE%\.cua-driver` | Package home — holds `packages/releases/<v>/` and `packages/current`. |
| `CUA_DRIVER_RS_NO_MODIFY_PATH` *(Linux/macOS only)* | `0` | use `-NoPathUpdate` switch on `install.ps1` | Skip the PATH append. On Windows the installer appends `%LOCALAPPDATA%\Programs\Cua\cua-driver\bin` to the User-scope `Path` by default; use the fetch+invoke form with `-NoPathUpdate` to opt out (see the Windows install section above for the exact one-liner). |
| `CUA_DRIVER_RS_KEEP_VERSIONS` *(Linux/Windows only)* | `5` | `5` | Keep the N most recent per-version release dirs after install (`0` disables GC). See the **Old-version cleanup** callout below for per-target and active-install invariants. |

<Callout type="info">
Expand Down Expand Up @@ -225,7 +225,7 @@ cat ~/.cua-driver-rs/packages/.install.lock.d/info
```

```powershell
Get-Content $env:USERPROFILE\.cua-driver-rs\install.lock
Get-Content $env:USERPROFILE\.cua-driver\install.lock
# pid=43210
# started=2026-05-17T09:14:22.123Z
# invocation=install.ps1 -Release latest
Expand All @@ -247,17 +247,17 @@ Both primitives are unprivileged — no sudo, no admin elevation, no Developer M

```bash
cua-driver --version
# cua-driver 0.1.0
# cua-driver 0.3.2

cua-driver --help
# OVERVIEW: macOS Accessibility-driven computer-use agent — MCP stdio server.
# cua-driver 0.3.2 — cross-platform computer-use automation driver
```

For a structured environment + install report on any platform, run:

```bash
cua-driver doctor
# [ok ] binary: cua-driver 0.2.1 (aarch64-macos)
# [ok ] binary: cua-driver 0.3.2 (aarch64-macos)
# [ok ] install dir: /Users/you/.local/bin/cua-driver
# [ok ] home dir: /Users/you/.cua-driver-rs (3 release dirs cached)
# [ok ] telemetry: enabled (install-id present)
Expand Down Expand Up @@ -313,7 +313,7 @@ The Windows-native equivalent of macOS's LaunchAgent is a **Scheduled Task trigg
`install.ps1` prints the exact one-shot registration block on a successful install. To register it manually (substitute your install path if you built from source):

```powershell
$exe = "$env:LOCALAPPDATA\Programs\trycua\cua-driver-rs\bin\cua-driver.exe"
$exe = "$env:LOCALAPPDATA\Programs\Cua\cua-driver\bin\cua-driver.exe"
$user = "$env:COMPUTERNAME\$env:USERNAME"
$action = New-ScheduledTaskAction -Execute $exe -Argument 'serve' -WorkingDirectory $env:USERPROFILE
$trigger = New-ScheduledTaskTrigger -AtLogOn -User $user
Expand Down Expand Up @@ -355,13 +355,13 @@ open -n -g -a CuaDriver --args serve
Then trigger the prompts:

```bash
cua-driver check_permissions
cua-driver call check_permissions
```

macOS raises the Accessibility and Screen Recording system dialogs. Grant both, then re-run the command to confirm:

```bash
cua-driver check_permissions
cua-driver call check_permissions
# ✅ Accessibility: granted.
# ✅ Screen Recording: granted.
```
Expand Down Expand Up @@ -425,9 +425,9 @@ If a grant still reads `NOT granted` after granting in the dialog, open **System
two-line banner to stderr when a newer `cua-driver-rs-v*` release exists:

```
✨ cua-driver v0.1.4 is available (you have v0.1.3).
✨ cua-driver v0.3.2 is available (you have v0.3.1).
Update with: cua-driver update
Release notes: https://github.com/trycua/cua/releases/tag/cua-driver-rs-v0.1.4
Release notes: https://github.com/trycua/cua/releases/tag/cua-driver-rs-v0.3.2
```

The answer is cached at `~/.cua-driver-rs/version_check.json` for ~20
Expand Down Expand Up @@ -489,7 +489,7 @@ cua-driver stop

## Register with an MCP client (optional)

The MCP server is one of two ways to use cua-driver — skip this section if you only want the CLI (`cua-driver list_apps`, etc.). You can register both later, MCP and CLI work side-by-side.
The MCP server is one of two ways to use cua-driver — skip this section if you only want the CLI (`cua-driver call list_apps`, etc.). You can register both later, MCP and CLI work side-by-side.

Cua Driver speaks MCP over stdio. Use `cua-driver mcp-config --client <name>` to print the right command for your client, or copy one of the snippets below directly:

Expand Down Expand Up @@ -536,7 +536,7 @@ cua-driver mcp-config | pbcopy
```

<Callout type="info">
**Pi (badlogic/pi-mono)** does not support MCP natively. Use cua-driver as a plain CLI from inside Pi instead — `cua-driver list_apps`, `cua-driver click '{...}'`, etc. — which is exactly the shape Pi is built around. Run `cua-driver mcp-config --client pi` for the full guidance, or see the [Quickstart](/cua-driver/guide/getting-started/quickstart) for CLI usage.
**Pi (badlogic/pi-mono)** does not support MCP natively. Use cua-driver as a plain CLI from inside Pi instead — `cua-driver call list_apps`, `cua-driver call click '{...}'`, etc. — which is exactly the shape Pi is built around. Run `cua-driver mcp-config --client pi` for the full guidance, or see the [Quickstart](/cua-driver/guide/getting-started/quickstart) for CLI usage.
</Callout>

The client spawns `cua-driver mcp` on demand once registered.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ import { Callout } from 'fumadocs-ui/components/callout';
`cua-driver mcp` is a stdio MCP server. Any agent that supports MCP can use it — no extra setup beyond adding it to the agent's MCP config.

<Callout type="warn">
Grant Accessibility and Screen Recording permissions to cua-driver before connecting any agent.
Run `cua-driver check_permissions` to verify.
Grant the required permissions before connecting any agent — on macOS that's Accessibility and Screen
Recording (Windows and Linux have no equivalent prompt). Run `cua-driver call check_permissions` to verify.
</Callout>

## Claude Code
Expand Down Expand Up @@ -132,7 +132,7 @@ If you are using a vision-capable model via Ollama, you must also declare its in
"npm": "@ai-sdk/openai-compatible",
"options": { "baseURL": "http://localhost:11434/v1" },
"models": {
"gemma4:26b": {
"llama3.2-vision": {
"modalities": {
"input": ["text", "image"],
"output": ["text"]
Expand Down
Loading
Loading