# Agent Workspace Linux

Use when a task needs a hidden Linux desktop running in the background or a...

- Repository: https://github.com/ilysenko/codex-desktop-linux (3923 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add ilysenko/codex-desktop-linux --skill agent-workspace-linux -g -a claude-code -y`
Codex: `npx skills add ilysenko/codex-desktop-linux --skill agent-workspace-linux -g -a codex -y`
Cursor: `npx skills add ilysenko/codex-desktop-linux --skill agent-workspace-linux -g -a cursor -y`
Gemini CLI: `npx skills add ilysenko/codex-desktop-linux --skill agent-workspace-linux -g -a gemini-cli -y`

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

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

The rest: https://github.com/ilysenko/codex-desktop-linux/blob/HEAD/linux-features/agent-workspace/skills/agent-workspace-linux/SKILL.md