Linux Computer

Linux Computer gives an AI agent a fixed local X11 workspace while you keep using the same laptop. The workspace appears as one ordinary Linux Computer window that can be moved, tiled, floated, resized, hidden, killed, and reopened without changing the agent's desktop or screenshot coordinates.

This is experimental, machine-specific systems software—not a general-purpose desktop product. Read Supported environment and the disclaimer before running it.

What it does

• Presents a persistent fixed-size desktop through a detachable local viewer.

• Runs its own container-scoped dwm with nine tags, layouts, and focus state.

• Gives MCP a stable screenshot and coordinate space independent of the viewer.

• Separates agent and human pointer/keyboard focus with an XInput2 MPX seat.

• Allows atomic agent/human ownership handoff; agent ownership makes the viewer watch-only.

• Can attach and detach the same live host X11 window without restarting its process or changing its application state.

• Leaves the installed host dwm binary and configuration untouched.

• Ships ready-to-run x86-64 native artifacts; normal installation does not compile Xorg, dwm, or the native workspace components.

The first-principles architecture is in DESIGN.md.

Related MCP server: taw-computer

Supported environment

The only supported and tested target is the original development laptop:

Other Xorg releases, kernels, GPUs, drivers, window managers, distributions, multi-monitor layouts, docks, hotplug, suspend/resume, and application releases are untested and unsupported. They may work, but please treat that as a porting effort. There is no native Wayland support, and Wayland windows cannot be attached.

The prebuilt executables in vendor/ are dynamically linked x86-64/glibc binaries from that Gentoo system. They are not promised to run on another distribution or libc. Integrity verification does not imply ABI compatibility.

Backends

same-server

The native backend keeps the host and workspace on the same Xorg server. It reserves an unscanned rectangle below the physical outputs, runs an internal dwm beneath an override-redirect container, and uses a separate MPX input seat. Because attached windows never leave :0, the exact live X11 window can be reparented into and out of the workspace.

This backend temporarily changes the root framebuffer and RandR panning tracking state. It does not add a monitor or patch/restart host dwm. A device-scoped barrier keeps the human pointer on the physical display, and clean stop/recovery restores RandR and MPX state.

xephyr

The default fallback runs a separate X server in the viewer. It provides a stronger accidental separation boundary, but a live :0 window cannot migrate to Xephyr's :100. Applications must be launched inside the nested server.

Install

Follow INSTALL.md. The short version for the tested layout is:

git clone https://github.com/Ocean-Moist/linux-computer.git ~/linux-computer
cd ~/linux-computer
uv sync --frozen --no-dev
./scripts/verify-production-artifacts

Do not run make for a normal installation. Source and build files are present for maintainers, but the launchers consume the checked-in native artifacts.

If you would rather have Codex or Claude Code inspect the machine, install the MCP, and adapt/install the bundled skill, use the guarded prompts and exact commands in Agent-assisted setup.

Start and stop

Start the isolated Xephyr fallback:

~/linux-computer/bin/linux-computer start

Start the native same-server backend:

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

The start command is the foreground supervisor. Keep it in a durable terminal or session. In another terminal:

~/linux-computer/bin/linux-computer status
~/linux-computer/bin/linux-computer doctor
~/linux-computer/bin/linux-computer show
~/linux-computer/bin/linux-computer hide
~/linux-computer/bin/linux-computer stop

If the same-server supervisor was killed or left stale state:

~/linux-computer/bin/linux-computer recover

doctor verifies observed agent-pointer coordinates and performs an invisible XI2 motion/hit-test/button canary; structural MPX state alone is not considered proof that input works.

Ownership and live windows

The workspace starts in agent ownership. The viewer remains visible but ignores local input. Take control and return it atomically with:

~/linux-computer/bin/linux-computer takeover
~/linux-computer/bin/linux-computer release

takeover arms human input but does not steal the laptop immediately. Click inside the rendered canvas to capture the keyboard and pointer; the title says when capture is active. While captured, host dwm shortcuts are contained and operate the internal desktop. Press Ctrl+Alt+G to release the devices back to the host. release, viewer hide/close, and ownership loss also force-release capture.

With same-server, attach the currently focused host X11 window, attach its declared family, launch a new application, or detach it later:

~/linux-computer/bin/linux-computer attach "$(xdotool getactivewindow)"
~/linux-computer/bin/linux-computer attach --family "$(xdotool getactivewindow)"
~/linux-computer/bin/linux-computer launch alacritty
~/linux-computer/bin/linux-computer windows
~/linux-computer/bin/linux-computer detach WINDOW_ID

--family may move more windows than the selected one. It is useful when an multi-window application shares one X client connection across top-levels, because X11 ClientPointer policy is per client rather than per window.

Linux Computer does not automatically start or special-case a browser. Launch or attach applications explicitly. Attaching a signed-in application preserves its existing process, credentials, and authority, which is convenient but also part of the AI-control risk described below.

Internal dwm

Internal dwm uses Alt as Mod. Common bindings are:

• Alt+1..9: view a tag

• Alt+Shift+1..9: move the focused window to a tag

• Alt+j/k: change focus

• Alt+t/f/m: tiled/floating/monocle layout

• Alt+Shift+Space: toggle floating

• Alt+Enter: terminal

• Alt+d: dmenu

• Alt+Shift+q: close the focused workspace client

The complete list is in skills/linux-computer-use/references/dwm-bindings.md. In same-server mode, MCP routes internal dwm Alt shortcuts over a private daemon command rather than injecting host-visible Alt chords.

MCP

The stdio entry point is:

~/linux-computer/bin/linux-computer-mcp

It exposes only fixed-canvas capture, bounded workspace input, status/waiting, and exact-executable launch. It does not receive the host DISPLAY or Xauthority and cannot attach windows, change ownership, manage viewers, recover, or stop the workspace. Those remain trusted local CLI operations.

The server is expected to fail initialization while no workspace is running. Start Linux Computer before starting or reloading the client that owns the MCP connection. Codex and Claude Code registration are covered in INSTALL.md.

Verification

uv run --frozen pytest
./scripts/verify-production-artifacts
./scripts/isolated-production-test
./scripts/live-isolation-test

The isolated production test starts a disposable Xorg dummy server and exercises the real daemon, bounded input/capture, internal dwm, live attach/detach, and cleanup. The live isolation test touches the active X session; read it before running it and do not run it while doing important work.

Security and disclaimer

Same-server mode is an isolation mechanism for cooperative local software, not a security boundary against malicious X11 clients or other processes running as the same Unix user. It reparents live windows and temporarily changes Xorg RandR/input state. A crash or driver incompatibility can disrupt the graphical session, strand windows, lose unsaved application work, or require restarting Xorg.

Giving an AI computer-use access is independently dangerous. An agent may read private on-screen data, follow prompt-injection instructions from a webpage, send messages, alter or delete data, make purchases, download or upload files, or act through any account already signed in to a controlled application. A live attached window retains the authority of its existing process and account. The bounded MCP transport limits access to workspace actions; it does not make the agent's decisions trustworthy or make consequential web actions reversible.

Back up important data, close or save important work, test Xephyr first, and be prepared to use recover or restart the X session. Use least-privilege test accounts/profiles, keep sensitive information out of the workspace, supervise the agent, and require confirmation for external or irreversible actions. Do not use this on a machine where interruption, disclosure, or data loss is unacceptable. See DISCLAIMER.md for the complete project warning and THIRD_PARTY_NOTICES.md for bundled-component terms.

License

Original Linux Computer code and documentation are released into the public domain under the Unlicense. Bundled and derived third-party components retain their upstream licenses; the Unlicense does not replace those terms.