# Agent Workspace Linux

> Use when a task needs a hidden Linux desktop running in the background or a workspace-owned browser: GUI app QA, web/browser/shopping automation, app observation, or stale workspace cleanup. Routes agent-workspace-linux MCP tools on demand. Does NOT apply to host desktop/Chrome control, generic MCP setup, or pure code/file edits.

- Skill: `agent-sh/agent-workspace-linux` (Agent Skill)
- Install (CLI): `npx get-skill add agent-sh/agent-workspace-linux`
- Raw SKILL.md: https://api.skillmd.com/api/skills/agent-sh/agent-workspace-linux/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: agent-sh (https://skillmd.com/u/agent-sh)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/agent-sh/agent-workspace-linux

---


# agent-workspace-linux

Drive an agent-owned Linux desktop and workspace-owned browser in the
background through the `agent-workspace-linux` MCP server. The workspace runs
apps, browser automation, screenshots, clipboard, and input inside its own
hidden display, never the user's real desktop, focus, or host Chrome.

It is not a sandbox. Apps you launch there run as the user, with the user's
files and network. Host runtimes also relay the keyring and SSH agent; prepared
GNOME 46 does not relay host session services. A `git push`, a sent message or a file
deleted from a workspace terminal is real. Act as carefully as on the user's
own machine. Launch Chrome through `workspace_open_browser` or with `--user-data-dir`: a plain launch would hand off to the user's running browser and is refused.

This skill is the lightweight entry point. The MCP exposes many tools; do not
load, list, or paste them all up front. Route by phase and ask the host to load
only the tool schemas needed for the next action.

## Critical Boundaries

### Use the dedicated Codex for Linux feature page for setup
Codex for Linux owns Agent Workspace setup through the **Agent Workspaces** page:
binary path, page-authored permission rules, permission file mutation,
Reconnect/Smoke test, profile creation, workspace start/stop, and viewer launch.
Do not send users to generic MCP settings, general configuration pages, or
`~/.codex/config.toml` for normal Codex for Linux setup.

Skip unless: the host is Codex for Linux and the task is setup, permission
changes, reconnect/restart, or the workspace tools are unavailable.

### Keep tools progressive
The bundled installer is skill-first. `./install.sh` installs this skill under
`~/.codex/skills` by default and leaves generic Codex MCP config untouched
unless the user explicitly chooses `--codex-configure` or `--permissions`.
For migration only, `./install.sh --clean-codex-config` removes stale generic
Codex MCP entries left by older installs; restart or reconnect Codex afterward.

Skip unless: the user asks how to install/register the backend or why the tool
family should not be loaded at startup.

### Never target the host desktop
Use this skill only for the hidden workspace. For the user's real Linux desktop,
real Chrome profile, existing tabs, or host focus/mouse/keyboard, use the
appropriate host-desktop or browser tool instead.

Skip unless: the requested action can run inside the workspace display
or workspace-owned browser.

## When To Use

- GUI app QA in a throwaway desktop.
- Browser/web/shopping automation that must not hijack host Chrome.
- Observation of workspace windows, logs, events, screenshots, or artifacts.
- Cleanup of stale or orphaned agent workspaces.

Skip unless: the user task requires running or driving a real GUI app/browser
off the user's screen. For pure code, shell, or file edits, do not start a workspace.

## Permission Model

- **Default**: no MCP ceiling is configured; the host/client owns approvals.
  Call `mcp_permissions` once before mutating to confirm `configured=false`.
- **App allowlist**: `--permissions PATH` or `AGENT_WORKSPACE_PERMISSIONS`
  limits which programs agents may launch, for the life of that MCP process. It can only be broadened by changing the config and
  restarting/reconnecting the backend from the owning setup surface.
- **Action marks**: `mcp_action_catalog` marks each tool read-only, write,
  destructive or open-world. Ask the user before destructive or open-world
  actions they did not request.
- **Live control**: `mcp_control_state` read-only/paused/active is a
  best-effort runtime control, not the authoritative boundary.
- **Real-world actions**: checkout, purchases, account changes, and messages
  require explicit user approval. Keep drafting separate from final action.

Skip unless: you are about to start a workspace, open a profile, launch/run an
app, send input, or act on an external account/site.

## Phase Router

Always orient before mutating.

| Phase | Load only these tools |
| --- | --- |
| Orient | `mcp_agent_context`, `mcp_session_brief`, `mcp_task_plan`, `mcp_permissions`, `mcp_action_catalog`, `workspace_doctor`, `workspace_list`, `workspace_status` |
| Profiles | `profile_list`, `profile_get`, `profile_template`, `profile_put`, `profile_check` |
| Start | `workspace_start`, `workspace_open_profile` |
| Observe | `workspace_observe`, `workspace_screenshot`, `workspace_list_windows`, `workspace_active_window`, `workspace_read_app_log`, `workspace_events` |
| Act | `workspace_launch_app`, `workspace_run_app`, `workspace_click`, `workspace_type_text`, `workspace_key`, `workspace_paste_text`, `workspace_focus_window`, `workspace_close_window` |
| Browser | `workspace_open_browser`, `workspace_browser_targets`, `workspace_browser_snapshot`, `workspace_browser_navigate`, `workspace_browser_search_results`, `workspace_browser_click` |
| Viewer/control | `mcp_control_state`, `mcp_control_update`, `workspace_open_viewer`, `workspace_list_viewers`, `workspace_close_viewer` |
| Teardown | `workspace_stop`, `workspace_kill_app`, `workspace_cleanup_stale` |

Skip unless: the current phase needs one of the listed capabilities. Do not load
schemas for later phases until the plan reaches them.

## Safe Workflow

1. Orient: call `mcp_agent_context` or `mcp_session_brief`, then use
   `mcp_task_plan` for app-QA, browser, observe, or cleanup intent.
2. Check permissions: call `mcp_permissions` before mutating.
3. Start: use `workspace_start` with `ack_hidden_workspace=true` and a clear
   `purpose`, or `workspace_open_profile` for a saved profile.
4. Observe: use `workspace_observe` or focused screenshot/window/log/event
   tools before sending input.
5. Act: launch apps, run commands, click/type/paste/key only inside the
   workspace.
6. Stop: use `workspace_stop` when finished; use `workspace_cleanup_stale` for
   orphaned runtimes.

Session selection supports X11 (`Xvfb` + Openbox), i3 on private Xvfb, and
native Wayland sessions on KWin, GNOME, Hyprland and COSMIC. MCP callers pass
`session: {"backend":"<name>"}` with one of `x11`, `kwin`, `gnome`, `i3`,
`hyprland` or `cosmic`, and may add `"scale":1.5` on the native Wayland
backends for 150% output scaling. CLI start/open-profile accepts the same
names with `--session NAME --scale 1.5`. Explicit MCP input overrides the
profile session; omitting both keeps the pinned X11 default.
KWin needs version 6.6 or newer, kwin-common, kscreen-doctor, wl-clipboard,
and an accessible DRM render node. It runs directly, without a parent Xvfb, and
is not a full Plasma shell. GNOME runs GNOME Shell 50 or 51 with a private
headless output and software rendering; Mutter accepts only scales the chosen
output mode supports. Hyprland uses a private KWin renderer and supports
fractional output scales; see [the Hyprland backend guide](../../docs/hyprland.md).
COSMIC runs `cosmic-comp` under a software-only private Weston parent; see
[the COSMIC guide](../../docs/native-cosmic.md) for its compositor and
XWayland dependencies.
Select i3 with `session: {"backend":"i3"}` or `--session i3`. It uses scale 1,
needs `i3-wm` and the X11 dependencies including ImageMagick `import`, and has
no launcher bindings or startup commands. Move and resize float the target window.
Minimize uses the scratchpad; show restores the window to the current workspace.
Pointer and window coordinates use screenshot pixels on every backend.
Unsupported session names are rejected.

For a prepared GNOME 46 userspace, pass
`session: {"backend":"gnome","version":"46","scale":1.25}` or
`--session gnome --session-version 46 --scale 1.25`. Check the doctor's
`session_runtimes` field or `agent-workspace-linux runtime list` first.
Prepare a missing runtime with
`agent-workspace-linux runtime prepare --backend gnome --version 46`.
Preparation requires Docker and writes a versioned cache; startup requires
bubblewrap with overlay support. It never replaces host packages or falls
back to a different version. Omit `version` to keep using host packages.
GNOME 46 is the only prepared entry. Its system programs and libraries come
from Ubuntu 24.04; user files in HOME remain accessible, and display/bus
sockets and temporary files remain private.

Skip unless: each step's precondition is visible in the previous tool result
(workspace id, app id, target window, browser target, or explicit user approval).

## Browser Tasks

Use the workspace-owned browser over its loopback DevTools endpoint. Start with
`workspace_open_browser`, discover pages with `workspace_browser_targets`, read
with `workspace_browser_snapshot` or `workspace_browser_search_results`, then
navigate or click with browser tools.

Browser tools require a Chrome launched with `--user-data-dir` and loopback
DevTools. Always get it from `workspace_open_browser` (MCP) or
`workspace open-browser` (CLI) rather than hand-rolling a `workspace_launch_app`
argv.

If you attach your own CDP/WebSocket client to that endpoint, omit the `Origin`
header (e.g. `websocket-client`'s `suppress_origin=True`). The DevTools port is
ephemeral, so Chrome's origin allow-list cannot be pre-seeded and an `Origin`-
bearing handshake is rejected with `403 Forbidden`.

After `workspace_browser_navigate` or `workspace_browser_click`, read
`page.url` / `page.title` for post-action state. `target.*` is refreshed to match,
but if the refresh fails the response carries a warning saying it may be stale —
check `warnings` before trusting `target` for verification.

Skip unless: the task is web/browser automation that can run in the
workspace. Do not attach to host Chrome, Playwright, or Computer Use as a
shortcut.

## Do NOT

- Do not dump all MCP tools into the agent context at startup.
- Do not send users to generic MCP/configuration pages for Codex for Linux
  Agent Workspace setup.
- Do not start a workspace without `ack_hidden_workspace=true` and a `purpose`.
- Do not send input to or screenshot the user's real desktop.
- Do not perform purchases, checkout, account changes, or sends without explicit
  user approval.
- Do not leave workspaces running after the task.

## Example Trajectory

Task: "QA the settings dialog of myapp."

1. `mcp_agent_context` and `mcp_task_plan` for app-QA.
2. `mcp_permissions` to confirm the active boundary.
3. `workspace_start` with `ack_hidden_workspace=true` and purpose
   `"QA myapp settings"`.
4. `workspace_launch_app` with the app command.
5. `workspace_observe` to find the window.
6. `workspace_click` / `workspace_type_text` to exercise Settings.
7. `workspace_screenshot` and `workspace_read_app_log` for evidence.
8. `workspace_stop`.

## Constraints

- Keep activation low-noise: only use this skill for background GUI/browser work.
- Keep context small: frontmatter loads by default; body loads on activation;
  tool schemas load on demand.
- Omit `allowed-tools` intentionally: different hosts namespace MCP tools
  differently, and the skill routes the full family progressively.
- Validate with `agnix --target generic|claude-code|cursor|codex|kiro`
  when changing this file.

