Matchlock

实验性项目： 本项目目前处于活跃开发阶段，未来可能会有破坏性的变更。

Matchlock 是一款 CLI 工具，旨在通过短暂的微型虚拟机（microVM）来运行 AI Agent 工作负载。它具备网络白名单管理、通过中间人（MITM）代理进行密钥注入以及虚拟机级别的隔离能力，确保你的敏感密钥永远不会进入虚拟机内部。

为什么选择 Matchlock？

AI Agent 需要运行代码，但给予其对宿主机的无限制访问权限存在安全风险。Matchlock 为你提供了一个完整的 Linux 环境，启动时间不到一秒，且具备隔离性与可销毁性。

当你使用 --allow-host 或 --secret 时，Matchlock 会对网络进行“封锁”——只有明确允许的主机可以进行通信，其余所有流量均被拦截。当 Agent 调用 API 时，真正的凭据由宿主机在传输过程中进行注入，沙箱内部始终只能看到占位符。即使 Agent 被诱导执行恶意代码，你的密钥也不会泄露，数据也无处外传。Agent 在内部拥有完整的 Linux 环境，可以随心所欲地安装软件包、编写文件或进行各种操作，而宿主机丝毫不受影响。卷叠加挂载（Volume overlay mounts）是独立的快照，在任务完成后会自动消失。无论是在 Linux 服务器还是 MacBook 上，CLI 和操作行为完全一致。

快速上手

系统要求

• Linux（需支持 KVM）
• macOS（需 Apple Silicon 芯片）

安装

详见 docs/install.md 获取完整的安装说明。

快速安装

以下脚本会自动检测操作系统，并在 macOS 上使用 Homebrew，在 Debian/RHEL 系 Linux 发行版上使用 rpm/deb 进行安装：

curl -fsSL https://raw.githubusercontent.com/jingkaihe/matchlock/main/scripts/install.sh | bash

# 或者安装特定版本
curl -fsSL https://raw.githubusercontent.com/jingkaihe/matchlock/main/scripts/install.sh | bash -s -- --version 0.2.4

Homebrew

macOS 和 Linux 均支持通过 Homebrew 安装：

brew tap jingkaihe/essentials
brew install matchlock

Debian / Ubuntu (.deb)

sudo dpkg -i ./matchlock__linux_amd64.deb
sudo apt-get install -f
matchlock diagnose

Fedora / RHEL / CentOS Stream (.rpm)

sudo dnf install ./matchlock__linux_amd64.rpm
matchlock diagnose

如果 matchlock diagnose 报告缺少主机配置，请运行：

sudo matchlock setup linux

若需明确注册特定用户，请运行：

sudo matchlock setup user 

使用方法

# 基础用法
matchlock run --image alpine:latest cat /etc/os-release
matchlock run --image alpine:latest -it sh
matchlock run --image alpine:latest --no-network -- sh -lc 'echo offline'

# 网络白名单
matchlock run --image python:3.12-alpine \
  --allow-host "api.openai.com" python agent.py

# 即使在空白名单下也启用拦截，以便在运行时添加/删除主机
matchlock run --image alpine:latest --rm=false --network-intercept
matchlock allow-list add  api.openai.com,api.anthropic.com
matchlock allow-list delete  api.openai.com

# 密钥注入（密钥永远不会进入虚拟机）
export ANTHROPIC_API_KEY=sk-xxx
matchlock run --image python:3.12-alpine \
  --secret ANTHROPIC_API_KEY@api.anthropic.com python call_api.py

# 长效沙箱
matchlock run --image alpine:latest --rm=false   # 打印 VM ID
matchlock run --image nginx:latest -d             # 同上，后台运行
matchlock exec vm-abc12345 -it sh                # 进入 VM
matchlock port-forward vm-abc12345 8080:8080     # 端口转发 host:8080 -> guest:8080

# 启动时发布端口
matchlock run --image alpine:latest --rm=false -p 8080:8080

# 生命周期管理
matchlock list | kill | rm | prune

# 从 Dockerfile 构建（在虚拟机内使用 BuildKit）
matchlock build -f Dockerfile -t myapp:latest .

# 从镜像仓库预构建 rootfs（缓存以实现更快的启动）
matchlock build alpine:latest

# 镜像管理
matchlock image ls                                           # 列出所有镜像
matchlock image rm myapp:latest                              # 删除本地镜像
docker save myapp:latest | matchlock image import myapp:latest  # 从 tarball 导入

SDK

Matchlock 提供 Go、Python 和 TypeScript SDK，可直接将沙箱嵌入到你的应用程序中。你可以以编程方式启动虚拟机、执行命令、流式传输输出以及管理文件。

Go

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/jingkaihe/matchlock/pkg/sdk"
)

func main() {
	ctx := context.Background()

	client, err := sdk.NewClient(sdk.DefaultConfig())
	if err != nil {
		panic(err)
	}
	defer client.Close(0)
	defer client.Remove()

	sandbox := sdk.New("alpine:latest").
		AllowHost("dl-cdn.alpinelinux.org", "api.anthropic.com").
		AddSecret("ANTHROPIC_API_KEY", os.Getenv("ANTHROPIC_API_KEY"), "api.anthropic.com")
	if _, err := client.Launch(sandbox); err != nil {
		panic(err)
	}
	if _, err := client.Exec(ctx, "apk add --no-cache curl"); err != nil {
		panic(err)
	}
	// 虚拟机始终只能看到占位符——真实密钥永远不会进入 VM
}