pyro-mcp/docs/first-run.md

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

Bare pyro mcp serve now starts workspace-core, which is the intended chat path:

$ uvx --from pyro-mcp pyro mcp serve

6. Connect a chat host

Claude Code:

$ claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve
$ claude mcp list

Codex:

$ codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve
$ codex mcp list

OpenCode uses the local config shape shown in:

• opencode_mcp_config.json

Other host-specific references:

• claude_code_mcp.md
• codex_mcp.md
• mcp_client_config.md

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 story is:

• use-cases/repro-fix-loop.md

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