> ## Documentation Index
> Fetch the complete documentation index at: https://docs.feral.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# GUI Computer Use

> Let FERAL control your desktop — click, type, scroll, and read the screen (macOS / Linux only)

# GUI Computer Use

FERAL can see your screen and interact with any desktop application using Anthropic-style computer-use primitives: screenshots, mouse clicks, typing, key combos, scrolling, and window management.

<Warning>
  GUI computer-use is supported on **macOS** and **Linux** only. On Windows the implementation returns `{"success": false, "reason": "unsupported_platform"}` for every action — earlier docs marked Windows as "Stable", which was wrong. If you need GUI control on Windows today, run FERAL inside WSL2 (Linux subsystem) — the X11 path works there.
</Warning>

## Permission Requirements

### macOS

1. Open **System Settings → Privacy & Security → Accessibility**
2. Add your terminal app (Terminal, iTerm2, or the app running FERAL)
3. Also grant **Screen Recording** permission for screenshots

### Linux (X11)

No special permissions needed on X11. Wayland requires `xdg-portal` or running FERAL in an X11 session.

Install one of: `gnome-screenshot`, `scrot`, or `imagemagick` (for the `import` command).

### Windows

Not supported — see warning above. WSL2 (Ubuntu running an X11 server) is the supported path.

## Rate Limits

FERAL enforces a configurable rate limit on GUI actions to prevent runaway automation:

```bash theme={null}
export FERAL_GUI_MAX_ACTIONS_PER_S=10   # default: 10 actions/second
```

Screenshots are exempt from rate limiting. When the limit is exceeded, the action returns `{"success": false, "reason": "rate_limit_exceeded"}`.

## Coordinate Scaling (Retina / HiDPI)

VLMs see a screenshot image (max 1920px wide). On Retina/HiDPI displays, the physical screen is larger. FERAL automatically detects the DPI scale factor and converts coordinates:

* **macOS:** Queries `NSScreen.backingScaleFactor()` (typically 2.0)
* **Linux:** Reads `GDK_SCALE` environment variable
* **Windows:** Falls back to 1.0

## Troubleshooting

1. **"Screenshot capture failed"** — Check that Screen Recording permission is granted (macOS) or that `scrot`/`gnome-screenshot` is installed (Linux).
2. **Clicks land in the wrong spot** — Usually a DPI mismatch. Check the `dpi_scale` value in screenshot responses. Override with `GDK_SCALE` on Linux.
3. **"rate\_limit\_exceeded" errors** — Increase `FERAL_GUI_MAX_ACTIONS_PER_S` or slow down the automation loop.
4. **Typing non-ASCII fails** — Install `pyperclip`. FERAL uses clipboard paste for non-ASCII text.
5. **Window focus doesn't work** — macOS needs Accessibility permission. Linux needs `wmctrl` or `xdotool`.