Thales Maciel
535efc6919
Make repo-root chat startup native by letting MCP servers carry a default project source for workspace creation. When a chat host starts from a Git checkout, workspace_create can now omit seed_path and inherit the server startup source; explicit --project-path and clean-clone --repo-url/--repo-ref paths are supported as fallbacks. Add project startup resolution and materialization, surface origin_kind/origin_ref in workspace_seed, update chat-host docs and the repro/fix smoke to use project-aware workspace creation, and switch dist-check to uv run pyro so verification stays stable after uv reinstalls. Validated with uv lock, focused startup/server/CLI pytest coverage, UV_CACHE_DIR=.uv-cache make check, UV_CACHE_DIR=.uv-cache make dist-check, and real guest-backed smokes for both explicit project_path and bare repo-root auto-detection.
271 lines
7.2 KiB
Markdown
271 lines
7.2 KiB
Markdown
# Install
|
|
|
|
`pyro-mcp` is built for chat-based coding agents on Linux `x86_64` with KVM.
|
|
This document is intentionally biased toward that path.
|
|
|
|
`pyro-mcp` currently has no users. Expect breaking changes while the chat-host
|
|
flow is still being shaped.
|
|
|
|
## Support Matrix
|
|
|
|
Supported today:
|
|
|
|
- Linux `x86_64`
|
|
- Python `3.12+`
|
|
- `uv`
|
|
- `/dev/kvm`
|
|
|
|
Optional for outbound guest networking:
|
|
|
|
- `ip`
|
|
- `nft` or `iptables`
|
|
- privilege to create TAP devices and configure NAT
|
|
|
|
Not supported today:
|
|
|
|
- macOS
|
|
- Windows
|
|
- Linux hosts without working KVM at `/dev/kvm`
|
|
|
|
If you do not already have `uv`, install it first:
|
|
|
|
```bash
|
|
python -m pip install uv
|
|
```
|
|
|
|
Use these command forms consistently:
|
|
|
|
- published package without install: `uvx --from pyro-mcp pyro ...`
|
|
- installed package: `pyro ...`
|
|
- source checkout: `uv run pyro ...`
|
|
|
|
## Fastest Evaluation Path
|
|
|
|
Use either of these equivalent evaluator paths:
|
|
|
|
```bash
|
|
# Package without install
|
|
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
|
|
```
|
|
|
|
```bash
|
|
# Already installed
|
|
pyro doctor
|
|
pyro env list
|
|
pyro env pull debian:12
|
|
pyro run debian:12 -- git --version
|
|
```
|
|
|
|
If you are running from a repo checkout instead, replace `pyro` with
|
|
`uv run pyro`.
|
|
|
|
After that one-shot proof works, the intended next step is `pyro mcp serve`.
|
|
|
|
## 1. Check the host
|
|
|
|
```bash
|
|
uvx --from pyro-mcp pyro doctor
|
|
```
|
|
|
|
Expected success signals:
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
If `Runtime: FAIL`, stop here and use [troubleshooting.md](troubleshooting.md).
|
|
|
|
## 2. Inspect the catalog
|
|
|
|
```bash
|
|
uvx --from pyro-mcp pyro env list
|
|
```
|
|
|
|
Expected output:
|
|
|
|
```bash
|
|
Catalog version: 4.1.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
|
|
|
|
```bash
|
|
uvx --from pyro-mcp pyro env pull debian:12
|
|
```
|
|
|
|
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.
|
|
|
|
Expected success signals:
|
|
|
|
```bash
|
|
[pull] phase=install environment=debian:12
|
|
[pull] phase=ready environment=debian:12
|
|
Pulled: debian:12
|
|
...
|
|
```
|
|
|
|
## 4. Run one command in a guest
|
|
|
|
```bash
|
|
uvx --from pyro-mcp pyro run debian:12 -- git --version
|
|
```
|
|
|
|
Expected success signals:
|
|
|
|
```bash
|
|
[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. Use `--json` if you need a
|
|
deterministic structured result.
|
|
|
|
## 5. Connect a chat host
|
|
|
|
Bare `pyro mcp serve` now 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, use:
|
|
|
|
```bash
|
|
uvx --from pyro-mcp pyro mcp serve --project-path /abs/path/to/repo
|
|
```
|
|
|
|
If you are starting outside a local checkout, use a clean clone source:
|
|
|
|
```bash
|
|
uvx --from pyro-mcp pyro mcp serve --repo-url https://github.com/example/project.git
|
|
```
|
|
|
|
Copy-paste host-specific starts:
|
|
|
|
- Claude Code setup: [claude_code_mcp.md](../examples/claude_code_mcp.md)
|
|
- Codex setup: [codex_mcp.md](../examples/codex_mcp.md)
|
|
- OpenCode config: [opencode_mcp_config.json](../examples/opencode_mcp_config.json)
|
|
- Generic MCP fallback: [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 uses the `mcp` / `type: "local"` config shape shown in
|
|
[opencode_mcp_config.json](../examples/opencode_mcp_config.json).
|
|
|
|
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.
|
|
|
|
## 6. Go from zero to hero
|
|
|
|
The intended user journey is:
|
|
|
|
1. validate the host with `pyro doctor`
|
|
2. pull `debian:12`
|
|
3. prove guest execution with `pyro run debian:12 -- git --version`
|
|
4. connect Claude Code, Codex, or OpenCode with `pyro mcp serve` from a repo
|
|
root, or use `--project-path` / `--repo-url` when needed
|
|
5. start with one use-case recipe from [use-cases/README.md](use-cases/README.md)
|
|
6. trust but verify with `make smoke-use-cases`
|
|
|
|
If you want the shortest chat-first story, start with
|
|
[use-cases/repro-fix-loop.md](use-cases/repro-fix-loop.md).
|
|
|
|
## 7. Manual terminal workspace flow
|
|
|
|
If you want to inspect the workspace model directly from the terminal, use the
|
|
companion flow below. This is for understanding and debugging the chat-host
|
|
product, not the primary story.
|
|
|
|
```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 update "$WORKSPACE_ID" --label owner=codex
|
|
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"
|
|
```
|
|
|
|
When you need deeper debugging or richer recipes, add:
|
|
|
|
- `pyro workspace shell *` for interactive PTY state
|
|
- `pyro workspace service *` for long-running processes and readiness probes
|
|
- `pyro workspace create --network-policy egress+published-ports` plus
|
|
`workspace service start --publish` for host-probed services
|
|
- `pyro workspace create --secret` and `--secret-file` when the sandbox needs
|
|
private tokens
|
|
- `pyro workspace stop` plus `workspace disk *` for offline inspection
|
|
|
|
## 8. Trustworthy verification path
|
|
|
|
The five recipe docs in [use-cases/README.md](use-cases/README.md) are backed
|
|
by a real Firecracker smoke pack:
|
|
|
|
```bash
|
|
make smoke-use-cases
|
|
```
|
|
|
|
Treat that smoke pack as the trustworthy guest-backed verification path for the
|
|
advertised chat-host workflows.
|
|
|
|
## Installed CLI
|
|
|
|
If you already installed the package, the same path works with plain `pyro ...`:
|
|
|
|
```bash
|
|
uv tool install pyro-mcp
|
|
pyro --version
|
|
pyro doctor
|
|
pyro env list
|
|
pyro env pull debian:12
|
|
pyro run debian:12 -- git --version
|
|
pyro mcp serve
|
|
```
|
|
|
|
## Contributor clone
|
|
|
|
```bash
|
|
git lfs install
|
|
git clone <repo>
|
|
cd pyro
|
|
git lfs pull
|
|
make setup
|
|
```
|