Matchlock – 通过基于 Linux 的沙箱保护 AI 代理工作负载

Source: Hacker News

Matchlock

Matchlock 是一个用于在 短暂的 microVM 中运行 AI 代理的 CLI 工具。它提供：

• 网络白名单 – 仅允许明确授权的连接。
• 通过 MITM 代理进行密钥注入 – 密钥安全注入，且永不触及 VM 的文件系统。
• 安全默认设置 – 其他所有（网络、存储等）默认被阻止。

您的密钥永不进入 VM，保持工作负载的隔离与安全。

Source: …

为什么选择 Matchlock？

AI 代理需要运行代码，但让它们无限制地访问你的机器风险很大。Matchlock 提供了一个 完整的 Linux 环境，具备以下特点：

• 启动不到一秒 —— 默认隔离、一次性使用，并且默认上锁。
• 在飞行中注入真实凭证，当代理调用 API 时；沙箱只会看到占位符。
• 默认封闭网络 —— 除非你明确允许，否则任何东西都无法离开沙箱。
• 保护你的机密 —— 即使代理被诱导运行恶意代码，你的密钥也永远不会泄露，数据也无处可逃。

在沙箱内部，代理获得一个完整的 Linux 环境，能够：

• 安装软件包
• 写入文件
• 创建任何临时的混乱

在外部，你的主机保持不受影响。每个沙箱都运行在独立的 写时复制文件系统 上，使用完毕后即会消失。无论你是在 Linux 服务器还是在 MacBook 上，体验都是相同的——相同的 CLI、相同的行为。

Source: …

快速开始

系统要求

• Linux – 需要 KVM 支持
• macOS – Apple Silicon

安装

brew tap jingkaihe/essentials
brew install matchlock

使用

基本

matchlock run --image alpine:latest cat /etc/os-release
matchlock run --image alpine:latest -it sh

网络白名单

matchlock run --image python:3.12-alpine \
  --allow-host "api.openai.com" python agent.py

密钥注入（永不进入 VM）

export ANTHROPIC_API_KEY=sk-xxx
matchlock run --image python:3.12-alpine \
  --secret ANTHROPIC_API_KEY@api.anthropic.com python call_api.py

长期沙箱

# 创建持久化 VM（会打印 VM ID）
matchlock run --image alpine:latest --rm=false

# 附加到已有的 VM
matchlock exec vm-abc12345 -it sh

生命周期命令

matchlock list          # 列出运行中的 VM
matchlock kill          # 停止 VM
matchlock rm            # 删除 VM
matchlock prune         # 清理已停止的 VM

从 Dockerfile 构建（使用 BuildKit‑in‑VM）

matchlock build -f Dockerfile -t myapp:latest .

预构建根文件系统（从注册表镜像缓存，加快启动）

matchlock build alpine:latest

镜像管理

# 列出所有镜像
matchlock image ls

# 删除本地镜像
matchlock image rm myapp:latest

# 从 tar 包导入镜像
docker save myapp:latest | \
  matchlock image import myapp:latest

Source: …

SDK

Matchlock 附带 Go 和 Python SDK，允许您直接在应用程序中嵌入沙箱。您可以以编程方式启动 VM、执行命令、流式输出以及写入文件。

Go

package main

import (
	"fmt"
	"os"

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

func main() {
	// 创建使用默认配置的客户端。
	client, _ := sdk.NewClient(sdk.DefaultConfig())
	defer client.Close()

	// 定义沙箱。
	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")

	// 启动沙箱并安装 curl。
	client.Launch(sandbox)
	client.Exec("apk add --no-cache curl")

	// VM 只会看到占位符——真实的密钥永远不会进入沙箱。
	result, _ := client.Exec("echo $ANTHROPIC_API_KEY")
	fmt.Print(result.Stdout) // 打印 "SANDBOX_SECRET_a1b2c3d4..."

	// 向 Anthropic 的 API 发起流式请求。
	curlCmd := `curl -s --no-buffer https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-haiku-4-5-20251001","max_tokens":1024,"stream":true,
       "messages":[{"role":"user","content":"Explain TCP to me"}]}'`

	client.ExecStream(curlCmd, os.Stdout, os.Stderr)
}

Python (PyPI)

pip install matchlock
# or
uv add matchlock

import os
import sys

from matchlock import Client, Config, Sandbox

# 定义沙箱。
sandbox = (
    Sandbox("alpine:latest")
    .allow_host("dl-cdn.alpinelinux.org", "api.anthropic.com")
    .add_secret(
        "ANTHROPIC_API_KEY", os.environ["ANTHROPIC_API_KEY"], "api.anthropic.com"
    )
)

curl_cmd = """curl -s --no-buffer https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-haiku-4-5-20251001","max_tokens":1024,"stream":true,
       "messages":[{"role":"user","content":"Explain TCP/IP."}]}'"""

# 使用客户端启动沙箱并运行命令。
with Client(Config()) as client:
    client.launch(sandbox)
    client.exec("apk add --no-cache curl")
    client.exec_stream(curl_cmd, stdout=sys.stdout, stderr=sys.stderr)

完整示例

• Go:
• Python:

Source: …

架构

graph LR
    subgraph Host
        CLI["Matchlock CLI"]
        Policy["Policy Engine"]
        Proxy["Transparent Proxy + TLS MITM"]
        VFS["VFS Server"]

        CLI --> Policy
        CLI --> Proxy
        Policy --> Proxy
    end

    subgraph VM["Micro‑VM (Firecracker / Virtualization.framework)"]
        Agent["Guest Agent"]
        FUSE["/workspace (FUSE)"]
        Image["Any OCI Image (Alpine, Ubuntu, etc.)"]

        Agent --- Image
        FUSE --- Image
    end

    Proxy -- "vsock :5000" --> Agent
    VFS   -- "vsock :5001" --> FUSE

该图展示了 Matchlock CLI、Policy Engine、Transparent Proxy 与 VFS Server 在宿主机侧的关系，以及 Guest Agent、FUSE 工作区 与 OCI 镜像在微型虚拟机（Firecracker 或 Virtualization.framework）内部的关系。宿主机与虚拟机之间通过 vsock 端口 5000 和 5001 进行通信。

网络模式

文档

请在 AGENTS.md 中查看完整的开发者参考。

许可证

MIT