
Sandbox efêmero de microVM para agentes de IA com listagem de permissões de rede, injeção de segredos via proxy MITM e isolamento em nível de VM. Inicializa em menos de um segundo, suporta SDKs Go/Python/TypeScript.
Experimental: Este projeto ainda está em desenvolvimento ativo e sujeito a alterações que podem quebrar a compatibilidade.
Matchlock é uma ferramenta de CLI para executar agentes de IA em microVMs efêmeras - com lista de permissões de rede, injeção de segredos via proxy MITM e isolamento em nível de VM. Seus segredos nunca entram na VM.
Agentes de IA precisam executar código, mas dar a eles acesso irrestrito à sua máquina é um risco. O Matchlock permite entregar a um agente um ambiente Linux completo que inicializa em menos de um segundo - isolado e descartável.
Quando você passa --allow-host ou --secret, o Matchlock sela a rede - apenas o tráfego para hosts explicitamente permitidos passa, e todo o resto é bloqueado. Quando seu agente chama uma API, as credenciais reais são injetadas em trânsito pelo host. O sandbox só vê um placeholder. Mesmo que o agente seja induzido a executar algo malicioso, suas chaves não vazam e não há para onde os dados irem. Dentro dele, o agente recebe um ambiente Linux completo para fazer o que precisar. Ele pode instalar pacotes, escrever arquivos e fazer uma bagunça. Diretórios do host nunca são compartilhados com o guest: forneça entradas explicitamente e recupere saídas através das APIs de arquivos do guest. Alterações locais do guest são descartáveis, a menos que você anexe um volume de bloco persistente. Mesma CLI e mesmo comportamento, seja em um servidor Linux ou em um MacBook.
Consulte docs/install.md para detalhes completos de instalação.
Instalação Rápida
O script abaixo detecta o sistema operacional e instala o matchlock usando Homebrew no Macos, e rpm/deb em distribuições Linux baseadas em 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
A instalação baseada em Homebrew é suportada tanto no macOS quanto no 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 relatar configuração ausente do host, execute:
sudo matchlock setup linux
Para inscrever um usuário específico explicitamente, execute:
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
O Matchlock não oferece suporte a montagens de diretórios do host nem a interceptação de sistema de arquivos. Copie arquivos para dentro e para fora explicitamente com matchlock cp, run --copy-in / --copy-out, ou com as APIs de cópia e de arquivos do SDK. As operações de sistema de arquivos ocorrem no armazenamento nativo do guest. Use matchlock volume com run --disk @name:/guest/path para armazenamento persistente. Consulte o guia de migração.
# 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 executa o BuildKit dentro de uma VM e importa o resultado para o armazenamento local de imagens. O contexto de build é copiado para a VM, respeitando o .dockerignore e os arquivos de ignore específicos do Dockerfile, portanto --build-disk deve ser grande o suficiente para armazená-lo. O cache de build persiste entre builds, e nenhum diretório do host é compartilhado com a VM.
O Matchlock fornece SDKs para Go, Python e TypeScript para incorporar sandboxes diretamente na sua aplicação. Você pode iniciar VMs, executar comandos, transmitir saída e gerenciar arquivos programaticamente.
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 de IP privado no Go SDK (10/8, 172.16/12, 192.168/16):
.WithBlockPrivateIPs(true) (ou .BlockPrivateIPs())..AllowPrivateIPs() ou .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