Thales Maciel d0cf6d8f21 Add opinionated MCP modes for workspace workflows

Introduce explicit repro-fix, inspect, cold-start, and review-eval modes across the MCP server, CLI, and host helpers, with canonical mode-to-tool mappings, narrowed schemas, and mode-specific tool descriptions on top of the existing workspace runtime.

Reposition the docs, host onramps, and use-case recipes so named modes are the primary user-facing startup story while the generic no-mode workspace-core path remains the escape hatch, and update the shared smoke runner to validate repro-fix and cold-start through mode-backed servers.

Validation: UV_OFFLINE=1 UV_CACHE_DIR=.uv-cache uv run pytest --no-cov tests/test_api.py tests/test_server.py tests/test_host_helpers.py tests/test_public_contract.py tests/test_cli.py tests/test_workspace_use_case_smokes.py; UV_OFFLINE=1 UV_CACHE_DIR=.uv-cache make check; UV_OFFLINE=1 UV_CACHE_DIR=.uv-cache make dist-check; real guest-backed make smoke-repro-fix-loop smoke-cold-start-validation outside the sandbox.

2026-03-13 20:00:35 -03:00

8.5 KiB

Raw Blame History

Install

pyro-mcp is built for chat-based coding agents on Linux x86_64 with KVM. This document is intentionally biased toward that path.

pyro-mcp currently has no users. Expect breaking changes while the chat-host flow is still being shaped.

Support Matrix

Supported today:

Linux x86_64
Python 3.12+
uv
/dev/kvm

Optional for outbound guest networking:

ip
nft or iptables
privilege to create TAP devices and configure NAT

Not supported today:

macOS
Windows
Linux hosts without working KVM at /dev/kvm

If you do not already have uv, install it first:

python -m pip install uv

Use these command forms consistently:

published package without install: uvx --from pyro-mcp pyro ...
installed package: pyro ...
source checkout: uv run pyro ...

Fastest Evaluation Path

Use either of these equivalent evaluator paths:

# Package without install
uvx --from pyro-mcp pyro doctor
uvx --from pyro-mcp pyro env list
uvx --from pyro-mcp pyro env pull debian:12
uvx --from pyro-mcp pyro run debian:12 -- git --version

# Already installed
pyro doctor
pyro env list
pyro env pull debian:12
pyro run debian:12 -- git --version

If you are running from a repo checkout instead, replace pyro with uv run pyro.

After that one-shot proof works, the intended next step is a named chat mode through pyro host connect or pyro host print-config.

1. Check the host

uvx --from pyro-mcp pyro doctor

Expected success signals:

Platform: linux-x86_64
Runtime: PASS
KVM: exists=yes readable=yes writable=yes
Environment cache: /home/you/.cache/pyro-mcp/environments
Capabilities: vm_boot=yes guest_exec=yes guest_network=yes
Networking: tun=yes ip_forward=yes

If Runtime: FAIL, stop here and use troubleshooting.md.

2. Inspect the catalog

uvx --from pyro-mcp pyro env list

Expected output:

Catalog version: 4.4.0
debian:12 [installed|not installed] Debian 12 environment with Git preinstalled for common agent workflows.
debian:12-base [installed|not installed] Minimal Debian 12 environment for shell and core Unix tooling.
debian:12-build [installed|not installed] Debian 12 environment with Git and common build tools preinstalled.

3. Pull the default environment

uvx --from pyro-mcp pyro env pull debian:12

The first pull downloads an OCI environment from public Docker Hub, requires outbound HTTPS access to registry-1.docker.io, and needs local cache space for the guest image. See host-requirements.md for the full host requirements.

Expected success signals:

[pull] phase=install environment=debian:12
[pull] phase=ready environment=debian:12
Pulled: debian:12
...

4. Run one command in a guest

uvx --from pyro-mcp pyro run debian:12 -- git --version

Expected success signals:

[run] phase=create environment=debian:12
[run] phase=start vm_id=...
[run] phase=execute vm_id=...
[run] environment=debian:12 execution_mode=guest_vsock exit_code=0 duration_ms=...
git version ...

The guest command output and the [run] ... summary are written to different streams, so they may appear in either order. Use --json if you need a deterministic structured result.

5. Connect a chat host

Use the helper flow first:

uvx --from pyro-mcp pyro host connect codex --mode repro-fix
uvx --from pyro-mcp pyro host connect codex --mode inspect
uvx --from pyro-mcp pyro host connect claude-code --mode cold-start
uvx --from pyro-mcp pyro host connect claude-code --mode review-eval
uvx --from pyro-mcp pyro host print-config opencode --mode repro-fix

If setup drifts later, inspect and repair it with:

uvx --from pyro-mcp pyro host doctor
uvx --from pyro-mcp pyro host repair claude-code
uvx --from pyro-mcp pyro host repair codex
uvx --from pyro-mcp pyro host repair opencode

Use a named mode when one workflow already matches the job:

uvx --from pyro-mcp pyro mcp serve --mode repro-fix
uvx --from pyro-mcp pyro mcp serve --mode inspect
uvx --from pyro-mcp pyro mcp serve --mode cold-start
uvx --from pyro-mcp pyro mcp serve --mode review-eval

Use the generic no-mode path when the mode feels too narrow. Bare pyro mcp serve still starts workspace-core. From a repo root, it also auto-detects the current Git checkout so the first workspace_create can omit seed_path.

uvx --from pyro-mcp pyro mcp serve

If the host does not preserve the server working directory, use:

uvx --from pyro-mcp pyro mcp serve --project-path /abs/path/to/repo

If you are starting outside a local checkout, use a clean clone source:

uvx --from pyro-mcp pyro mcp serve --repo-url https://github.com/example/project.git

Copy-paste host-specific starts:

Claude Code setup: claude_code_mcp.md
Codex setup: codex_mcp.md
OpenCode config: opencode_mcp_config.json
Generic MCP fallback: mcp_client_config.md

Claude Code cold-start or review-eval:

pyro host connect claude-code --mode cold-start
claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode cold-start

Codex repro-fix or inspect:

pyro host connect codex --mode repro-fix
codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode repro-fix

OpenCode uses the mcp / type: "local" config shape shown in opencode_mcp_config.json.

If pyro-mcp is already installed, replace uvx --from pyro-mcp pyro with pyro in the same command or config shape.

Use the generic no-mode path when the named mode is too narrow. Move to --profile workspace-full only when the chat truly needs shells, services, snapshots, secrets, network policy, or disk tools.

6. Go from zero to hero

The intended user journey is:

validate the host with pyro doctor
pull debian:12
prove guest execution with pyro run debian:12 -- git --version
connect Claude Code, Codex, or OpenCode with one named mode such as pyro host connect codex --mode repro-fix, then use raw pyro mcp serve --mode ... or the generic no-mode path when needed
start with one use-case recipe from use-cases/README.md
trust but verify with make smoke-use-cases

If you want the shortest chat-first story, start with use-cases/repro-fix-loop.md.

7. Manual terminal workspace flow

If you want to inspect the workspace model directly from the terminal, use the companion flow below. This is for understanding and debugging the chat-host product, not the primary story.

uv tool install pyro-mcp
WORKSPACE_ID="$(pyro workspace create debian:12 --seed-path ./repo --name repro-fix --label issue=123 --id-only)"
pyro workspace list
pyro workspace update "$WORKSPACE_ID" --label owner=codex
pyro workspace sync push "$WORKSPACE_ID" ./changes
pyro workspace file read "$WORKSPACE_ID" note.txt --content-only
pyro workspace patch apply "$WORKSPACE_ID" --patch-file fix.patch
pyro workspace exec "$WORKSPACE_ID" -- cat note.txt
pyro workspace summary "$WORKSPACE_ID"
pyro workspace snapshot create "$WORKSPACE_ID" checkpoint
pyro workspace reset "$WORKSPACE_ID" --snapshot checkpoint
pyro workspace export "$WORKSPACE_ID" note.txt --output ./note.txt
pyro workspace delete "$WORKSPACE_ID"

When you need deeper debugging or richer recipes, add:

pyro workspace shell * for interactive PTY state
pyro workspace service * for long-running processes and readiness probes
pyro workspace create --network-policy egress+published-ports plus workspace service start --publish for host-probed services
pyro workspace create --secret and --secret-file when the sandbox needs private tokens
pyro workspace stop plus workspace disk * for offline inspection

8. Trustworthy verification path

The five recipe docs in use-cases/README.md are backed by a real Firecracker smoke pack:

make smoke-use-cases

Treat that smoke pack as the trustworthy guest-backed verification path for the advertised chat-host workflows.

Installed CLI

If you already installed the package, the same path works with plain pyro ...:

uv tool install pyro-mcp
pyro --version
pyro doctor
pyro env list
pyro env pull debian:12
pyro run debian:12 -- git --version
pyro mcp serve

Contributor clone

git lfs install
git clone <repo>
cd pyro
git lfs pull
make setup

8.5 KiB Raw Blame History

Install

Support Matrix

Fastest Evaluation Path

1. Check the host

2. Inspect the catalog

3. Pull the default environment

4. Run one command in a guest

5. Connect a chat host

6. Go from zero to hero

7. Manual terminal workspace flow

8. Trustworthy verification path

Installed CLI

Contributor clone

8.5 KiB

Raw Blame History