{"id":44304520,"url":"https://github.com/jingkaihe/matchlock","last_synced_at":"2026-04-02T12:10:54.583Z","repository":{"id":337091559,"uuid":"1150822093","full_name":"jingkaihe/matchlock","owner":"jingkaihe","description":"Matchlock secures AI agent workloads with a Linux-based sandbox.","archived":false,"fork":false,"pushed_at":"2026-03-23T19:07:23.000Z","size":8568,"stargazers_count":532,"open_issues_count":7,"forks_count":26,"subscribers_count":8,"default_branch":"main","last_synced_at":"2026-03-24T05:58:34.774Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jingkaihe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-05T18:22:39.000Z","updated_at":"2026-03-23T19:07:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jingkaihe/matchlock","commit_stats":null,"previous_names":["jingkaihe/matchlock"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/jingkaihe/matchlock","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jingkaihe%2Fmatchlock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jingkaihe%2Fmatchlock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jingkaihe%2Fmatchlock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jingkaihe%2Fmatchlock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jingkaihe","download_url":"https://codeload.github.com/jingkaihe/matchlock/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jingkaihe%2Fmatchlock/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31305973,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T09:48:21.550Z","status":"ssl_error","status_checked_at":"2026-04-02T09:48:19.196Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-11T03:00:36.261Z","updated_at":"2026-04-02T12:10:54.576Z","avatar_url":"https://github.com/jingkaihe.png","language":"Go","readme":"# Matchlock\n\n\u003e **Experimental:** This project is still in active development and subject to breaking changes.\n\nMatchlock is a CLI tool for running AI agents in ephemeral microVMs - with network allowlisting, secret injection via MITM proxy, and VM-level isolation. Your secrets never enter the VM.\n\n## Why Matchlock?\n\nAI agents need to run code, but giving them unrestricted access to your machine is a risk. Matchlock lets you hand an agent a full Linux environment that boots in under a second - isolated and disposable.\n\nWhen you pass `--allow-host` or `--secret`, Matchlock seals the network - only traffic to explicitly allowed hosts gets through, and everything else is blocked. When your agent calls an API the real credentials are injected in-flight by the host. The sandbox only ever sees a placeholder. Even if the agent is tricked into running something malicious your keys don't leak and there's nowhere for data to go. Inside the agent gets a full Linux environment to do whatever it needs. It can install packages and write files and make a mess. Outside your machine doesn't feel a thing. Volume overlay mounts are isolated snapshots that vanish when you're done. Same CLI and same behaviour whether you're on a Linux server or a MacBook.\n\n## Quick Start\n\n### System Requirements\n\n- **Linux** with KVM support\n- **macOS** on Apple Silicon\n\n### Install\n\nSee [`docs/install.md`](./docs/install.md) for full installation details.\n\n**Quick Installation**\n\nThe script below detect OS, and install matchlock using Homebrew on Macos, and rpm/deb on Debian/RHEL flavourd Linux Distros\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/jingkaihe/matchlock/main/scripts/install.sh | bash\n\n# Or install a specific release\ncurl -fsSL https://raw.githubusercontent.com/jingkaihe/matchlock/main/scripts/install.sh | bash -s -- --version 0.2.4\n```\n\n**Homebrew**\n\nHomebrew based installation is supported on both macOS and Linux:\n\n```bash\nbrew tap jingkaihe/essentials\nbrew install matchlock\n```\n\n**Debian / Ubuntu (.deb)**\n\n```bash\nsudo dpkg -i ./matchlock_\u003cversion\u003e_linux_amd64.deb\nsudo apt-get install -f\nmatchlock diagnose\n```\n\n**Fedora / RHEL / CentOS Stream (.rpm)**\n\n```bash\nsudo dnf install ./matchlock_\u003cversion\u003e_linux_amd64.rpm\nmatchlock diagnose\n```\n\nIf `matchlock diagnose` reports missing host setup, run:\n\n```bash\nsudo matchlock setup linux\n```\n\nTo enroll a specific user explicitly, run:\n\n```bash\nsudo matchlock setup user \u003cname\u003e\n```\n\n### Usage\n\n```bash\n# Basic\nmatchlock run --image alpine:latest cat /etc/os-release\nmatchlock run --image alpine:latest -it sh\nmatchlock run --image alpine:latest --no-network -- sh -lc 'echo offline'\n\n# Network allowlist\nmatchlock run --image python:3.12-alpine \\\n  --allow-host \"api.openai.com\" python agent.py\n\n# Keep interception enabled even with an empty allowlist,\n# so hosts can be added/removed at runtime.\nmatchlock run --image alpine:latest --rm=false --network-intercept\nmatchlock allow-list add \u003cvm-id\u003e api.openai.com,api.anthropic.com\nmatchlock allow-list delete \u003cvm-id\u003e api.openai.com\n\n# Secret injection (never enters the VM)\nexport ANTHROPIC_API_KEY=sk-xxx\nmatchlock run --image python:3.12-alpine \\\n  --secret ANTHROPIC_API_KEY@api.anthropic.com python call_api.py\n\n# Long-lived sandboxes\nmatchlock run --image alpine:latest --rm=false   # prints VM ID\nmatchlock run --image nginx:latest -d             # same as above, detached\nmatchlock exec vm-abc12345 -it sh                # attach to it\nmatchlock port-forward vm-abc12345 8080:8080     # forward host:8080 -\u003e guest:8080\n\n# Publish ports at startup\nmatchlock run --image alpine:latest --rm=false -p 8080:8080\n\n# Lifecycle\nmatchlock list | kill | rm | prune\n\n# Build from Dockerfile (uses BuildKit-in-VM)\nmatchlock build -f Dockerfile -t myapp:latest .\n\n# Pre-build rootfs from registry image (caches for faster startup)\nmatchlock build alpine:latest\n\n# Image management\nmatchlock image ls                                           # List all images\nmatchlock image rm myapp:latest                              # Remove a local image\ndocker save myapp:latest | matchlock image import myapp:latest  # Import from tarball\n```\n\n## SDK\n\nMatchlock ships Go, Python, and TypeScript SDKs for embedding sandboxes directly in your application. You can launch VMs, execute commands, stream output, and manage files programmatically.\n\n**Go**\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"os\"\n\n\t\"github.com/jingkaihe/matchlock/pkg/sdk\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := sdk.NewClient(sdk.DefaultConfig())\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer client.Close(0)\n\tdefer client.Remove()\n\n\tsandbox := sdk.New(\"alpine:latest\").\n\t\tAllowHost(\"dl-cdn.alpinelinux.org\", \"api.anthropic.com\").\n\t\tAddSecret(\"ANTHROPIC_API_KEY\", os.Getenv(\"ANTHROPIC_API_KEY\"), \"api.anthropic.com\")\n\tif _, err := client.Launch(sandbox); err != nil {\n\t\tpanic(err)\n\t}\n\tif _, err := client.Exec(ctx, \"apk add --no-cache curl\"); err != nil {\n\t\tpanic(err)\n\t}\n\t// The VM only ever sees a placeholder - the real key never enters the sandbox\n\tresult, err := client.Exec(ctx, \"echo $ANTHROPIC_API_KEY\")\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tfmt.Print(result.Stdout) // prints \"SANDBOX_SECRET_a1b2c3d4...\"\n\n\tcurlCmd := `curl -s --no-buffer https://api.anthropic.com/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -H \"x-api-key: $ANTHROPIC_API_KEY\" \\\n  -H \"anthropic-version: 2023-06-01\" \\\n  -d '{\"model\":\"claude-haiku-4-5-20251001\",\"max_tokens\":1024,\"stream\":true,\n       \"messages\":[{\"role\":\"user\",\"content\":\"Explain TCP to me\"}]}'`\n\tif _, err := client.ExecStream(ctx, curlCmd, os.Stdout, os.Stderr); err != nil {\n\t\tpanic(err)\n\t}\n}\n```\n\nGo SDK private-IP behavior (`10/8`, `172.16/12`, `192.168/16`):\n\n- Default (unset): private IPs are blocked whenever a network config is sent.\n- Explicit block: call `.WithBlockPrivateIPs(true)` (or `.BlockPrivateIPs()`).\n- Explicit allow: call `.AllowPrivateIPs()` or `.WithBlockPrivateIPs(false)`.\n\n```go\nsandbox := sdk.New(\"alpine:latest\").\n\tAllowHost(\"api.openai.com\").\n\tAddHost(\"api.internal\", \"10.0.0.10\").\n\tWithNetworkMTU(1200).\n\tAllowPrivateIPs() // explicit override: block_private_ips=false\n\n// SDK network interception (request/response mutation, body shaping, SSE data-line transform)\nsandbox = sandbox.WithNetworkInterception(\u0026sdk.NetworkInterceptionConfig{\n\tRules: []sdk.NetworkHookRule{\n\t\t{\n\t\t\tPhase:      sdk.NetworkHookPhaseBefore,\n\t\t\tAction:     sdk.NetworkHookActionMutate,\n\t\t\tHosts:      []string{\"api.openai.com\"},\n\t\t\tSetHeaders: map[string]string{\"X-Trace-Id\": \"trace-123\"},\n\t\t},\n\t\t{\n\t\t\tPhase:  sdk.NetworkHookPhaseAfter,\n\t\t\tAction: sdk.NetworkHookActionMutate,\n\t\t\tHosts:  []string{\"api.openai.com\"},\n\t\t\tBodyReplacements: []sdk.NetworkBodyTransform{\n\t\t\t\t{Find: \"internal-id\", Replace: \"redacted\"},\n\t\t\t},\n\t\t},\n\t},\n})\n```\n\nIf you use `client.Create(...)` directly (without the builder), set:\n- `BlockPrivateIPsSet: true`\n- `BlockPrivateIPs: false` (or `true`)\n\nFor fully offline sandboxes (no guest NIC / no egress), use:\n- CLI: `--no-network`\n- Go SDK builder: `.WithNoNetwork()`\n- Python SDK builder: `.with_no_network()`\n- TypeScript SDK builder: `.withNoNetwork()`\n\n**Python** ([PyPI](https://pypi.org/project/matchlock/))\n\n```bash\npip install matchlock\n# or\nuv add matchlock\n```\n\n```python\nimport os\nimport sys\n\nfrom matchlock import Client, Sandbox\n\nsandbox = (\n    Sandbox(\"python:3.12-alpine\")\n    .allow_host(\n        \"dl-cdn.alpinelinux.org\",\n        \"files.pythonhosted.org\", \"pypi.org\",\n        \"astral.sh\", \"github.com\", \"objects.githubusercontent.com\",\n        \"api.anthropic.com\",\n    )\n    .add_secret(\n        \"ANTHROPIC_API_KEY\", os.environ[\"ANTHROPIC_API_KEY\"], \"api.anthropic.com\"\n    )\n)\n\nSCRIPT = \"\"\"\\\n# /// script\n# requires-python = \"\u003e=3.12\"\n# dependencies = [\"anthropic\"]\n# ///\nimport anthropic, os\n\nclient = anthropic.Anthropic(api_key=os.environ[\"ANTHROPIC_API_KEY\"])\nwith client.messages.stream(\n    model=\"claude-haiku-4-5-20251001\",\n    max_tokens=1024,\n    messages=[{\"role\": \"user\", \"content\": \"Explain TCP/IP.\"}],\n) as stream:\n    for text in stream.text_stream:\n        print(text, end=\"\", flush=True)\nprint()\n\"\"\"\n\nwith Client() as client:\n    client.launch(sandbox)\n    client.exec(\"pip install --quiet uv\")\n    client.write_file(\"/workspace/ask.py\", SCRIPT)\n    client.exec_stream(\"uv run /workspace/ask.py\", stdout=sys.stdout, stderr=sys.stderr)\n\nclient.remove()\n```\n\n**TypeScript**\n\n```bash\nnpm install matchlock-sdk\n```\n\n```ts\nimport { Client, Sandbox } from \"matchlock-sdk\";\n\nconst SCRIPT = `import Anthropic from \"@anthropic-ai/sdk\";\n\nconst anthropic = new Anthropic({\n  apiKey: process.env.ANTHROPIC_API_KEY,\n});\n\nconst stream = anthropic.messages\n  .stream({\n    model: \"claude-haiku-4-5-20251001\",\n    max_tokens: 1024,\n    messages: [{ role: \"user\", content: \"Explain TCP/IP.\" }],\n  })\n  .on(\"text\", (text) =\u003e {\n    process.stdout.write(text);\n  });\n\nawait stream.finalMessage();\nprocess.stdout.write(\"\\\\n\");\n`;\n\nconst client = new Client();\ntry {\n  const sandbox = new Sandbox(\"node:22-alpine\")\n    .allowHost(\"registry.npmjs.org\", \"*.npmjs.org\", \"api.anthropic.com\")\n    .addSecret(\"ANTHROPIC_API_KEY\", process.env.ANTHROPIC_API_KEY ?? \"\", \"api.anthropic.com\");\n\n  await client.launch(sandbox);\n  await client.exec(\n    \"npm init -y \u003e/dev/null 2\u003e\u00261 \u0026\u0026 npm install --quiet --no-bin-links @anthropic-ai/sdk\",\n    { workingDir: \"/workspace\" },\n  );\n  await client.writeFile(\"/workspace/ask.mjs\", SCRIPT);\n  await client.execStream(\"node ask.mjs\", {\n    workingDir: \"/workspace\",\n    stdout: process.stdout,\n    stderr: process.stderr,\n  });\n} finally {\n  await client.close();\n  await client.remove();\n}\n```\n\nMore examples in the [`examples/`](examples/) directory:\n\n| Description | Example |\n|---|---|\n| Streams Anthropic API response with secret injection (Go) | [`examples/go/basic/`](examples/go/basic/) |\n| Interactive terminal with PTY using ExecInteractive (Go) | [`examples/go/exec_modes/`](examples/go/exec_modes/) |\n| Injects API key via network interception hook (Go) | [`examples/go/network_interception/`](examples/go/network_interception/) |\n| VFS interception hooks for file operation mutations (Go) | [`examples/go/vfs_hooks/`](examples/go/vfs_hooks/) |\n| Streams Anthropic API response (Python) | [`examples/python/basic/`](examples/python/basic/) |\n| Stream, pipe, and interactive execution modes (Python) | [`examples/python/exec_modes/`](examples/python/exec_modes/) |\n| Injects API key via network interception hook (Python) | [`examples/python/network_interception/`](examples/python/network_interception/) |\n| VFS interception hooks for file operation mutations (Python) | [`examples/python/vfs_hooks/`](examples/python/vfs_hooks/) |\n| Streams Anthropic API response (TypeScript) | [`examples/typescript/basic/`](examples/typescript/basic/) |\n| Stream, pipe, and interactive execution modes (TypeScript) | [`examples/typescript/exec_modes/`](examples/typescript/exec_modes/) |\n| Injects API key via network interception hook (TypeScript) | [`examples/typescript/network_interception/`](examples/typescript/network_interception/) |\n| Claude Code CLI in micro-VM with GitHub bootstrap | [`examples/claude-code/`](examples/claude-code/) |\n| Claude Code with Docker inside sandbox via SDK | [`examples/claude-code-with-docker/`](examples/claude-code-with-docker/) |\n| OpenAI Codex CLI in micro-VM with GitHub bootstrap | [`examples/codex/`](examples/codex/) |\n| Docker daemon inside sandbox with systemd | [`examples/docker-in-sandbox/`](examples/docker-in-sandbox/) |\n| Streamlit chatbot using Agent Client Protocol | [`examples/agent-client-protocol/`](examples/agent-client-protocol/) |\n| Browser automation with Kodelet and Playwright MCP | [`examples/playwright/`](examples/playwright/) |\n\n## Architecture\n\n```mermaid\ngraph LR\n    subgraph Host\n        CLI[\"Matchlock CLI\"]\n        Policy[\"Policy Engine\"]\n        Proxy[\"Transparent Proxy + TLS MITM\"]\n        VFS[\"VFS Server\"]\n\n        CLI --\u003e Policy\n        CLI --\u003e Proxy\n        Policy --\u003e Proxy\n    end\n\n    subgraph VM[\"Micro-VM (Firecracker / Virtualization.framework)\"]\n        Agent[\"Guest Agent\"]\n        FUSE[\"/workspace (FUSE)\"]\n        Image[\"Any OCI Image (Alpine, Ubuntu, etc.)\"]\n\n        Agent --- Image\n        FUSE --- Image\n    end\n\n    Proxy -- \"vsock :5000\" --\u003e Agent\n    VFS -- \"vsock :5001\" --\u003e FUSE\n```\n\n### Network Modes\n\n| Platform | Mode | Mechanism |\n|----------|------|-----------|\n| Linux | Transparent proxy | nftables DNAT on ports 80/443 |\n| macOS | NAT (default) | Virtualization.framework built-in NAT |\n| macOS | Interception (with `--allow-host`/`--secret`) | gVisor userspace TCP/IP at L4 |\n\n## Docs\n\n- [Lifecycle and Cleanup Runbook](docs/lifecycle.md)\n- [Network Interception](docs/network-interception.md)\n- [VFS Interception](docs/vfs-interception.md)\n- [Developer Reference](AGENTS.md)\n\n## License\n\nMIT\n","funding_links":[],"categories":["Go","Host-level sandboxes and local workspace isolation","Sandboxing \u0026 Isolation"],"sub_categories":["Linux"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjingkaihe%2Fmatchlock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjingkaihe%2Fmatchlock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjingkaihe%2Fmatchlock/lists"}