Skip to content
Skills Library
AI & agents · Automation

agent-workspace-linux

/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.

Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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.

Original author description

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.

How it works

  1. Critical Boundaries
  2. When To Use
  3. Permission Model
  4. Phase Router
  5. Safe Workflow
  6. Browser Tasks
  7. Do NOT
  8. Example Trajectory
  9. Constraints
Original SKILL.md headings · 194 lines, 1,364 words
SKILL.md preview
---
name: agent-workspace-linux
description: "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."
---

# 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, network, keyring and SSH agent: 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](https://github.com/agent-sh/agent-workspace-linux/blob/main/docs/hyprland.md).
COSMIC runs `cosmic-comp` under a software-only private Weston parent; see
[the COSMIC guide](https://github.com/agent-sh/agent-workspace-linux/blob/main/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.

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.

Versions

The database has no other skills named agent-workspace-linux.

Database snapshot: 13.11.2026 · package version 2c064a03cc26 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100agent-desktop
    通过原生无障碍树,使用 agent-desktop CLI 在 macOS、Windows 和 Linux 上操作桌面应用。 适用于 AI agent 需要查看或操作桌面 GUI 的场景:点击按钮、填写表单、读取 UI 状态、导航菜单、 切换复选框、滚动、拖拽、输入文本、按下快捷键、截图、管理窗口、使用剪贴板、启动或关闭应用、 读取通知。 触发词:"click button"、"fill form"、"open app"、"read UI"、"computer use"、 "operate desktop"、"accessibility…
  • 95agent-desktop-linux
    Linux platform guide for the agent-desktop CLI. Lists per command group what works on X11 and on Wayland, how to check the AT-SPI accessibility bus, the first-contact gotchas (app names, Chromium and Electron flags, headed focus, blocked key combos), and where to find lifecycle,…
  • 100agent-desktop-linux
    Linux platform guide for the agent-desktop CLI. Lists per command group what works on X11 and on Wayland, how to check the AT-SPI accessibility bus, the first-contact gotchas (app names, Chromium and Electron flags, headed focus, blocked key combos), and where to find lifecycle,…
  • 90ai-workspace-orchestrator
    ai-workspace-orchestrator plugin. Routes to its sub-skills: adversarial-setup-review, build-agent-orchestrator, context-handoff, setup-ai-workspace, workspace-contract, write-project-skill. Use when the task matches any of the capabilities listed below.
  • 100agent-desktop-linux
    Linux platform guide for the agent-desktop CLI. Lists per command group what works on X11 and on Wayland, how to check the AT-SPI accessibility bus, the first-contact gotchas (app names, Chromium and Electron flags, headed focus, blocked key combos), and where to find lifecycle,…
  • 100desktop-act
    Cross-OS computer-use MCP: multi-agent exclusive desktop leases, Xvnc pool on Linux, single-session macOS/Windows. Use for GUI/desktop automation and concurrent agent desktops.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.