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
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 Cua AI, Inc.
//! Linux platform backend for cua-driver-rs.
//!
//! Background automation on Linux via:
//! - /proc filesystem for process enumeration
//! - X11 _NET_CLIENT_LIST for window enumeration
//! - X11 XSendEvent for background mouse/keyboard injection (no focus steal)
//! - AT-SPI D-Bus protocol for accessibility tree (via subprocess bridge)
//! - xwd/scrot/import for window screenshots
//!
//! Wayland: falls back to xdg-output and virtual-keyboard protocols when
//! running under a Wayland compositor with XWayland support.
// Off Linux the crate still builds (so workspace-wide checks compile on every
// host) but its native backends are cfg'd out, which strands the shared
// helpers they call. They are live on Linux, where dead_code stays enforced.
#![cfg_attr(not(target_os = "linux"), allow(dead_code))]
// Tool helpers return `Result<_, ToolResult>`: the error arm is the finished
// tool reply (see the note in cua-driver-core), not a propagated error.
#![allow(clippy::result_large_err)]
use cua_driver_core::tool::ToolRegistry;
pub mod health_report;
pub mod overlay;
pub mod overlay_capture;
pub mod pip;
pub mod tools;
#[cfg(target_os = "linux")]
pub mod x11;
#[cfg(any(target_os = "linux", test))]
mod x11_client_pid;
#[cfg(target_os = "linux")]
pub mod input;
#[cfg(target_os = "linux")]
pub mod tty;
#[cfg(target_os = "linux")]
pub mod proc_fs;
#[cfg(target_os = "linux")]
pub mod history;
#[cfg(target_os = "linux")]
pub mod browser_platform;
#[cfg(target_os = "linux")]
mod browser_setup_ui;
#[cfg(target_os = "linux")]
mod browser_consent_ui;
#[cfg(target_os = "linux")]
pub mod installed_apps;
#[cfg(target_os = "linux")]
pub mod capture;
mod capture_action_frame;
#[cfg(target_os = "linux")]
mod clipboard;
#[cfg(target_os = "linux")]
mod interaction;
#[cfg(target_os = "linux")]
pub mod atspi;
#[cfg(any(target_os = "linux", test))]
mod snapshot_queries;
#[cfg(target_os = "linux")]
pub mod a11y;
#[cfg(target_os = "linux")]
pub mod recording_hooks;
#[cfg(target_os = "linux")]
pub mod video_wayland;
#[cfg(target_os = "linux")]
pub mod wayland;
// Pure AT-SPI role / X cursor name tables for presence cursor shapes; tested
// on every host.
pub mod pointer_shape_map;
#[cfg(target_os = "linux")]
pub mod pointer_shape;
/// Install the Linux [`cua_driver_core::pointer_shape::PointerShapeBackend`]
/// (and the X11 real-cursor probe for `cursor_shape`). False off Linux, when
/// no display is reachable, or when a backend is already installed.
pub fn install_pointer_shape_backend() -> bool {
#[cfg(target_os = "linux")]
{
pointer_shape::install()
}
#[cfg(not(target_os = "linux"))]
{
false
}
}
// `terminal` is OS-independent (pure string matching + a thin x11 hook).
// Keeping it un-gated lets the unit tests run on any host.
pub mod terminal;
// Pure background pixel-click routing facts; un-gated so their unit tests run
// on every host.
#[cfg_attr(not(target_os = "linux"), allow(dead_code))]
mod at_point_policy;
#[cfg(target_os = "linux")]
pub mod xauth;
#[cfg(target_os = "linux")]
pub mod session_bus;
/// Process-environment overrides for unit tests. Every lib test that changes
/// display variables must go through [`test_env::unreachable_x11_display`] so
/// writers are serialized and the prior values are restored even on panic.
#[cfg(all(test, target_os = "linux"))]
pub(crate) mod test_env {
use std::ffi::OsString;
use std::sync::{Mutex, MutexGuard};
static ENV_LOCK: Mutex<()> = Mutex::new(());
pub(crate) struct DisplayOverride {
display: Option<OsString>,
wayland_display: Option<OsString>,
_lock: MutexGuard<'static, ()>,
}
/// Point `DISPLAY` at a server that cannot exist and hide
/// `WAYLAND_DISPLAY`, so the X11 path is taken and its connect fails
/// regardless of the host session.
pub(crate) fn unreachable_x11_display() -> DisplayOverride {
x11_display(":9999999")
}
/// Point `DISPLAY` at `display` and hide `WAYLAND_DISPLAY`.
pub(crate) fn x11_display(display: &str) -> DisplayOverride {
let lock = ENV_LOCK
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner());
let guard = DisplayOverride {
display: std::env::var_os("DISPLAY"),
wayland_display: std::env::var_os("WAYLAND_DISPLAY"),
_lock: lock,
};
std::env::set_var("DISPLAY", display);
std::env::remove_var("WAYLAND_DISPLAY");
guard
}
impl Drop for DisplayOverride {
fn drop(&mut self) {
for (name, value) in [
("DISPLAY", self.display.take()),
("WAYLAND_DISPLAY", self.wayland_display.take()),
] {
match value {
Some(value) => std::env::set_var(name, value),
None => std::env::remove_var(name),
}
}
}
}
}
/// Pure WSL-detection predicate, split out from [`is_wsl`] so both branches
/// are unit-testable without the process-global env / `OnceLock` cache.
/// `wsl_env` mirrors `$WSL_DISTRO_NAME`/`$WSL_INTEROP` being set; `osrelease`
/// is the `/proc/sys/kernel/osrelease` contents.
fn detect_wsl(wsl_env_set: bool, osrelease: Option<&str>) -> bool {
if wsl_env_set {
return true;
}
osrelease
.map(|s| {
let s = s.to_ascii_lowercase();
s.contains("microsoft") || s.contains("wsl")
})
.unwrap_or(false)
}
/// True when this process is running under WSL (Windows Subsystem for Linux).
/// WSL leaks its identity through the kernel release string ("microsoft" /
/// "WSL") and `/proc/sys/kernel/osrelease`. Cheap, side-effect-free, cached
/// after the first probe.
pub fn is_wsl() -> bool {
use std::sync::OnceLock;
static IS_WSL: OnceLock<bool> = OnceLock::new();
*IS_WSL.get_or_init(|| {
let env_set = std::env::var_os("WSL_DISTRO_NAME").is_some()
|| std::env::var_os("WSL_INTEROP").is_some();
let osrelease = std::fs::read_to_string("/proc/sys/kernel/osrelease").ok();
detect_wsl(env_set, osrelease.as_deref())
})
}
/// Actionable hint appended to "no usable display" errors. Tailored for WSL,
/// where the common failure is "no real X/Wayland display, or WSLg geometry
/// isn't resolvable". Kept as a trailing fragment so callers can splice it
/// onto a more specific message. See issue #2005.
pub fn no_display_hint() -> String {
let neither_display_set =
std::env::var_os("DISPLAY").is_none() && std::env::var_os("WAYLAND_DISPLAY").is_none();
if is_wsl() {
" — no usable display detected (WSL). WSLg provides $DISPLAY/$WAYLAND_DISPLAY \
under a recent Windows 11 + 'wsl --update'; on older setups install an X server \
(e.g. VcXsrv) and export DISPLAY. cua-driver needs a real display to capture and \
report screen size."
.to_owned()
} else if neither_display_set {
" — no usable display detected: neither $DISPLAY (X11) nor $WAYLAND_DISPLAY is set. \
Start an X server / Wayland compositor (or Xvfb for headless) before running cua-driver."
.to_owned()
} else {
String::new()
}
}
pub fn register_tools() -> ToolRegistry {
#[cfg(target_os = "linux")]
wayland::ensure_nested_session();
tools::build_registry(false)
}
/// `compat` is a legacy Claude Code compatibility flag with no current
/// tool-surface effect. It remains accepted for launch compatibility.
pub fn register_tools_with_cursor(cfg: cursor_overlay::CursorConfig, compat: bool) -> ToolRegistry {
register_tools_with_cursor_and_provider(None, cfg, compat)
}
pub fn register_tools_with_cursor_and_provider(
provider: Option<std::sync::Arc<dyn cua_driver_core::consent::ProtectedConsentProvider>>,
cfg: cursor_overlay::CursorConfig,
compat: bool,
) -> ToolRegistry {
#[cfg(target_os = "linux")]
wayland::ensure_nested_session();
#[cfg(target_os = "linux")]
wayland::overlay::set_config(cfg.clone());
if cfg.enabled {
overlay::init(cfg.clone());
overlay::run_on_thread();
}
tools::build_registry_with_provider(compat, provider)
}
/// Standalone daemon startup recovery. Keep this out of registry construction:
/// read-only commands such as describe/list-tools must not mutate X11 devices.
#[cfg(target_os = "linux")]
pub fn recover_orphaned_mpx_devices() {
input::reap_orphaned_master_pointers();
}
#[cfg(test)]
mod display_detection_tests {
use super::detect_wsl;
#[test]
fn wsl_env_var_short_circuits() {
// $WSL_DISTRO_NAME / $WSL_INTEROP present → WSL regardless of osrelease.
assert!(detect_wsl(true, None));
assert!(detect_wsl(true, Some("6.1.0-generic")));
}
#[test]
fn wsl2_osrelease_microsoft_tag_detected() {
// Real WSL2 kernel release string (verified live on a WSL2 box).
assert!(detect_wsl(false, Some("6.18.33.1-microsoft-standard-WSL2")));
}
#[test]
fn wsl1_osrelease_microsoft_tag_detected() {
// WSL1 kernels also carry the Microsoft tag, mixed-case.
assert!(detect_wsl(false, Some("4.4.0-19041-Microsoft")));
}
#[test]
fn plain_linux_is_not_wsl() {
assert!(!detect_wsl(false, Some("6.8.0-39-generic")));
assert!(!detect_wsl(false, None));
}
}