
Эфемерная песочница microVM для AI-агентов с сетевым белым списком, инъекцией секретов через MITM-прокси и изоляцией на уровне ВМ. Загружается менее чем за секунду, поддерживает SDK для Go/Python/TypeScript.
Экспериментальный проект: Этот проект всё ещё находится в активной разработке и может быть подвержен критическим изменениям.
Matchlock — это CLI-инструмент для запуска AI-агентов в эфемерных microVM — с сетевым allowlisting, внедрением секретов через MITM-прокси и изоляцией на уровне VM. Ваши секреты никогда не попадают внутрь VM.
AI-агентам нужно выполнять код, но давать им неограниченный доступ к вашей машине — это риск. Matchlock позволяет выдать агенту полноценное Linux-окружение, которое загружается менее чем за секунду — изолированное и одноразовое.
Когда вы передаёте --allow-host или --secret, Matchlock запечатывает сеть — проходит только трафик к явно разрешённым хостам, а всё остальное блокируется. Когда ваш агент вызывает API, настоящие учётные данные внедряются на лету со стороны хоста. Песочница видит только заполнитель. Даже если агента обманом заставят запустить что-то вредоносное, ваши ключи не утекут, и данным просто некуда будет уйти. Внутри агент получает полноценное Linux-окружение, чтобы делать всё, что ему нужно. Он может устанавливать пакеты, записывать файлы и устраивать беспорядок. Каталоги хоста никогда не разделяются с гостем: входные данные передаются явно, а выходные извлекаются через гостевые файловые API. Изменения внутри гостя одноразовые, если вы не подключите постоянный блочный том. Тот же CLI и то же поведение, будь вы на Linux-сервере или на MacBook.
Полные сведения об установке см. в docs/install.md.
Быстрая установка
Приведённый ниже скрипт определяет ОС и устанавливает matchlock с помощью Homebrew на macOS и rpm/deb в дистрибутивах Linux на базе Debian/RHEL.
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 или API копирования и работы с файлами в SDK. Операции с файловой системой выполняются в нативном хранилище гостя. Используйте 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 запускает BuildKit внутри виртуальной машины и импортирует результат в локальное хранилище образов. Контекст сборки копируется в виртуальную машину с учётом .dockerignore и файлов игнорирования, специфичных для Dockerfile, поэтому --build-disk должен быть достаточно большим, чтобы его вместить. Кэш сборки сохраняется между сборками, и ни один каталог хоста не используется совместно с виртуальной машиной.
Matchlock поставляется с SDK для Go, Python и TypeScript, позволяющими встраивать песочницы непосредственно в ваше приложение. Вы можете запускать виртуальные машины, выполнять команды, транслировать вывод и управлять файлами программно.
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