Matchlock provides a secure CLI tool for running AI agents within ephemeral microVMs, addressing the inherent risks of code execution by untrusted agents. It offers VM-level isolation, network traffic allowlisting, and a novel secret injection mechanism where sensitive credentials are never exposed directly to the agent's environment. This enables safe execution of AI workloads, even those requiring external API access or package installations, by providing a disposable, secure Linux sandbox.

How It Works

The core of Matchlock is its ability to spin up microVMs (using Firecracker on Linux or Virtualization.framework on macOS) that boot in under a second. It enforces network security by sealing the VM's network access, permitting only explicitly defined hosts. A transparent proxy with TLS MITM capabilities intercepts outbound traffic, injecting real API keys or secrets only when traffic is destined for an allowed host, while the VM agent sees only a placeholder. Each sandbox operates on a copy-on-write filesystem that is automatically discarded upon termination, ensuring complete isolation and a clean slate.

Quick Start & Requirements

• Installation (macOS):

  brew tap jingkaihe/essentials
  brew install matchlock
  

• System Requirements: Linux with KVM support or macOS on Apple Silicon.
• Dependencies: Bash.
• SDKs: Go and Python SDKs are available for programmatic integration.
• Docs: Refer to AGENTS.md for detailed developer documentation.

Highlighted Details

• Rapid MicroVM Boot: Sandboxes boot in under a second, ideal for ephemeral workloads.
• Zero-Trust Secrets: Secrets are injected in-flight via a host-based MITM proxy, never residing within the VM.
• Granular Network Control: Network traffic can be strictly allowlisted to specific hosts.
• Build System Integration: Supports building container images directly within the VM using BuildKit and pre-building rootfs from OCI images for faster startup.
• Cross-Platform CLI: Consistent command-line interface across Linux and macOS.
• Programmable SDKs: Go and Python SDKs allow embedding Matchlock's sandbox capabilities into applications.

Maintenance & Community

The provided README does not contain information regarding specific contributors, sponsorships, or community channels (e.g., Discord, Slack).

Licensing & Compatibility

• License: MIT License.
• Compatibility: The permissive MIT license generally supports commercial use and integration into closed-source applications.

Limitations & Caveats

The project is explicitly marked as "Experimental" and is subject to breaking changes. Network interception mechanisms differ between Linux (transparent proxy) and macOS (gVisor userspace TCP/IP).