
AI एजेंटों के लिए क्षणिक microVM सैंडबॉक्स जिसमें नेटवर्क अनुमति सूची, MITM प्रॉक्सी के माध्यम से गुप्त इंजेक्शन, और VM स्तर पर अलगाव शामिल है। एक सेकंड से भी कम समय में बूट होता है, Go/Python/TypeScript SDKs का समर्थन करता है।
प्रयोगात्मक: यह प्रोजेक्ट अभी भी सक्रिय विकास में है और इसमें ब्रेकिंग बदलाव हो सकते हैं।
Matchlock एक CLI टूल है जो AI एजेंट्स को अल्पकालिक microVM में चलाने के लिए है - नेटवर्क allowlisting, MITM प्रॉक्सी के माध्यम से secret injection, और VM-स्तरीय isolation के साथ। आपके secrets कभी VM में प्रवेश नहीं करते।
AI एजेंट्स को कोड चलाने की आवश्यकता होती है, लेकिन उन्हें आपकी मशीन तक अप्रतिबंधित पहुँच देना एक जोखिम है। Matchlock आपको एक एजेंट को पूर्ण Linux वातावरण सौंपने देता है जो एक सेकंड से कम समय में बूट होता है - पृथक और डिस्पोजेबल।
जब आप --allow-host या --secret पास करते हैं, तो Matchlock नेटवर्क को सील कर देता है - केवल स्पष्ट रूप से अनुमत hosts तक ट्रैफ़िक गुजरता है, और बाकी सब कुछ अवरुद्ध हो जाता है। जब आपका एजेंट किसी API को कॉल करता है तो वास्तविक credentials होस्ट द्वारा इन-फ़्लाइट इंजेक्ट किए जाते हैं। सैंडबॉक्स को केवल एक placeholder दिखता है। भले ही एजेंट को कुछ दुर्भावनापूर्ण चलाने के लिए धोखा दिया जाए, आपकी keys लीक नहीं होतीं और डेटा के जाने की कोई जगह नहीं होती। अंदर एजेंट को एक पूर्ण Linux वातावरण मिलता है जिसमें वह जो चाहे कर सकता है। यह packages इंस्टॉल कर सकता है, फ़ाइलें लिख सकता है और गड़बड़ कर सकता है। Host directories कभी भी guest के साथ साझा नहीं किए जाते: inputs स्पष्ट रूप से प्रदान करें और outputs guest file APIs के माध्यम से प्राप्त करें। Guest-स्थानीय परिवर्तन डिस्पोजेबल होते हैं जब तक कि आप एक persistent block volume संलग्न न करें। समान CLI और समान व्यवहार चाहे आप Linux सर्वर पर हों या MacBook पर।
पूर्ण इंस्टॉलेशन विवरण के लिए docs/install.md देखें।
त्वरित इंस्टॉलेशन
नीचे दिया गया स्क्रिप्ट OS का पता लगाता है, और macOS पर Homebrew तथा Debian/RHEL आधारित Linux डिस्ट्रीब्यूशन पर rpm/deb का उपयोग करके matchlock इंस्टॉल करता है
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
Homebrew आधारित इंस्टॉलेशन macOS और 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
यदि matchlock diagnose होस्ट सेटअप अनुपलब्ध होने की रिपोर्ट करता है, तो चलाएँ:
sudo matchlock setup linux
किसी विशिष्ट उपयोगकर्ता को स्पष्ट रूप से नामांकित करने के लिए, चलाएँ:
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 होस्ट-डायरेक्टरी माउंट या फ़ाइलसिस्टम इंटरसेप्शन का समर्थन नहीं करता है। फ़ाइलों को matchlock cp, run --copy-in / --copy-out, या SDK कॉपी और फ़ाइल API का उपयोग करके स्पष्ट रूप से अंदर और बाहर कॉपी करें। फ़ाइलसिस्टम संचालन नेटिव गेस्ट स्टोरेज पर होते हैं। स्थायी स्टोरेज के लिए run --disk @name:/guest/path के साथ matchlock volume का उपयोग करें। देखें माइग्रेशन गाइड।
# 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 VM के अंदर BuildKit चलाता है और परिणाम को स्थानीय इमेज स्टोर में आयात करता है। बिल्ड कॉन्टेक्स्ट को VM में कॉपी किया जाता है, जिसमें .dockerignore और Dockerfile-विशिष्ट इग्नोर फ़ाइलों का पालन किया जाता है, इसलिए --build-disk को इसे रखने के लिए पर्याप्त बड़ा होना चाहिए। बिल्ड कैश बिल्ड्स के बीच बना रहता है, और VM के साथ कोई होस्ट डायरेक्टरी साझा नहीं की जाती है।
Matchlock आपके एप्लिकेशन में सीधे सैंडबॉक्स एम्बेड करने के लिए Go, Python, और TypeScript SDKs प्रदान करता है। आप VM लॉन्च कर सकते हैं, कमांड निष्पादित कर सकते हैं, आउटपुट स्ट्रीम कर सकते हैं, और प्रोग्रामेटिक रूप से फ़ाइलों को प्रबंधित कर सकते हैं।
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)
}
}
Go SDK का private-IP व्यवहार (10/8, 172.16/12, 192.168/16):
.WithBlockPrivateIPs(true) (या .BlockPrivateIPs()) कॉल करें।.AllowPrivateIPs() या .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