# linux-computer

A fixed X11 workspace for an AI agent, on the laptop you are still using.

The workspace is an ordinary window you can move, tile, hide, or kill. Behind
it is a persistent desktop with its own dwm, its own pointer and keyboard, and
its own screenshot coordinate space that never changes when you resize or close
the viewer. You can drag a live, signed-in application into it and take it back
out without restarting the process.

## How it works

Xorg lets the root framebuffer be larger than the region any monitor scans. The
workspace is a rectangle down there, below your screen, holding real mapped
windows that no output ever displays.

- **Off-viewport reservation.** The desktop lives in unscanned framebuffer
  space, so it is not a RandR monitor and host dwm never adopts it.
- **Panning escapes the CRTC clamp.** Xorg confines pointers to CRTC bounds
  even when the root is bigger. Setting panning *total* equal to the unchanged
  physical mode, with *tracking* over the whole root, lifts the clamp without
  growing the visible screen.
- **A second window manager, nested.** `SubstructureRedirect` is per window,
  not per server, so an internal dwm owns an override-redirect container while
  host dwm keeps the real root.
- **Two input seats.** XInput2 MPX gives the agent its own master pointer and
  keyboard. An XFixes barrier scoped to the human pointer keeps you out of the
  reservation.
- **Live window attachment.** Same server means `XReparentWindow` moves an
  existing window in and out, with the X save set as the crash net.

[DESIGN.md](DESIGN.md) is the long version: the constraints, why each one
forces the next, and the alternatives that don't work.

## Install

```sh
git clone https://github.com/Ocean-Moist/linux-computer.git ~/linux-computer
cd ~/linux-computer
uv sync --frozen --no-dev
```

The native components are prebuilt in `vendor/`. Nothing compiles.

Only tested on the laptop it was written on: Gentoo, x86-64/glibc, Xorg
1.21.1.18, dwm 6.2, amdgpu, one 2240×1400 eDP panel. The `vendor/` binaries are
dynamically linked against that system. Elsewhere, treat this as a porting
exercise. X11 only — Wayland windows cannot be attached.

## Run

Start the nested-Xephyr backend, which is the safe one to try first:

```sh
bin/linux-computer start
```

Or the native backend, which is the interesting one:

```sh
bin/linux-computer start --backend same-server
```

`start` is the supervisor and stays in the foreground. From another terminal:

```sh
bin/linux-computer status
bin/linux-computer doctor    # verifies input actually lands, not just that MPX exists
bin/linux-computer show / hide / stop
bin/linux-computer recover   # after a crash left RandR or MPX state behind
```

The workspace starts owned by the agent; the viewer watches but ignores input.
`takeover` arms your input, then a click inside the canvas grabs keyboard and
pointer VM-style. `Ctrl+Alt+G` gives them back. `release` returns the workspace
to the agent.

With `same-server`, move live windows in and out:

```sh
bin/linux-computer attach "$(xdotool getactivewindow)"
bin/linux-computer attach --family "$(xdotool getactivewindow)"
bin/linux-computer windows
bin/linux-computer detach WINDOW_ID
```

`--family` may move more windows than you selected: `XISetClientPointer` is per
X client, and one client can own several top-levels.

Internal dwm uses Alt as Mod — `Alt+1..9` tags, `Alt+j/k` focus, `Alt+t/f/m`
layouts, `Alt+Enter` terminal, `Alt+d` dmenu. Full list in
[the skill's bindings reference](skills/linux-computer-use/references/dwm-bindings.md).

## MCP

```sh
claude mcp add --transport stdio --scope user linux-computer -- "$PWD/bin/linux-computer-mcp"
ln -s "$PWD/skills/linux-computer-use" ~/.claude/skills/linux-computer-use
```

For Codex, `codex mcp add linux-computer -- "$PWD/bin/linux-computer-mcp"` and
symlink the same skill into `~/.agents/skills`.

The server exposes screenshots on the fixed canvas, bounded input, status, and
launching one exact executable. It gets no host `DISPLAY` or Xauthority, and it
cannot attach windows, change ownership, or stop the workspace — those stay on
the local CLI. Start the workspace before the client that connects to it.

## Caveats

Same-server mode is isolation between cooperative programs, not a security
boundary: everything still shares one X server and one Unix account. It moves
live windows and changes RandR and input state, so a crash can leave your
session odd-sized or strand a window. `recover` handles most of that; keep a
terminal free.

Handing a desktop to an agent is its own risk, separate from the code. It acts
with whatever authority is already signed in, and text on a page it reads can
redirect it. Attaching a logged-in window hands over that session too.

## Build from source

```sh
make -C native production
```

That rebuilds five of the seven `vendor/` artifacts. `Xephyr` is X.Org Server
21.1.18 plus `packaging/xephyr-fixed-scale.patch` then
`packaging/xephyr-input-capture.patch`; `dwm-linux-computer` is dwm 6.2 plus
`packaging/dwm-root-geometry.patch`. Build those from upstream yourself.

`scripts/verify-production-artifacts` hashes `vendor/` against checked-in sums.
Since the sums ship in the same repo, that catches corruption, not provenance —
build it yourself if that matters to you. A local build won't match the hashes.

## License

Public domain ([UNLICENSE](UNLICENSE)). dwm-derived code (`native/dwm-container/`,
`vendor/dwm-*`) is MIT — see `native/dwm-container/LICENSE` and
`vendor/dwm-LICENSE`. `vendor/Xephyr` derives from X.Org Server; see
`vendor/xorg-server-COPYING`.