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

Clarify workspace-core as the chat-host onramp

Browse source 
Make the recommended MCP profile visible from the first help and docs pass without changing 3.x behavior.

Rework  help, top-level docs, public-contract wording, and shipped MCP/OpenAI examples so  is the recommended first profile while  stays the compatibility default for full-surface hosts.

Bump the package and catalog to 3.8.0, mark the roadmap milestone done, and add regression coverage for the new MCP help and docs alignment. Validation included uv lock, targeted profile/help tests, make check, make dist-check, and a real guest-backed  server smoke.
This commit is contained in:
Thales Maciel 2026-03-13 11:23:51 -03:00
parent 7a0620fc0c
commit 407c805ce2
17 changed files with 150 additions and 50 deletions
Download patch file Download diff file Expand all files Collapse all files

8
docs/first-run.md
View file

@ -22,7 +22,7 @@ Networking: tun=yes ip_forward=yes
```bash
$ uvx --from pyro-mcp pyro env list
Catalog version: 3.7.0
Catalog version: 3.8.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.
@ -118,6 +118,10 @@ $ uvx --from pyro-mcp pyro workspace service start WORKSPACE_ID app --ready-http
$ uvx --from pyro-mcp pyro mcp serve --profile workspace-core
```
For most chat hosts, `workspace-core` is the recommended first MCP profile.
Move to `workspace-full` only when the host truly needs shells, services,
snapshots, secrets, network policy, or disk tools.
`pyro demo` proves the one-shot create/start/exec/delete VM lifecycle works end to end.
Once that stable workspace flow works, continue with the five recipe docs in
@ -255,7 +259,7 @@ State: started
Use `--seed-path` when the workspace should start from a host directory or a local
`.tar` / `.tar.gz` / `.tgz` archive instead of an empty `/workspace`. Use
`pyro workspace sync push` when you need to import later host-side changes into a started
workspace. Sync is non-atomic in `3.7.0`; if it fails partway through, prefer `pyro workspace reset`
workspace. Sync is non-atomic in `3.8.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 create
named checkpoints, and `pyro workspace export` to copy one changed file or directory back to the

18
docs/install.md
View file

@ -85,7 +85,7 @@ uvx --from pyro-mcp pyro env list
Expected output:
```bash
Catalog version: 3.7.0
Catalog version: 3.8.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.
@ -233,6 +233,20 @@ After the CLI path works, you can move on to:
- Python SDK: `from pyro_mcp import Pyro`
- Demos: `pyro demo` or `pyro demo --network`
## Chat Host Quickstart
For most chat-host integrations, start with `workspace-core`:
```bash
uvx --from pyro-mcp pyro mcp serve --profile workspace-core
```
Use profile progression like this:
- `workspace-core`: recommended first profile for normal persistent chat editing
- `vm-run`: one-shot-only integrations
- `workspace-full`: advanced 3.x compatibility surface when the host truly needs shells, services, snapshots, secrets, network policy, or disk tools
## Stable Workspace
Use `pyro workspace ...` when you need repeated commands in one sandbox instead of one-shot `pyro run`.
@ -280,7 +294,7 @@ the identifier programmatically, use `--id-only` for only the identifier or `--j
workspace payload. 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 `3.7.0`; if it fails partway through, prefer `pyro workspace reset` to recover
is non-atomic in `3.8.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

11
docs/integrations.md
View file

@ -7,10 +7,10 @@ CLI path in [install.md](install.md) or [first-run.md](first-run.md).
## Recommended Default
Use `vm_run` first for one-shot commands, then move to `workspace-core` when the
agent needs to inhabit one sandbox across multiple calls. Only promote the chat
surface to `workspace-full` when it truly needs shells, services, snapshots,
secrets, network policy, or disk tools.
Start most chat hosts with `workspace-core`. Use `vm_run` only for one-shot
integrations, and promote the chat surface to `workspace-full` only when it
truly needs shells, services, snapshots, secrets, network policy, or disk
tools.
That keeps the model-facing contract small:
@ -21,8 +21,8 @@ That keeps the model-facing contract small:
Profile progression:
- `workspace-core`: recommended first profile for persistent chat editing
- `vm-run`: one-shot only
- `workspace-core`: persistent workspace create/list/update/status/sync/exec/logs/file ops/diff/export/reset/delete
- `workspace-full`: the full stable workspace surface, including shells, services, snapshots, secrets, network policy, and disk tools
## OpenAI Responses API
@ -81,6 +81,7 @@ Best when:
Recommended default:
- `Pyro.run_in_vm(...)`
- `Pyro.create_server(profile="workspace-core")` for most chat hosts
- `Pyro.create_workspace(name=..., labels=...)` + `Pyro.list_workspaces()` + `Pyro.update_workspace(...)` when repeated workspaces need human-friendly discovery metadata
- `Pyro.create_workspace(seed_path=...)` + `Pyro.push_workspace_sync(...)` + `Pyro.exec_workspace(...)` when repeated workspace commands are required
- `Pyro.list_workspace_files(...)` / `Pyro.read_workspace_file(...)` / `Pyro.write_workspace_file(...)` / `Pyro.apply_workspace_patch(...)` when the agent needs model-native file inspection and text edits inside one live workspace

6
docs/public-contract.md
View file

@ -83,7 +83,7 @@ Behavioral guarantees:
- `pyro workspace create --id-only` prints only the new `workspace_id` plus a trailing newline.
- `pyro workspace create --name NAME --label KEY=VALUE` attaches human-oriented discovery metadata without changing the stable `workspace_id`.
- `pyro workspace create --network-policy {off,egress,egress+published-ports}` controls workspace guest networking and whether services may publish localhost ports.
- `pyro mcp serve --profile {vm-run,workspace-core,workspace-full}` narrows the model-facing MCP surface without changing runtime behavior.
- `pyro mcp serve --profile {vm-run,workspace-core,workspace-full}` narrows the model-facing MCP surface without changing runtime behavior; `workspace-core` is the recommended first profile for most chat hosts.
- `pyro workspace create --secret NAME=VALUE` and `--secret-file NAME=PATH` persist guest-only UTF-8 secrets outside `/workspace`.
- `pyro workspace list` returns persisted workspaces sorted by most recent `last_activity_at`.
- `pyro workspace sync push WORKSPACE_ID SOURCE_PATH [--dest WORKSPACE_PATH]` imports later host-side directory or archive content into a started workspace.
@ -277,7 +277,9 @@ Stable MCP profiles:
Behavioral defaults:
- `pyro mcp serve` and `create_server()` default to `workspace-full`.
- `pyro mcp serve` and `create_server()` default to `workspace-full` for 3.x compatibility.
- `workspace-core` is the recommended first profile for most new chat-host integrations.
- `create_server(profile="workspace-core")` and `Pyro.create_server(profile="workspace-core")` are the recommended entrypoints for most new chat-host integrations.
- `workspace-core` narrows `workspace_create` by omitting `network_policy` and `secrets`.
- `workspace-core` narrows `workspace_exec` by omitting `secret_env`.

16
docs/roadmap/llm-chat-ergonomics.md
View file

@ -6,7 +6,7 @@ goal:
make the core agent-workspace use cases feel trivial from a chat-driven LLM
interface.
Current baseline is `3.7.0`:
Current baseline is `3.8.0`:
- the stable workspace contract exists across CLI, SDK, and MCP
- one-shot `pyro run` still exists as the narrow entrypoint
@ -35,12 +35,8 @@ More concretely, the model should not need to:
The remaining UX friction for a technically strong new user is now narrower:
- the best chat-host profile is recommended in docs, but not yet obvious enough
from the default live `mcp serve` path
- canonical CLI walkthroughs are cleaner now, but the recommended chat-host
entrypoint still needs to be more obvious from the default docs and help
- human-mode file reads are functional, but still need final transcript polish
for copy-paste and chat logs
- the recommended chat-host onramp is now explicit, but human-mode file reads
still need final transcript polish for copy-paste and chat logs
## Locked Decisions
@ -62,7 +58,7 @@ The remaining UX friction for a technically strong new user is now narrower:
4. [`3.5.0` Chat-Friendly Shell Output](llm-chat-ergonomics/3.5.0-chat-friendly-shell-output.md) - Done
5. [`3.6.0` Use-Case Recipes And Smoke Packs](llm-chat-ergonomics/3.6.0-use-case-recipes-and-smoke-packs.md) - Done
6. [`3.7.0` Handoff Shortcuts And File Input Sources](llm-chat-ergonomics/3.7.0-handoff-shortcuts-and-file-input-sources.md) - Done
7. [`3.8.0` Chat-Host Onramp And Recommended Defaults](llm-chat-ergonomics/3.8.0-chat-host-onramp-and-recommended-defaults.md) - Planned
7. [`3.8.0` Chat-Host Onramp And Recommended Defaults](llm-chat-ergonomics/3.8.0-chat-host-onramp-and-recommended-defaults.md) - Done
8. [`3.9.0` Content-Only Reads And Human Output Polish](llm-chat-ergonomics/3.9.0-content-only-reads-and-human-output-polish.md) - Planned
Completed so far:
@ -83,11 +79,11 @@ Completed so far:
- `3.7.0` removed the remaining shell glue from canonical CLI workspace flows with `--id-only`,
`--text-file`, and `--patch-file`, so the shortest handoff path no longer depends on `python -c`
extraction or `$(cat ...)` expansion.
- `3.8.0` made `workspace-core` the obvious first MCP/chat-host profile from the first help and
docs pass while keeping `workspace-full` as the 3.x compatibility default.
Planned next:
- `3.8.0` makes the recommended chat-host entrypoint obvious from the top-level docs, help text,
and shipped MCP examples without changing the `3.x` compatibility default.
- `3.9.0` makes human-mode file reads cleaner in terminals and chat logs, with explicit
content-only reads where summaries would otherwise get in the way.

2
docs/roadmap/llm-chat-ergonomics/3.8.0-chat-host-onramp-and-recommended-defaults.md
View file

@ -1,6 +1,6 @@
# `3.8.0` Chat-Host Onramp And Recommended Defaults
Status: Planned
Status: Done
## Goal