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

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 — 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.