About this project

agent-workspace-linux is a Linux-only tool that gives AI agents their own headless X11 desktop environment, separate from the user's real desktop. It runs a hidden Xvfb display with a window manager, clipboard, and workspace-owned Chrome/Chromium browser, all controlled through the Model Context Protocol (MCP) over stdio. This lets agents perform GUI testing, website QA, and browser automation without moving the user's mouse, stealing focus, or touching their logged-in browser session. The project emphasizes clear permission boundaries. By default, the MCP host (such as Claude Code or Codex) owns approval flow. Developers can optionally enforce a hard permission ceiling via a JSON file or environment variable, restricting network mode, mount paths, and an app allowlist at both the MCP front-end and the workspace daemon's IPC socket. A floating GPUI viewer provides live observation with pause, read-only, and stop controls. Key features include window listing, screenshots, keyboard/mouse input, clipboard access, per-app logs, saveable workspace profiles, and browser automation over a loopback Chrome DevTools Protocol endpoint. A bundled skill enables progressive tool loading so agents only load the ~86 available tools when needed. Installation supports a shell script, cargo from source, npm wrapper, or prebuilt binaries for x86_64 and aarch64. Limitations include Linux-only support, pre-1.0 interface stability, a single-user trust model, and the requirement of bubblewrap for enforced mount and network isolation. The project is MIT licensed and complements the sibling computer-use-linux tool, which drives the user's actual desktop.