Install

./install.sh, cargo install, the npm wrapper, and the Claude/Codex plugin launcher all install computer-use-linux, computer-use-linux-cosmic (COSMIC Wayland helper), and computer-use-linux-indicator (on-screen activity overlay) together automatically. Only manual prebuilt-binary installs need you to download all three release assets.

Option A — `./install.sh` from a clone

Installs system packages on Debian/Ubuntu, Fedora/RHEL-like, Arch-like, or Artix systems; installs Rust if needed; builds all three release binaries (computer-use-linux, computer-use-linux-cosmic, and computer-use-linux-indicator); installs them to ~/.local/bin; configures ydotoold as a systemd user service when available; enables GNOME AT-SPI settings when running under GNOME; and installs the bundled GNOME Shell extension on GNOME Wayland.

```bash git clone https://github.com/agent-sh/computer-use-linux cd computer-use-linux ./install.sh

log out and back in if the GNOME extension was newly installed

computer-use-linux doctor | jq .readiness ```

ydotool is an optional fallback. On X11, the installer includes xdotool as the required keyboard backend. If ydotool is unavailable from the configured repositories, the installer continues, but doctor still requires a keyboard-capable RemoteDesktop portal on Wayland or xdotool on X11; direct uinput provides absolute pointer input only. On non-systemd hosts, automatic ydotoold service setup is skipped and the installer prints a command suitable for a per-user supervisor. For an unrecognized distro, pass --package-manager apt|dnf|pacman; --force-unknown-distro auto-selects only when exactly one of those managers is available.

Option B — `cargo install` (Rust binaries, no system setup)

Installs all three Rust binaries from crates.io. You still handle the system-level pieces yourself: AT-SPI, desktop portals, the optional ydotoold fallback, and the GNOME extension if you need the GNOME Wayland exact-focus backend.

cargo install computer-use-linux
computer-use-linux doctor

For unreleased changes from main, install directly from Git:

cargo install --git https://github.com/agent-sh/computer-use-linux

Then, as needed:

sudo apt install ydotool at-spi2-core         # ydotool 1.0.3+ when using this fallback
sudo apt install wtype                        # optional Unicode typing on wlroots/Hyprland Wayland
systemctl --user enable --now ydotoold         # only when doctor selects ydotool
computer-use-linux setup                      # gsettings AT-SPI bridge
computer-use-linux setup-window-targeting     # GNOME Shell extension

Codex Desktop (Linux build)

codex-desktop-linux includes a native computer-use-linux feature that embeds and stages this backend inside the app's unified Computer Use plugin. Enable computer-use-linux via make setup-native (or in linux-features/features.json followed by make install-native), then toggle Settings → Computer use → Any App in the desktop app. Do not register a second standalone computer-use-linux MCP server inside Codex Desktop when the native feature is enabled.

User-wide install (recommended for desktop control)

claude mcp add --scope user computer-use-linux -- computer-use-linux mcp

Quick start

Pick the setup that matches your agent or shell workflow:

Verify desktop readiness from the shell (after installing the CLI on PATH via npm install -g @agent-sh/computer-use-linux, ./install.sh, or cargo install computer-use-linux):

computer-use-linux doctor | jq .readiness
computer-use-linux setup                      # enable AT-SPI accessibility bridge if needed
computer-use-linux setup-window-targeting     # install GNOME Wayland window-control extension if needed

Plugin-only or Pi-only installs: The Claude Code / Codex plugin launcher and pi install manage private cached binaries and do not add computer-use-linux to PATH. Either run the MCP doctor / setup_accessibility / setup_window_targeting tools (or computer_use_linux_doctor in Pi) directly from your agent, or also install the CLI above when you want shell subcommands on PATH.

The Rust crate is published as computer-use-linux and the npm package as @agent-sh/computer-use-linux. Prebuilt x86_64 and aarch64 Linux binaries ship with the latest release.

Need an isolated desktop where the agent never touches your real mouse, keyboard, or focused window? Use the sibling project agent-workspace-linux alongside this one.

Screenshot sizing & coordinate scaling

Screenshot payloads are size-bounded by default before they are returned to the MCP host: max 1920 px width/height and 2 MiB image bytes, with hard caps even when callers request more. Agents that need more detail can pass max_width, max_height, max_bytes, scale, format: "jpeg", or quality, preferably with a window target or crop. PNG remains the default; JPEG lets callers trade lossless pixels for a smaller payload before the byte cap forces further resizing. Returned screenshot metadata includes coordinate_width, coordinate_height, scale, format, and quality so callers can convert from a downscaled preview to desktop coordinate pixels.

Option C — npm wrapper (binary download)

Good for users who already have Node.js and want a no-Rust install. The npm package downloads and verifies the matching computer-use-linux, computer-use-linux-cosmic, and computer-use-linux-indicator binaries during install, then the wrapper wires COMPUTER_USE_LINUX_COSMIC_HELPER and COMPUTER_USE_LINUX_INDICATOR_BIN to the bundled helpers automatically.

npm install -g @agent-sh/computer-use-linux
computer-use-linux doctor

You will still need AT-SPI enabled (computer-use-linux setup) and one input backend reported ready by doctor. Start ydotoold only when using the ydotool fallback.

Option D — prebuilt binaries

Linux x86_64 / aarch64 builds are published with each tag. Each binary ships a .sha256 next to it.

• Latest release: <https://github.com/agent-sh/computer-use-linux/releases/latest>

target=x86_64-unknown-linux-gnu
base=https://github.com/agent-sh/computer-use-linux/releases/latest/download
for binary in computer-use-linux computer-use-linux-cosmic computer-use-linux-indicator; do
  asset="$binary-$target"
  curl -L -O "$base/$asset"
  curl -L -O "$base/$asset.sha256"
  sha256sum -c "$asset.sha256"
  install -m 0755 "$asset" "$HOME/.local/bin/$binary"
done

You will still need AT-SPI enabled (computer-use-linux setup) and one input backend reported ready by doctor (start ydotoold only when using the ydotool fallback).

Optional: expose the tools to subagents as well.

inherit_mcp_toolsets: true

If you installed the binary somewhere that is not on `PATH`, pass the absolute path as `--command`.

Restart Hermes after editing the config. Hermes registers the tools as `mcp_computer_use_linux_<tool>` and creates the `mcp-computer-use-linux` runtime toolset.

You can verify both sides before asking Hermes to use the desktop:

For one-off installs without adding the tap first, Hermes also accepts hermes skills install agent-sh/computer-use-linux/skills/computer-use-linux.

Environment variables

Most setups need none of these — doctor and the installers pick sensible defaults. They exist for overriding auto-detected paths and input backends.

Server runtime (set in the MCP host's environment):

Build-time identity overrides (set while compiling a downstream embedded bundle): CUL_GNOME_EXTENSION_UUID, CUL_DBUS_SERVICE, and CUL_DBUS_OBJECT_PATH replace the default standalone GNOME Shell extension UUID and DBus endpoint in both the Rust probes and the generated extension files.

npm wrapper (set during npm install, or before running):

Claude Code and Codex plugin

This repo is a plugin marketplace for both Claude Code and Codex. The plugin registers the MCP server and ships the computer-use-linux skill. On first start it downloads the release binaries pinned to the plugin version, checks each against its published .sha256, and caches them under ~/.cache/computer-use-linux/plugin/. It needs curl or wget, and nothing else is installed.

Claude Code:

claude plugin marketplace add agent-sh/computer-use-linux
claude plugin install computer-use-linux@computer-use-linux

Codex CLI:

codex plugin marketplace add agent-sh/computer-use-linux
codex plugin add computer-use-linux@computer-use-linux

Start a new session afterwards. To run your own build instead of the pinned release, set COMPUTER_USE_LINUX_BIN to its path in the host's environment. System setup (computer-use-linux setup, setup-window-targeting, ydotoold) still applies; ask the agent to run the doctor tool to see what is missing. Codex passes only a short allowlist of environment variables to MCP servers, so the Codex manifest forwards the desktop session variables and the COMPUTER_USE_LINUX_* settings below explicitly. Codex Desktop's Linux build already bundles Computer Use; do not install both there.

Troubleshooting

To receive an explicit completion cue, start the MCP server with COMPUTER_USE_LINUX_NOTIFY_ON_COMPLETE=1. This exposes complete_interaction, a parameter-free tool the agent calls once after finishing its desktop work. It submits a notification through notify-send with a two-second execution limit and bounded process cleanup. Missing services, errors, or timeouts return cue: "skipped"; notification settings may suppress a submitted cue. This does not reserve the desktop or prove that other clients have stopped sending input. No sound or additional desktop settings are enabled by this option. This option currently applies only to directly spawned MCP hosts. The native Pi extension does not forward the flag or include this optional tool in its catalog.

setup and setup_accessibility write and read back GNOME's org.gnome.desktop.interface toolkit-accessibility setting, even if AT-SPI is already enabled at runtime. A runtime-only success is reported as a warning: newly launched GTK apps may still have no tree. Enabling the saved key may require restarting target apps. Other accessibility tools can change that key later; setup does not continuously override user settings.

For an explicit foreground guard while using desktop automation, run:

computer-use-linux guard-accessibility

The guard registers a passive AT-SPI window-activation listener and watches GNOME's saved toolkit-accessibility key. It re-enables the key after a reset and verifies it by readback, with periodic checks as well as change monitoring. This affects all applications using the current user's GNOME setting, not just the target app. It does not start a screen reader or change focus.

mcp, setup, setup_accessibility, and get_app_state never start this guard. Stop it with Ctrl-C or SIGTERM before intentionally disabling accessibility. Stopping ends setting writes and removes its listener without disabling other accessibility clients or restoring an old saved value. A reset and reassertion are not atomic: an app launched in that interval may still need restarting. This is an opt-in mitigation, not a guarantee that every GNOME toggle sequence preserves application accessibility trees.

computer-use-linux doctor is the source of truth. Common failure modes and fixes:

• accessibility.at_spi_bus.ok = false — AT-SPI registry isn't running or the toolkit bridge is off. Fix: computer-use-linux setup (or call the setup_accessibility MCP tool). Restart the apps you want to drive.
• windowing.gnome_shell_introspect.ok = false and gnome_shell_extension_dbus.ok = false — GNOME blocks introspection and the extension isn't installed. Fix: computer-use-linux setup-window-targeting, then log out and log back in.
• input.ydotool_socket.ok = false while ydotool is the selected fallback — daemon isn't running. On systemd, run systemctl --user enable --now ydotoold. On other init systems, rerun ./install.sh and configure your per-user supervisor with the command it prints. If ydotool is not packaged for your distro, use another input backend or install a compatible ydotool release manually.
• input.ydotool.ok = false with an unsupported CLI message — install ydotool 1.0.3 or newer. A running daemon or socket alone is not enough; doctor verifies the raw key, wheel, stdin typing, and absolute-movement command family before advertising the backend.
• input.uinput.ok = false — /dev/uinput isn't accessible to your user. Fix: add yourself to the input group (sudo usermod -aG input $USER) and re-login. On distros that ship uinput as a kernel module without auto-loading it, add uinput to /etc/modules-load.d/. Direct uinput supplies absolute pointer input only, so doctor also requires a keyboard-capable portal, xdotool, or ydotool backend.
• Portal calls hang or time out — xdg-desktop-portal or its backend (-gnome, -gtk, -kde, -wlr) crashed. Fix: check journalctl --user -u xdg-desktop-portal -u xdg-desktop-portal-gnome --since '5 min ago' and restart the relevant unit.
• KWin / Hyprland / niri / i3 / COSMIC / X11 windowing is unavailable — check doctor.windowing.backends. KWin needs session-bus scripting; Hyprland needs hyprctl; niri needs the session's NIRI_SOCKET, or an unambiguous matching niri.*.sock in XDG_RUNTIME_DIR; i3 needs i3-msg and its IPC socket; generic X11 needs wmctrl and xprop. COSMIC needs computer-use-linux-cosmic, which the standard installers provide automatically; if you copied binaries by hand, copy the he