Install

COSMIC users do not need a second package or a separate helper install when using ./install.sh, cargo install, or the npm wrapper. Those paths install computer-use-linux-cosmic alongside the main binary automatically. Only manual prebuilt-binary installs need you to copy both 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 both release binaries; 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 the 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)

The Linux build of Codex Desktop already bundles this binary as a plugin. You don't need to wire it up manually — the plugin definition lives in codex-desktop-linux under its plugins/ directory and is enabled by default. To upgrade the plugin in place, replace the binary it ships with the one from this repo's release assets.

User-wide install (recommended for desktop control)

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

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 main and COSMIC helper binaries during install, then the wrapper sets COMPUTER_USE_LINUX_COSMIC_HELPER to the bundled helper 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; 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 ydotoold running and AT-SPI enabled (run computer-use-linux setup and the systemd commands above).

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):

Troubleshooting

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 / i3 / COSMIC / X11 windowing is unavailable — check doctor.windowing.backends. KWin needs session-bus scripting; Hyprland needs hyprctl; 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 helper too or set COMPUTER_USE_LINUX_COSMIC_HELPER.
• Screenshots return black frames on multi-monitor setups — known portal / compositor edge case. Use get_app_state with include_screenshot: false and rely on AT-SPI until the portal backend is healthy.
• type_text types into the wrong window — pass an explicit target (window_id, pid, wm_class, title, or for terminals tty / terminal_pid / terminal_command / terminal_cwd). Without a target, input goes to whatever window currently has compositor focus.

If doctor is green and a specific tool still misbehaves, file an issue with the JSON output of doctor and the failing tool's request payload.