{"slug": "agent-workspace-linux-an-isolated-linux-desktop-that-an-ai-agent-control", "title": "Agent-workspace-Linux An isolated Linux desktop that an AI agent control", "summary": "Agent-sh released agent-workspace-linux, an open-source tool that gives AI agents their own isolated Linux desktop environment to control via the Model Context Protocol (MCP). The tool creates a headless X11 display with its own window manager, apps, clipboard, and browser, preventing agents from hijacking a user's real mouse, keyboard, or browser session. It is designed for GUI testing, web automation, and app inspection in a throwaway, observable environment that integrates with MCP hosts like Claude Code and Codex.", "body_md": "**An isolated, hidden Linux desktop that an AI agent fully controls — over MCP — without ever touching your real mouse, keyboard, focus, or browser.**\n\n*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.*\n\nAgents that \"use a computer\" normally take over *your* screen — they move your mouse, steal focus, and drive your logged-in browser. `agent-workspace-linux`\n\ngives 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](https://modelcontextprotocol.io) over stdio, so it drops into Claude Code, Codex, and other MCP hosts.\n\n**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.\n\nIt is deliberately **not** a tool for driving your actual desktop — for that, use its sibling [computer-use-linux](https://github.com/agent-sh/computer-use-linux). This one is the *separate, agent-owned* environment; the two are complements.\n\nRequires Linux. Install the runtime dependencies, then build + register in one step:\n\n```\nsudo apt install xvfb openbox xdotool xauth x11-utils imagemagick xclip \\\n    bubblewrap pkg-config libxkbcommon-x11-dev\n./install.sh\n```\n\n`./install.sh`\n\nbuilds the release binary, installs it to `~/.local/bin/`\n\n, installs the bundled skill, and registers the MCP server in `~/.codex/config.toml`\n\n. It is safe to rerun. See [ install.sh --help](/agent-sh/agent-workspace-linux/blob/main/install.sh) for flags (\n\n`--permissions`\n\n, `--skills-dir`\n\n, `--no-skill`\n\n, `--dry-run`\n\n).It builds from source straight from git — no crates.io needed. Install the system dependencies above, then:\n\n```\n# latest from main\ncargo install --git https://github.com/agent-sh/agent-workspace-linux\n# or pin a tagged release\ncargo install --git https://github.com/agent-sh/agent-workspace-linux --tag v0.1.0\n```\n\nThat puts `agent-workspace-linux`\n\non your `PATH`\n\n. Unlike `install.sh`\n\n, it installs only the binary — register it with your MCP host manually (below), and copy `skills/agent-workspace-linux/`\n\ninto your skills directory if you want the bundled skill.\n\nFor MCP hosts that read `.mcp.json`\n\n:\n\n```\n{\n  \"mcpServers\": {\n    \"agent-workspace-linux\": {\n      \"command\": \"/home/YOU/.local/bin/agent-workspace-linux\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nOr install the npm wrapper, which downloads the matching prebuilt Linux binary:\n\n```\nnpm install -g @agent-sh/agent-workspace-linux\n```\n\nPrebuilt `x86_64`\n\nand `aarch64`\n\nLinux binaries are also attached to each [GitHub Release](https://github.com/agent-sh/agent-workspace-linux/releases/latest) — download the one for your architecture, `chmod +x`\n\n, and put it on your `PATH`\n\n.\n\n```\n# 1. Ask the runtime what this machine can do (deps, display, sandbox backends)\nagent-workspace-linux doctor\n\n# 2. Preview a workspace without creating anything\nagent-workspace-linux workspace start --dry-run\n\n# 3. Create the hidden workspace (explicit acknowledgement required)\nagent-workspace-linux workspace start --ack-hidden-workspace --purpose \"QA run\"\n\n# 4. Watch it in the floating viewer\nagent-workspace-linux viewer\n\n# 5. Launch an app, see it, then stop the workspace\nagent-workspace-linux workspace launch --name editor -- xterm\nagent-workspace-linux workspace observe --screenshot --output /tmp/ws.png\nagent-workspace-linux workspace stop\n```\n\nThrough an MCP host you don't run these by hand — the agent calls the matching tools. Start it via the [bundled skill](#the-skill-progressive-tool-loading) so the agent loads only the tools it needs.\n\nThe single most important thing to understand is **who sets the limits in each scenario** — and the project is explicit about it:\n\n| Scenario | Who sets the boundary | What is enforced | Can it be overridden at runtime? |\n|---|---|---|---|\nDefault (no `--permissions` ) |\nYour agent host (Claude Code, Codex, …) |\nThe MCP adds no ceiling of its own and defers to the host's approval flow. One explicit hidden-workspace acknowledgement scopes workspace-local actions to that environment. |\nYes — the host/user owns approvals. |\nDeveloper ceiling (`--permissions file.json` or `AGENT_WORKSPACE_PERMISSIONS` env) |\nThe developer / operator who launched the MCP |\nNetwork mode, mount paths, and an app allowlist, enforced at both the MCP front-end and the workspace daemon's IPC socket — so even workspace-launched apps and other same-uid processes are capped. |\nNo — only by restarting the MCP with new config. This is the authoritative boundary. |\nLive viewer control (pause / read-only) |\nThe human watching, in real time |\nBest-effort: honors a runtime pause when the shared control state is readable, and fails open if it isn't. | It's a convenience layer, not the security boundary — the ceiling above is. |\nWorkspace vs. host |\nThe runtime |\nInput, screenshots, windows, clipboard, and browser control target the hidden workspace only — never your real desktop or host Chrome. |\nLeakage to the host is a reportable bug. |\n\nIn short: **by default the agent host owns permission**, a developer can **lock a hard, daemon-enforced ceiling** via flag or env, and the **viewer gives a human a best-effort live stop** — layered, not conflicting. See [docs/permission-model.md](/agent-sh/agent-workspace-linux/blob/main/docs/permission-model.md) and [SECURITY.md](/agent-sh/agent-workspace-linux/blob/main/SECURITY.md) for the full model and trust assumptions.\n\n**Hidden workspace**— a private`Xvfb`\n\ndisplay + window manager + control socket. Apps launched into it attach to that display, not your session. Creating one requires`--ack-hidden-workspace`\n\nso it is never silent.**Permission ceiling**— optional, declared in JSON (`network`\n\n,`mounts`\n\n,`apps`\n\n). When set, it is enforced for the life of the MCP process. Mount and network isolation are applied with[bubblewrap](https://github.com/containers/bubblewrap)when available.**Profiles**— reusable workspace definitions (mounts, network mode, setup commands, startup apps), e.g.`profile template project-dev`\n\nor`browser-session`\n\n.**Viewer**— a small GPUI window that shows workspace state and a live screen view, with pause / read-only / stop controls. It is not always-on-top by default.**Workspace browser**— workspace-owned Chrome/Chromium reached over a loopback DevTools endpoint, so browser automation never attaches to your host Chrome.\n\nThe MCP exposes ~86 tools. To avoid dumping them all into the agent's context, it ships a skill at [ skills/agent-workspace-linux/SKILL.md](/agent-sh/agent-workspace-linux/blob/main/skills/agent-workspace-linux/SKILL.md). Only the skill's short description stays loaded; when a task needs an isolated desktop or browser, the agent reads the skill and it routes to the right tools per phase (orient → start → observe → act → stop), loading tool schemas on demand.\n\n`./install.sh`\n\ninstalls it to `~/.claude/skills/`\n\n(override with `--skills-dir`\n\n).- Hidden X11 workspace with window listing, screenshots, keyboard/mouse input, clipboard, and per-app logs — all scoped to the workspace display.\n- Optional, daemon-enforced permission ceiling (network / mounts / app allowlist) via flag or\n`AGENT_WORKSPACE_PERMISSIONS`\n\n. - bubblewrap-backed mount and network isolation (\n`disabled`\n\n,`local_only`\n\n,`inherit_host`\n\n) when available. - Workspace-owned browser control over loopback CDP — discover targets, read pages, navigate, extract results.\n- A native floating viewer with best-effort live pause / read-only / stop.\n- Saveable profiles with setup and startup commands.\n- A bundled skill for low-context, on-demand tool use across MCP hosts.\n\n**Linux only.** Targets an X11 (`Xvfb`\n\n) workspace; the viewer is validated on X11/Xwayland, with native Wayland still maturing.**Pre-1.0.** Interfaces and tool schemas can change between versions.**Single-user trust model.** The control socket is a same-uid Unix socket (mode 0600); there is no cross-user protection by design. Run as a dedicated user for multi-user isolation.**Mount/network enforcement needs bubblewrap.** Without it, those policies are declared but not enforced (the runtime tells you which).**Live viewer control is best-effort**, not a hard guarantee — the permission ceiling is the authoritative boundary.\n\n[Permission boundary](/agent-sh/agent-workspace-linux/blob/main/docs/permission-model.md)— the authority model.[GPUI viewer direction](/agent-sh/agent-workspace-linux/blob/main/docs/gpui-viewer-direction.md)— the visible control surface.[SECURITY.md](/agent-sh/agent-workspace-linux/blob/main/SECURITY.md)— trust model and how to report a vulnerability.\n\n[computer-use-linux](https://github.com/agent-sh/computer-use-linux)— the sibling MCP that drives the**user's real** Linux desktop. It is the inverse of this project:`computer-use-linux`\n\nautomates the desktop you are already on, while`agent-workspace-linux`\n\ngives the agent a separate, isolated desktop of its own. Use them together — host control vs. sandboxed agent workspace.\n\nContributions are welcome. Build with `cargo build --locked`\n\n; before pushing, run the gates: `cargo fmt --check`\n\n, `cargo clippy --locked -- -D warnings`\n\n, `cargo test --locked`\n\n, `git diff --check`\n\n, and (for runtime changes) `scripts/integration_smoke.sh`\n\n. See [CONTRIBUTING.md](/agent-sh/agent-workspace-linux/blob/main/CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](/agent-sh/agent-workspace-linux/blob/main/CODE_OF_CONDUCT.md).\n\n[MIT](/agent-sh/agent-workspace-linux/blob/main/LICENSE) © Avi Fenesh", "url": "https://wpnews.pro/news/agent-workspace-linux-an-isolated-linux-desktop-that-an-ai-agent-control", "canonical_source": "https://github.com/agent-sh/agent-workspace-linux", "published_at": "2026-05-27 08:18:34+00:00", "updated_at": "2026-05-27 08:48:46.137244+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "ai-infrastructure", "ai-products", "artificial-intelligence"], "entities": ["Claude Code", "Codex", "MCP", "agent-workspace-linux", "computer-use-linux", "agent-sh"], "alternates": {"html": "https://wpnews.pro/news/agent-workspace-linux-an-isolated-linux-desktop-that-an-ai-agent-control", "markdown": "https://wpnews.pro/news/agent-workspace-linux-an-isolated-linux-desktop-that-an-ai-agent-control.md", "text": "https://wpnews.pro/news/agent-workspace-linux-an-isolated-linux-desktop-that-an-ai-agent-control.txt", "jsonld": "https://wpnews.pro/news/agent-workspace-linux-an-isolated-linux-desktop-that-an-ai-agent-control.jsonld"}}