
Sandbox microVM effimero per agenti AI con allowlisting di rete, iniezione di segreti tramite proxy MITM e isolamento a livello di VM. Si avvia in meno di un secondo, supporta SDK Go/Python/TypeScript.
Sperimentale: Questo progetto è ancora in fase di sviluppo attivo ed è soggetto a modifiche che possono rompere la compatibilità.
Matchlock è uno strumento CLI per eseguire agenti AI in microVM effimere - con allowlisting di rete, iniezione di segreti tramite proxy MITM e isolamento a livello di VM. I tuoi segreti non entrano mai nella VM.
Gli agenti AI devono eseguire codice, ma dare loro accesso illimitato alla tua macchina è un rischio. Matchlock ti permette di fornire a un agente un ambiente Linux completo che si avvia in meno di un secondo - isolato e usa e getta.
Quando passi --allow-host o --secret, Matchlock sigilla la rete - solo il traffico verso gli host esplicitamente consentiti passa, e tutto il resto viene bloccato. Quando il tuo agente chiama un'API, le credenziali reali vengono iniettate al volo dall'host. La sandbox vede sempre e solo un segnaposto. Anche se l'agente viene ingannato per eseguire qualcosa di malevolo, le tue chiavi non trapelano e non c'è modo per i dati di uscire. All'interno l'agente ottiene un ambiente Linux completo per fare tutto ciò di cui ha bisogno. Può installare pacchetti, scrivere file e fare disordine. Le directory dell'host non vengono mai condivise con il guest: fornisci gli input esplicitamente e recupera gli output tramite le API dei file del guest. Le modifiche locali al guest sono usa e getta a meno che tu non colleghi un volume a blocchi persistente. Stessa CLI e stesso comportamento sia su un server Linux che su un MacBook.
Consulta docs/install.md per i dettagli completi sull'installazione.
Installazione rapida
Lo script seguente rileva il sistema operativo e installa matchlock usando Homebrew su macOS, e rpm/deb sulle distribuzioni Linux derivate da 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'installazione tramite Homebrew è supportata sia su macOS che su 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
Se matchlock diagnose segnala una configurazione host mancante, esegui:
sudo matchlock setup linux
Per registrare esplicitamente un utente specifico, eseguire:
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 non supporta mount di directory host o intercettazione del filesystem. Copia i file dentro e fuori esplicitamente con matchlock cp, run --copy-in / --copy-out, oppure con le API di copia e file dell'SDK. Le operazioni sul filesystem avvengono sullo storage nativo del guest. Usa matchlock volume con run --disk @name:/guest/path per lo storage persistente. Consulta la guida alla migrazione.
# 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 esegue BuildKit all'interno di una VM e importa il risultato nell'archivio locale delle immagini. Il contesto di build viene copiato nella VM, rispettando .dockerignore e i file di ignore specifici del Dockerfile, quindi --build-disk deve essere sufficientemente grande da contenerlo. La cache di build persiste tra le build e nessuna directory dell'host è condivisa con la VM.
Matchlock fornisce SDK per Go, Python e TypeScript per incorporare sandbox direttamente nella tua applicazione. Puoi avviare VM, eseguire comandi, trasmettere l'output e gestire i file a livello di programmazione.
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)
}
}
Comportamento degli IP privati nell'SDK Go (10/8, 172.16/12, 192.168/16):
.WithBlockPrivateIPs(true) (oppure .BlockPrivateIPs())..AllowPrivateIPs() oppure .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