# niri-computer-use

> An MCP server that lets AI agents see and act on a niri Wayland desktop, with a lease, a stop key and an audit log.

It runs only on Linux, under niri 26.04 on Wayland, from a release build for x86_64 or aarch64 or built from source; with another major or minor release of niri it only looks. Every page is also plain Markdown at its address with `.md` in place of the trailing slash. [llms-full.txt](https://ayagmar.github.io/niri-computer-use/llms-full.txt) has all of them in one file.

If the user turned on `confirm_lease`, `acquire_desktop` waits up to a minute for them to choose Allow on the desktop, and fails with `lease_declined` if they don't. To read small text, call `screenshot` with target `region`, an earlier screenshot's `screenshot_ref`, and `region` in that image's pixels. A `save_path` saves the screenshot as a full-resolution PNG under `~/Pictures/niri-computer-use`, or the user's `capture_dir`.

## Using the tools (for agents operating a desktop)

- [skill/SKILL.md](https://ayagmar.github.io/niri-computer-use/skill/SKILL.md): load this first: how to look, take the lease, act one call at a time and hand back
- [skill/references/tools.md](https://ayagmar.github.io/niri-computer-use/skill/references/tools.md): every tool, its arguments and what its result means
- [skill/references/errors.md](https://ayagmar.github.io/niri-computer-use/skill/references/errors.md): each error name and what to do next
- [Tools overview](https://ayagmar.github.io/niri-computer-use/tools/overview.md): Every tool niri-computer-use offers, and the shapes of its results and errors.
- [Error reference](https://ayagmar.github.io/niri-computer-use/reference/errors.md): Every error name niri-computer-use returns, what causes it and what to do.

## Installing for a user

- [Install](https://ayagmar.github.io/niri-computer-use/start/install.md): Install niri-computer-use with the install script or with cargo, add the agent skill, and check it against your niri session.
- [The install script](https://ayagmar.github.io/niri-computer-use/start/install-script.md): What install.sh downloads, checks, writes and never touches, its variables, and how to update or uninstall.
- [Client setup](https://ayagmar.github.io/niri-computer-use/start/clients.md): Register niri-computer-use in Claude Code, Pi, Codex or another MCP client, and install the skill.
- [First session](https://ayagmar.github.io/niri-computer-use/start/first-session.md): Bind the stop key, then let an agent look at your desktop and act on it.
- [Troubleshooting](https://ayagmar.github.io/niri-computer-use/reference/troubleshooting.md): Fixes for common problems: the lease refused while unlocked, pointer tools refused on a second monitor, a server that finds no niri, and more.
- [Configuration](https://ayagmar.github.io/niri-computer-use/concepts/configuration.md): The policy file, every key it takes, and the environment the server reads.

## More

- [Home page](https://ayagmar.github.io/niri-computer-use/index.md): what the server does, five recorded sessions, what an action answers, the checks before an action, what it doesn't protect, requirements, and install in three steps
- [Safety](https://ayagmar.github.io/niri-computer-use/concepts/safety.md): What niri-computer-use enforces, what it doesn't, and how you take the desktop back.
- [Architecture](https://ayagmar.github.io/niri-computer-use/concepts/architecture.md): The processes niri-computer-use runs, the path one action takes, the lease's states, and the coordinate spaces a click passes through.
- [Looking](https://ayagmar.github.io/niri-computer-use/tools/looking.md): The read-only tools: status, desktop_state, clipboard_read and wait_for.
- [Screenshots](https://ayagmar.github.io/niri-computer-use/tools/screenshots.md): The screenshot tool, screenshot refs for the pointer, zooming in, settled screenshots and saving PNG files.
- [For agents](https://ayagmar.github.io/niri-computer-use/reference/agents.md): Plain-Markdown versions of this site, llms.txt, and the agent skill at stable URLs.

## Optional

- [Elements and accessibility](https://ayagmar.github.io/niri-computer-use/tools/elements.md): List a window's buttons, fields and menu items through the accessibility bus, aim the pointer at them, or activate them and set their text directly.
- [Keyboard and paste](https://ayagmar.github.io/niri-computer-use/tools/keyboard.md): key and type_text, typing and pasting, the focus check, and the virtual keyboard they type through.
- [Acting](https://ayagmar.github.io/niri-computer-use/tools/acting.md): The lease, the structured actions through niri, and the pointer tools.
- [CLI reference](https://ayagmar.github.io/niri-computer-use/reference/cli.md): The niri-computer-use subcommands, what each one prints and when it fails.
- [Noctalia](https://ayagmar.github.io/niri-computer-use/concepts/noctalia.md): What changes when the Noctalia shell is installed and running.