matchlock

# Matchlock

> **प्रायोगिक:** यह परियोजना अभी भी सक्रिय विकास में है और इसमें ब्रेकिंग चेंजेस हो सकते हैं।

मैचलॉक AI एजेंटों को अस्थायी माइक्रोवीएम में चलाने के लिए एक CLI उपकरण है - जिसमें नेटवर्क अनुमति-सूची, MITM प्रॉक्सी के माध्यम से सीक्रेट इंजेक्शन, और वीएम-स्तरीय आइसोलेशन शामिल है। आपके सीक्रेट कभी भी वीएम में प्रवेश नहीं करते।

## क्यों मैचलॉक?

AI एजेंटों को कोड चलाने की आवश्यकता होती है, लेकिन उन्हें आपकी मशीन तक अप्रतिबंधित पहुँच देना जोखिम भरा है। मैचलॉक आपको एक एजेंट को एक पूर्ण लिनक्स वातावरण देने की अनुमति देता है जो एक सेकंड से भी कम समय में बूट होता है - पृथक और डिस्पोज़ेबल।

जब आप `--allow-host` या `--secret` पास करते हैं, तो मैचलॉक नेटवर्क को सील कर देता है - केवल स्पष्ट रूप से अनुमत होस्ट्स पर ट्रैफिक ही गुजरता है, और बाकी सब कुछ ब्लॉक हो जाता है। जब आपका एजेंट किसी API को कॉल करता है तो वास्तविक क्रेडेंशियल्स होस्ट द्वारा फ्लाइट में इंजेक्ट किए जाते हैं। सैंडबॉक्स केवल एक प्लेसहोल्डर देखता है। भले ही एजेंट को कुछ दुर्भावनापूर्ण चलाने के लिए धोखा दिया जाए, आपकी कुंजियाँ लीक नहीं होतीं और डेटा के जाने की कोई जगह नहीं होती। अंदर, एजेंट को वह सब कुछ करने के लिए एक पूर्ण लिनक्स वातावरण मिलता है जो उसे चाहिए। वह पैकेज इंस्टॉल कर सकता है, फ़ाइलें लिख सकता है, और गंदगी कर सकता है। बाहर, आपकी मशीन को कुछ महसूस नहीं होता। वॉल्यूम ओवरले माउंट अलग-थलग स्नैपशॉट होते हैं जो आपके काम समाप्त होने पर गायब हो जाते हैं। चाहे आप लिनक्स सर्वर पर हों या मैकबुक पर, एक ही CLI और एक ही व्यवहार।

## त्वरित आरंभ

### सिस्टम आवश्यकताएँ

- **लिनक्स** KVM समर्थन के साथ
- **macOS** Apple Silicon पर

### स्थापित करें

पूर्ण स्थापना विवरण के लिए [`docs/install.md`](https://github.com/jingkaihe/matchlock/blob/main/docs/install.md) देखें।

**त्वरित स्थापना**

नीचे दिया गया स्क्रिप्ट OS का पता लगाता है, और macOS पर Homebrew का उपयोग करके matchlock स्थापित करता है, और Debian/RHEL स्वाद वाले Linux वितरणों पर rpm/deb का उपयोग करता है।

```bash
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 दोनों पर समर्थित है:

```bash
brew tap jingkaihe/essentials
brew install matchlock
```

**Debian / Ubuntu (.deb)**

```bash
sudo dpkg -i ./matchlock_<version>_linux_amd64.deb
sudo apt-get install -f
matchlock diagnose
```

**Fedora / RHEL / CentOS Stream (.rpm)**

```bash
sudo dnf install ./matchlock_<version>_linux_amd64.rpm
matchlock diagnose
```

यदि `matchlock diagnose` होस्ट सेटअप गायब होने की रिपोर्ट करता है, तो चलाएँ:

```bash
sudo matchlock setup linux
```

किसी विशिष्ट उपयोगकर्ता को स्पष्ट रूप से नामांकित करने के लिए, चलाएँ:

```bash
sudo matchlock setup user <name>
```

### उपयोग

```bash
# 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 .

# Pre-build rootfs from registry image (caches for faster startup)
matchlock build 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
```

## SDK

मैचलॉक आपके एप्लिकेशन में सीधे सैंडबॉक्स एम्बेड करने के लिए Go, Python और TypeScript SDK प्रदान करता है। आप VMs लॉन्च कर सकते हैं, कमांड निष्पादित कर सकते हैं, आउटपुट स्ट्रीम कर सकते हैं, और प्रोग्रामेटिक रूप से फ़ाइलों का प्रबंधन कर सकते हैं।

**Go**

```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 में निजी-IP व्यवहार (`10/8`, `172.16/12`, `192.168/16`):

- डिफ़ॉल्ट (अनसेट): जब भी कोई नेटवर्क कॉन्फ़िग भेजा जाता है तब निजी IP ब्लॉक हो जाते हैं।
- स्पष्ट ब्लॉक: `.WithBlockPrivateIPs(true)` (या `.BlockPrivateIPs()`) कॉल करें।
- स्पष्ट अनुमति: `.AllowPrivateIPs()` या `.WithBlockPrivateIPs(false)` कॉल करें।

```go
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

// SDK network interception (request/response mutation, body shaping, SSE data-line transform)
sandbox = sandbox.WithNetworkInterception(&sdk.NetworkInterceptionConfig{
	Rules: []sdk.NetworkHookRule{
		{
			Phase:      sdk.NetworkHookPhaseBefore,
			Action:     sdk.NetworkHookActionMutate,
			Hosts:      []string{"api.openai.com"},
			SetHeaders: map[string]string{"X-Trace-Id": "trace-123"},
		},
		{
			Phase:  sdk.NetworkHookPhaseAfter,
			Action: sdk.NetworkHookActionMutate,
			Hosts:  []string{"api.openai.com"},
			BodyReplacements: []sdk.NetworkBodyTransform{
				{Find: "internal-id", Replace: "redacted"},
			},
		},
	},
})
```

यदि आप बिल्डर के बिना सीधे `client.Create(...)` का उपयोग करते हैं, तो सेट करें:
- `BlockPrivateIPsSet: true`
- `BlockPrivateIPs: false` (या `true`)

पूरी तरह से ऑफ़लाइन सैंडबॉक्स (कोई गेस्ट NIC / कोई ईग्रेस नहीं) के लिए, उपयोग करें:
- CLI: `--no-network`
- Go SDK बिल्डर: `.WithNoNetwork()`
- Python SDK बिल्डर: `.with_no_network()`
- TypeScript SDK बिल्डर: `.withNoNetwork()`

**Python** ([PyPI](https://pypi.org/project/matchlock/))

```bash
pip install matchlock
# or
uv add matchlock
```

```python
import os
import sys

from matchlock import Client, Sandbox

sandbox = (
    Sandbox("python:3.12-alpine")
    .allow_host(
        "dl-cdn.alpinelinux.org",
        "files.pythonhosted.org", "pypi.org",
        "astral.sh", "github.com", "objects.githubusercontent.com",
        "api.anthropic.com",
    )
    .add_secret(
        "ANTHROPIC_API_KEY", os.environ["ANTHROPIC_API_KEY"], "api.anthropic.com"
    )
)

SCRIPT = """\
# /// script
# requires-python = ">=3.12"
# dependencies = ["anthropic"]
# ///
import anthropic, os

client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
with client.messages.stream(
    model="claude-haiku-4-5-20251001",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain TCP/IP."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
print()
"""

with Client() as client:
    client.launch(sandbox)
    client.exec("pip install --quiet uv")
    client.write_file("/workspace/ask.py", SCRIPT)
    client.exec_stream("uv run /workspace/ask.py", stdout=sys.stdout, stderr=sys.stderr)

client.remove()
```

**TypeScript**

```bash
npm install matchlock-sdk
```

```ts
import { Client, Sandbox } from "matchlock-sdk";

const SCRIPT = `import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const stream = anthropic.messages
  .stream({
    model: "claude-haiku-4-5-20251001",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Explain TCP/IP." }],
  })
  .on("text", (text) => {
    process.stdout.write(text);
  });

await stream.finalMessage();
process.stdout.write("\\n");
`;

const client = new Client();
try {
  const sandbox = new Sandbox("node:22-alpine")
    .allowHost("registry.npmjs.org", "*.npmjs.org", "api.anthropic.com")
    .addSecret("ANTHROPIC_API_KEY", process.env.ANTHROPIC_API_KEY ?? "", "api.anthropic.com");

  await client.launch(sandbox);
  await client.exec(
    "npm init -y >/dev/null 2>&1 && npm install --quiet --no-bin-links @anthropic-ai/sdk",
    { workingDir: "/workspace" },
  );
  await client.writeFile("/workspace/ask.mjs", SCRIPT);
  await client.execStream("node ask.mjs", {
    workingDir: "/workspace",
    stdout: process.stdout,
    stderr: process.stderr,
  });
} finally {
  await client.close();
  await client.remove();
}
```

[`examples/`](https://github.com/jingkaihe/matchlock/blob/main/examples) निर्देशिका में और उदाहरण:

| विवरण | उदाहरण |
|---|---|
| गुप्त इंजेक्शन के साथ Anthropic API प्रतिक्रिया स्ट्रीम करता है (Go) | [`examples/go/basic/`](https://github.com/jingkaihe/matchlock/blob/main/examples/go/basic) |
| ExecInteractive का उपयोग करके PTY के साथ इंटरैक्टिव टर्मिनल (Go) | [`examples/go/exec_modes/`](https://github.com/jingkaihe/matchlock/blob/main/examples/go/exec_modes) |
| नेटवर्क इंटरसेप्शन हुक के माध्यम से API कुंजी इंजेक्ट करता है (Go) | [`examples/go/network_interception/`](https://github.com/jingkaihe/matchlock/blob/main/examples/go/network_interception) |
| फ़ाइल संचालन म्यूटेशन के लिए VFS इंटरसेप्शन हुक (Go) | [`examples/go/vfs_hooks/`](https://github.com/jingkaihe/matchlock/blob/main/examples/go/vfs_hooks) |
| Anthropic API प्रतिक्रिया स्ट्रीम करता है (Python) | [`examples/python/basic/`](https://github.com/jingkaihe/matchlock/blob/main/examples/python/basic) |
| स्ट्रीम, पाइप और इंटरैक्टिव निष्पादन मोड (Python) | [`examples/python/exec_modes/`](https://github.com/jingkaihe/matchlock/blob/main/examples/python/exec_modes) |
| नेटवर्क इंटरसेप्शन हुक के माध्यम से API कुंजी इंजेक्ट करता है (Python) | [`examples/python/network_interception/`](https://github.com/jingkaihe/matchlock/blob/main/examples/python/network_interception) |
| फ़ाइल संचालन म्यूटेशन के लिए VFS इंटरसेप्शन हुक (Python) | [`examples/python/vfs_hooks/`](https://github.com/jingkaihe/matchlock/blob/main/examples/python/vfs_hooks) |
| Anthropic API प्रतिक्रिया स्ट्रीम करता है (TypeScript) | [`examples/typescript/basic/`](https://github.com/jingkaihe/matchlock/blob/main/examples/typescript/basic) |
| स्ट्रीम, पाइप और इंटरैक्टिव निष्पादन मोड (TypeScript) | [`examples/typescript/exec_modes/`](https://github.com/jingkaihe/matchlock/blob/main/examples/typescript/exec_modes) |
| नेटवर्क इंटरसेप्शन हुक के माध्यम से API कुंजी इंजेक्ट करता है (TypeScript) | [`examples/typescript/network_interception/`](https://github.com/jingkaihe/matchlock/blob/main/examples/typescript/network_interception) |
| GitHub बूटस्ट्रैप के साथ माइक्रो-VM में Claude Code CLI | [`examples/claude-code/`](https://github.com/jingkaihe/matchlock/blob/main/examples/claude-code) |
| SDK के माध्यम से सैंडबॉक्स के अंदर Docker के साथ Claude Code | [`examples/claude-code-with-docker/`](https://github.com/jingkaihe/matchlock/blob/main/examples/claude-code-with-docker) |
| सैंडबॉक्स में Claude Pro/Max सब्सक्रिप्शन के साथ Claude Code | [`examples/claude-danger/`](https://github.com/jingkaihe/matchlock/blob/main/examples/claude-danger) |
| GitHub बूटस्ट्रैप के साथ माइक्रो-VM में OpenAI Codex CLI | [`examples/codex/`](https://github.com/jingkaihe/matchlock/blob/main/examples/codex) |
| systemd के साथ सैंडबॉक्स के अंदर Docker डेमन | [`examples/docker-in-sandbox/`](https://github.com/jingkaihe/matchlock/blob/main/examples/docker-in-sandbox) |
| एजेंट क्लाइंट प्रोटोकॉल का उपयोग करके Streamlit चैटबॉट | [`examples/agent-client-protocol/`](https://github.com/jingkaihe/matchlock/blob/main/examples/agent-client-protocol) |
| Kodelet और Playwright MCP के साथ ब्राउज़र ऑटोमेशन | [`examples/playwright/`](https://github.com/jingkaihe/matchlock/blob/main/examples/playwright) |

## आर्किटेक्चर

```mermaid
graph LR
    subgraph Host
        CLI["Matchlock CLI"]
        Policy["Policy Engine"]
        Proxy["Transparent Proxy + TLS MITM"]
        VFS["VFS Server"]

        CLI --> Policy
        CLI --> Proxy
        Policy --> Proxy
    end

    subgraph VM["Micro-VM (Firecracker / Virtualization.framework)"]
        Agent["Guest Agent"]
        FUSE["/workspace (FUSE)"]
        Image["Any OCI Image (Alpine, Ubuntu, etc.)"]

        Agent --- Image
        FUSE --- Image
    end

    Proxy -- "vsock :5000" --> Agent
    VFS -- "vsock :5001" --> FUSE
```

### नेटवर्क मोड

| प्लेटफ़ॉर्म | मोड | तंत्र |
|----------|------|-----------|
| Linux | पारदर्शी प्रॉक्सी | पोर्ट 80/443 पर nftables DNAT |
| macOS | NAT (डिफ़ॉल्ट) | Virtualization.framework अंतर्निहित NAT |
| macOS | इंटरसेप्शन (`--allow-host`/`--secret` के साथ) | L4 पर gVisor उपयोगकर्ता-स्थान TCP/IP |

## दस्तावेज़

- [लाइफ़साइकल और क्लीनअप रनबुक](https://github.com/jingkaihe/matchlock/blob/main/docs/lifecycle.md)
- [नेटवर्क इंटरसेप्शन](https://github.com/jingkaihe/matchlock/blob/main/docs/network-interception.md)
- [VFS इंटरसेप्शन](https://github.com/jingkaihe/matchlock/blob/main/docs/vfs-interception.md)
- [डेवलपर संदर्भ](https://github.com/jingkaihe/matchlock/blob/main/AGENTS.md)

## लाइसेंस

MIT