Related Pages

Related topics: System Architecture & Components, Workspace Lifecycle, Viewer & Browser Tools

Overview & Installation

Project Purpose and Scope

agent-workspace-linux is a Rust-based MCP (Model Context Protocol) server that provisions an isolated, hidden X11 Linux desktop fully controllable by an AI agent. Unlike computer-use tools that hijack the user's real screen, mouse, keyboard, and browser, this project gives the agent a separate Xvfb-backed display with its own window manager, applications, clipboard, and browser session. The agent can launch apps, type, click, take screenshots, and browse — all within a private desktop that the user can observe and pause through a small floating viewer. Source: README.md:1-15

The project is designed for scenarios where an agent must perform GUI or web automation without touching the user's live environment. Common use cases include QA runs on GUI applications or websites, throwaway profile-based browser automation (e.g., shopping, web scraping), headless desktop inspection, and long-running automated tasks that would otherwise require human supervision. Source: README.md:17-31

The project is deliberately not a tool for driving the user's actual desktop — for that, the sibling project computer-use-linux exists. The two are complementary: computer-use-linux automates the desktop the user is already on, while agent-workspace-linux provides a separate, agent-owned environment. Source: README.md:33-35

The latest release is v0.1.4 (v0.1.4 release). The project is pre-1.0, so tool schemas and interfaces may change between versions. Source: README.md:88-90

System Requirements

The project targets Linux only and depends on a specific set of system packages for a complete installation:

• xvfb — headless X11 display server
• openbox — lightweight window manager
• xdotool — synthetic input and window management
• xauth, x11-utils — X11 authentication and utilities
• imagemagick — screenshot capture
• xclip — clipboard management
• bubblewrap — optional but recommended for mount and network isolation
• pkg-config, libxkbcommon-x11-dev — build dependencies

Source: README.md:37-42

If bubblewrap is not available, the runtime will declare the mount and network policies but will not enforce them; the doctor command reports the missing backend. Source: README.md:93-95

Installation Methods

One-step install script (recommended)

The simplest path builds the release binary from source, installs it to ~/.local/bin/, and installs the bundled skill to ~/.codex/skills/ by default. The script is safe to rerun and supports several flags: --permissions for declaring a JSON permission ceiling, --clean-codex-config to remove stale MCP tables, --skills-dir to override the skill installation path, --no-skill to skip skill installation, and --dry-run to preview changes. Source: README.md:37-53

sudo apt install xvfb openbox xdotool xauth x11-utils imagemagick xclip \
    bubblewrap pkg-config libxkbcommon-x11-dev
./install.sh

Install with cargo (from source)

For users who prefer Cargo, the project can be installed directly from git. This method installs only the binary; the user must register it with their MCP host manually and copy the skill separately. Source: README.md:55-72

cargo install --git https://github.com/agent-sh/agent-workspace-linux
# or pin a tagged release
cargo install --git https://github.com/agent-sh/agent-workspace-linux --tag v0.1.1

Install via npm wrapper

The npm distribution at @agent-sh/agent-workspace-linux (version 0.1.4 per the package manifest) provides a wrapper that downloads the matching prebuilt Linux binary from the corresponding GitHub Release and verifies the required .sha256 sidecar before installation. The package supports x64 (x86_64) and arm64 (aarch64) architectures on Linux only. Source: npm/package.json:2-40, npm/README.md:1-30

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

For package managers that skip lifecycle scripts (e.g., pnpm with ignore-scripts=true), the postinstall step can be run manually:

node $(npm root -g)/@agent-sh/agent-workspace-linux/scripts/postinstall.js

Source: npm/README.md:18-23

Prebuilt binaries

Prebuilt x86_64 and aarch64 Linux binaries are attached to each GitHub Release with their .sha256 sidecars. Users download the appropriate asset, verify it with sha256sum -c, make it executable, and place it on their PATH. Source: README.md:86-95

Installation Workflow

flowchart TD
    A[Choose install method] --> B{Method}
    B -->|install.sh| C[apt install deps + run script]
    B -->|cargo| D[cargo install --git ...]
    B -->|npm| E[npm install -g wrapper]
    B -->|prebuilt| F[download binary + verify sha256]
    C --> G[Binary in ~/.local/bin/]
    D --> G
    E --> H[postinstall downloads binary]
    H --> G
    F --> G
    G --> I[agent-workspace-linux doctor]
    I --> J[Register with MCP host]
    J --> K[Install skill to skills dir]
    K --> L[workspace start --ack-hidden-workspace]

Quick Start and MCP Registration

After installation, a typical first-run workflow involves verifying the runtime environment, creating a workspace, observing it through the viewer, launching an application, and stopping the workspace. Source: README.md:99-115

# 1. Check what this machine can do (deps, display, sandbox backends)
agent-workspace-linux doctor

# 2. Preview a workspace without creating anything
agent-workspace-linux workspace start --dry-run

# 3. Create the hidden workspace (explicit acknowledgement required)
agent-workspace-linux workspace start --ack-hidden-workspace --purpose "QA run"

# 4. Watch it in the floating viewer
agent-workspace-linux viewer

# 5. Launch an app, see it, then stop the workspace
agent-workspace-linux workspace launch --name editor -- xterm
agent-workspace-linux workspace observe --screenshot --output /tmp/ws.png
agent-workspace-linux workspace stop

For MCP hosts that read .mcp.json, the server can be registered with the following configuration: Source: README.md:74-82

{
  "mcpServers": {
    "agent-workspace-linux": {
      "command": "/home/YOU/.local/bin/agent-workspace-linux",
      "args": ["mcp"]
    }
  }
}

For other clients, the equivalent Claude Code configuration is provided in the npm wrapper documentation. Source: npm/README.md:30-42

Post-Installation Concepts

The skill (progressive tool loading)

The MCP exposes approximately 86 tools. To prevent context bloat, the project ships a skill at skills/agent-workspace-linux/SKILL.md that the agent reads only when a task requires an isolated desktop or browser. The skill routes through phases (orient → start → observe → act → stop) and loads tool schemas on demand. Source: README.md:148-156

Permission ceiling

A permission ceiling can be declared in JSON with fields for network, mounts, and apps. When set via the --permissions flag or the AGENT_WORKSPACE_PERMISSIONS environment variable, it is enforced for the lifetime of the MCP process at both the front-end and the workspace daemon's IPC socket. Mount and network isolation are applied with bubblewrap when available, supporting modes such as disabled, local_only, and inherit_host. Source: README.md:136-146

Workspace browser

Browser automation is handled through a workspace-owned Chrome/Chromium instance reached over a loopback DevTools endpoint. The helper library at scripts/lib/chrome_cdp.js enforces loopback-only connections and validates WebSocket endpoints to ensure browser control never attaches to the host Chrome. Source: scripts/lib/chrome_cdp.js:1-50

Known limitations

• Linux only. Targets an X11 (Xvfb) workspace; the viewer is validated on X11/Xwayland, with native Wayland still maturing.
• Single-user trust model. The control socket is a same-uid Unix socket (mode 0600) with no cross-user protection by design.
• Without bubblewrap, mount and network policies are declared but not enforced.
• Live viewer control is best-effort, not a hard guarantee — it may fail open when the control state file is unreadable (see issue #21).
• Host clipboard paste into the workspace is not size-capped and carries no explicit consent prompt (see issue #22).

Source: README.md:88-96, issue #21, issue #22

See Also

• Permission Model — authoritative trust model and boundary details
• GPUI Viewer Direction — the visible control surface
• SECURITY.md — vulnerability reporting and trust assumptions
• computer-use-linux — sibling project for driving the user's real desktop

Related Pages

Related topics: Overview & Installation, Permission Model & Security, Workspace Lifecycle, Viewer & Browser Tools

System Architecture & Components

Overview

agent-workspace-linux is an MCP (Model Context Protocol) server that provisions and drives a separate, hidden Linux desktop so an AI agent can take screenshots, launch apps, type, click, and browse without ever touching the user's real session (README.md:5-15). The binary exposes roughly 86 tools over JSON-RPC stdio and is intended to be wired into Claude Code, Codex, or any other MCP host.

The architecture is intentionally layered: a MCP front-end is the only process that talks to the host, a workspace daemon owns the live display and IPC enforcement, and the hidden X11 session plus optional browser and GPUI viewer are isolated children. Each layer enforces a different boundary — host approval, developer-set ceiling, or human-supervised pause — and the layers are explicit about which is authoritative (README.md:117-130).

High-Level Architecture

flowchart TB
    Host["MCP Host<br/>(Claude Code / Codex)"]
    Front["MCP Front-end<br/>agent-workspace-linux mcp<br/>JSON-RPC stdio"]
    Daemon["Workspace Daemon<br/>Unix socket 0600<br/>(authoritative IPC gate)"]
    X11["Hidden Workspace<br/>Xvfb + openbox<br/>xdotool / xclip / xauth"]
    CDP["Workspace Browser<br/>Chromium + loopback CDP"]
    Viewer["GPUI Viewer<br/>floating, best-effort controls"]
    Perm["Permission Ceiling<br/>(--permissions / env)"]
    Bwrap["bubblewrap<br/>mount + network isolation"]
    Skill["Skill<br/>skills/agent-workspace-linux/SKILL.md"]

    Host -- "tool calls" --> Front
    Front -- "MCP tools" --> Daemon
    Front -. "enforces" .- Perm
    Daemon -- "controls" --> X11
    Daemon -. "enforces" .- Perm
    Daemon -- "spawns" --> CDP
    Daemon -- "spawns" --> Bwrap
    Viewer -- "observe + pause" --> Daemon
    Skill -. "routes agent to" .- Front

Core Components

MCP Front-end

The agent-workspace-linux binary is the single entry point. It is built and installed by ./install.sh to ~/.local/bin/, or distributed as the npm wrapper @agent-sh/agent-workspace-linux, which downloads a prebuilt Linux binary and verifies its .sha256 sidecar (README.md:55-79; npm/README.md:5-21). The current distribution is version 0.1.4 per npm/package.json:3. The front-end speaks stdio JSON-RPC and exposes the ~86 tools that agents consume; it is registered with hosts either through a .mcp.json entry or via Codex's "Agent Workspaces" feature page.

Workspace Daemon

The daemon is the authoritative enforcement point for live control. It holds a same-uid Unix control socket (mode 0600) and arbitrates every mutating IPC request (README.md:31-35). It is responsible for the permission ceiling (network mode, mount paths, app allowlist) when one is configured, and it is the process the viewer talks to for live pause / read-only / stop. The community has flagged a known fail-open behavior: when the shared mcp-control.json is unreadable, the daemon's live-control gate allows mutating IPC requests rather than denying them — see issue #21.

Hidden Workspace (Xvfb + openbox)

The actual desktop is a headless Xvfb display running openbox as a window manager, with xdotool for input, xclip for clipboard, and xauth for per-display credentials. Creating one requires an explicit --ack-hidden-workspace acknowledgement so that a hidden desktop is never spawned silently (README.md:131-140). All input, screenshots, window listing, clipboard, and per-app logs are scoped to this display — leakage to the host display is a reportable bug.

Permission Ceiling

When the developer passes --permissions <file.json> or sets AGENT_WORKSPACE_PERMISSIONS, the ceiling (network, mounts, apps) is enforced at both the MCP front-end and the daemon's IPC socket, so even apps launched from inside the workspace and other same-uid processes are capped (README.md:117-130). Without this flag the MCP adds no ceiling of its own and defers to the host's approval flow. Mount and network isolation are applied with bubblewrap when available; without it, those policies are declared but not enforced and the runtime reports the gap.

Workspace Browser (loopback CDP)

Browser automation is workspace-owned: a workspace-spawned Chromium exposes its DevTools endpoint on a loopback address, and the scripts/lib/chrome_cdp.js helper speaks the Chrome DevTools Protocol over plain http and ws. The library validates that the HTTP endpoint uses http: and that the host is one of 127.0.0.1, localhost, ::1, or [::1] before any request is made (scripts/lib/chrome_cdp.js:18-30), and it applies the same loopback + ws: checks when opening the WebSocket (scripts/lib/chrome_cdp.js:106-117). Frame parsing is implemented from scratch (mask, length, ping/pong, close) so no third-party CDP client is needed.

GPUI Viewer

The native floating viewer is built on GPUI and shows live state plus a screen preview, with best-effort pause / read-only / stop. It is explicitly not the security boundary — only the permission ceiling is — and it can fail open if the control state is unreadable (README.md:121-128). A community-raised concern (issue #22) notes that host→workspace clipboard paste is not size-capped and carries no explicit consent prompt, so a human watching the viewer should be aware that the host clipboard flows into the agent's environment.

Skill and Profiles

To keep tool schemas out of context, the project ships a skill at skills/agent-workspace-linux/SKILL.md that routes the agent through orient → start → observe → act → stop and loads tool schemas on demand (README.md:91-100). Profiles — reusable workspace definitions of mounts, network mode, setup commands, and startup apps — are created with profile template project-dev and similar, so a single command can rebuild a known-good environment.

Known Failure Modes

• Daemon fail-open on unreadable control state (#21): if mcp-control.json is unreadable, mutating IPC is allowed rather than denied. Treat the viewer as a convenience, not a gate.
• Clipboard leak surface (#22): host→workspace clipboard is uncapped and has no consent UI; treat any paste into the viewer as disclosing the host clipboard to the workspace.
• Bubblewrap absent: mount and network policies are still declared but not enforced; the runtime reports which backends are missing.
• Single-user trust model: the control socket is a same-uid 0600 Unix socket by design — there is no cross-user protection (README.md:39-44).

See Also

• Permission Model — the authoritative trust boundary.
• GPUI Viewer Direction — the visible control surface.
• SECURITY.md — trust model and vulnerability reporting.
• Related project: computer-use-linux — the inverse sibling for driving the host desktop.

Related Pages

Related topics: System Architecture & Components, Workspace Lifecycle, Viewer & Browser Tools

Permission Model & Security

Overview and Threat Model

agent-workspace-linux gives an MCP-driven agent its own hidden Linux desktop (Xvfb + window manager + workspace browser) so it can launch GUI apps, type, click, screenshot, and browse without hijacking the user's real screen. Because the agent runs as a peer to the user inside a private display, the permission model is the project's core safety contract: it decides who can do what inside that workspace and what is allowed to leave it.

The model is layered rather than absolute. Three orthogonal authorities can each set a boundary:

1. The MCP host (Claude Code, Codex, …) owns approval flow by default.
2. The developer/operator who launched the MCP can lock a hard ceiling via --permissions or AGENT_WORKSPACE_PERMISSIONS.
3. A human watching the floating viewer can pause or mark read-only in real time (best-effort only).

The README is explicit that these layers are not interchangeable: only the developer ceiling is the authoritative boundary; the viewer control is a convenience, and the host's approvals are an out-of-MCP concern. Source: README.md

Trust Assumptions and Workspace Isolation

The runtime assumes a single-user, same-uid trust boundary. The workspace daemon's control socket is a Unix domain socket created with mode 0600, and there is no cross-user protection by design — for multi-user isolation the project recommends launching under a dedicated unprivileged user. Source: README.md

Workspace scope is enforced by routing every input, screenshot, window operation, clipboard read/write, and browser automation through the hidden workspace display only. The host's mouse, keyboard, focus, and Chrome session are never attached, and any leakage of host resources into the workspace is treated as a reportable bug rather than a configuration choice. Source: SECURITY.md

Workspace browser control is anchored on a loopback Chrome DevTools endpoint. The helper module at scripts/lib/chrome_cdp.js actively rejects DevTools URLs whose host is not 127.0.0.1, localhost, or ::1, preventing accidental remote attachment. Source: scripts/lib/chrome_cdp.js

Permission Scenarios

Source: README.md

The developer ceiling is the only row that is non-overrideable for the lifetime of the MCP process. It is declared as JSON with three keys: network (disabled | local_only | inherit_host), mounts, and apps. When bubblewrap is installed, mount and network isolation are actually applied; without it, the policy is reported by the runtime as declared-but-unenforced, so operators must read the diagnostic output of agent-workspace-linux doctor. Source: docs/permission-model.md and README.md

The install.sh script accepts --permissions <file> and forwards it to the installed MCP entry point, while the bundled skill at skills/agent-workspace-linux/SKILL.md loads tool schemas on demand so the agent only sees the permission-relevant tools it actually needs. Source: install.sh and skills/agent-workspace-linux/SKILL.md. The npm distribution documents the same trust model and recommends the dedicated Codex Agent Workspaces feature page so permission rules and reconnect control stay scoped away from the generic MCP settings page. Source: npm/README.md

Live Enforcement Layer and Known Failure Modes

The workspace daemon is the authoritative enforcement point for viewer-forwarded input — key/mouse traffic injected from the floating viewer reaches the daemon over its IPC socket, where it must pass the shared live-control gate (active / read_only / paused, stored in mcp-control.json) before being delivered to the workspace. Source: docs/gpui-viewer-direction.md

Two open issues describe concrete failure modes in this layer:

• Issue #21 — Daemon live-control gate fails open on unreadable mcp-control.json. When the daemon cannot read the shared control state file, mutating IPC requests are allowed through rather than rejected. Because viewer-forwarded input does not pass through the MCP front-end's approval flow, the daemon is the only enforcement point for that path; a transient filesystem error or missing file therefore disables the pause/read-only guarantees for viewer input until the file becomes readable again. Source: issue #21
• Issue #22 — Host → workspace clipboard paste lacks size cap and explicit consent. When the host clipboard is pasted into the workspace there is no upper bound on payload size and no explicit confirmation that host clipboard contents (which may carry secrets, tokens, or unreleased prompts) will enter the agent-controlled workspace. This is a host-to-workspace confidentiality surface. Source: issue #22

The project publishes its trust assumptions and disclosure process in SECURITY.md, and gates runtime changes through scripts/integration_smoke.sh plus cargo test --locked. Source: scripts/integration_smoke.sh

Operational Guidance

For users running the project today:

• Treat the developer ceiling (declared in JSON, enforced through bubblewrap when available) as the only durable boundary. Layer the host's approval flow and the viewer control on top of it; do not rely on them alone. Source: docs/permission-model.md
• Install bubblewrap before relying on network or mounts policies — without it those policies are reported but not enforced. Source: README.md
• For multi-tenant or shared hosts, run the MCP under a dedicated unprivileged user; the same-uid socket model does not isolate across users by design. Source: SECURITY.md
• Treat --ack-hidden-workspace as a real consent gate: it is the project's single explicit acknowledgement that the operator understands they are creating an agent-owned, isolated desktop. Source: README.md

See Also

• README.md — installation, quick start, and boundary overview.
• docs/permission-model.md — the authoritative permission model document.
• SECURITY.md — trust assumptions and how to report vulnerabilities.
• docs/gpui-viewer-direction.md — the live viewer control surface.

Related Pages

Related topics: Overview & Installation, System Architecture & Components, Permission Model & Security

Workspace Lifecycle, Viewer & Browser Tools

Purpose and Scope

agent-workspace-linux gives an AI agent its own hidden Linux desktop — a headless Xvfb display, a window manager, an isolated clipboard, and a workspace-owned browser — so the agent can launch apps, type, click, screenshot, and browse without ever touching the host's mouse, keyboard, focus, or logged-in Chrome session. The three subsystems documented on this page — the workspace lifecycle (start/observe/act/stop), the floating viewer (the visible, human-facing control surface), and the workspace browser tools (loopback CDP automation) — are the only entry points the agent or operator normally uses after installation. Everything else is plumbing. Source: README.md:1-19.

The MCP server speaks JSON-RPC over stdio, exposes ~86 tools, and ships a progressive-loading skill at skills/agent-workspace-linux/SKILL.md so the agent only pulls in the tool schemas it actually needs, routed by phase (orient → start → observe → act → stop). Source: README.md:103-128, skills/agent-workspace-linux/SKILL.md.

Workspace Lifecycle

The lifecycle is a small, explicit state machine. The README documents the canonical hand-driven flow that the MCP tools mirror internally. Source: README.md:62-80.

stateDiagram-v2
    [*] --> PreFlight: doctor
    PreFlight --> DryRun: workspace start --dry-run
    DryRun --> Created: workspace start --ack-hidden-workspace
    Created --> Running: workspace launch --name <app> -- <cmd>
    Running --> Observed: workspace observe --screenshot
    Running --> Paused: viewer pause
    Paused --> Running: viewer resume
    Running --> ReadOnly: viewer read-only
    ReadOnly --> Running: viewer resume
    Running --> Stopped: workspace stop
    Running --> Stopped: viewer stop
    Stopped --> [*]

Key lifecycle rules:

• Acknowledgement is mandatory. Creating the hidden display requires --ack-hidden-workspace so the operation is never silent. Source: README.md:46-49.
• Profiles are reusable workspace definitions (mounts, network mode, setup commands, startup apps) like profile template project-dev or browser-session. Source: README.md:101-104.
• The doctor command is the only safe first step: it reports runtime dependencies, the available display backend, and which sandbox backends (bubblewrap, etc.) are present, so a failed workspace start is never a surprise. Source: README.md:62-66.
• Installation is layered. install.sh builds the release binary into ~/.local/bin/ and copies the bundled skill into ~/.codex/skills/ (override with --skills-dir); the npm wrapper at npm/package.json:1-41 instead downloads the matching prebuilt x86_64 / aarch64 Linux binary from the GitHub Release and verifies the required .sha256 sidecar before installing. Source: install.sh, npm/package.json:18-30, npm/README.md:9-25.

Viewer and Live Control

The viewer is a small native GPUI window that shows workspace state and a live screen view, with pause / read-only / stop controls. It is the only place a human can see what the agent is doing in real time. Source: README.md:18-25, README.md:105-107.

The runtime splits responsibility explicitly, and the project is upfront that the viewer is not the security boundary:

Source: README.md:82-99, docs/permission-model.md.

Because the viewer is best-effort, the README warns: *"It's a convenience layer, not the security boundary — the ceiling above is."* Source: README.md:96-99.

Browser Tools

Browser automation never attaches to the host's Chrome. Instead, the workspace launches its own Chrome/Chromium and reaches it over a loopback DevTools endpoint. The client logic lives in scripts/lib/chrome_cdp.js and enforces the loopback boundary at every layer:

• normalizeEndpoint() rejects anything whose URL is not http: and whose host is not in 127.0.0.1, localhost, ::1, or [::1]. Source: scripts/lib/chrome_cdp.js:31-44.
• The WebSocket constructor CdpConnection.connect() repeats the same checks — only ws: schemes and the same loopback host set are accepted, and it validates the Sec-WebSocket-Accept handshake against the expected SHA-1 of the client's nonce. Source: scripts/lib/chrome_cdp.js:68-104.
• httpJson() similarly pins the protocol to http: and timeouts the request if Chrome stalls. Source: scripts/lib/chrome_cdp.js:9-30.
• The frame parser in CdpConnection.onData() enforces a MAX_SAFE_INTEGER length cap and treats any client-to-server frame as masked, matching RFC 6455. Source: scripts/lib/chrome_cdp.js:119-162.
• request() correlates responses by id, rejects on error, and timeouts any unanswered CDP call (timed out waiting for CDP <method>). Source: scripts/lib/chrome_cdp.js:191-204.

Real-profile session validation is intentionally not silent. The helper scripts/mcp_real_profile_browser_session_dogfood.js refuses obvious active-profile hazards, copies the approved profile to a disposable directory, and proves the logged-in page with workspace browser tools (not the host Chrome bridge). It supports --site github, --site slack, --expect-text, and BROWSER_BIN=chromium. Source: README.md:114-127.

Limitations, Risks, and Community Issues

Known operational limits worth surfacing:

• Linux only, X11 / Xvfb. Native Wayland is still maturing; the viewer is validated on X11/Xwayland. Source: README.md:31-33.
• Pre-1.0. Tool schemas may change between versions. Source: README.md:34-35.
• Single-user trust model. The control socket is a same-uid Unix socket (mode 0600); there is no cross-user protection by design. Source: README.md:36-37.
• Sandbox is declared, not enforced, without bubblewrap. The runtime reports which isolation backends are active. Source: README.md:38-39.
• Live viewer control is best-effort. Two open community issues track concrete failure modes of this surface: #21 documents that the daemon's live-control gate (active / read_only / paused) fails open for mutating IPC requests when the shared mcp-control.json cannot be read, allowing forwarded viewer input to slip past the intended pause. Source: issue #21.
• Clipboard flow has no size cap or explicit consent. Issue #22 records that host clipboard contents pasted into the workspace are not size-capped and lack an explicit "this sends your host clipboard into the agent-controlled workspace" prompt, opening a host → workspace confidentiality surface. Source: issue #22.

See Also

• docs/permission-model.md — the full authority model.
• docs/gpui-viewer-direction.md — the visible control surface.
• SECURITY.md — trust model and vulnerability reporting.
• computer-use-linux — the sibling MCP that drives the user's real desktop (the inverse of this project).
• skills/agent-workspace-linux/SKILL.md — the progressive-loading skill that routes the agent to the right tools per lifecycle phase.

Doramagic Pitfall Log

Found 9 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | github_repo:1247893483 | https://github.com/agent-sh/agent-workspace-linux

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | github_repo:1247893483 | https://github.com/agent-sh/agent-workspace-linux

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | github_repo:1247893483 | https://github.com/agent-sh/agent-workspace-linux

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | github_repo:1247893483 | https://github.com/agent-sh/agent-workspace-linux

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | github_repo:1247893483 | https://github.com/agent-sh/agent-workspace-linux

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/agent-sh/agent-workspace-linux/issues/21

7. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/agent-sh/agent-workspace-linux/issues/22

8. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | github_repo:1247893483 | https://github.com/agent-sh/agent-workspace-linux

9. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | github_repo:1247893483 | https://github.com/agent-sh/agent-workspace-linux

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using agent-workspace-linux with real data or production workflows.

• No size cap or explicit consent on host->workspace clipboard paste - github / github_issue
• Daemon live-control gate fails open on unreadable mcp-control.json (muta - github / github_issue
• v0.1.4 - github / github_release
• v0.1.3 - github / github_release
• v0.1.2 - github / github_release
• v0.1.1 - github / github_release
• v0.1.0 - github / github_release
• Configuration risk requires verification - GitHub / issue