| name | agent-workspace-linux |
| description | Use when a task needs an isolated hidden Linux desktop or workspace-owned browser: GUI app QA, web/browser/shopping automation, sandboxed 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 isolated, agent-owned Linux desktop and workspace-owned browser 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.
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 isolated 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 sandboxed 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 in
isolation. 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.
- Permission ceiling:
--permissions PATH or
AGENT_WORKSPACE_PERMISSIONS caps network, mounts, and app allowlist 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.
- Live control:
mcp_control_state read-only/paused/active is a
best-effort runtime control, not the authoritative security 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_context or mcp_session_brief, then use
mcp_task_plan for app-QA, browser, observe, or cleanup intent.
- Check permissions: call
mcp_permissions before mutating.
- Start: use
workspace_start with ack_hidden_workspace=true and a clear
purpose, or workspace_open_profile for a saved profile.
- Observe: use
workspace_observe or 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_stop when finished; use workspace_cleanup_stale for
orphaned runtimes.
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 isolated
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."
mcp_agent_context and mcp_task_plan for app-QA.mcp_permissions to confirm the active boundary.workspace_start with ack_hidden_workspace=true and purpose
"QA myapp settings".workspace_launch_app with the app command.workspace_observe to find the window.workspace_click / workspace_type_text to exercise Settings.workspace_screenshot and workspace_read_app_log for evidence.workspace_stop.
Constraints
- Keep activation low-noise: only use this skill for isolated 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.
