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 is the long version: the constraints, why each one forces the next, and the alternatives that don't work.

Related MCP server: computer-use

Install

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:

bin/linux-computer start

Or the native backend, which is the interesting one:

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

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

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:

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.

MCP

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

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