实验性: 本项目仍在积极开发中,可能会有破坏性变更。
Matchlock 是一个 CLI 工具,用于在临时 microVM 中运行 AI 代理——具备网络允许列表、通过 MITM 代理进行密钥注入以及 VM 级隔离。你的密钥永远不会进入 VM。
AI 代理需要运行代码,但让它们不受限制地访问你的机器是一种风险。Matchlock 让你可以交给代理一个完整的 Linux 环境,它能在不到一秒内启动——隔离且可丢弃。
当你传入 --allow-host 或 --secret 时,Matchlock 会封闭网络——只有发往明确允许的主机的流量才能通过,其他一切都被阻止。当你的代理调用 API 时,真实凭据由主机在传输过程中注入。沙箱只能看到占位符。即使代理被骗去运行恶意内容,你的密钥也不会泄露,数据也无处可去。在内部,代理获得一个完整的 Linux 环境来做它需要做的任何事情。它可以安装软件包、写入文件、把一切弄得一团糟。主机目录永远不会与客户机共享:显式提供输入,并通过客户机文件 API 获取输出。除非你挂载持久块卷,否则客户机本地的更改都是可丢弃的。无论你是在 Linux 服务器还是 MacBook 上,CLI 和行為都相同。
完整安装详情请参阅 docs/install.md。
快速安装
下面的脚本会检测操作系统,并在 macOS 上使用 Homebrew 安装 matchlock,在 Debian/RHEL 系 Linux 发行版上使用 rpm/deb 安装
curl -fsSL https://raw.githubusercontent.com/jingkaihe/matchlock/main/scripts/install.sh | bash
# Or install a specific release
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_<version>_linux_amd64.deb
sudo apt-get install -f
matchlock diagnose
Fedora / RHEL / CentOS Stream (.rpm)
sudo dnf install ./matchlock_<version>_linux_amd64.rpm
matchlock diagnose
如果 matchlock diagnose 报告缺少主机设置,请运行:
sudo matchlock setup linux
要显式注册特定用户,请运行:
sudo matchlock setup user <name>
# Basic
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'
# Network allowlist
matchlock run --image python:3.12-alpine \
--allow-host "api.openai.com" python agent.py
# Keep interception enabled even with an empty allowlist,
# so hosts can be added/removed at runtime.
matchlock run --image alpine:latest --rm=false --network-intercept
matchlock allow-list add <vm-id> api.openai.com,api.anthropic.com
matchlock allow-list delete <vm-id> api.openai.com
# Secret injection (never enters the VM)
export ANTHROPIC_API_KEY=sk-xxx
matchlock run --image python:3.12-alpine \
--secret [email protected] python call_api.py
# Long-lived sandboxes
matchlock run --image alpine:latest --rm=false # prints VM ID
matchlock run --image nginx:latest -d # same as above, detached
matchlock exec vm-abc12345 -it sh # attach to it
matchlock port-forward vm-abc12345 8080:8080 # forward host:8080 -> guest:8080
# Publish ports at startup
matchlock run --image alpine:latest --rm=false -p 8080:8080
# Lifecycle
matchlock list | kill | rm | prune
# Build from Dockerfile (uses BuildKit-in-VM)
matchlock build -f Dockerfile -t myapp:latest .
# Pull a registry image (caches for faster startup)
matchlock pull alpine:latest
# Image management
matchlock image ls # List all images
matchlock image rm myapp:latest # Remove a local image
docker save myapp:latest | matchlock image import myapp:latest # Import from tarball
Matchlock 不支持宿主机目录挂载或文件系统拦截。请使用 matchlock cp、run --copy-in / --copy-out,或 SDK 的复制与文件 API 显式地复制文件进出。文件系统操作在原生客户机存储上进行。如需持久化存储,请使用 matchlock volume 配合 run --disk @name:/guest/path。参见迁移指南。
# Copy ./src in, run the build, and copy the results out
matchlock run --image alpine:latest --copy-in ./src/.:/workspace --copy-out /workspace/dist:./dist -w /workspace -- make
# Copy files to and from a running sandbox
matchlock cp ./src/. vm-abc12345:/workspace
matchlock cp vm-abc12345:/workspace/dist ./dist
matchlock build 在 VM 内运行 BuildKit,并将结果导入本地镜像存储。构建上下文会被复制到 VM 中,并遵循 .dockerignore 和 Dockerfile 专用的忽略文件,因此 --build-disk 必须足够大以容纳它。构建缓存在多次构建之间持久保留,且不与 VM 共享任何主机目录。
Matchlock 提供 Go、Python 和 TypeScript SDK,用于将沙箱直接嵌入你的应用程序。你可以通过编程方式启动 VM、执行命令、流式传输输出并管理文件。
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)
}
// The VM only ever sees a placeholder - the real key never enters the sandbox
result, err := client.Exec(ctx, "echo $ANTHROPIC_API_KEY")
if err != nil {
panic(err)
}
fmt.Print(result.Stdout) // prints "SANDBOX_SECRET_a1b2c3d4..."
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"}]}'`
if _, err := client.ExecStream(ctx, curlCmd, os.Stdout, os.Stderr); err != nil {
panic(err)
}
}
Go SDK 私有 IP 行为(10/8、172.16/12、192.168/16):
.WithBlockPrivateIPs(true)(或 .BlockPrivateIPs())。.AllowPrivateIPs() 或 .WithBlockPrivateIPs(false)。sandbox := sdk.New("alpine:latest").
AllowHost("api.openai.com").
AddHost("api.internal", "10.0.0.10").
WithNetworkMTU(1200).
AllowPrivateIPs() // explicit override: block_private_ips=false
// SDK network interception (request/response mutation, body shaping, SSE data-line transform)
sandbox = sandbox.WithNetworkInterception(&sdk.NetworkInterceptionConfig{
Rules: []sdk.NetworkHookRule{
{
Phase: sdk.NetworkHookPhaseBefore,
Action: sdk.NetworkHookActionMutate,
Hosts: []string{"api.openai.com"},
SetHeaders: map[string]string{"X-Trace-Id": "trace-123"},
},
{
Phase: sdk.NetworkHookPhaseAfter,
Action: sdk.NetworkHookActionMutate,
Hosts: []string{"api.openai.com"},
BodyReplacements: []sdk.NetworkBodyTransform{
{Find: "internal-id", Replace: "redacted"},
},
},
},
})
如果直接使用 client.Create(...)(不通过 builder),请设置:
BlockPrivateIPsSet: trueBlockPrivateIPs: false(或 true)对于完全离线的沙箱(无 guest NIC / 无出站流量),请使用:
--no-network.WithNoNetwork().with_no_network().withNoNetwork()Python(PyPI)
pip install matchlock
# or
uv add matchlock
import os
import sys
from matchlock import Client, Sandbox
sandbox = (
Sandbox("python:3.12-alpine")
.allow_host(
"dl-cdn.alpinelinux.org",
"files.pythonhosted.org", "pypi.org",
"astral.sh", "github.com", "objects.githubusercontent.com",
"api.anthropic.com",
)
.add_secret(
"ANTHROPIC_API_KEY", os.environ["ANTHROPIC_API_KEY"], "api.anthropic.com"
)
)
SCRIPT = """\
# /// script
# requires-python = ">=3.12"
# dependencies = ["anthropic"]
# ///
import anthropic, os
client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
with client.messages.stream(
model="claude-haiku-4-5-20251001",
max_tokens=1024,
messages=[{"role": "user", "content": "Explain TCP/IP."}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
print()
"""