pyro-mcp/docs/public-contract.md

Public Contract

This document defines the supported public interface for pyro-mcp 1.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

Behavioral guarantees:

• pyro run <environment> --vcpu-count <n> --mem-mib <mib> -- <command> returns structured JSON.
• pyro env list, pyro env pull, pyro env inspect, and pyro env prune return structured JSON.
• pyro doctor returns structured JSON diagnostics.
• 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(...)

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

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.