
Sandbox microVM éphémère pour agents d'IA avec liste blanche réseau, injection de secrets via proxy MITM, et isolation au niveau de la VM. Démarre en moins d'une seconde, prend en charge les SDK Go, Python et TypeScript.
Expérimental : Ce projet est toujours en développement actif et sujet à des changements incompatibles.
Matchlock est un outil CLI pour exécuter des agents IA dans des microVM éphémères - avec liste d'autorisation réseau, injection de secrets via un proxy MITM et isolation au niveau de la VM. Vos secrets n'entrent jamais dans la VM.
Les agents IA ont besoin d'exécuter du code, mais leur donner un accès illimité à votre machine est un risque. Matchlock vous permet de fournir à un agent un environnement Linux complet qui démarre en moins d'une seconde - isolé et jetable.
Lorsque vous passez --allow-host ou --secret, Matchlock verrouille le réseau - seul le trafic vers les hôtes explicitement autorisés passe, et tout le reste est bloqué. Lorsque votre agent appelle une API, les véritables identifiants sont injectés à la volée par l'hôte. Le bac à sable ne voit jamais qu'un espace réservé. Même si l'agent est amené à exécuter quelque chose de malveillant, vos clés ne fuient pas et les données n'ont nulle part où aller. À l'intérieur, l'agent dispose d'un environnement Linux complet pour faire tout ce dont il a besoin. Il peut installer des paquets, écrire des fichiers et faire du désordre. Les répertoires de l'hôte ne sont jamais partagés avec l'invité : fournissez les entrées explicitement et récupérez les sorties via les API de fichiers de l'invité. Les modifications locales à l'invité sont jetables, sauf si vous attachez un volume bloc persistant. Même CLI et même comportement, que vous soyez sur un serveur Linux ou un MacBook.
Consultez docs/install.md pour tous les détails d'installation.
Installation rapide
Le script ci-dessous détecte le système d'exploitation et installe matchlock à l'aide de Homebrew sur macOS, et de rpm/deb sur les distributions Linux de type 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
L'installation via Homebrew est prise en charge sur macOS et 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
Si matchlock diagnose signale une configuration de l'hôte manquante, exécutez :
sudo matchlock setup linux
Pour inscrire explicitement un utilisateur spécifique, exécutez :
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 ne prend pas en charge les montages de répertoires hôtes ni l'interception du système de fichiers. Copiez les fichiers explicitement vers et depuis l'environnement avec matchlock cp, run --copy-in / --copy-out, ou les API de copie et de fichiers du SDK. Les opérations sur le système de fichiers s'effectuent sur le stockage natif de l'invité. Utilisez matchlock volume avec run --disk @name:/guest/path pour un stockage persistant. Consultez le guide de migration.
# 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 exécute BuildKit dans une VM et importe le résultat dans le magasin d'images local. Le contexte de build est copié dans la VM, en respectant .dockerignore et les fichiers d'ignore spécifiques au Dockerfile, donc --build-disk doit être suffisamment grand pour le contenir. Le cache de build persiste entre les builds, et aucun répertoire de l'hôte n'est partagé avec la VM.
Matchlock fournit des SDK Go, Python et TypeScript pour intégrer des sandboxes directement dans votre application. Vous pouvez lancer des VM, exécuter des commandes, diffuser la sortie et gérer des fichiers par programmation.
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)
}
}
Comportement des IP privées dans le SDK Go (10/8, 172.16/12, 192.168/16) :
.WithBlockPrivateIPs(true) (ou .BlockPrivateIPs())..AllowPrivateIPs() ou .WithBlockPrivateIPs(false).