# 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

```bash
$ uvx --from pyro-mcp pyro doctor --environment debian:12
Platform: linux-x86_64
Runtime: PASS
KVM: exists=yes readable=yes writable=yes
Environment cache: /home/you/.cache/pyro-mcp/environments
Catalog version: 4.5.0
Capabilities: vm_boot=yes guest_exec=yes guest_network=yes
Networking: tun=yes ip_forward=yes
Daily loop: COLD (debian:12)
  Run: pyro prepare debian:12
```

## 2. Inspect the catalog

```bash
$ 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](host-requirements.md) for the
full host requirements.

```bash
$ 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

```bash
$ 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

Warm the daily loop first so the host is already ready for repeated create and
reset cycles:

```bash
$ uvx --from pyro-mcp pyro prepare debian:12
Prepare: debian:12
Daily loop: WARM
Result: prepared network_prepared=no
```

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

```bash
$ 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`:

```bash
$ uvx --from pyro-mcp pyro mcp serve
```

If the host does not preserve the server working directory:

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

If you are outside a local checkout:

```bash
$ 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:

```bash
$ 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:

```bash
$ 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:

```bash
$ 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:

```bash
$ 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:

- [opencode_mcp_config.json](../examples/opencode_mcp_config.json)

Other host-specific references:

- [claude_code_mcp.md](../examples/claude_code_mcp.md)
- [codex_mcp.md](../examples/codex_mcp.md)
- [mcp_client_config.md](../examples/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](use-cases/README.md).

The shortest chat-first mode and story is:

- [use-cases/repro-fix-loop.md](use-cases/repro-fix-loop.md)

If you want terminal-level visibility into what the agent gets, use the manual
workspace flow below:

```bash
$ 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:

```bash
$ 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.

For the machine-level warmup plus retry story specifically:

```bash
$ make smoke-daily-loop
```

## 9. Optional one-shot demo

```bash
$ 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.