Torna agli aggiornamenti
New releaseJul 27, 2026

matchlock v0.2.17

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.

Condividi

Matchlock

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.

Perché Matchlock?

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.

Avvio rapido

Requisiti di sistema

  • Linux con supporto KVM
  • macOS su Apple Silicon

Installazione

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>

Utilizzo

# 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

File e build

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.

SDK

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):

  • Predefinito (non impostato): gli IP privati vengono bloccati ogni volta che viene inviata una configurazione di rete.
  • Blocco esplicito: chiamare .WithBlockPrivateIPs(true) (oppure .BlockPrivateIPs()).
  • Autorizzazione esplicita: chiamare .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

Categorie