Agent Workspaces Linux Feature

July 10, 2026 · View on GitHub

agent-workspace is an opt-in ChatGPT Desktop for Linux feature that adds the agent-workspace-linux control surface to the app settings UI.

Enable it in linux-features/features.json before running the install/build pipeline:

{
  "enabled": [
    "agent-workspace"
  ]
}

When enabled, the feature stages the bundled agent-workspace-linux skill inside the generated app and installs it for the current user at launch time to ${CODEX_HOME:-~/.codex}/skills/agent-workspace-linux/SKILL.md. The skill is the agent-facing progressive routing entrypoint; the feature does not write ~/.codex/config.toml or register a generic MCP server at startup.

The feature adds a Linux-only settings section named Agent Workspaces. The page can point ChatGPT Desktop at an agent-workspace-linux binary, list and edit saved profiles, validate profile JSON without saving, preview profile-backed workspace starts, require an explicit approval card before starting a hidden workspace, stop running workspaces, run stale workspace cleanup, and create a restricted Chrome starter profile that keeps the --no-sandbox browser tradeoff visible. It can also prepare a browser-session profile from a picked browser data directory, defaulting to a managed copy under Agent Workspace data and keeping direct read-write mounting behind an explicit profile-lock warning. The friendly profile editor intentionally exposes only three network choices: Closed (network.mode=disabled), Local (network.mode=local_only), and Open (network.mode=inherit_host). More complex host allowlists are not a current product path; advanced JSON can still show older/internal profile data without making the normal UI promise filtering that the runtime does not enforce. The startup-app picker accepts ordinary executable files and Linux .desktop launchers; when a launcher is selected, the bridge reads its Name/Exec fields, removes desktop field codes such as %U, and stores the parsed command array without invoking a shell. Manual startup commands typed into the profile editor are also parsed into an argv array directly; shell syntax such as redirection, pipes, or environment assignment is not interpreted unless the user explicitly chooses a shell binary as the program.

The launcher ignores an inherited ELECTRON_RENDERER_URL by default so the app always uses its own verified webview bundle. Set CODEX_LINUX_ALLOW_RENDERER_URL_OVERRIDE=1 only for explicit debugging.

Install agent-workspace-linux (v0.1.1 or newer) from the Agent Workspaces page with Install from npm, or install it manually. v0.1.1 is the first release whose default ./install.sh no longer writes to ~/.codex/config.toml, matching this feature's app-owned configuration model. If a previous v0.1.0 install left a stale agent-workspace-linux entry in the generic Codex MCP config, run ./install.sh --clean-codex-config once from a v0.1.1+ checkout to remove it; the Agent Workspaces settings page then owns command path, permission file, and viewer launch.

The npm package is published as:

npm i -g @agent-sh/agent-workspace-linux

The npm package name is @agent-sh/agent-workspace-linux; the installed CLI/binary is still called agent-workspace-linux. You can also install a GitHub release binary from https://github.com/agent-sh/agent-workspace-linux/releases, placed on PATH or at ~/.local/bin/agent-workspace-linux.

The bridge is intentionally allowlisted. It invokes agent-workspace-linux through execFile, never through a shell, and exposes only profile/workspace lifecycle actions needed by the UI. The install button also uses execFile with the fixed npm package name. When no npm prefix is already configured, the install button runs npm install -g --prefix ~/.local @agent-sh/agent-workspace-linux so packaged installs do not try to write into the bundled managed Node.js runtime or a system directory. It resolves the binary in this order (highest priority first):

  1. the settings-page command field, persisted as codex-linux-agent-workspace-command
  2. CODEX_AGENT_WORKSPACE_BIN=/absolute/path/to/agent-workspace-linux
  3. an existing binary in Cargo's global bin dir ($CARGO_HOME/bin or ~/.cargo/bin)
  4. npm global bin/package locations ($NPM_CONFIG_PREFIX/bin, common home prefixes, /usr/local/bin, and the published package bin)
  5. an agent-workspace-linux found on PATH
  6. ~/.local/bin/agent-workspace-linux when $HOME is available
  7. a bare agent-workspace-linux (left for the OS to resolve, or to fail with a clear error)

The settings command field and CODEX_AGENT_WORKSPACE_BIN both expand a leading ~/. The feature does not inspect generic Codex MCP config to locate or control the backend; published npm installs and already-present global binaries are the default path, with the command field kept as an explicit override.

The Agent Workspaces settings page is the single user-facing place for this feature. The page owns the command path, optional permission file path, page-authored permission rules, Reconnect, Smoke test, profile templates, workspace start/stop, and viewer launch. The feature does not require the user to visit another settings page or edit shared Codex configuration for Agent Workspace permissions. It does not patch the generic MCP settings page, general configuration page, or conversation/composer surfaces; those pages should remain byte-for-byte unchanged by this feature. Agent-facing workspace tools are expected to be introduced through the bundled skill's progressive, on-demand routing rather than by dumping the entire Agent Workspace MCP tool family into Codex startup context.

Reconnect reruns the backend doctor check and refreshes page-owned state. Smoke test runs doctor, guardrails, profile path, profile list, workspace list, and permission-file inspection so a user can validate the install before approving a real profile directory.

The Permission rules editor controls the actual runtime ceiling shape: network mode, local host entries, allowed file/folder mounts, mount access mode, and app allowlist. Saving those rules writes a page-owned JSON permission file under the Agent Workspace data directory, stores that file path in app state, and immediately makes it the --permissions file for future CLI actions. Reconnect/Smoke test are page-owned backend control paths; changing permission rules does not require the user to visit the generic MCP server page.

If the page has a permission file path, the bridge prepends --permissions PATH to CLI profile/workspace actions. Invalid or missing permission files fail before spawning the CLI, so the page can report the failure directly. If no permission file is configured, the page stays in the existing app-owned permission mode: after the user approves the hidden workspace, normal workspace-local actions follow the Codex session permission choice, including full-access sessions that should not ask again for every click, launch, screenshot, or keystroke.

The feature does not maintain its own hand-listed table of per-action approval defaults. Approval is gated once, at hidden-workspace start, via the dry-run plus approval card; after that the configured permission file and the Codex session permission mode govern individual actions. Per-action classification is owned by the binary and is surfaced through the page instead of duplicated across Codex settings surfaces.

After the user approves a workspace start, the settings page opens the native GPUI viewer with agent-workspace-linux viewer --id WORKSPACE_ID --exit-when-workspace-gone. The active/stopped workspace controls can reopen the same viewer explicitly. This is a detached child process rather than another Codex conversation surface, keeps always-on-top disabled unless explicitly requested, and uses the same page-owned --permissions path when one is configured. Viewer launch errors are reported through the bridge instead of falling back to a shell or crashing the app on an asynchronous spawn failure.

The feature intentionally does not inject a conversation workspace screen. The planned visible monitor is the native GPUI viewer launched by the settings page/bridge, so the Codex conversation stays focused on the thread instead of competing with the floating viewer. The feature only patches the Electron bridge and the Settings webview bundles; conversation and composer webview assets stay untouched.

The dedicated Settings page owns local start approvals: pressing Start first runs a dry-run preview and renders an Approve hidden workspace card with the request, profile, purpose, setup/startup choices, and required acknowledgements. The bridge sends --ack-hidden-workspace and any needed policy acknowledgement only after the user presses Approve and start.

Manual validation checklist for a build that enables this feature:

  1. Launch a side-by-side dev app from clean patched assets.
  2. Open Settings → Agent Workspaces and run Smoke test.
  3. Create or preview the Project, Chrome, and Browser session templates.
  4. Start a workspace only through the dry-run approval card.
  5. Confirm the detached native GPUI viewer opens, then stop the workspace and run stale cleanup.

The removed in-conversation monitor must stay absent: the bridge should not expose the old screenshot-backed workspaceObserve action, and active workspaces should be controlled from Settings plus the native viewer.

Run the feature tests with:

node --test linux-features/agent-workspace/test.js