Thales Maciel
dc86d84e96
Add workspace summary across the CLI, SDK, and MCP, and include it in the workspace-core profile so chat hosts can review one concise view of the current session. Persist lightweight review events for syncs, file edits, patch applies, exports, service lifecycle, and snapshot activity, then synthesize them with command history, current services, snapshot state, and current diff data since the last reset. Update the walkthroughs, use-case docs, public contract, changelog, and roadmap for 4.3.0, and make dist-check invoke the CLI module directly so local package reinstall quirks do not break the packaging gate. Validation: uv lock; ./.venv/bin/pytest --no-cov tests/test_vm_manager.py tests/test_cli.py tests/test_api.py tests/test_server.py tests/test_public_contract.py tests/test_workspace_use_case_smokes.py; UV_OFFLINE=1 UV_CACHE_DIR=.uv-cache make check; UV_OFFLINE=1 UV_CACHE_DIR=.uv-cache make dist-check; real guest-backed workspace create -> patch apply -> workspace summary --json -> delete smoke.
293 lines
7.8 KiB
Markdown
293 lines
7.8 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 host connect`
|
|
or `pyro host print-config`.
|
|
|
|
## 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.3.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
|
|
|
|
Use the helper flow first:
|
|
|
|
```bash
|
|
uvx --from pyro-mcp pyro host connect claude-code
|
|
uvx --from pyro-mcp pyro host connect codex
|
|
uvx --from pyro-mcp pyro host print-config opencode
|
|
```
|
|
|
|
If setup drifts later, inspect and repair it with:
|
|
|
|
```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
|
|
```
|
|
|
|
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
|
|
pyro host connect claude-code
|
|
claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve
|
|
```
|
|
|
|
Codex:
|
|
|
|
```bash
|
|
pyro host connect codex
|
|
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 host connect ...` or
|
|
`pyro host print-config opencode`, then use raw `pyro mcp serve` only when
|
|
you need `--project-path` / `--repo-url`
|
|
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 summary "$WORKSPACE_ID"
|
|
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
|
|
```
|