pyro-mcp/docs/integrations.md

# Integration Targets

These are the main ways to integrate `pyro-mcp` into an LLM application.

Use this page after you have already validated the host and guest execution through the
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 the stable workspace surface when the
agent needs to inhabit one sandbox across multiple calls.

That keeps the model-facing contract small:

- one tool
- one command
- one ephemeral VM
- automatic cleanup

Move to `workspace_*` when the agent needs repeated commands, shells, services, snapshots, reset,
diff, or export in one stable workspace across multiple calls.

## OpenAI Responses API

Best when:

- your agent already uses OpenAI models directly
- you want a normal tool-calling loop instead of MCP transport
- you want the smallest amount of integration code

Recommended surface:

- `vm_run`
- `workspace_create(seed_path=...)` + `workspace_sync_push` + `workspace_exec` when the agent needs persistent workspace state
- `workspace_file_list` / `workspace_file_read` / `workspace_file_write` / `workspace_patch_apply` when the agent needs model-native file inspection and text edits inside one live workspace
- `workspace_create(..., secrets=...)` + `workspace_exec(..., secret_env=...)` when the workspace needs private tokens or authenticated setup
- `workspace_create(..., network_policy="egress+published-ports")` + `start_service(..., published_ports=[...])` when the host must probe one workspace service
- `workspace_diff` + `workspace_export` when the agent needs explicit baseline comparison or host-out file transfer
- `stop_workspace(...)` + `list_workspace_disk(...)` / `read_workspace_disk(...)` / `export_workspace_disk(...)` when one stopped guest-backed workspace needs offline inspection or a raw ext4 copy
- `start_service` / `list_services` / `status_service` / `logs_service` / `stop_service` when the agent needs long-running processes inside that workspace
- `open_shell(..., secret_env=...)` / `read_shell` / `write_shell` when the agent needs an interactive PTY inside that workspace

Canonical example:

- [examples/openai_responses_vm_run.py](../examples/openai_responses_vm_run.py)

## MCP Clients

Best when:

- your host application already supports MCP
- you want `pyro` to run as an external stdio server
- you want tool schemas to be discovered directly from the server

Recommended entrypoint:

- `pyro mcp serve`

Starter config:

- [examples/mcp_client_config.md](../examples/mcp_client_config.md)
- [examples/claude_desktop_mcp_config.json](../examples/claude_desktop_mcp_config.json)
- [examples/cursor_mcp_config.json](../examples/cursor_mcp_config.json)

## Direct Python SDK

Best when:

- your application owns orchestration itself
- you do not need MCP transport
- you want direct access to `Pyro`

Recommended default:

- `Pyro.run_in_vm(...)`
- `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
- `Pyro.create_workspace(..., secrets=...)` + `Pyro.exec_workspace(..., secret_env=...)` when the workspace needs private tokens or authenticated setup
- `Pyro.create_workspace(..., network_policy="egress+published-ports")` + `Pyro.start_service(..., published_ports=[...])` when the host must probe one workspace service
- `Pyro.diff_workspace(...)` + `Pyro.export_workspace(...)` when the agent needs baseline comparison or host-out file transfer
- `Pyro.start_service(..., secret_env=...)` + `Pyro.list_services(...)` + `Pyro.logs_service(...)` when the agent needs long-running background processes in one workspace
- `Pyro.open_shell(..., secret_env=...)` + `Pyro.write_shell(...)` + `Pyro.read_shell(...)` when the agent needs an interactive PTY inside the workspace

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_workspace(seed_path=...)` when the agent needs repeated commands in one persistent
  `/workspace` that starts from host content
- use `push_workspace_sync(...)` when later host-side changes need to be imported into that
  running workspace without recreating it
- use `list_workspace_files(...)`, `read_workspace_file(...)`, `write_workspace_file(...)`, and
  `apply_workspace_patch(...)` when the agent should inspect or edit workspace files without shell
  quoting tricks
- use `create_workspace(..., secrets=...)` plus `secret_env` on exec, shell, or service start when
  the agent needs private tokens or authenticated startup inside that workspace
- use `create_workspace(..., network_policy="egress+published-ports")` plus
  `start_service(..., published_ports=[...])` when the host must probe one service from that
  workspace
- use `diff_workspace(...)` when the agent needs a structured comparison against the immutable
  create-time baseline
- use `export_workspace(...)` when the agent needs one file or directory copied back to the host
- use `stop_workspace(...)` plus `list_workspace_disk(...)`, `read_workspace_disk(...)`, or
  `export_workspace_disk(...)` when the agent needs offline inspection or one raw ext4 copy from
  a stopped guest-backed workspace
- use `start_service(...)` when the agent needs long-running processes and typed readiness inside
  one workspace
- use `open_shell(...)` when the agent needs interactive shell state instead of one-shot execs

Examples:

- [examples/python_run.py](../examples/python_run.py)
- [examples/python_lifecycle.py](../examples/python_lifecycle.py)
- [examples/python_workspace.py](../examples/python_workspace.py)
- [examples/python_shell.py](../examples/python_shell.py)

## Agent Framework Wrappers

Examples:

- LangChain tools
- PydanticAI tools
- custom in-house orchestration layers

Best when:

- you already have an application framework that expects a Python callable tool
- you want to wrap `vm_run` behind framework-specific abstractions

Recommended pattern:

- keep the framework wrapper thin
- map one-shot framework tool input directly onto `vm_run`
- expose `workspace_*` only when the framework truly needs repeated commands in one workspace

Concrete example:

- [examples/langchain_vm_run.py](../examples/langchain_vm_run.py)

## Selection Rule

Choose the narrowest integration that matches the host environment:

1. OpenAI Responses API if you want a direct provider tool loop.
2. MCP if your host already speaks MCP.
3. Python SDK if you own orchestration and do not need transport.
4. Framework wrappers only as thin adapters over the same `vm_run` contract.