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 task create
• pyro task sync push
• pyro task exec
• pyro task status
• pyro task logs
• pyro task delete
• 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.
• pyro task create auto-starts a persistent workspace.
• pyro task create --source-path PATH seeds /workspace from a host directory or a local .tar / .tar.gz / .tgz archive before the task is returned.
• pyro task sync push TASK_ID SOURCE_PATH [--dest WORKSPACE_PATH] imports later host-side directory or archive content into a started task workspace.
• pyro task exec runs in the persistent /workspace for that task and does not auto-clean.
• pyro task logs returns persisted command history for that task until pyro task delete.
• Task create/status results expose workspace_seed metadata describing how /workspace was initialized.

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.create_task(...)
• Pyro.push_task_sync(task_id, source_path, *, dest="/workspace")
• Pyro.start_vm(vm_id)
• Pyro.exec_vm(vm_id, *, command, timeout_seconds=30)
• Pyro.exec_task(task_id, *, command, timeout_seconds=30)
• Pyro.stop_vm(vm_id)
• Pyro.delete_vm(vm_id)
• Pyro.delete_task(task_id)
• Pyro.status_vm(vm_id)
• Pyro.status_task(task_id)
• Pyro.logs_task(task_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(...)
• create_task(...)
• push_task_sync(task_id, source_path, *, dest="/workspace")
• start_vm(vm_id)
• exec_vm(vm_id, *, command, timeout_seconds=30)
• exec_task(task_id, *, command, timeout_seconds=30)
• stop_vm(vm_id)
• delete_vm(vm_id)
• delete_task(task_id)
• status_vm(vm_id)
• status_task(task_id)
• logs_task(task_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.
• Pyro.create_task(...) defaults to vcpu_count=1 and mem_mib=1024.
• allow_host_compat defaults to False on create_vm(...) and run_in_vm(...).
• allow_host_compat defaults to False on create_task(...).
• Pyro.create_task(..., source_path=...) seeds /workspace from a host directory or a local .tar / .tar.gz / .tgz archive before the task is returned.
• Pyro.push_task_sync(...) imports later host-side directory or archive content into a started task workspace.
• Pyro.exec_vm(...) runs one command and auto-cleans that VM after the exec completes.
• Pyro.exec_task(...) runs one command in the persistent task workspace and leaves the task alive.

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

Task workspace tools:

• task_create
• task_sync_push
• task_exec
• task_status
• task_logs
• task_delete

Behavioral defaults:

• vm_run and vm_create default to vcpu_count=1 and mem_mib=1024.
• task_create defaults to vcpu_count=1 and mem_mib=1024.
• vm_run and vm_create expose allow_host_compat, which defaults to false.
• task_create exposes allow_host_compat, which defaults to false.
• task_create accepts optional source_path and seeds /workspace from a host directory or a local .tar / .tar.gz / .tgz archive before the task is returned.
• task_sync_push imports later host-side directory or archive content into a started task workspace, with an optional dest under /workspace.
• vm_exec runs one command and auto-cleans that VM after the exec completes.
• task_exec runs one command in a persistent /workspace and leaves the task alive.

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.