pyro

Features

• Fast — sub-second sandbox creation with snapshot pools
• Isolated — each sandbox is a Firecracker microVM with its own kernel
• Simple API — REST + WebSocket + SSE for sandbox lifecycle
• Multi-image — default, minimal, ubuntu, python, node base images
• SDKs — Python and TypeScript clients
• Dashboard — built-in SvelteKit UI for fleet management
• Observability — OpenTelemetry metrics, Prometheus endpoint, audit log

Quickstart

Python

pip install pyrovm-sdk

import asyncio
from pyro_sdk import Pyro

async def main():
    pyro = Pyro(api_key="pk_...", base_url="http://localhost:8080")

    async with await pyro.sandbox.create(image="python") as sb:
        result = await sb.run("print('Hello from Pyro!')")
        print(result.stdout)

asyncio.run(main())

TypeScript

npm install @pyrovm/sdk

import { Pyro } from '@pyrovm/sdk'

const pyro = new Pyro({ apiKey: 'pk_...', baseUrl: 'http://localhost:8080' })
const sandbox = await pyro.sandbox.create({ image: 'python', timeout: 300 })
const result = await sandbox.run('print("Hello from Pyro!")')
console.log(result.stdout)
await sandbox.stop()

CLI

export PYRO_API_KEY=pk_...
pyro sandbox create --image python --ttl 300
pyro sandbox exec <id> python3 -c "print('hello')"
pyro sandbox kill <id>

Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│  SDK / CLI  │────▶│  pyro-server │────▶│  Firecracker VM │
│             │ HTTP│  (REST API)  │vsock│  (pyro-agent)   │
└─────────────┘     └──────────────┘     └─────────────────┘
                           │
                    ┌──────┴──────┐
                    │   SQLite    │
                    │  (state DB) │
                    └─────────────┘

• pyro-server — HTTP API server managing VM lifecycle, auth, quotas, and file operations
• pyro-agent — runs as PID 1 inside each VM, handles exec/file commands over vsock
• pyro — CLI for host setup, image building, and sandbox operations

API Endpoints

Self-hosting

Requires a Linux host with KVM support.

# One-command setup (kernel, images, bridge, systemd)
sudo pyro setup

# Create an API key
pyro create-key my-key

# Start the server
systemctl start pyro

Build from source

make build          # build all binaries
make build-linux    # cross-compile for Linux
make deploy         # build + SCP to remote host

Images

Build custom images from Dockerfiles:

pyro build-image <name>
# or via API:
curl -X POST /api/images -d '{"name":"custom","dockerfile":"..."}'

Configuration

Environment variables

Server flags

--listen          API listen address (default :8080)
--db              SQLite path
--images-dir      Base images directory
--max-sandboxes   Max concurrent VMs (default 100)
--max-per-key     Max VMs per API key (default 10)
--rate-limit      Creates per minute per key (default 30)
--pool-size       Warm snapshot pool per image (default 0)
--prometheus      Enable /metrics endpoint

SDKs

Examples

• Code Runner — run user-provided Python code in isolated sandboxes
• LangChain Agent — give an LLM agent a sandboxed code execution tool

License

MIT