agent-workspace-linux MCP
An MCP server and CLI that give an agent its own hidden Linux desktop on X11 or Wayland without touching your screen or browser
- 219 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The agent drives mouse, keyboard and windows of a hidden desktop and launches apps as you
- The workspace is not a sandbox: apps see your files and network, and host runtimes relay your keyring and SSH agent
Install
- Works in
Manual install
npm install -g @agent-sh/agent-workspace-linuxDownloads the prebuilt binary and checks sha256; system packages (xvfb, openbox, xdotool and others) install separately through apt.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent drives mouse, keyboard and windows of a hidden desktop and launches apps as you
- The workspace is not a sandbox: apps see your files and network, and host runtimes relay your keyring and SSH agent
This is third-party code. Review the repository files before installing.
What it does
agent-workspace-linux creates a separate desktop for an agent: a private X11 display or native Wayland with its own window manager or compositor and a control socket. An agent that "uses a computer" usually takes over your mouse and logged-in browser, whereas here screenshots, input, windows, clipboard and browser control are all directed only at the workspace and your own screen stays untouched. Backends are X11, i3, KWin, GNOME, Hyprland and COSMIC. The workspace start, launch, observe and stop commands create the area, launch apps and take screenshots, and a floating viewer shows what happens and lets you pause or stop the agent. Creating a workspace needs the explicit --ack-hidden-workspace flag. An allowlist of programs is set with a --permissions file, and that list is the hard boundary. The MCP server starts with agent-workspace-linux mcp, tools are marked read-only, write, destructive or open-world, and a routing skill ships with it.
Who it is for. Linux developers and QA engineers who want an agent to test apps and websites or browse the web on a separate desktop.
Good fit when
- An agent must check a GUI app or website without taking your mouse and browser
- Web tasks run in a browser you can watch and stop
- You want a clean browser profile or your own login, in a separate area
- Screenshots and window automation need a GNOME, KWin, Hyprland or COSMIC Wayland compositor
Not a fit when
- You need isolation for untrusted code: the workspace is not a sandbox and apps run as you
- The platform is not Linux: the project works only there
- You need protection from other users of the machine: the trust model is single-user
Example request
Create a hidden workspace, open my web service in a browser inside it, walk through the login flow and save a screenshotMCP
- Transport
- stdio
- Authentication
- not required
Environment variables
AGENT_WORKSPACE_PERMISSIONS- Path to the file with the program allowlist
Limitations
Linux only; the viewer is validated on X11 and XWayland and native Wayland is still maturing. The project is pre-1.0, so interfaces and tool schemas can change. It is not a sandbox: apps run with your files and network, and host runtimes relay your keyring and SSH agent, so do not launch code you would not run yourself. The program allowlist is the hard boundary and live viewer control is not. One process per profile: a second launch of an app is handed to the instance already running.
How to disable. Stop the workspace with agent-workspace-linux workspace stop and remove the package with npm uninstall -g @agent-sh/agent-workspace-linux or delete the binary from ~/.local/bin. Remove the MCP entry from the client settings.
FAQ
How is it different from ordinary computer use?
Usually an agent moves your mouse, steals focus and drives your logged-in browser. Here the agent has its own display and session bus, so its input, screenshots and windows stay off your desktop.
Which desktop backends are supported?
X11 (the default), i3, KWin, GNOME, Hyprland and COSMIC. The backend is chosen with --session on workspace start or in an MCP call. GNOME takes a version and a scale.
How do I stop the agent?
Through the floating viewer: pause, read-only or stop. If the control state cannot be read, mutating calls fail closed. The hard boundary is the program allowlist.
How do I install it?
System packages through apt (xvfb, openbox, xdotool and others), then the binary: ./install.sh, npm install -g @agent-sh/agent-workspace-linux or cargo install --git. The server is registered with agent-workspace-linux mcp.
Can it browse with my own profile?
Yes, but apps run as you, so web tasks run either in a throwaway profile or with your logins by your choice. For Chromium pass a separate --user-data-dir, or the window opens in the browser already running.
Discussion
No questions or reviews yet.
Related
MCP serversCLI, MCP server and typed Node.js API so an agent can verify its changes in a live mobile app on iOS, Android and more
An MCP server with 29 tools that runs Wayland apps in a virtual KDE Plasma 6 session and reads the accessibility tree
The sbx CLI and an MCP server run an agent's app in a clean Windows Sandbox and return a report with screenshots and crashes
An MCP server that checks whether the agent is really done: drives the real app and returns pass, fail or couldn't tell with the file and line
An agent gets a live session of your web, iOS or Android app, sees the screen, writes tests and checks its own edits.
BrowserStack MCP Server: testing on real devices
BrowserStack MCP Server
The official BrowserStack MCP server: real devices, automated tests and test cases driven by an agent from your editor
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| agent-workspace-linux (this card) | no | not required | 219 | |
| Open Computer Use | no | not required | 2,940 | gives an agent computer control, while this one adds a separate hidden Linux desktop with a viewer |
| ClawX Computer Use | no | 7,601 | a computer-use skill, while agent-workspace-linux has separate display backends and a program allowlist |
README in short
The README explains why an agent needs its own desktop, shows installation (packages, binary, MCP), a quick start, six backends, browser automation, the security model, limitations and validation on disposable Ubuntu 26.04 machines. The skill and MCP have their own sections.