
صندوق رمل صغير VM مؤقت لوكلاء الذكاء الاصطناعي مع قائمة السماح بالشبكة، وحقن الأسرار عبر وكيل MITM، وعزل على مستوى VM. يتم التشغيل في أقل من ثانية، ويدعم SDKs لـ Go/Python/TypeScript.
تجريبي: لا يزال هذا المشروع قيد التطوير النشط ومعرّض لتغييرات كاسرة.
Matchlock هي أداة سطر أوامر (CLI) لتشغيل وكلاء الذكاء الاصطناعي في أجهزة افتراضية دقيقة (microVMs) مؤقتة - مع قوائم السماح للشبكة، وحقن الأسرار عبر وسيط MITM، وعزل على مستوى الجهاز الافتراضي. أسرارك لا تدخل الجهاز الافتراضي أبدًا.
يحتاج وكلاء الذكاء الاصطناعي إلى تشغيل التعليمات البرمجية، لكن منحهم وصولًا غير مقيّد إلى جهازك يُعدّ مخاطرة. تتيح لك Matchlock تسليم الوكيل بيئة Linux كاملة تُقلع في أقل من ثانية - معزولة وقابلة للتخلص منها.
عند تمرير --allow-host أو --secret، تُغلق Matchlock الشبكة - فلا يمرّ سوى حركة المرور إلى المضيفين المسموح بهم صراحةً، ويُحظر كل ما عدا ذلك. وعندما يستدعي وكيلك واجهة برمجية (API)، تُحقن بيانات الاعتماد الحقيقية أثناء النقل من قِبل المضيف. لا ترى بيئة العزل سوى عنصر نائب (placeholder). وحتى لو خُدع الوكيل لتشغيل شيء خبيث، فلن تتسرّب مفاتيحك ولا يوجد مكان تذهب إليه البيانات. في الداخل يحصل الوكيل على بيئة Linux كاملة ليفعل ما يحتاجه. يمكنه تثبيت الحزم وكتابة الملفات وإحداث فوضى. لا تُشارَك أدلة المضيف مع الضيف أبدًا: قدّم المدخلات صراحةً واسترجع المخرجات عبر واجهات برمجة ملفات الضيف. التغييرات المحلية في الضيف قابلة للتخلص منها ما لم تُرفق وحدة تخزين كتلية دائمة (persistent block volume). نفس سطر الأوامر ونفس السلوك سواء كنت على خادم Linux أو على جهاز MacBook.
راجع docs/install.md للحصول على تفاصيل التثبيت الكاملة.
تثبيت سريع
يكتشف السكربت أدناه نظام التشغيل، ويثبّت matchlock باستخدام Homebrew على macOS، وrpm/deb على توزيعات Linux من نوع 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
تتوفر عملية التثبيت عبر 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. تحدث عمليات نظام الملفات على وحدة التخزين الأصلية للضيف. استخدم matchlock volume مع run --disk @name:/guest/path للتخزين الدائم. راجع دليل الترحيل.
# 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 يشغّل BuildKit داخل جهاز ظاهري ويستورد النتيجة إلى مخزن الصور المحلي. يُنسخ سياق البناء إلى الجهاز الظاهري، مع مراعاة .dockerignore وملفات التجاهل الخاصة بـ Dockerfile، لذا يجب أن يكون --build-disk كبيرًا بما يكفي لاستيعابه. تستمر ذاكرة التخزين المؤقت للبناء بين عمليات البناء، ولا يُشارك أي دليل مضيف مع الجهاز الظاهري.
توفّر Matchlock حزم SDK لـ Go وPython وTypeScript لتضمين بيئات الحماية (sandboxes) مباشرةً في تطبيقك. يمكنك تشغيل الأجهزة الظاهرية وتنفيذ الأوامر وبثّ المخرجات وإدارة الملفات برمجيًا.
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)
}
}
سلوك عناوين IP الخاصة في Go SDK (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