Agent Workspace Desktop
Give an AI agent its own Linux desktop and browser for GUI and web work without taking over your screen.
- Source repo
- agent-sh/agent-workspace-linux
- Stars
- ★ 228
- Last updated
- 6d ago
- License
- MIT
- Primary language
- Rust
- FA score
- 80/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free, no paid service needed
- Setup effort
- Medium · a few setup steps
- You'll need
- 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.
- A development team running GUI or website QA without taking over an employee's desktop or Chrome session.
- A user asking an agent to do background web work in a separate browser that can be watched and stopped.
- A tester who needs a clean Linux desktop to launch an app, inspect screenshots, and tear down the environment afterward.
- 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-linuxcargo 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-devInstall from a clone:
./install.shOr install the prebuilt package:
npm install -g @agent-sh/agent-workspace-linuxOr build from Git with Cargo:
cargo install --git https://github.com/agent-sh/agent-workspace-linuxExample 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 stopAn 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 2000What are this agent's strengths and limitations?
- 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.
- 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?
Why each dimension lost points
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.
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.
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.
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.
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.
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.
- 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.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
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 ↗ -
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 ↗ -
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?
--ack-hidden-workspace; the MCP flow also requires explicit acknowledgement.Is this a security sandbox?
Can it control my current Chrome or real desktop?
Do I need a paid model or API key?
What happens to workspace files when it stops?
Is Agent Workspace Desktop open source?
Is Agent Workspace Desktop still maintained?
Who makes Agent Workspace Desktop?
Thanks — we use this to improve the page.