pyro-mcp/README.md

# pyro-mcp

`pyro-mcp` is a disposable MCP workspace for chat-based coding agents such as
Claude Code, Codex, and OpenCode.

It is built for Linux `x86_64` hosts with working KVM. The product path is:

1. prove the host works
2. connect a chat host over MCP
3. let the agent work inside a disposable workspace
4. validate the workflow with the recipe-backed smoke pack

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

This repo is not trying to be a generic VM toolkit, a CI runner, or an
SDK-first platform.

[![PyPI version](https://img.shields.io/pypi/v/pyro-mcp.svg)](https://pypi.org/project/pyro-mcp/)

## Start Here

- Install and zero-to-hero path: [docs/install.md](docs/install.md)
- First run transcript: [docs/first-run.md](docs/first-run.md)
- Chat host integrations: [docs/integrations.md](docs/integrations.md)
- Use-case recipes: [docs/use-cases/README.md](docs/use-cases/README.md)
- Vision: [docs/vision.md](docs/vision.md)
- Public contract: [docs/public-contract.md](docs/public-contract.md)
- Host requirements: [docs/host-requirements.md](docs/host-requirements.md)
- Troubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md)
- Stable workspace walkthrough GIF: [docs/assets/workspace-first-run.gif](docs/assets/workspace-first-run.gif)
- Terminal walkthrough GIF: [docs/assets/first-run.gif](docs/assets/first-run.gif)
- What's new in 4.0.0: [CHANGELOG.md#400](CHANGELOG.md#400)
- PyPI package: [pypi.org/project/pyro-mcp](https://pypi.org/project/pyro-mcp/)

## Who It's For

- Claude Code users who want disposable workspaces instead of running directly
  on the host
- Codex users who want an MCP-backed sandbox for repo setup, bug fixing, and
  evaluation loops
- OpenCode users who want the same disposable workspace model
- people evaluating repo setup, test, and app-start workflows from a chat
  interface on a clean machine

If you want a general VM platform, a queueing system, or a broad SDK product,
this repo is intentionally biased away from that story.

## Quickstart

Use either of these equivalent quickstart paths:

```bash
# Package without install
python -m pip install uv
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
```

![Quickstart walkthrough](docs/assets/first-run.gif)

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

From a repo checkout, replace `pyro` with `uv run pyro`.

What success looks like:

```bash
Platform: linux-x86_64
Runtime: PASS
Catalog version: 4.0.0
...
[pull] phase=install environment=debian:12
[pull] phase=ready environment=debian:12
Pulled: debian:12
...
[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 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.

## Chat Host Quickstart

After the quickstart works, the intended next step is to connect a chat host.
Bare `pyro mcp serve` starts `workspace-core`, which is the default product
path.

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

Copy-paste host-specific starts:

- Claude Code: [examples/claude_code_mcp.md](examples/claude_code_mcp.md)
- Codex: [examples/codex_mcp.md](examples/codex_mcp.md)
- OpenCode: [examples/opencode_mcp_config.json](examples/opencode_mcp_config.json)
- Generic MCP config: [examples/mcp_client_config.md](examples/mcp_client_config.md)

Claude Code:

```bash
claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve
```

Codex:

```bash
codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve
```

OpenCode `opencode.json` snippet:

```json
{
  "mcp": {
    "pyro": {
      "type": "local",
      "enabled": true,
      "command": ["uvx", "--from", "pyro-mcp", "pyro", "mcp", "serve"]
    }
  }
}
```

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

Use `--profile workspace-full` only when the chat truly needs shells, services,
snapshots, secrets, network policy, or disk tools.

## Zero To Hero

1. Validate the host with `pyro doctor`.
2. Pull `debian:12` and prove guest execution with `pyro run debian:12 -- git --version`.
3. Connect Claude Code, Codex, or OpenCode with `pyro mcp serve`.
4. Start with one recipe from [docs/use-cases/README.md](docs/use-cases/README.md).
   `repro-fix-loop` is the shortest chat-first story.
5. Use `make smoke-use-cases` as the trustworthy guest-backed verification path
   for the advertised workflows.

That is the intended user journey. The terminal commands exist to validate and
debug that chat-host path, not to replace it as the main product story.

## Manual Terminal Workspace Flow

If you want to understand what the agent gets inside the sandbox, or debug a
recipe outside the chat host, use the terminal companion flow below:

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

Add `workspace-full` only when the chat or your manual debugging loop really
needs:

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

The five recipe docs show when those capabilities are justified:
[docs/use-cases/README.md](docs/use-cases/README.md)

## Official Environments

Current official environments in the shipped catalog:

- `debian:12`
- `debian:12-base`
- `debian:12-build`

The embedded Firecracker runtime ships with the package. Official environments
are pulled as OCI artifacts from public Docker Hub into a local cache on first
use or through `pyro env pull`. End users do not need registry credentials to
pull or run the official environments.

## Contributor Workflow

For work inside this repository:

```bash
make help
make setup
make check
make dist-check
```

Contributor runtime sources live under `runtime_sources/`. The packaged runtime
bundle under `src/pyro_mcp/runtime_bundle/` contains the embedded boot/runtime
assets plus manifest metadata. End-user environment installs pull
OCI-published environments by default. Use
`PYRO_RUNTIME_BUNDLE_DIR=build/runtime_bundle` only when you are explicitly
validating a locally built contributor runtime bundle.

Official environment publication is performed locally against Docker Hub:

```bash
export DOCKERHUB_USERNAME='your-dockerhub-username'
export DOCKERHUB_TOKEN='your-dockerhub-token'
make runtime-materialize
make runtime-publish-official-environments-oci
```

For a local PyPI publish:

```bash
export TWINE_PASSWORD='pypi-...'
make pypi-publish
```