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

Refresh docs and examples for workspaces

Browse source 
Rewrite the user-facing persistent sandbox story around pyro workspace ..., including the install guide, first-run transcript, integrations notes, and public contract reference.

Rename the Python example to examples/python_workspace.py and update the docs to use the new workspace create, sync, exec, status, logs, and delete flows with seed_path/workspace_id terminology.

Mark the 2.4.0 workspace-contract pivot as done in the roadmap now that the shipped CLI, SDK, MCP, docs, and tests all use the workspace-first surface.
This commit is contained in:
Thales Maciel 2026-03-12 01:22:26 -03:00
parent 48b82d8386
commit 2de31306b6
9 changed files with 148 additions and 150 deletions
Download patch file Download diff file Expand all files Collapse all files

16
docs/integrations.md
View file

@ -16,7 +16,7 @@ That keeps the model-facing contract small:
- one ephemeral VM
- automatic cleanup
Move to `task_*` only when the agent truly needs repeated commands in one workspace across
Move to `workspace_*` only when the agent truly needs repeated commands in one workspace across
multiple calls.
## OpenAI Responses API
@ -30,7 +30,7 @@ Best when:
Recommended surface:
- `vm_run`
- `task_create(source_path=...)` + `task_sync_push` + `task_exec` when the agent needs persistent workspace state
- `workspace_create(seed_path=...)` + `workspace_sync_push` + `workspace_exec` when the agent needs persistent workspace state
Canonical example:
@ -65,23 +65,23 @@ Best when:
Recommended default:
- `Pyro.run_in_vm(...)`
- `Pyro.create_task(source_path=...)` + `Pyro.push_task_sync(...)` + `Pyro.exec_task(...)` when repeated workspace commands are required
- `Pyro.create_workspace(seed_path=...)` + `Pyro.push_workspace_sync(...)` + `Pyro.exec_workspace(...)` when repeated workspace commands are required
Lifecycle note:
- `Pyro.exec_vm(...)` runs one command and auto-cleans the VM afterward
- use `create_vm(...)` + `start_vm(...)` only when you need pre-exec inspection or status before
that final exec
- use `create_task(source_path=...)` when the agent needs repeated commands in one persistent
- use `create_workspace(seed_path=...)` when the agent needs repeated commands in one persistent
`/workspace` that starts from host content
- use `push_task_sync(...)` when later host-side changes need to be imported into that running
workspace without recreating the task
- use `push_workspace_sync(...)` when later host-side changes need to be imported into that
running workspace without recreating it
Examples:
- [examples/python_run.py](../examples/python_run.py)
- [examples/python_lifecycle.py](../examples/python_lifecycle.py)
- [examples/python_task.py](../examples/python_task.py)
- [examples/python_workspace.py](../examples/python_workspace.py)
## Agent Framework Wrappers
@ -100,7 +100,7 @@ Recommended pattern:
- keep the framework wrapper thin
- map one-shot framework tool input directly onto `vm_run`
- expose `task_*` only when the framework truly needs repeated commands in one workspace
- expose `workspace_*` only when the framework truly needs repeated commands in one workspace
Concrete example: