Cua Driver on Windows and Linux: Setup and Troubleshooting

Cua Driver runs on Windows 10/11 and x86_64 Linux with X11 or XWayland. On both platforms cua-driver mcp owns its runtime directly — there is no separate app bundle with its own OS permission grants the way CuaDriver.app works on macOS. This page covers the platform-specific installation, session model, MCP setup, autostart, and common troubleshooting steps for each OS.

Windows

Install

Run the one-line PowerShell installer from an interactive session:

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

The installer downloads the release under %USERPROFILE%\.cua-driver\packages\releases\, exposes cua-driver.exe from %LOCALAPPDATA%\Programs\Cua\cua-driver\bin, and appends that directory to your User-scope Path. It detects whether the host is x64 or arm64. No administrator privileges are required. Verify the install:

cua-driver --version
cua-driver doctor

doctor runs the Windows session probe and reports whether the daemon is running in an interactive session. A result like [warn] interactive session: running in Session 0 means window-driving tools will return empty results — see the SSH section below.

The Windows session model

Windows window APIs (EnumWindows, UIA, BitBlt) are scoped to the caller’s WindowStation and Desktop. Interactive sessions (Session 1+) have an attached desktop; the services session (Session 0) does not. A process that runs in Session 0 — including shells launched from OpenSSH — cannot see the user’s windows. On Windows, cua-driver mcp owns its runtime directly. This means the MCP process must run in an interactive session for GUI tools to work. There is no app bundle that holds grants on the process’s behalf.

Set up autostart

cua-driver autostart enable
cua-driver autostart kick

enable registers the task. kick starts it immediately without waiting for the next logon. Both commands must be run from an interactive session (RDP or local console) — running them from SSH fails with a confusing error about account-name mapping. Check the task state:

cua-driver autostart status
# registered (running)

The Scheduled Task keeps running after an RDP disconnect. A disconnected session remains in Disc state and is still a live interactive session. The daemon stops only on explicit logoff or reboot.

Run cua-driver mcp on Windows

After the daemon is running in an interactive session, cua-driver mcp in any session (including SSH) proxies to it over the named pipe:

cua-driver mcp
# or make the socket explicit:
cua-driver mcp --socket \\.\pipe\cua-driver

claude mcp add --transport stdio cua-driver -- cua-driver.exe mcp --socket \\.\pipe\cua-driver

The explicit --socket keeps the MCP process as a protocol proxy to the interactive daemon. Bare cua-driver mcp on Windows owns a direct runtime and therefore fails closed in Session 0 — it never silently falls back to another session.

Set a permission mode on Windows

cua-driver autostart enable registers a bare serve command with no mode flags. Configure the mode using User-scope environment variables that the Scheduled Task inherits at logon:

setx CUA_DRIVER_PERMISSION_MODE bounded
setx CUA_DRIVER_SESSION_POLICY_FILE "$env:USERPROFILE\cua-session.yaml"
setx CUA_DRIVER_SESSION_POLICY_APPROVED 1

setx affects new processes only. Restart the daemon for the change to take effect:

cua-driver stop
cua-driver autostart kick

Driving Windows apps over SSH

Windows OpenSSH runs in Session 0, the non-interactive services session. list_windows and other window-driving tools return empty results from Session 0 because they cannot see the user’s interactive desktop. The solution is to run a cua-driver serve daemon in your interactive session via the autostart Scheduled Task, and have the SSH-side CLI or MCP adapter connect to that daemon through the named pipe.

From an interactive session (RDP or local console), set up autostart

cua-driver autostart enable
cua-driver autostart kick

Confirm your session is interactive:

query session
# SESSIONNAME    USERNAME    ID  STATE   TYPE
# rdp-tcp#23     you         2  Active

From your SSH session, verify the daemon is reachable

cua-driver status
# Cua Driver daemon is running
#   socket: \\.\pipe\cua-driver
#   pid: 12345
#   session: 2    ← daemon is in your interactive session

Call tools from SSH

cua-driver call list_apps
cua-driver call list_windows

Both commands resolve the named pipe automatically. Pass --socket \\.\pipe\cua-driver to make the endpoint explicit.

Windows troubleshooting

If list_windows returns an empty array or tools behave unexpectedly:

Run cua-driver --version from SSH and confirm it reports the current installed version.
Run cua-driver status and confirm a running daemon is reported.
Run query session and confirm your user has a row in Active or Disc state.
Run cua-driver doctor from RDP and check for [ok] interactive session: session N has an attached interactive desktop.
Confirm the MCP command includes --socket \\.\pipe\cua-driver.

If cua-driver autostart enable fails with an account-name mapping error, you are running it from a non-interactive context. Switch to RDP or the local console and try again.

Linux

Install

On a minimal or server image, install the required runtime libraries first (this step needs sudo; the installer itself does not):

sudo apt install libxi6 at-spi2-core

Then run the installer:

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

The installer downloads the binary to ~/.cua-driver/packages/releases/, points ~/.cua-driver/packages/current at that release, and creates the ~/.local/bin/cua-driver symlink. Verify the install:

cua-driver --version
cua-driver doctor

doctor checks the AT-SPI bus and display server. It flags missing dependencies and Wayland compositor compatibility before you connect an agent.

X11 and Wayland support

X11 is fully supported. Cua Driver can discover windows, capture them, deliver background input through AT-SPI, and route foreground input through XTest — all proven across GTK, Electron, and Tauri applications. Native Wayland support is opt-in and compositor-specific:

CUA_DRIVER_RS_ENABLE_WAYLAND=1 cua-driver serve

Compositor	State	Notes
X11/Xorg	Supported	Full background AX and PX, foreground input, desktop scope
Sway (wlroots)	Supported with limits	Complete typed Electron, Tauri, and GTK catalog; focus-bound raw input refused
GNOME/Mutter	Supported with limits	Requires the WinRects Shell helper for geometry; portal video recording incomplete
KDE/KWin	Experimental	No target-addressable activation adapter yet; focus-bound input refused
XWayland	Supported with limits	X11 routes used when the app exposes a real X11 window

Arbitrary raw background pixel injection is not available to an ordinary client on a standard Wayland compositor. Background AT-SPI actions work where the target exposes them. A background_unavailable or background_occluded result is a deliberate safety refusal — not a silent success.

Without the Wayland opt-in, Wayland sessions use XWayland routes where the target exposes a real X11 window.

Run cua-driver mcp on Linux

On Linux cua-driver mcp owns its runtime directly — no separate daemon is required for MCP use, though a persistent daemon is useful for clients that reconnect frequently:

cua-driver mcp

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

For generic MCP config:

{
  "mcpServers": {
    "cua-driver": {
      "command": "cua-driver",
      "args": ["mcp"]
    }
  }
}

Set up autostart with systemd

cua-driver autostart is Windows-only. On Linux, create a systemd user unit:

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/cua-driver.service << 'EOF'
[Unit]
Description=cua-driver background daemon
After=graphical-session.target
PartOf=graphical-session.target

[Service]
Type=simple
ExecStart=%h/.local/bin/cua-driver serve
Restart=on-failure
RestartSec=2

[Install]
WantedBy=graphical-session.target
EOF

Enable and start the unit:

systemctl --user daemon-reload
systemctl --user enable --now cua-driver.service
systemctl --user status cua-driver.service

On headless machines where the daemon should survive user logout, enable linger:

loginctl enable-linger $USER

On headless boxes without a graphical-session.target, also change the [Install] section to WantedBy=default.target so the unit has something to hook into at boot.

Set a permission mode on Linux

Add flags directly to ExecStart in the unit file:

ExecStart=%h/.local/bin/cua-driver serve \
  --permission-mode bounded \
  --session-policy %h/cua-session.yaml \
  --approve-session-policy

Reload and restart the unit:

systemctl --user daemon-reload
systemctl --user restart cua-driver.service

Linux troubleshooting

AT-SPI tools return empty results or fail:

# Check that the AT-SPI bus is running
cua-driver doctor
# Manually start the AT-SPI daemon if needed
/usr/lib/at-spi2-core/at-spi-bus-launcher --launch-immediately &

Missing shared libraries on launch:

# libXi missing
sudo apt install libxi6
# AT-SPI missing
sudo apt install at-spi2-core

Wayland: background input not working: Background pixel injection is not available on most Wayland compositors. Use AT-SPI element actions (element_index) for background work, or escalate to foreground delivery for apps that only accept focused input. Check cua-driver doctor for compositor-specific notes. Display not found:

export DISPLAY=:0
cua-driver doctor

On headless machines with Xvfb:

Xvfb :99 -screen 0 1920x1080x24 &
export DISPLAY=:99
cua-driver serve

Get Started

Concepts

Cua Driver

Cua Sandbox

Lume

Cua Bench

Use Cua With

Cua Driver on Windows and Linux: Setup and Troubleshooting

Windows

Install

The Windows session model

Set up autostart

Run cua-driver mcp on Windows

Set a permission mode on Windows

Driving Windows apps over SSH

Windows troubleshooting

Linux

Install

X11 and Wayland support

Run cua-driver mcp on Linux

Set up autostart with systemd

Set a permission mode on Linux

Linux troubleshooting

Next steps

Installation

Connect Agent

Background Delivery

Permission Modes

Build docs developers (and LLMs) love

Get Started

Concepts

Cua Driver

Cua Sandbox

Lume

Cua Bench

Use Cua With

Documentation Index

​Windows

​Install

​The Windows session model

​Set up autostart

​Run cua-driver mcp on Windows

​Set a permission mode on Windows

​Driving Windows apps over SSH

​Windows troubleshooting

​Linux

​Install

​X11 and Wayland support

​Run cua-driver mcp on Linux

​Set up autostart with systemd

​Set a permission mode on Linux

​Linux troubleshooting

​Next steps

Installation

Connect Agent

Background Delivery

Permission Modes

Build docs developers (and LLMs) love

Windows

Install

The Windows session model

Set up autostart

Run cua-driver mcp on Windows

Set a permission mode on Windows

Driving Windows apps over SSH

Windows troubleshooting

Linux

Install

X11 and Wayland support

Run cua-driver mcp on Linux

Set up autostart with systemd

Set a permission mode on Linux

Linux troubleshooting

Next steps