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.
- Author
- ilysenko ↗
- Repository
- codex-desktop-linux ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
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
- Critical Boundaries
- When To Use
- Permission Model
- Phase Router
- Safe Workflow
- Browser Tasks
- Do NOT
- Example Trajectory
- Constraints
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.