
Ephemere microVM-Sandbox für KI-Agenten mit Network Allowlisting, Secret Injection via MITM-Proxy und VM-Isolation. Startet in unter einer Sekunde, unterstützt Go/Python/TypeScript-SDKs.
Experimentell: Dieses Projekt befindet sich noch in aktiver Entwicklung und kann Änderungen unterliegen, die die Kompatibilität brechen.
Matchlock ist ein CLI-Tool zum Ausführen von KI-Agenten in kurzlebigen microVMs – mit Netzwerk-Allowlisting, Secret-Injection über einen MITM-Proxy und Isolation auf VM-Ebene. Deine Secrets gelangen niemals in die VM.
KI-Agenten müssen Code ausführen, aber ihnen uneingeschränkten Zugriff auf deinen Rechner zu geben, ist ein Risiko. Mit Matchlock kannst du einem Agenten eine vollständige Linux-Umgebung geben, die in unter einer Sekunde startet – isoliert und wegwerfbar.
Wenn du --allow-host oder --secret übergibst, versiegelt Matchlock das Netzwerk – nur Datenverkehr zu ausdrücklich erlaubten Hosts kommt durch, alles andere wird blockiert. Wenn dein Agent eine API aufruft, werden die echten Anmeldedaten während der Übertragung vom Host injiziert. Die Sandbox sieht immer nur einen Platzhalter. Selbst wenn der Agent dazu verleitet wird, etwas Bösartiges auszuführen, gelangen deine Schlüssel nicht nach außen und es gibt keinen Ort, an den Daten abfließen könnten. Im Inneren erhält der Agent eine vollständige Linux-Umgebung, um alles zu tun, was er benötigt. Er kann Pakete installieren, Dateien schreiben und Unordnung verursachen. Host-Verzeichnisse werden niemals mit dem Gast geteilt: Eingaben werden explizit bereitgestellt und Ausgaben über die Datei-APIs des Gasts abgerufen. Gastlokale Änderungen sind wegwerfbar, sofern du kein persistentes Block-Volume anhängst. Gleiche CLI und gleiches Verhalten, egal ob du auf einem Linux-Server oder einem MacBook arbeitest.
Vollständige Installationsdetails findest du in docs/install.md.
Schnellinstallation
Das folgende Skript erkennt das Betriebssystem und installiert matchlock unter macOS über Homebrew sowie über rpm/deb auf Debian/RHEL-basierten Linux-Distributionen
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
Die Installation über Homebrew wird sowohl unter macOS als auch unter Linux unterstützt:
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
Wenn matchlock diagnose eine fehlende Host-Einrichtung meldet, führen Sie Folgendes aus:
sudo matchlock setup linux
Um einen bestimmten Benutzer explizit einzuschreiben, führen Sie aus:
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 unterstützt keine Host-Verzeichnis-Mounts oder Dateisystem-Interception. Kopiere Dateien explizit hinein und heraus mit matchlock cp, run --copy-in / --copy-out oder den Copy- und Datei-APIs des SDK. Dateisystemoperationen finden auf nativem Gast-Speicher statt. Verwende matchlock volume mit run --disk @name:/guest/path für persistenten Speicher. Siehe die Migrationsanleitung.
# 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 führt BuildKit in einer VM aus und importiert das Ergebnis in den lokalen Image-Store. Der Build-Kontext wird in die VM kopiert, wobei .dockerignore und Dockerfile-spezifische Ignore-Dateien berücksichtigt werden, sodass --build-disk groß genug sein muss, um ihn aufzunehmen. Der Build-Cache bleibt zwischen Builds erhalten, und es wird kein Host-Verzeichnis mit der VM geteilt.
Matchlock bietet Go-, Python- und TypeScript-SDKs, um Sandboxes direkt in Ihre Anwendung einzubetten. Sie können VMs starten, Befehle ausführen, Ausgaben streamen und Dateien programmatisch verwalten.
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-Verhalten für private IPs (10/8, 172.16/12, 192.168/16):
.WithBlockPrivateIPs(true) aufrufen (oder .BlockPrivateIPs())..AllowPrivateIPs() oder .WithBlockPrivateIPs(false) aufrufen.