pyro-mcp/docs/public-contract.md

Public Contract

This document defines the supported public interface for pyro-mcp 2.x.

Package Identity

• Distribution name: pyro-mcp
• Public executable: pyro
• Public Python import: from pyro_mcp import Pyro
• Public package-level factory: from pyro_mcp import create_server

CLI Contract

Top-level commands:

• pyro env list
• pyro env pull
• pyro env inspect
• pyro env prune
• pyro mcp serve
• pyro run
• pyro doctor
• pyro demo
• pyro demo ollama

Stable pyro run interface:

• positional environment name
• --vcpu-count
• --mem-mib
• --timeout-seconds
• --ttl-seconds
• --network
• --allow-host-compat
• --json

Behavioral guarantees:

• pyro run <environment> -- <command> defaults to 1 vCPU / 1024 MiB.
• pyro run fails if guest boot or guest exec is unavailable unless --allow-host-compat is set.
• pyro run, pyro env list, pyro env pull, pyro env inspect, pyro env prune, and pyro doctor are human-readable by default and return structured JSON with --json.
• pyro demo ollama prints log lines plus a final summary line.

Python SDK Contract

Primary facade:

• Pyro

Supported public entrypoints:

• create_server()
• Pyro.create_server()
• Pyro.list_environments()
• Pyro.pull_environment(environment)
• Pyro.inspect_environment(environment)
• Pyro.prune_environments()
• Pyro.create_vm(...)
• Pyro.start_vm(vm_id)
• Pyro.exec_vm(vm_id, *, command, timeout_seconds=30)
• Pyro.stop_vm(vm_id)
• Pyro.delete_vm(vm_id)
• Pyro.status_vm(vm_id)
• Pyro.network_info_vm(vm_id)
• Pyro.reap_expired()
• Pyro.run_in_vm(...)

Stable public method names:

• create_server()
• list_environments()
• pull_environment(environment)
• inspect_environment(environment)
• prune_environments()
• create_vm(...)
• start_vm(vm_id)
• exec_vm(vm_id, *, command, timeout_seconds=30)
• stop_vm(vm_id)
• delete_vm(vm_id)
• status_vm(vm_id)
• network_info_vm(vm_id)
• reap_expired()
• run_in_vm(...)

Behavioral defaults:

• Pyro.create_vm(...) and Pyro.run_in_vm(...) default to vcpu_count=1 and mem_mib=1024.
• allow_host_compat defaults to False on create_vm(...) and run_in_vm(...).

MCP Contract

Primary tool:

• vm_run

Advanced lifecycle tools:

• vm_list_environments
• vm_create
• vm_start
• vm_exec
• vm_stop
• vm_delete
• vm_status
• vm_network_info
• vm_reap_expired

Behavioral defaults:

• vm_run and vm_create default to vcpu_count=1 and mem_mib=1024.
• vm_run and vm_create expose allow_host_compat, which defaults to false.

Versioning Rule

• pyro-mcp uses SemVer.
• Environment names are stable identifiers in the shipped catalog.
• Changing a public command name, public flag, public method name, public MCP tool name, or required request field is a breaking change.