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, or Arch-like distros; installs Rust if needed; builds both release binaries; installs them to ~/.local/bin; enables ydotoold as a user service; 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 ```

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

Installs the Rust binaries from crates.io. You still handle the system-level pieces yourself: ydotoold, AT-SPI, desktop portals, 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         # or your distro's equivalent
systemctl --user enable --now ydotoold
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 ydotoold running and AT-SPI enabled (run computer-use-linux setup and the systemd commands above).

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

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 — daemon isn't running. Fix: systemctl --user enable --now ydotoold. If the unit doesn't exist, install the ydotool package and rerun ./install.sh (or copy the unit from systemd/ydotoold.service in this repo).
• 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/.
• 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 windowing is unavailable — check doctor.windowing.backends. KWin needs session-bus scripting; Hyprland needs hyprctl; i3 needs i3-msg and its IPC socket. 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.