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_permissionsonce before mutating to confirmconfigured=false. - App allowlist:
--permissions PATHorAGENT_WORKSPACE_PERMISSIONSlimits 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_catalogmarks 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_stateread-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
- Orient: call
mcp_agent_contextormcp_session_brief, then usemcp_task_planfor app-QA, browser, observe, or cleanup intent. - Check permissions: call
mcp_permissionsbefore mutating. - Start: use
workspace_startwithack_hidden_workspace=trueand a clearpurpose, orworkspace_open_profilefor a saved profile. - Observe: use
workspace_observeor focused screenshot/window/log/event tools before sending input. - Act: launch apps, run commands, click/type/paste/key only inside the workspace.
- Stop: use
workspace_stopwhen finished; useworkspace_cleanup_stalefor 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.
COSMIC runs cosmic-comp under a software-only private Weston parent; see
the COSMIC guide 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=trueand apurpose. - 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."
mcp_agent_contextandmcp_task_planfor app-QA.mcp_permissionsto confirm the active boundary.workspace_startwithack_hidden_workspace=trueand purpose"QA myapp settings".workspace_launch_appwith the app command.workspace_observeto find the window.workspace_click/workspace_type_textto exercise Settings.workspace_screenshotandworkspace_read_app_logfor evidence.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-toolsintentionally: different hosts namespace MCP tools differently, and the skill routes the full family progressively. - Validate with
agnix --target generic|claude-code|cursor|codex|kirowhen changing this file.