thaloco/pyro-mcp
1
Fork 0
Code Pull requests Releases Packages Activity Actions

Promote stable workspace product for 3.0.0

Browse source 
Freeze the current workspace-first surface as the stable 3.0 contract and reposition the
landing docs, CLI help, and public contract around the stable workspace path after the
one-shot proof.

Bump the package and catalog compatibility to 3.0.0, add a dedicated workspace walkthrough
tape/GIF, and mark the 3.0.0 roadmap milestone done while keeping runtime capability
unchanged in this release.

Validation: uv lock; UV_CACHE_DIR=.uv-cache make check; UV_CACHE_DIR=.uv-cache make dist-check;
UV_CACHE_DIR=.uv-cache uv build; UV_CACHE_DIR=.uv-cache uvx --from twine twine check dist/*;
built-wheel CLI smoke for pyro --help and pyro workspace --help; vhs validate plus rendered
workspace-first-run.gif outside the sandbox because vhs crashes when sandboxed.
This commit is contained in:
Thales Maciel 2026-03-12 18:59:09 -03:00
parent c82f4629b2
commit f2d20ef30a
15 changed files with 255 additions and 42 deletions
Download patch file Download diff file Expand all files Collapse all files

37
docs/install.md
View file

@ -55,6 +55,8 @@ 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, continue into the stable workspace path with `pyro workspace ...`.
### 1. Check the host first
```bash
@ -83,7 +85,7 @@ uvx --from pyro-mcp pyro env list
Expected output:
```bash
Catalog version: 2.10.0
Catalog version: 3.0.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.
@ -131,7 +133,34 @@ deterministic structured result.
If guest execution is unavailable, the command fails unless you explicitly pass
`--allow-host-compat`.
## 5. Optional demo proof point
## 5. Continue into the stable workspace path
The commands below use plain `pyro ...`. Run the same flow with `uvx --from pyro-mcp pyro ...`
for the published package, or `uv run pyro ...` from a source checkout.
```bash
uv tool install pyro-mcp
WORKSPACE_ID="$(pyro workspace create debian:12 --seed-path ./repo --json | python -c 'import json,sys; print(json.load(sys.stdin)["workspace_id"])')"
pyro workspace sync push "$WORKSPACE_ID" ./changes
pyro workspace exec "$WORKSPACE_ID" -- cat note.txt
pyro workspace snapshot create "$WORKSPACE_ID" checkpoint
pyro workspace service start "$WORKSPACE_ID" web --ready-file .web-ready -- sh -lc 'touch .web-ready && while true; do sleep 60; done'
pyro workspace reset "$WORKSPACE_ID" --snapshot checkpoint
pyro workspace export "$WORKSPACE_ID" note.txt --output ./note.txt
pyro workspace delete "$WORKSPACE_ID"
```
This is the stable persistent-workspace contract:
- `workspace create` seeds `/workspace`
- `workspace sync push` imports later host-side changes
- `workspace exec` and `workspace shell *` keep work inside one sandbox
- `workspace service *` manages long-running processes with typed readiness
- `workspace snapshot *` and `workspace reset` make reset-over-repair explicit
- `workspace diff` compares against the immutable create-time baseline
- `workspace export` copies results back to the host
## 6. Optional demo proof point
```bash
uvx --from pyro-mcp pyro demo
@ -188,7 +217,7 @@ After the CLI path works, you can move on to:
- Python SDK: `from pyro_mcp import Pyro`
- Demos: `pyro demo` or `pyro demo --network`
## Persistent Workspace
## Stable Workspace
Use `pyro workspace ...` when you need repeated commands in one sandbox instead of one-shot `pyro run`.
@ -225,7 +254,7 @@ Workspace commands default to the persistent `/workspace` directory inside the g
the identifier programmatically, use `--json` and read the `workspace_id` field. Use `--seed-path`
when the workspace should start from a host directory or a local `.tar` / `.tar.gz` / `.tgz`
archive. Use `pyro workspace sync push` for later host-side changes to a started workspace. Sync
is non-atomic in `2.10.0`; if it fails partway through, prefer `pyro workspace reset` to recover
is non-atomic in `3.0.0`; if it fails partway through, prefer `pyro workspace reset` to recover
from `baseline` or one named snapshot. Use `pyro workspace diff` to compare the current workspace
tree to its immutable create-time baseline, `pyro workspace snapshot *` to capture named
checkpoints, and `pyro workspace export` to copy one changed file or directory back to the host. Use