
에페머럴 마이크로VM 샌드박스로, AI 에이전트를 위한 네트워크 허용 목록, 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를 사용하여 파일을 명시적으로 복사해 넣고 빼십시오. 파일시스템 작업은 네이티브 게스트 스토리지에서 이루어집니다. 영구 저장소가 필요하면 run --disk @name:/guest/path와 함께 matchlock volume을 사용하십시오. 마이그레이션 가이드를 참조하십시오.
# 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을 실행하고 그 결과를 로컬 이미지 저장소로 가져옵니다. 빌드 컨텍스트는 .dockerignore 및 Dockerfile 전용 ignore 파일을 준수하여 VM으로 복사되므로, --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 없음 / 이그레스 없음)의 경우, 다음을 사용하세요:
--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"
)
)