Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

4.6 KB
Raw Blame

cua-driver Rust workspace

This directory is the standalone Cargo workspace for the driver daemon, platform implementations, testkit, and helper crates.

Crates

Crate Purpose
cua-driver Main CLI/MCP daemon and hermetic integration tests
cua-driver-e2e Desktop E2E suites that the canonical OS runners select; never shipped
cua-driver-core Shared protocol, tool models, config, and CDP helpers
platform-macos macOS AX, capture, input, browser, and daemon support
platform-windows Windows UIA, capture, input, overlay, and diagnostics
platform-linux Linux AT-SPI, X11/Wayland, capture, and input support
cua-driver-testkit Test-only helpers for spawning the daemon and parsing responses
cua-driver-uia Windows UIAccess worker
cursor-overlay Cross-platform semantic cursor renderer and bounded compiled-theme loader
cursor-theme-cli Short-lived dotLottie validation, compilation, preview, and installation sidecar
pip-preview Packaging preview helper

Platform crates are selected with cfg(target_os) from the main driver crate. Keep platform-specific behavior inside the matching platform-<os> crate.

Build

cargo build -p cua-driver
cargo build -p cua-driver --release

The Python wrapper and install scripts expect the built binary at target/<profile>/cua-driver (or cua-driver.exe on Windows), unless CUA_DRIVER_BINARY is set.

Formatting

The supported Rust toolchain and rustfmt component are pinned in rust-toolchain.toml. Install rustup and run the canonical formatting check from this directory:

cargo fmt --all -- --check

To apply formatting, omit --check:

cargo fmt --all

Tests

Default tests should be headless and safe for CI:

cargo test -p cua-driver-core
cargo test -p cua-driver --test protocol_schema_test

GUI and VM-backed tests live in cua-driver-e2e, are marked #[ignore], and require a built driver, harness apps from ../tests/fixtures/build/, and a real interactive desktop session:

cargo build -p cua-driver
cargo test -p cua-driver-e2e --test harness_appkit_test -- --ignored --nocapture
cargo test -p cua-driver-e2e --test harness_wpf_test -- --ignored --nocapture

See crates/cua-driver-e2e/tests/README.md for the desktop E2E suites and crates/cua-driver/tests/README.md for the hermetic driver tests.

Testkit-owned daemons use a temporary CUA_DRIVER_RS_HOME on every platform. A nonempty override also places Computer History data and its admission.json under <CUA_DRIVER_RS_HOME>/computer-history. Without an override (or with an empty value), History keeps its platform-specific default location. Existing data is not migrated, and installed-product admission checks still apply. On Windows this isolates driver state without redirecting LOCALAPPDATA, APPDATA, or USERPROFILE, which Windows app discovery needs. Explicit caller environment values take precedence; SHARE_HOST_STATE opts a testkit spawn out of isolation. Use separate roots for independent driver instances. This isolates files, not the operating system's credential store.

Generated Outputs

  • target/: Cargo output, ignored.
  • test-apps/harness-*/: staged harness apps, ignored.
  • test-apps/README.md: explains how staged harness outputs are produced.

Permission Policies

Set CUA_DRIVER_POLICY_FILE on the daemon to enforce a deny-by-default policy on all tool calls from MCP and CLI clients. If the variable is unset, or points to a path that does not exist, the driver keeps its backward-compatible behavior with no policy enforcement. Supported paths are:

  • .yaml / .yml: a single YAML policy file.
  • .rego: a single Rego policy file.
  • A directory: all top-level .rego files are loaded in sorted order.

YAML policies allow unconstrained tools through allow.tools, constrained calls through allow.rules, and explicit overrides through deny.tools:

allow:
  tools: [get_window_state, get_desktop_state, scroll, wait]
  rules:
    - tool: click
      constraints:
        x: { min: 0, max: 1920 }
        y: { min: 0, max: 1080 }
    - tool: type_text
      constraints:
        text: { max_length: 1000, pattern: "^[a-zA-Z0-9\\s]+$" }
    - tool: launch_app
      constraints:
        app:
          allowed: [Calculator, TextEdit, Safari]
deny:
  tools: [shell_execute, file_delete]

Rego policies must expose a boolean rule at data.cua.policy.allow. The input shape is { "server": "cua-driver", "tool": <name>, "arguments": <object> }. Regorus evaluates policies inside the daemon; no OPA service is required.