┌──────────────────────────────────────────────────────────┐
│                     AI Agents / Users                     │
├────────────┬────────────┬────────────┬───────────────────┤
│  MCP Server│    CLI     │  REST API  │  Web Dashboard    │
├────────────┴────────────┴────────────┴───────────────────┤
│                    VM Manager                             │
│              (orchestration + audit)                      │
├──────────────────────┬───────────────────────────────────┤
│   Sandbox Executor   │     Compliance Engine             │
│  (pooled isolation)  │  (audit log + policy controls)    │
├──────────────────────┴───────────────────────────────────┤
│               Hypervisor Abstraction                      │
│    ┌──────────┬──────────────┬──────────────┐            │
│    │ QEMU/KVM │ HVF (macOS)  │ WHPX (Win)   │            │
│    └──────────┴──────────────┴──────────────┘            │
└──────────────────────────────────────────────────────────┘

vm_create  : vm.nonexistent → vm.created
vm_start   : vm.created | vm.stopped → vm.running
vm_stop    : vm.running | vm.paused → vm.stopped
vm_destroy : vm.created | vm.running | vm.stopped | vm.paused → vm.destroyed
vm_exec    : vm.running → vm.running  (endomorphism)

$ virtualize algebra verify

  PASS  identity — id ∘ t = t = t ∘ id holds for all generators
  PASS  closure — All generators map C → C
  PASS  associativity — (t₁ ∘ t₂) ∘ t₃ = t₁ ∘ (t₂ ∘ t₃)
  PASS  audit_monotonicity — A_{n+1}.seq ≥ A_n.seq
  PASS  audit_irreversibility — ∄ t such that t(A_n) = A_{n-1}
  PASS  transition_determinism — All transitions are deterministic

# Valid lifecycle
$ virtualize algebra validate '[
  ["vm_create", null, {"name": "my-vm"}],
  ["vm_start", "my-vm", {}],
  ["vm_exec", "my-vm", {"command": "echo hello"}],
  ["vm_stop", "my-vm", {}],
  ["vm_destroy", "my-vm", {}]
]'
# → VALID — 5 steps validated

# Invalid: exec on nonexistent VM
$ virtualize algebra validate '[["vm_exec", "ghost", {}]]'
# → INVALID — vm_exec requires VM 'ghost' in {vm.running}, but it is in 'vm.nonexistent'

$ virtualize algebra rewrite '[
  ["identity", null, {}],
  ["vm_create", "vm-1", {"name": "vm-1"}],
  ["identity", null, {}],
  ["vm_start", "vm-1", {}],
  ["vm_status", "vm-1", {}],
  ["vm_status", "vm-1", {}],
  ["vm_destroy", "vm-1", {}]
]'
# → Original: 7 steps → Optimized: 4 steps (3 eliminated via algebraic laws)

# Install agent dependencies
pip install -e ".[agent]"

# Ask anything
virtualize ask "start me a vm that i can connect to openclaw"

╭─────────────── Execution Plan ───────────────╮
│                                               │
│  1. Create VM 'openclaw-vm'                   │
│  2. Start VM on 'openclaw-vm'                 │
│  3. Run `pip install openclaw && python -m    │
│     openclaw` on 'openclaw-vm'                │
│                                               │
╰───────────────────────────────────────────────╯
  VALID — 3 steps, audit seq → 3

User (English) → LLM → JSON tool chain → Compositor.validate() → Execute
                                               ↓ (if invalid)
                                         Retry with error feedback

virtualize ask "create a vm called dev-box"
virtualize ask "check compliance for hipaa"
virtualize ask "make a vm, start it, and run uname"
virtualize ask "run print(42) in a sandbox"

pip install -e .
virtualize setup

# Linux (Ubuntu/Debian)
sudo apt install qemu-system-x86 qemu-utils

# Linux (Fedora/RHEL)
sudo dnf install qemu-system-x86 qemu-img

# macOS
brew install qemu

# Windows
choco install qemu
# or download from https://qemu.org/download

pip install -e .

# Create a VM
virtualize create my-dev-vm --cpus 4 --memory 4096 --disk 50

# Start it
virtualize start <vm_id>

# Run a command inside
virtualize exec <vm_id> "uname -a"

# Run sandboxed code
virtualize sandbox run "print('hello from sandbox')" --lang python

# List VMs
virtualize list

# Stop and destroy
virtualize stop <vm_id>
virtualize destroy <vm_id>

# Start the API server (includes dashboard at http://localhost:8420)
python -m uvicorn virtualize.api.server:app --host 0.0.0.0 --port 8420

{
  "mcpServers": {
    "virtualize": {
      "command": "python",
      "args": ["-m", "virtualize.mcp_server.server"]
    }
  }
}

virtualize mcp serve

# Generate a SOC 2 compliance report
virtualize compliance report soc2

# Verify audit log integrity
virtualize compliance audit-verify

# Query audit events
virtualize compliance audit-query --actor alice --limit 20

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/ tests/

# Type check
mypy src/

virtualize/
├── src/virtualize/
│   ├── core/
│   │   ├── algebra.py         # Formal algebra: states, transitions, compositor, axioms
│   │   ├── models.py          # Pydantic data models (VMConfig, VMInstance, AuditEvent)
│   │   ├── manager.py         # VM lifecycle orchestration with algebraic pre-validation
│   │   ├── hypervisor.py      # Cross-platform QEMU abstraction (KVM/HVF/WHPX)
│   │   ├── mock_hypervisor.py # Mock backend for dev/testing without QEMU
│   │   └── bootstrap.py       # OS-detecting setup system
│   ├── agent/
│   │   └── nl_agent.py        # NL→algebra agent (local LLM → validated tool chains)
│   ├── sandbox/
│   │   └── executor.py        # Sandboxed code execution with pooled VMs
│   ├── compliance/
│   │   ├── audit.py           # Append-only, integrity-chained audit log (SHA-256 HMAC)
│   │   └── policies.py        # SOC 1/2/3, HIPAA, ISO 27001 policy controls
│   ├── mcp_server/
│   │   └── server.py          # MCP server — 13 tools over stdio transport
│   ├── api/
│   │   ├── server.py          # FastAPI REST server (port 8420)
│   │   └── dashboard.py       # Built-in React/Tailwind web dashboard
│   └── cli/
│       └── main.py            # Typer CLI (lifecycle, sandbox, compliance, algebra, ask)
├── tests/                     # 103 tests (algebra, agent, API, compliance, models)
├── AGENTS.md                  # Machine-readable context for LLMs
├── bootstrap.sh               # One-line clone + setup script
├── mcp-config.json            # MCP client configuration
├── pyproject.toml
└── README.md