| name | matchlock |
| description | Run AI agents and arbitrary code in ephemeral micro-VMs with VM-level isolation, network allowlisting, and host-side secret injection. Use for Matchlock CLI and SDK workflows. |
Matchlock
CLI tool and SDK for running AI agents in ephemeral micro-VMs with VM-level isolation, network allowlisting, and secret injection via MITM proxy.
Repository: github.com/jingkaihe/matchlock
For deeper dives, use the Matchlock repo as the source of truth and reference these locations: Go SDK (pkg/sdk), Python SDK (sdk/python), TypeScript SDK (sdk/typescript), and core source code (cmd/, internal/, pkg/).
Key principle: Secrets never enter the VM. The VM only sees placeholder values; a host-side MITM proxy replaces them in-flight when HTTP requests go to explicitly allowed hosts.
When software inside the VM expects a specific token shape, Matchlock also supports caller-defined placeholders via CLI flags (--secret-placeholder, --secret-file) and SDK builder helpers.
Architecture
โโโโโโโโโโโโโ Host โโโโโโโโโโโโโ โโโโโ Micro-VM โโโโโโ
โ Matchlock CLI / SDK โ โ Guest Agent โ
โ Policy Engine โโโโโโโโ (vsock :5000) โ
โ Transparent Proxy + TLS MITM โ โ โ
โ VFS Server โโโโโโโโ /workspace (FUSE) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโ
Platforms: Linux (Firecracker/KVM) and macOS (Apple Silicon via Virtualization.framework).
CLI Reference
Run a Command in a New Sandbox
matchlock run --image <image> [flags] -- <command>
Run matchlock run --help for the complete, version-matched list of flags and defaults.
