Thales Maciel
d0cf6d8f21
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.
6.8 KiB
First Run Transcript
This is the intended evaluator-to-chat-host path for a first successful run on a supported host.
Copy the commands as-is. Paths and timing values will differ on your machine.
The same sequence works with an installed pyro binary by dropping the
uvx --from pyro-mcp prefix. If you are running from a source checkout
instead of the published package, replace pyro with uv run pyro.
pyro-mcp currently has no users. Expect breaking changes while the chat-host
path is still being shaped.
1. Verify the host
$ uvx --from pyro-mcp pyro doctor
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
2. Inspect the catalog
$ uvx --from pyro-mcp pyro env list
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
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.
$ uvx --from pyro-mcp pyro env pull debian:12
[pull] phase=install environment=debian:12
[pull] phase=ready environment=debian:12
Pulled: debian:12
Version: 1.0.0
Distribution: debian 12
Installed: yes
Cache dir: /home/you/.cache/pyro-mcp/environments
Default packages: bash, coreutils, git
Install dir: /home/you/.cache/pyro-mcp/environments/linux-x86_64/debian_12-1.0.0
OCI source: registry-1.docker.io/thalesmaciel/pyro-environment-debian-12:1.0.0
4. Run one command in a guest
$ uvx --from pyro-mcp pyro run debian:12 -- git --version
[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 in terminals or capture tools. Use
--json if you need a deterministic structured result.
5. Start the MCP server
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:
$ uvx --from pyro-mcp pyro mcp serve --project-path /abs/path/to/repo
If you are outside a local checkout:
$ uvx --from pyro-mcp pyro mcp serve --repo-url https://github.com/example/project.git
6. 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:
$ 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
Claude Code cold-start or review-eval:
$ uvx --from pyro-mcp pyro host connect claude-code --mode cold-start
$ claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode cold-start
$ claude mcp list
Codex repro-fix or inspect:
$ uvx --from pyro-mcp pyro host connect codex --mode repro-fix
$ codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode repro-fix
$ codex mcp list
OpenCode uses the local config shape shown in:
Other host-specific references:
7. Continue into a real workflow
Once the host is connected, move to one of the five recipe docs in use-cases/README.md.
The shortest chat-first mode and story is:
If you want terminal-level visibility into what the agent gets, use the manual workspace flow below:
$ export WORKSPACE_ID="$(uvx --from pyro-mcp pyro workspace create debian:12 --seed-path ./repo --name repro-fix --label issue=123 --id-only)"
$ uvx --from pyro-mcp pyro workspace list
$ uvx --from pyro-mcp pyro workspace sync push "$WORKSPACE_ID" ./changes
$ uvx --from pyro-mcp pyro workspace file read "$WORKSPACE_ID" note.txt --content-only
$ uvx --from pyro-mcp pyro workspace patch apply "$WORKSPACE_ID" --patch-file fix.patch
$ uvx --from pyro-mcp pyro workspace exec "$WORKSPACE_ID" -- cat note.txt
$ uvx --from pyro-mcp pyro workspace summary "$WORKSPACE_ID"
$ uvx --from pyro-mcp pyro workspace snapshot create "$WORKSPACE_ID" checkpoint
$ uvx --from pyro-mcp pyro workspace reset "$WORKSPACE_ID" --snapshot checkpoint
$ uvx --from pyro-mcp pyro workspace export "$WORKSPACE_ID" note.txt --output ./note.txt
$ uvx --from pyro-mcp pyro workspace delete "$WORKSPACE_ID"
Move to the generic no-mode path when the named mode is too narrow. Move to
--profile workspace-full only when the chat really needs shells, services,
snapshots, secrets, network policy, or disk tools.
8. Trust the smoke pack
The repo now treats the full smoke pack as the trustworthy guest-backed verification path for the advertised workflows:
$ make smoke-use-cases
That runner creates real guest-backed workspaces, exercises all five documented stories, exports concrete results where relevant, and cleans up on both success and failure.
9. Optional one-shot demo
$ uvx --from pyro-mcp pyro demo
{
"cleanup": {
"deleted": true,
"reason": "post_exec_cleanup",
"vm_id": "..."
},
"command": "git --version",
"environment": "debian:12",
"execution_mode": "guest_vsock",
"exit_code": 0,
"stdout": "git version ...\n"
}
pyro demo proves the one-shot create/start/exec/delete VM lifecycle works end
to end.