GitHub - jingkaihe/matchlock: Matchlock bảo mật công việc AI với sandbox Linux

Matchlock là gì?

Matchlock là một công cụ dòng lệnh (CLI) cho phép chạy các AI agent trong các microVM ngắn hạn - với mạng danh sách trắng, thông tin mật được tiêm thông qua proxy giữa chặn và các thứ khác bị khóa mặc định. Thông tin mật sẽ không bao giờ vào VM.

Tại sao nên dùng Matchlock?

AI agent cần chạy mã nhưng cho phép chúng truy cập không giới hạn vào máy của bạn là một rủi ro. Matchlock cho phép bạn cung cấp một môi trường Linux đầy đủ cho agent để hoạt động - tách biệt, có thể tái chế, và bị khóa mặc định.

Yêu cầu hệ thống

• Linux với hỗ trợ KVM
• macOS trên Apple Silicon

Cài đặt

brew tap jingkaihe/essentials
brew install matchlock

Cách sử dụng

# Cơ bản
matchlock run --image alpine:latest cat /etc/os-release
matchlock run --image alpine:latest -it sh

# Danh sách trắng mạng
matchlock run --image python:3.12-alpine \
  --allow-host "api.openai.com" python agent.py

# Tiêm thông tin mật (không vào 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

# Sandbox kéo dài
matchlock run --image alpine:latest --rm=false   # in VM ID
matchlock exec vm-abc12345 -it sh                # kết nối

# Quản lý vòng đời
matchlock list | kill | rm | prune

# Xây dựng từ Dockerfile
matchlock build -f Dockerfile -t myapp:latest .

# Quản lý hình ảnh
matchlock image ls                                           # Liệt kê tất cả hình ảnh
matchlock image rm myapp:latest                              # Xóa hình ảnh cục bộ

SDK

Matchlock cũng kèm theo SDK cho Go và Python giúp tích hợp sandbox trực tiếp vào ứng dụng.

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")

	client.Launch(sandbox)
	client.Exec("apk add --no-cache curl")

	// VM chỉ thấy placeholder - khóa thực không vào sandbox
	result, _ := client.Exec("echo $ANTHROPIC_API_KEY")
	fmt.Print(result.Stdout) // in "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"}]}'`
	client.ExecStream(curlCmd, os.Stdout, os.Stderr)
}

Python

pip install matchlock
# hoặc
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)

Xem đầy đủ ví dụ tại examples/go và examples/python.

Kiến trúc

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

Các chế độ mạng

Tài liệu

Xem AGENTS.md để tham khảo đầy đủ của nhà phát triển.

Giấy phép

MIT

Về

Matchlock bảo mật công việc của AI agent với môi trường sandbox Linux.

Readme