Agent Workspace Desktop

Give an AI agent its own Linux desktop and browser for GUI and web work without taking over your screen.

Stars
★ 228
Last updated
6d ago
License
MIT
Primary language
Rust

At a glance

How it runs
CLIMCP serverAgent plugin / skill
Works with
Universal · cross-platformCodex · Claude Code
Cost
Free, no paid service needed
Setup effort
Medium · a few setup steps
You'll need
LinuxXvfbOpenboxxdotoolxauthx11-utilsImageMagickxclipdbus-daemonpkg-configlibxkbcommon-x11-devShell / CLINetwork accessLocal filesystemMCP Server
Typical use
A development team running GUI or website QA without taking over an employee's desktop or Chrome session.
Not a fit if
  • Users who need automation of their real desktop or host Chrome
  • Teams that require cross-user isolation or a security sandbox
  • Teams using a non-Linux system
Maintenance
Commits in the last 30 dayslast commit 2026-11-15latest release v0.6.4 (2026-11-06)+1.3 ★/day over 7 days
Source review
80/100 · Good

What does this agent do, and when should you use it?

agent-workspace-linux creates a hidden workspace with a private X11 or native Wayland display, its own window manager or compositor, apps, clipboard, and browser. It offers a CLI and an MCP server over stdio for hosts such as Codex and Claude Code. An agent can launch apps, type and click, capture screenshots, and control workspace-owned Chrome or Chromium; a floating viewer lets a person watch, pause, or stop the workspace. Six backends are documented: X11, i3, KWin, GNOME, Hyprland, and COSMIC, with reusable workspace profiles. Apps still run as the current user and can access that user's files and network, so the workspace is not a security sandbox.

Run agent-workspace-linux doctor to check dependencies and available backends, then create a workspace with workspace start --ack-hidden-workspace. The agent can start apps with workspace launch, capture a screen with workspace observe --screenshot, and use keyboard, pointer, window, and clipboard operations. For browser tasks, workspace open-browser starts workspace-owned Chrome, followed by commands such as browser-navigate and browser-snapshot to inspect and act on pages. An MCP host can call the corresponding tools, while the floating viewer provides live viewing, pause, read-only, and stop controls. Stopping the workspace removes its writable runtime layer and temporary files.

  1. A development team running GUI or website QA without taking over an employee's desktop or Chrome session.
  2. A user asking an agent to do background web work in a separate browser that can be watched and stopped.
  3. A tester who needs a clean Linux desktop to launch an app, inspect screenshots, and tear down the environment afterward.
  4. An operations team giving a long-running or headless agent a desktop of its own.

Key setup facts

Pulled from the install and usage notes below. The project README has the current values.

Install / run
  • npm install -g @agent-sh/agent-workspace-linux
  • cargo install --git https://github.com/agent-sh/agent-workspace-linux
Config files
.mcp.json
Install notes cover
Linux

How do you install or deploy this agent?

Install the system packages for the default X11 backend, then choose a source install, the npm package with a prebuilt binary, or a Cargo build. Register the MCP server in an MCP host using .mcp.json. The documented setup does not require a separate model API key; the agent calls the workspace through its MCP host.

sudo apt install xvfb openbox xdotool xauth x11-utils imagemagick xclip \
    dbus-daemon pkg-config libxkbcommon-x11-dev

Install from a clone:

./install.sh

Or install the prebuilt package:

npm install -g @agent-sh/agent-workspace-linux

Or build from Git with Cargo:

cargo install --git https://github.com/agent-sh/agent-workspace-linux

Example MCP host configuration:

{
  "mcpServers": {
    "agent-workspace-linux": {
      "command": "/home/YOU/.local/bin/agent-workspace-linux",
      "args": ["mcp"]
    }
  }
}

How do you use this agent?

Check the machine and preview the workspace before explicitly creating it. Once started, open the viewer, launch an app, capture a screenshot, and stop the workspace when finished.

agent-workspace-linux doctor
agent-workspace-linux workspace start --dry-run
agent-workspace-linux workspace start --ack-hidden-workspace --purpose "QA run"
agent-workspace-linux viewer
agent-workspace-linux workspace launch --name editor -- xterm
agent-workspace-linux workspace observe --screenshot --output /tmp/ws.png
agent-workspace-linux workspace stop

An agent can call the matching tools through an MCP host. Browser workflow example:

agent-workspace-linux workspace open-browser "http://127.0.0.1:8111"
agent-workspace-linux workspace browser-navigate "http://127.0.0.1:8111/page" --wait-ms 1500
agent-workspace-linux workspace browser-snapshot --max-text-chars 2000

What are this agent's strengths and limitations?

Pros
  • A separate display, window manager or compositor, clipboard, and browser keep workspace input away from the user's desktop.
  • Six X11 and native Wayland backends let operators choose for their host environment.
  • MCP tools are marked read-only, write, destructive, or open-world, and an app allowlist can be enforced by the daemon.
  • The floating viewer supports live viewing, pause, read-only mode, and stop.
Limitations
  • Linux only; the default X11 setup needs several system packages, and native backends have additional dependencies.
  • The project explicitly says it is not a sandbox; workspace apps run as the user and can access files and the network.
  • The project is pre-1.0, so interfaces and tool schemas may change.
  • Native Wayland viewer support is still maturing, and the control socket follows a same-user trust model.

How does this agent compare with similar options?

For automating the user's actual Linux desktop, the repository points to its sibling computer-use-linux. This project instead gives the agent a separate background workspace; the two are described as complementary.

Key facts side by side with the most closely related agents.

Agent Source review Form / cost Stars Updated Language Full support on
Agent Workspace Desktop This agent 80 · Good CLIFree ★ 228 6d ago Rust Codex · Claude Code
OpenBot: AI Coworkers You Can Trust with Real Work 87 · Good Self-hosted serviceFree + model costs ★ 13k today TypeScript —
Open Computer Use (MCP desktop service) 79 · Good CLIFree + model costs ★ 3k 1d ago Swift Codex · Claude Code
Auto Browser 76 · Some gaps Self-hosted serviceFree + model costs ★ 929 5d ago Python OpenAI API · Claude API

How does FollowAgents rate this agent?

FollowAgents source review · FARS-2.1
Good
80/ 100 5-point scale 4.0 / 5
Trust 19/29
Reliability 11/14
Adaptability 18/18
Convention 15/18
Effectiveness 10/13
Verifiability 7/8
Why each dimension lost points
Trust19 / 29 · 3.3/5

The docs plainly state that workspaces are not sandboxes and that host runtimes share user files, network, keyring, and SSH agent. Permission ceilings, tool risk marks, read-only/pause controls, and explicit acknowledgement for hidden workspaces provide concrete constraints, supporting scores of 2 for least privilege and confirmation. README, the skill, and the security policy disclose data boundaries and browser-profile risks, so transparency is strong; however, the default has no app allowlist and live control is best-effort, leaving sensitive-data protection incomplete. External actions require approval, and cleanup stops with an error when process ownership cannot be verified, but recovery from all external side effects is not fully covered. Dependency auditing has documented exceptions and rationale, while a Git dependency tracks the main branch and the security policy supports only latest. The license and maintainer are named in repository files, but publisher provenance is unverified and no clear alternate maintenance or update responsibility is shown, so attribution is partial.

Reliability11 / 14 · 3.9/5

README, SKILL, permission docs, security policy, and the code entry point largely agree on product boundaries and operating flow; doctor, dry-run, status inspection, and checked error paths help prevent mistakes. CI configuration covers builds, static checks, tests, and dependency auditing, but this is configuration evidence, not a result from this review. Dependencies include GPUI from a moving Git main branch, which can change and is less reproducible than a pinned revision. Visible error paths add context and fail closed, but the sample does not establish that all failure messages are clear, so these criteria do not receive full marks.

Adaptability18 / 18 · 5.0/5

The product clearly targets background GUI/web QA, browsing, and unattended desktop tasks, while excluding host-desktop control and pure code edits. The skill routes tools through progressive phase-based loading, and the permission boundaries, supported backends, runtime versions, scaling differences, and Linux limits are concrete. Multiple backends and an on-demand prepared GNOME runtime support varied Linux setups, with substantial evidence for these scores.

Convention15 / 18 · 4.2/5

The README is organized around installation, quick start, backends, security, limitations, and docs; installation covers system packages, binaries, MCP registration, and multiple methods. Naming and version information are mostly clear, but the project explicitly says it is pre-1.0 and interfaces may change; no changelog is included in the sample, and examples are extensive without a visible FAQ index, so those areas are partial. Limitations are detailed and the MIT license is clear. The security policy documents latest-version support and a private reporting route, but maintenance responsibility appears centered on one named maintainer without a broader team or succession path.

Effectiveness10 / 13 · 3.8/5

The product supplies a separate desktop, dedicated browser, observation and control surface, and MCP-callable GUI automation for a clear use case that avoids taking over the user's desktop. Plans and tool results include state, previews, warnings, and approval checkpoints, but the sample does not show the full output schemas, so downstream usability is only partly established. System dependencies and multiple backend setup add meaningful cost, with limited cost-benefit guidance.

Verifiability7 / 8 · 4.4/5

Key security and capability claims in the README have corresponding support in the permission model, security policy, SKILL, Cargo configuration, and visible code. The CI file lists reviewable build, check, and audit steps. Cross-source corroboration is good but limited by the packet's partial sample of skills and source. The docs distinguish implemented mechanisms, runtime limits, and probe descriptions; this assessment treats them as static claims and does not present CI configuration as executed results, keeping fact and inference distinct.

Risks and how to mitigate them
  • A workspace is not a sandbox: apps in host runtimes run as the current user and can access user files, network, keyring, and SSH agent; no app allowlist is configured by default.
  • Using real accounts or browser profiles can expose live sessions and cause external effects; use an explicitly approved profile copy and separately confirm sending, purchasing, or account changes.
  • The project is pre-1.0 and a GPUI dependency tracks Git main, so interfaces and build dependencies may change.
Evidence confidence: Low Reviewed Nov 11, 2026 Reviewed revision 3bb1e46250e0 New commits since this review; the score may not cover them
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/agent-workspace-linux.svg)](https://followagents.com/en/agents/agent-workspace-linux)
<a href="https://followagents.com/en/agents/agent-workspace-linux"><img src="https://followagents.com/badge/agent-workspace-linux.svg" alt="FARS review"></a>

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

  1. v0.6.4
    Release notes excerpt
    KWin 6.8.2 workspaces now start when screenshots use RGBX8888. X11 display selection now skips stale artifacts owned by another user instead of aborting. - Accept KWin QImage::Format_RGBX8888 screenshots and force the unused alpha byte to opaque (#194). - Skip unremovable stale X11 sockets and locks, then continue with the next display (#195). - Keep prepared-runtime cache hashes stable with explicit lowercase SHA-256 encoding (#185). - Fix permission tests on NixOS and cover symlinked absolute allow entries (#196). …
    View on GitHub ↗
  2. v0.6.3
    Release notes excerpt
    GNOME 46 is available as a prepared workspace runtime. Use --session gnome --session-version 46, or session: {"backend":"gnome","version":"46"} through MCP and saved profiles. GNOME 46 is the only prepared version. Host packages remain the default. - Fix KWin clicks that dropped the button press. Motion and following input now share one connection and allow pointer focus to settle. Drag start and scrolling use the same path. …
    View on GitHub ↗
  3. v0.6.2
    Release notes excerpt
    The native viewer now uses bundled Inter and supports saved Light, Dark and System themes. The header wraps in narrow windows, secondary controls scroll, and status labels are easier to read. - Viewer typography, colors, spacing and empty states refreshed in #173. - Faster local builds and nextest-based test runs in #172. - Focus smoke now waits for its test window to finish input setup before typing. - Updated rmcp, libc and wayland-protocols dependencies. Install or update: ```sh npm install -g @agent-sh/[email protected] ``` …
    View on GitHub ↗

FAQ

Does workspace creation happen silently?
No. Creation requires --ack-hidden-workspace; the MCP flow also requires explicit acknowledgement.
Is this a security sandbox?
No. Workspace apps run as the current user and can access files and the network. Host runtimes also relay SSH/GPG agents and some session services.
Can it control my current Chrome or real desktop?
Input and browser control are scoped to the workspace. Browser commands require workspace-owned Chrome or Chromium and are not for driving the host desktop or host Chrome.
Do I need a paid model or API key?
The repository lists an MIT license, and the documented installation and examples do not require a paid model or API key. The MCP host supplies the agent.
What happens to workspace files when it stops?
The writable runtime layer and temporary files are removed on shutdown; a prepared GNOME 46 image remains cached for reuse.
Is Agent Workspace Desktop open source?
Yes. The source code is on GitHub (agent-sh/agent-workspace-linux) under the MIT licence.
Is Agent Workspace Desktop still maintained?
Yes. The latest commit on GitHub is from 2026-11-15, within the last 30 days. The latest release is v0.6.4 (2026-11-06).
Who makes Agent Workspace Desktop?
Agent Workspace Desktop is published on GitHub by the account agent-sh. FollowAgents has not verified which person or company is behind that account.
Was this page helpful?
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts