Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
fix(cua-driver-rs): release installer unifies home on ~/.cua-driver + cleans up prior local install (#1803)
Francesco Bonacci33a6893634f4
diff --git a/docs/content/docs/cua-driver/guide/getting-started/installation.mdx b/docs/content/docs/cua-driver/guide/getting-started/installation.mdxindex acc716cf25..28fd7203c7 100644--- a/docs/content/docs/cua-driver/guide/getting-started/installation.mdx+++ b/docs/content/docs/cua-driver/guide/getting-started/installation.mdx@@ -27,7 +27,17 @@ irm https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/inOn macOS, the installer drops `CuaDriver.app` into `/Applications` and symlinks the binary at `~/.local/bin/cua-driver`. The bundle is signed under `com.trycua.driver`, so TCC grants survive every release.-On Linux, the pre-release backend installer downloads the release into `~/.cua-driver-rs/packages/releases/`, retargets `~/.cua-driver-rs/packages/current`, and symlinks `~/.local/bin/cua-driver`.+On Linux, the pre-release backend installer downloads the release into `~/.cua-driver/packages/releases/`, retargets `~/.cua-driver/packages/current`, and symlinks `~/.local/bin/cua-driver`.++<Callout type="info">+ **Install home is `~/.cua-driver` on every platform.** Earlier `cua-driver-rs` releases (before+ v0.2.16) put the Linux/macOS package home at `~/.cua-driver-rs`; the release installer now writes+ to `~/.cua-driver` like the local installer and the runtime already do. Re-running the installer+ over an older release **auto-sweeps** a stale `~/.cua-driver-rs`, and also cleans up any prior+ `install-local` dev build (`*-local-*` release dirs + the local signing-identity marker) under the+ shared home so the downloaded release is the single authoritative install. The `CUA_DRIVER_RS_HOME`+ override is still honored for back-compat.+</Callout><Callout type="warn">**Linux is pre-release.** Linux artifacts and install paths are published for early testing, but@@ -79,7 +89,7 @@ Linux and Windows installs land in a three-tier layout that makes upgrades and r**Linux**```-$CUA_DRIVER_RS_HOME/ (default: ~/.cua-driver-rs)+$CUA_DRIVER_RS_HOME/ (default: ~/.cua-driver)packages/releases/0.2.0-x86_64-unknown-linux-gnu/cua-driver (real binary, immutable)@@ -114,10 +124,10 @@ Both platforms ship every release into its own per-version directory under `pack**Linux — roll back to a specific version**```bash-# The symlink target is RELATIVE to ~/.cua-driver-rs/packages/, so just+# The symlink target is RELATIVE to ~/.cua-driver/packages/, so just# "releases/<v>-<target>" (no leading "../") — matches what install.sh writes.-ln -sfn releases/0.2.0-x86_64-unknown-linux-gnu ~/.cua-driver-rs/packages/.current.tmp-mv -Tf ~/.cua-driver-rs/packages/.current.tmp ~/.cua-driver-rs/packages/current+ln -sfn releases/0.2.0-x86_64-unknown-linux-gnu ~/.cua-driver/packages/.current.tmp+mv -Tf ~/.cua-driver/packages/.current.tmp ~/.cua-driver/packages/currentcua-driver --version # → 0.2.0```@@ -141,7 +151,7 @@ Clear `$env:CUA_DRIVER_RS_VERSION` and re-run to roll forward to the newest rele| ---------------------------------------------------- | ------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || `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\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_HOME` | `~/.cua-driver` | `%USERPROFILE%\.cua-driver` | Package home — holds `packages/releases/<v>/` and `packages/current`. (Renamed from `~/.cua-driver-rs` in v0.2.16; a stale legacy dir is auto-swept on the next install.) || `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. |@@ -183,13 +193,13 @@ The macOS install path is unaffected — `/Applications/CuaDriver.app` is an in-```==> another cua-driver-rs install is already in progress (lock at- ~/.cua-driver-rs/packages/.install.lock.d); waiting...+ ~/.cua-driver/packages/.install.lock.d); waiting...```If you see this, the safe action is to let it block — it polls every 1 second and proceeds the moment the holding install finishes. The lock entry stamps the holder's pid, start time, and invocation args so you can confirm what's running:```bash-cat ~/.cua-driver-rs/packages/.install.lock.d/info+cat ~/.cua-driver/packages/.install.lock.d/info# pid=43210# started=2026-05-17T09:14:22Z# argv=install.sh@@ -231,7 +241,7 @@ For a structured environment + install report on any platform, run:cua-driver doctor# [ok ] binary: cua-driver 0.2.1 (aarch64-macos)# [ok ] install dir: /Users/you/.local/bin/cua-driver-# [ok ] home dir: /Users/you/.cua-driver-rs (3 release dirs cached)+# [ok ] home dir: /Users/you/.cua-driver (3 release dirs cached)# [ok ] telemetry: enabled (install-id present)# ...```@@ -415,7 +425,7 @@ other value (including unset) leaves the gate active.Release notes: https://github.com/trycua/cua/releases/tag/cua-driver-rs-v0.1.4```-The answer is cached at `~/.cua-driver-rs/version_check.json` for ~20+The answer is cached at `~/.cua-driver/version_check.json` for ~20hours, so subsequent launches reuse the cached result without a networkcall. Network failures are silent — the next launch retries.@@ -624,8 +634,8 @@ One canonical uninstall URL per platform mirrors the install side:| Platform | Symlink / bin | App bundle / package home | Autostart entry | Skill links | Claude MCP registrations || -------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |-| macOS | `~/.local/bin/cua-driver` _(when it resolves into `CuaDriver.app` and `~/.cua-driver-rs/` exists)_ | `/Applications/CuaDriver.app` (current), `/Applications/CuaDriverRs.app` (legacy), `~/.cua-driver-rs/` | `~/Library/LaunchAgents/com.trycua.cua-driver-rs.plist` | `cua-driver` and legacy `cua-driver-rs` links under agent skill dirs | Scrubbed from `~/.claude.json` |-| Linux | `~/.local/bin/cua-driver` _(when it resolves into `~/.cua-driver-rs/`)_ | `~/.cua-driver-rs/` | `~/.config/systemd/user/cua-driver-rs.service` (stop + disable + remove) | Same as macOS | Scrubbed from `~/.claude.json` |+| macOS | `~/.local/bin/cua-driver` _(when it resolves into `CuaDriver.app` and a Rust marker exists)_ | `/Applications/CuaDriver.app` (current), `/Applications/CuaDriverRs.app` (legacy), `~/.cua-driver/` (legacy `~/.cua-driver-rs/` also swept) | `~/Library/LaunchAgents/com.trycua.cua-driver-rs.plist` | `cua-driver` and legacy `cua-driver-rs` links under agent skill dirs | Scrubbed from `~/.claude.json` |+| Linux | `~/.local/bin/cua-driver` _(when it resolves into `~/.cua-driver/`)_ | `~/.cua-driver/` (legacy `~/.cua-driver-rs/` also swept) | `~/.config/systemd/user/cua-driver-rs.service` (stop + disable + remove) | Same as macOS | Scrubbed from `~/.claude.json` || Windows | `%LOCALAPPDATA%\Programs\Cua\cua-driver\bin` _(directory junction; legacy `Programs\trycua\cua-driver-rs\bin` also swept)_ | `%USERPROFILE%\.cua-driver\` (entire tree, including `packages\current` junction; legacy `~\.cua-driver-rs\` also swept) | Scheduled Task `cua-driver-serve` (`schtasks /Delete`; script self-elevates when needed) | Junctions under `%USERPROFILE%\.claude\skills`, `.agents\skills`, `.openclaw\skills`, `%APPDATA%\opencode\skills`, `.gemini\skills` | Not auto-edited — closing message prints the manual `claude mcp remove` command |<Callout type="info">diff --git a/docs/content/docs/cua-driver/guide/getting-started/linux.mdx b/docs/content/docs/cua-driver/guide/getting-started/linux.mdxindex 47ffbf8ae6..668e3e0beb 100644--- a/docs/content/docs/cua-driver/guide/getting-started/linux.mdx+++ b/docs/content/docs/cua-driver/guide/getting-started/linux.mdx@@ -148,7 +148,7 @@ This is a useful recipe for local CI experiments with the Linux pre-release back## Distro-specific notes-The canonical install script (`/bin/bash -c "$(curl -fsSL …/install.sh)"`) downloads a Linux x86_64 binary tarball from GitHub Releases, drops it into `~/.cua-driver-rs/packages/releases/<v>-x86_64-unknown-linux-gnu/`, and symlinks `~/.local/bin/cua-driver`. Because Linux support is pre-release, expect distro-specific gaps and prerequisites.+The canonical install script (`/bin/bash -c "$(curl -fsSL …/install.sh)"`) downloads a Linux x86_64 binary tarball from GitHub Releases, drops it into `~/.cua-driver/packages/releases/<v>-x86_64-unknown-linux-gnu/`, and symlinks `~/.local/bin/cua-driver`. Because Linux support is pre-release, expect distro-specific gaps and prerequisites.The bit that varies is **what accessibility / display tooling is pre-installed**:diff --git a/docs/content/docs/cua-driver/reference/changelog.mdx b/docs/content/docs/cua-driver/reference/changelog.mdxindex d0e9c38395..2bdbfba3cf 100644--- a/docs/content/docs/cua-driver/reference/changelog.mdx+++ b/docs/content/docs/cua-driver/reference/changelog.mdx@@ -18,6 +18,24 @@ The canonical, always-current source is therelease body is auto-generated per release from the commits touching`libs/cua-driver/rust`, including SHA256 checksums and install instructions.+## Unreleased++- **Install home unified on `~/.cua-driver` + collision fix.** The release+ installer (`install.sh` → `_install-rust.sh`) was still defaulting its package+ home to the legacy `~/.cua-driver-rs`, while the local installer+ (`install-local.sh`) and the runtime already used `~/.cua-driver` (renamed in+ v0.2.16). That mismatch meant a machine could end up with two homes and two+ conflicting installs. The release installer now defaults to `~/.cua-driver`+ (still honoring the `CUA_DRIVER_RS_HOME` override), and on every install it (a)+ cleans up a prior `install-local` dev build under the shared home — stops the+ daemon, removes the `*-local-*` release dirs and the local signing-identity+ marker — and (b) sweeps a stale `~/.cua-driver-rs` left by an older release.+ Both steps are best-effort, idempotent, and conservative (marker-gated; they+ never touch a real release dir, the `current` symlink, or unrelated user+ state). TCC grants are preserved — the `/Applications/CuaDriver.app` bundle is+ replaced in place, not `tccutil reset`. The Windows installer (`install.ps1`)+ already used `~/.cua-driver` and migrated the legacy home, so it is unchanged.+## 0.5.0 (2026-06-01)- **Windows: per-session agent cursors** — the per-session cursor model (macOSdiff --git a/libs/cua-driver/scripts/_install-rust.sh b/libs/cua-driver/scripts/_install-rust.shindex 44233561ca..3b18d5bf1a 100644--- a/libs/cua-driver/scripts/_install-rust.sh+++ b/libs/cua-driver/scripts/_install-rust.sh@@ -28,9 +28,14 @@# binary location# CUA_DRIVER_RS_BIN_DIR=PATH legacy alias for INSTALL_DIR# CUA_DRIVER_RS_HOME=PATH package home for versioned installs-# (default ~/.cua-driver-rs). Holds+# (default ~/.cua-driver). Holds# packages/releases/<v>-<target>/ and# packages/current/ on Linux/Windows.+# Renamed from ~/.cua-driver-rs in+# v0.2.16 / PR #1644 — this release+# installer was missed in that rename+# and is reconciled here; a stale+# ~/.cua-driver-rs is swept post-install.# CUA_DRIVER_RS_NO_MODIFY_PATH=1 same as --no-modify-path# CUA_DRIVER_RS_KEEP_VERSIONS=N keep the N most recent per-version# release dirs after install; older@@ -110,7 +115,17 @@ TAG_PREFIX="cua-driver-rs-v"# CUA_DRIVER_RS_INSTALL_DIR is the documented name; CUA_DRIVER_RS_BIN_DIR is# the legacy alias kept for users with the old env in their shell rc.BIN_DIR="${CUA_DRIVER_RS_INSTALL_DIR:-${CUA_DRIVER_RS_BIN_DIR:-$HOME/.local/bin}}"-HOME_DIR="${CUA_DRIVER_RS_HOME:-$HOME/.cua-driver-rs}"+# Canonical home is ~/.cua-driver (renamed from ~/.cua-driver-rs in v0.2.16 /+# PR #1644). The local installer (_install-local-rust.sh) and the runtime+# already default here; this release installer was missed in that rename and+# kept writing to the legacy ~/.cua-driver-rs, which is the root cause of the+# install collision (release wrote one home, install-local + runtime used the+# other). Reconcile the default here, keep accepting the CUA_DRIVER_RS_HOME+# override for back-compat, and sweep the stale legacy dir post-install below.+HOME_DIR="${CUA_DRIVER_RS_HOME:-$HOME/.cua-driver}"+# Pre-v0.2.16 home this installer used to write to. Swept after the new+# install is staged so a single rooted home (~/.cua-driver) is left behind.+LEGACY_HOME_DIR="$HOME/.cua-driver-rs"NO_MODIFY_PATH="${CUA_DRIVER_RS_NO_MODIFY_PATH:-0}"# Post-install GC: how many per-version release dirs to retain. Validated# below as a non-negative integer; 0 means "never GC". The dir that@@ -352,6 +367,84 @@ prune_old_releases() {printf '%s\0' "${to_prune[@]}" | xargs -0 rm -rf}+# --- Clean up a pre-existing LOCAL (install-local) install --------------+#+# `install-local.sh` (`_install-local-rust.sh`) installs a dev build into the+# SAME canonical home this release installer now writes to (~/.cua-driver, see+# the HOME_DIR reconciliation above), under a `*-local-*` versioned release dir+# (VERSION_TAG="0.0.0-local-<config>"). On macOS it also cert-signs the shared+# /Applications/CuaDriver.app with a self-signed identity recorded at+# `~/.cua-driver/.tcc-signing-identity`.+#+# A user who ran install-local and then runs this release installer would+# otherwise end up with the local artifacts lingering alongside the fresh+# release: the `*-local-*` release dir(s) sit in `packages/releases/` (the+# release `current` swap re-points away from them, but they're never removed+# explicitly here), and the stale `.tcc-signing-identity` marker survives even+# though the release bundle is CI-signed, not locally cert-signed. Follow the+# same logic install-local / uninstall.sh use: stop the daemon, then remove+# ONLY the unambiguously-local artifacts so the release install is the single+# authoritative one.+#+# Conservative by construction: we only ever remove `*-local-*` release dirs+# and the local signing-identity marker — never a real release dir, never the+# `current` symlink (the release branch owns that), never unrelated user state+# under the home. Every step is best-effort + idempotent; a machine with no+# prior local install is a clean no-op.+#+# TCC is preserved deliberately: we do NOT `tccutil reset` here. The bundle at+# /Applications/CuaDriver.app is shared (bundle id com.trycua.driver) and the+# subsequent release `ditto` re-points the binary in place; grants keyed on the+# bundle id survive (macOS may re-prompt once on the cdhash change, same as any+# upgrade). Churning the signing identity would gratuitously invalidate+# cert-pinned grants, so we leave it alone.+cleanup_prior_local_install() {+ local releases_dir="$HOME_DIR/packages/releases"+ local tcc_marker="$HOME_DIR/.tcc-signing-identity"++ # Collect the local-build release dirs (the unambiguous install-local+ # signature — a release install never creates a `*-local-*` dir).+ local local_dirs=()+ local d+ if [[ -d "$releases_dir" ]]; then+ for d in "$releases_dir"/*-local-*/; do+ [[ -d "$d" ]] && local_dirs+=("${d%/}")+ done+ fi++ # Nothing local on disk → clean no-op (no marker, no local dirs).+ if [[ ${#local_dirs[@]} -eq 0 && ! -f "$tcc_marker" ]]; then+ return 0+ fi++ log "detected a prior install-local build under $HOME_DIR — cleaning it up so this release install is authoritative"++ # Stop the local daemon BEFORE we yank its binary out from under it,+ # mirroring the post-swap stop both installers already do. Best-effort.+ stop_cua_driver_daemons++ # Remove the `*-local-*` release dirs. The release install stages into its+ # own `<version>-<target>` dir and swaps `current` to it, so deleting the+ # local dirs can't strand the active install. If `current` somehow still+ # points into a local dir (e.g. a partial prior run), the release branch+ # below re-creates `current` immediately after, so a transient dangling+ # link is harmless.+ if [[ ${#local_dirs[@]} -gt 0 ]]; then+ for d in "${local_dirs[@]}"; do+ rm -rf "$d" 2>/dev/null || true+ log " removed local build dir ${d##*/}"+ done+ fi++ # Remove the local signing-identity marker — it describes the locally+ # cert-signed bundle, which the release `ditto` is about to replace with+ # the CI-signed one. Leaving it would misreport the bundle's identity.+ if [[ -f "$tcc_marker" ]]; then+ rm -f "$tcc_marker" 2>/dev/null || true+ log " removed local signing-identity marker $tcc_marker"+ fi+}+# --- Resolve OS/arch ----------------------------------------------------OS=$(uname -s)@@ -506,6 +599,11 @@ fi# --- Install ------------------------------------------------------------+# Before staging the new release, sweep any prior install-local build that+# shares this home so the release install ends up authoritative (see the+# function definition above for the conservative marker-gated logic).+cleanup_prior_local_install+mkdir -p "$BIN_DIR"# macOS: install the .app to /Applications first, then symlink the@@ -641,6 +739,23 @@ elseprune_old_releases "$RELEASES_DIR" "$CURRENT_LINK" "$TARGET" "$KEEP_VERSIONS"fi+# --- Sweep the legacy ~/.cua-driver-rs home -----------------------------+#+# This release installer used to default HOME_DIR to ~/.cua-driver-rs (the+# pre-v0.2.16 name). Now that it writes to ~/.cua-driver like install-local+# and the runtime, a prior RELEASE install can have left a stale+# ~/.cua-driver-rs behind — the source of the two-homes collision this PR+# fixes. Sweep it now that the new install is fully staged under the canonical+# home, mirroring the same belt-and-braces sweep _install-local-rust.sh does.+# Runs AFTER staging so we never delete state before the replacement exists;+# skipped when the user pinned CUA_DRIVER_RS_HOME to the legacy path on+# purpose. Best-effort + idempotent.+if [[ -d "$LEGACY_HOME_DIR" && "$HOME_DIR" != "$LEGACY_HOME_DIR" ]]; then+ rm -rf "$LEGACY_HOME_DIR" 2>/dev/null \+ && log "swept legacy package home $LEGACY_HOME_DIR (reconciled onto $HOME_DIR)" \+ || log "note: could not fully remove legacy package home $LEGACY_HOME_DIR (best-effort)"+fi+# --- Stop any pre-swap cua-driver daemons -------------------------------## Mirror of install.ps1's `Stop-CuaDriverDaemons` call sequence. The@@ -663,7 +778,7 @@ show_cua_driver_daemon_survivors# --- Fire the one-shot install telemetry ping ---------------------------## Anonymous adoption signal — sends `cua_driver_install` to PostHog-# exactly once per install (guarded by ~/.cua-driver-rs/.installation_recorded+# exactly once per install (guarded by ~/.cua-driver/.installation_recorded# on the binary side). The Rust port keeps its install signal independent# of the Swift `cua-driver` install (separate marker dir + separate env var)# so users can opt out of one without affecting the other.