
AIエージェント向けの一時的なmicroVMサンドボックス。ネットワークの許可リスト化、MITMプロキシによるシークレットインジェクション、VMレベルの分離を提供。1秒未満で起動し、Go/Python/TypeScript SDKをサポート。
実験的: このプロジェクトは現在も活発に開発中であり、破壊的な変更が行われる可能性があります。
Matchlock は、エフェメラルな microVM 上で AI エージェントを実行するための CLI ツールです。ネットワークの許可リスト、MITM プロキシ経由のシークレットインジェクション、VM レベルの分離を備えています。シークレットが VM 内に入ることはありません。
AI エージェントはコードを実行する必要がありますが、マシンへの無制限のアクセスを与えるのはリスクです。Matchlock を使えば、1 秒未満で起動する完全な Linux 環境をエージェントに渡すことができます。分離され、使い捨て可能です。
--allow-host または --secret を渡すと、Matchlock はネットワークを封鎖します。明示的に許可されたホストへのトラフィックのみが通過し、それ以外はすべてブロックされます。エージェントが API を呼び出すと、実際の認証情報はホスト側で転送中にインジェクトされます。サンドボックスはプレースホルダーしか見ることができません。たとえエージェントが悪意のあるコードを実行するよう仕向けられても、キーが漏洩することはなく、データの行き先もありません。内部では、エージェントは必要なことを何でも行える完全な Linux 環境を利用できます。パッケージのインストール、ファイルの書き込み、環境の破壊も自由です。ホストのディレクトリがゲストと共有されることは決してありません。入力を明示的に渡し、出力はゲストのファイル API を通じて取得します。永続ブロックボリュームをアタッチしない限り、ゲストローカルの変更は使い捨てです。Linux サーバーでも MacBook でも、同じ CLI、同じ動作です。
完全なインストール手順については docs/install.md を参照してください。
クイックインストール
以下のスクリプトは OS を検出し、macOS では Homebrew を、Debian/RHEL 系の Linux ディストリビューションでは rpm/deb を使用して matchlock をインストールします
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
Homebrew ベースのインストールは macOS と Linux の両方でサポートされています:
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 固有の ignore ファイルが適用されるため、--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(...) を直接使用する場合(ビルダーを使わない場合)は、次のように設定します:
BlockPrivateIPsSet: trueBlockPrivateIPs: false(または true)完全にオフラインのサンドボックス(ゲスト NIC なし/egress なし)を使用する場合は、次のとおりです:
--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"
)
)