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.
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.
1---2name: agent-workspace-linux3description: 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.4---56# agent-workspace-linux78Drive an isolated, agent-owned Linux desktop and workspace-owned browser through9the `agent-workspace-linux` MCP server. The workspace runs apps, browser10automation, screenshots, clipboard, and input inside its own hidden display,11never the user's real desktop, focus, or host Chrome.1213This skill is the lightweight entry point. The MCP exposes many tools; do not14load, list, or paste them all up front. Route by phase and ask the host to load15only the tool schemas needed for the next action.1617## Critical Boundaries1819### Use the dedicated Codex for Linux feature page for setup20Codex for Linux owns Agent Workspace setup through the **Agent Workspaces** page:21binary path, page-authored permission rules, permission file mutation,22Reconnect/Smoke test, profile creation, workspace start/stop, and viewer launch.23Do not send users to generic MCP settings, general configuration pages, or24`~/.codex/config.toml` for normal Codex for Linux setup.2526Skip unless: the host is Codex for Linux and the task is setup, permission27changes, reconnect/restart, or the workspace tools are unavailable.2829### Keep tools progressive30The bundled installer is skill-first. `./install.sh` installs this skill under31`~/.codex/skills` by default and leaves generic Codex MCP config untouched32unless the user explicitly chooses `--codex-configure` or `--permissions`.33For migration only, `./install.sh --clean-codex-config` removes stale generic34Codex MCP entries left by older installs; restart or reconnect Codex afterward.3536Skip unless: the user asks how to install/register the backend or why the tool37family should not be loaded at startup.3839### Never target the host desktop40Use this skill only for the hidden workspace. For the user's real Linux desktop,41real Chrome profile, existing tabs, or host focus/mouse/keyboard, use the42appropriate host-desktop or browser tool instead.4344Skip unless: the requested action can run inside the isolated workspace display45or workspace-owned browser.4647## When To Use4849- GUI app QA in a throwaway desktop.50- Browser/web/shopping automation that must not hijack host Chrome.51- Observation of sandboxed windows, logs, events, screenshots, or artifacts.52- Cleanup of stale or orphaned agent workspaces.5354Skip unless: the user task requires running or driving a real GUI app/browser in55isolation. For pure code, shell, or file edits, do not start a workspace.5657## Permission Model5859- **Default**: no MCP ceiling is configured; the host/client owns approvals.60 Call `mcp_permissions` once before mutating to confirm `configured=false`.61- **Permission ceiling**: `--permissions PATH` or62 `AGENT_WORKSPACE_PERMISSIONS` caps network, mounts, and app allowlist for the63 life of that MCP process. It can only be broadened by changing the config and64 restarting/reconnecting the backend from the owning setup surface.65- **Live control**: `mcp_control_state` read-only/paused/active is a66 best-effort runtime control, not the authoritative security boundary.67- **Real-world actions**: checkout, purchases, account changes, and messages68 require explicit user approval. Keep drafting separate from final action.6970Skip unless: you are about to start a workspace, open a profile, launch/run an71app, send input, or act on an external account/site.7273## Phase Router7475Always orient before mutating.7677| Phase | Load only these tools |78| --- | --- |79| Orient | `mcp_agent_context`, `mcp_session_brief`, `mcp_task_plan`, `mcp_permissions`, `mcp_action_catalog`, `workspace_doctor`, `workspace_list`, `workspace_status` |80| Profiles | `profile_list`, `profile_get`, `profile_template`, `profile_put`, `profile_check` |81| Start | `workspace_start`, `workspace_open_profile` |82| Observe | `workspace_observe`, `workspace_screenshot`, `workspace_list_windows`, `workspace_active_window`, `workspace_read_app_log`, `workspace_events` |83| Act | `workspace_launch_app`, `workspace_run_app`, `workspace_click`, `workspace_type_text`, `workspace_key`, `workspace_paste_text`, `workspace_focus_window`, `workspace_close_window` |84| Browser | `workspace_open_browser`, `workspace_browser_targets`, `workspace_browser_snapshot`, `workspace_browser_navigate`, `workspace_browser_search_results`, `workspace_browser_click` |85| Viewer/control | `mcp_control_state`, `mcp_control_update`, `workspace_open_viewer`, `workspace_list_viewers`, `workspace_close_viewer` |86| Teardown | `workspace_stop`, `workspace_kill_app`, `workspace_cleanup_stale` |8788Skip unless: the current phase needs one of the listed capabilities. Do not load89schemas for later phases until the plan reaches them.9091## Safe Workflow92931. Orient: call `mcp_agent_context` or `mcp_session_brief`, then use94 `mcp_task_plan` for app-QA, browser, observe, or cleanup intent.952. Check permissions: call `mcp_permissions` before mutating.963. Start: use `workspace_start` with `ack_hidden_workspace=true` and a clear97 `purpose`, or `workspace_open_profile` for a saved profile.984. Observe: use `workspace_observe` or focused screenshot/window/log/event99 tools before sending input.1005. Act: launch apps, run commands, click/type/paste/key only inside the101 workspace.1026. Stop: use `workspace_stop` when finished; use `workspace_cleanup_stale` for103 orphaned runtimes.104105Skip unless: each step's precondition is visible in the previous tool result106(workspace id, app id, target window, browser target, or explicit user approval).107108## Browser Tasks109110Use the workspace-owned browser over its loopback DevTools endpoint. Start with111`workspace_open_browser`, discover pages with `workspace_browser_targets`, read112with `workspace_browser_snapshot` or `workspace_browser_search_results`, then113navigate or click with browser tools.114115Skip unless: the task is web/browser automation that can run in the isolated116workspace. Do not attach to host Chrome, Playwright, or Computer Use as a117shortcut.118119## Do NOT120121- Do not dump all MCP tools into the agent context at startup.122- Do not send users to generic MCP/configuration pages for Codex for Linux123 Agent Workspace setup.124- Do not start a workspace without `ack_hidden_workspace=true` and a `purpose`.125- Do not send input to or screenshot the user's real desktop.126- Do not perform purchases, checkout, account changes, or sends without explicit127 user approval.128- Do not leave workspaces running after the task.129130## Example Trajectory131132Task: "QA the settings dialog of myapp."1331341. `mcp_agent_context` and `mcp_task_plan` for app-QA.1352. `mcp_permissions` to confirm the active boundary.1363. `workspace_start` with `ack_hidden_workspace=true` and purpose137 `"QA myapp settings"`.1384. `workspace_launch_app` with the app command.1395. `workspace_observe` to find the window.1406. `workspace_click` / `workspace_type_text` to exercise Settings.1417. `workspace_screenshot` and `workspace_read_app_log` for evidence.1428. `workspace_stop`.143144## Constraints145146- Keep activation low-noise: only use this skill for isolated GUI/browser work.147- Keep context small: frontmatter loads by default; body loads on activation;148 tool schemas load on demand.149- Omit `allowed-tools` intentionally: different hosts namespace MCP tools150 differently, and the skill routes the full family progressively.151- Validate with `agnix --target generic|claude-code|cursor|codex|kiro`152 when changing this file.
ilysenko