# Public Contract

This document describes the chat way to use `pyro-mcp` in `4.x`.

`pyro-mcp` currently has no users. Expect breaking changes while this chat-host
path is still being shaped.

This document is intentionally biased. It describes the path users are meant to
follow today:

- prove the host with the terminal companion commands
- serve disposable workspaces over MCP
- connect Claude Code, Codex, or OpenCode
- use the recipe-backed workflows

This page does not try to document every building block in the repo. It
documents the chat-host path the project is actively shaping.

## Package Identity

- distribution name: `pyro-mcp`
- public executable: `pyro`
- primary product entrypoint: `pyro mcp serve`

`pyro-mcp` is a disposable MCP workspace for chat-based coding agents on Linux
`x86_64` KVM hosts.

## Supported Product Path

The intended user journey is:

1. `pyro doctor`
2. `pyro prepare debian:12`
3. `pyro run debian:12 -- git --version`
4. `pyro mcp serve`
5. connect Claude Code, Codex, or OpenCode
6. use `workspace reset` as the normal retry step
7. run one of the documented recipe-backed workflows
8. validate the whole story with `make smoke-use-cases`

## Evaluator CLI

These terminal commands are the documented companion path for the chat-host
product:

- `pyro doctor`
- `pyro prepare`
- `pyro env list`
- `pyro env pull`
- `pyro run`
- `pyro demo`

What to expect from that path:

- `pyro run <environment> -- <command>` defaults to `1 vCPU / 1024 MiB`
- `pyro run` fails if guest boot or guest exec is unavailable unless
  `--allow-host-compat` is set
- `pyro run`, `pyro env list`, `pyro env pull`, `pyro env inspect`,
  `pyro env prune`, `pyro doctor`, and `pyro prepare` are human-readable by
  default and return structured JSON with `--json`
- the first official environment pull downloads from public Docker Hub into the
  local environment cache
- `pyro prepare debian:12` proves the warmed daily loop with one throwaway
  workspace create, exec, reset, and delete cycle
- `pyro demo` proves the one-shot create/start/exec/delete VM lifecycle end to
  end

These commands exist to validate and debug the chat-host path. They are not the
main product destination.

## MCP Entry Point

The product entrypoint is:

```bash
pyro mcp serve
```

What to expect:

- named modes are now the first chat-host story:
  - `pyro mcp serve --mode repro-fix`
  - `pyro mcp serve --mode inspect`
  - `pyro mcp serve --mode cold-start`
  - `pyro mcp serve --mode review-eval`
- bare `pyro mcp serve` remains the generic no-mode path and starts
  `workspace-core`
- from a repo root, bare `pyro mcp serve` also auto-detects the current Git
  checkout so `workspace_create` can omit `seed_path`
- `pyro mcp serve --profile workspace-full` explicitly opts into the larger
  tool surface
- `pyro mcp serve --profile vm-run` exposes the smallest one-shot-only surface
- `pyro mcp serve --project-path /abs/path/to/repo` is the fallback when the
  host does not preserve cwd
- `pyro mcp serve --repo-url ... [--repo-ref ...]` starts from a clean clone
  source instead of a local checkout

Host-specific setup docs:

- [claude_code_mcp.md](../examples/claude_code_mcp.md)
- [codex_mcp.md](../examples/codex_mcp.md)
- [opencode_mcp_config.json](../examples/opencode_mcp_config.json)
- [mcp_client_config.md](../examples/mcp_client_config.md)

The chat-host bootstrap helper surface is:

- `pyro host connect claude-code`
- `pyro host connect codex`
- `pyro host print-config opencode`
- `pyro host doctor`
- `pyro host repair HOST`

These helpers wrap the same `pyro mcp serve` entrypoint and are the preferred
setup and repair path for supported hosts.

## Named Modes

The supported named modes are:

| Mode | Intended workflow | Key tools |
| --- | --- | --- |
| `repro-fix` | reproduce, patch, rerun, diff, export, reset | file ops, patch, diff, export, reset, summary |
| `inspect` | inspect suspicious or unfamiliar code with the smallest persistent surface | file list/read, exec, export, summary |
| `cold-start` | validate a fresh repo and keep services alive long enough to prove readiness | exec, export, reset, summary, service tools |
| `review-eval` | interactive review, checkpointing, shell-driven evaluation, and export | shell tools, snapshot tools, diff/export, summary |

Use the generic no-mode path when one of those named modes feels too narrow for
the job.

## Generic Workspace Contract

`workspace-core` is the normal chat path. It exposes:

- `vm_run`
- `workspace_create`
- `workspace_list`
- `workspace_update`
- `workspace_status`
- `workspace_sync_push`
- `workspace_exec`
- `workspace_logs`
- `workspace_summary`
- `workspace_file_list`
- `workspace_file_read`
- `workspace_file_write`
- `workspace_patch_apply`
- `workspace_diff`
- `workspace_export`
- `workspace_reset`
- `workspace_delete`

That is enough for the normal persistent editing loop:

- create one workspace, often without `seed_path` when the server already has a
  project source
- sync or seed repo content
- inspect and edit files without shell quoting
- run commands repeatedly in one sandbox
- review the current session in one concise summary
- diff and export results
- reset and retry
- delete the workspace when the task is done

Move to `workspace-full` only when the chat truly needs:

- persistent PTY shell sessions
- long-running services and readiness probes
- secrets
- guest networking and published ports
- stopped-workspace disk inspection

## Recipe-Backed Workflows

The documented product workflows are:

| Workflow | Recommended mode | Doc |
| --- | --- | --- |
| Cold-start repo validation | `cold-start` | [use-cases/cold-start-repo-validation.md](use-cases/cold-start-repo-validation.md) |
| Repro plus fix loop | `repro-fix` | [use-cases/repro-fix-loop.md](use-cases/repro-fix-loop.md) |
| Parallel isolated workspaces | `repro-fix` | [use-cases/parallel-workspaces.md](use-cases/parallel-workspaces.md) |
| Unsafe or untrusted code inspection | `inspect` | [use-cases/untrusted-inspection.md](use-cases/untrusted-inspection.md) |
| Review and evaluation workflows | `review-eval` | [use-cases/review-eval-workflows.md](use-cases/review-eval-workflows.md) |

Treat this smoke pack as the trustworthy guest-backed verification path for the
advertised product:

```bash
make smoke-use-cases
```

The chat-host MCP path above is the thing the docs are intentionally shaping
around.