agent-workspace-linux

An isolated, hidden Linux desktop that an AI agent fully controls — over MCP — without ever touching your real mouse, keyboard, focus, or browser.

The floating viewer (right) shows the agent doing live website QA inside the hidden workspace, while a Claude Code session (left) drives it. Your real desktop stays yours.

Running open models for your company? Tiyuvta helps with model choice, deployment and optimization, and fine-tuning on your hardware or cloud account.

Agents that "use a computer" normally take over your screen — they move your mouse, steal focus, and drive your logged-in browser. agent-workspace-linux gives the agent its own desktop instead: a headless X11 display with its own window manager, apps, clipboard, and browser. The agent launches apps, types, clicks, screenshots, and browses there; you can watch (and pause) through a small floating viewer. It speaks MCP over stdio, so it drops into Claude Code, Codex, and other MCP hosts.

Why this project

• Use it when an agent needs to QA a GUI app or a website but must not hijack your live desktop or Chrome session.
• Use it when you want browser/web/shopping automation in a throwaway, isolated profile — observable and stoppable.
• Use it when you need a clean Linux desktop to run, screenshot, and inspect an app, then tear it down.
• Use it when a long-running or headless agent needs a desktop it can drive without a human babysitting the real one.

It is deliberately not a tool for driving your actual desktop — for that, use its sibling computer-use-linux. This one is the separate, agent-owned environment; the two are complements.

Install

Requires Linux. Install the runtime dependencies, then build and install in one step:

sudo apt install xvfb openbox xdotool xauth x11-utils imagemagick xclip \
    bubblewrap pkg-config libxkbcommon-x11-dev
./install.sh

./install.sh builds the release binary, installs it to ~/.local/bin/, and installs the bundled skill to ~/.codex/skills/ by default. It is safe to rerun. Codex MCP registration is opt-in: use --codex-configure only for generic MCP-host workflows. In Codex for Linux, use the dedicated Agent Workspaces feature page to configure the backend and permission ceiling so the generic MCP settings/configuration pages stay clean. If an older install still appears in generic MCP/configuration pages, run ./install.sh --clean-codex-config to remove the stale agent-workspace-linux server and tool tables. See install.sh --help for flags (--permissions, --clean-codex-config, --skills-dir, --no-skill, --dry-run).

Install with cargo (from source)

It builds from source straight from git — no crates.io needed. Install the system dependencies above, then:

# latest from main
cargo install --git https://github.com/agent-sh/agent-workspace-linux
# or pin a tagged release
cargo install --git https://github.com/agent-sh/agent-workspace-linux --tag v0.2.0

That puts agent-workspace-linux on your PATH. Unlike install.sh, it installs only the binary — register it with your MCP host manually (below), and copy skills/agent-workspace-linux/ into your skills directory if you want the bundled skill.

For MCP hosts that read .mcp.json: