
Sandbox de microVM efímero para agentes de IA con listas de permitidos de red, inyección de secretos mediante proxy MITM y aislamiento a nivel de VM. Arranca en menos de un segundo, compatible con SDKs de Go/Python/TypeScript.
Experimental: Este proyecto aún está en desarrollo activo y está sujeto a cambios que pueden romper la compatibilidad.
Matchlock es una herramienta CLI para ejecutar agentes de IA en microVM efímeras, con listas de permitidos de red, inyección de secretos mediante un proxy MITM y aislamiento a nivel de VM. Tus secretos nunca entran en la VM.
Los agentes de IA necesitan ejecutar código, pero darles acceso sin restricciones a tu máquina es un riesgo. Matchlock te permite entregar a un agente un entorno Linux completo que arranca en menos de un segundo, aislado y desechable.
Cuando pasas --allow-host o --secret, Matchlock sella la red: solo pasa el tráfico hacia los hosts explícitamente permitidos, y todo lo demás queda bloqueado. Cuando tu agente llama a una API, las credenciales reales se inyectan en vuelo desde el host. El sandbox solo ve un marcador de posición. Incluso si se engaña al agente para que ejecute algo malicioso, tus claves no se filtran y no hay a dónde puedan ir los datos. Dentro, el agente obtiene un entorno Linux completo para hacer lo que necesite. Puede instalar paquetes, escribir archivos y causar desorden. Los directorios del host nunca se comparten con el guest: proporciona las entradas explícitamente y recupera las salidas mediante las APIs de archivos del guest. Los cambios locales del guest son desechables a menos que adjuntes un volumen de bloque persistente. La misma CLI y el mismo comportamiento tanto si estás en un servidor Linux como en un MacBook.
Consulta docs/install.md para obtener todos los detalles de la instalación.
Instalación rápida
El siguiente script detecta el sistema operativo e instala matchlock usando Homebrew en macOS, y rpm/deb en distribuciones Linux basadas en 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
La instalación basada en Homebrew es compatible tanto con macOS como con 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 informa que falta la configuración del host, ejecute:
sudo matchlock setup linux
Para inscribir explícitamente a un usuario específico, ejecute:
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 no admite montajes de directorios del host ni interceptación del sistema de archivos. Copia archivos de entrada y salida explícitamente con matchlock cp, run --copy-in / --copy-out, o con las API de copia y archivos del SDK. Las operaciones del sistema de archivos se realizan en el almacenamiento nativo del invitado. Usa matchlock volume con run --disk @name:/guest/path para almacenamiento persistente. Consulta la guía de migración.
# 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 ejecuta BuildKit dentro de una VM e importa el resultado en el almacén de imágenes local. El contexto de compilación se copia en la VM, respetando .dockerignore y los archivos de ignorados específicos del Dockerfile, por lo que --build-disk debe ser lo suficientemente grande para contenerlo. La caché de compilación persiste entre compilaciones y no se comparte ningún directorio del host con la VM.
Matchlock incluye SDKs para Go, Python y TypeScript para integrar sandboxes directamente en tu aplicación. Puedes lanzar VMs, ejecutar comandos, transmitir la salida y gestionar archivos de forma programática.
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)
}
}
Comportamiento de IP privada en el SDK de Go (10/8, 172.16/12, 192.168/16):
.WithBlockPrivateIPs(true) (o .BlockPrivateIPs())..AllowPrivateIPs() o .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