### Install and Run Example

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/typescript/exec_modes/README.md

Navigate to the example directory, install dependencies, and run the TypeScript script.

```bash
cd examples/typescript/exec_modes
npm install
npm run start
```

--------------------------------

### Run the Go SDK Interactive Terminal Example

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/go/exec_modes/README.md

Execute the example from the repository root to start the interactive shell.

```bash
go run ./examples/go/exec_modes
```

--------------------------------

### Running the TypeScript Basic Example

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/typescript/basic/README.md

Instructions for setting up and running the basic TypeScript example from the repository root. This includes setting the API key, navigating to the example directory, installing dependencies, and executing the script.

```bash
export ANTHROPIC_API_KEY=sk-ant-...
cd examples/typescript/basic
npm install
npm run start
```

--------------------------------

### Quick Start: Launch Sandbox and Execute Command

Source: https://github.com/jingkaihe/matchlock/blob/main/sdk/python/README.md

A basic example demonstrating how to launch a Python sandbox and execute a simple command.

```python
from matchlock import Client, Sandbox

sandbox = Sandbox("python:3.12-alpine")

with Client() as client:
    client.launch(sandbox)

    result = client.exec("echo hello from the sandbox")
    print(result.stdout)  # "hello from the sandbox\n"
```

--------------------------------

### Setup Linux Host

Source: https://github.com/jingkaihe/matchlock/blob/main/docs/install.md

Run this command on Linux if the host still needs administrative setup after installation.

```bash
sudo matchlock setup linux
```

--------------------------------

### Run with Editable Install and Custom Binary

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/python/port_forward/README.md

Run the port-forwarding example with an editable install of the Python SDK and specify a custom Matchlock binary path.

```bash
MATCHLOCK_BIN=./bin/matchlock uv run --with-editable ./sdk/python examples/python/port_forward/main.py
```

--------------------------------

### Install and Run Network Interception Example

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/typescript/network_interception/README.md

Install dependencies and run the TypeScript network interception example. Ensure the ANTHROPIC_API_KEY environment variable is set.

```bash
export ANTHROPIC_API_KEY=sk-ant-...
cd examples/typescript/network_interception
npm install
npm run start
```

--------------------------------

### Quick Install Script

Source: https://github.com/jingkaihe/matchlock/blob/main/docs/install.md

Use the installer script to quickly install Matchlock. This script automatically detects the OS and architecture.

```bash
curl -fsSL https://raw.githubusercontent.com/jingkaihe/matchlock/main/scripts/install.sh | bash
```

--------------------------------

### Run Port-Forward Example

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/python/port_forward/README.md

Execute the Python port-forwarding example script from the repository root.

```bash
uv run examples/python/port_forward/main.py
```

--------------------------------

### Build Example Image with Docker

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/codex/README.md

Build the example image using Docker and import it into Matchlock. This is an alternative to building with Matchlock directly.

```bash
docker build -t codex:latest examples/codex
docker save codex:latest | matchlock image import codex:latest
```

--------------------------------

### Build Example Image with Matchlock

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/codex/README.md

Build the example image using Matchlock. This method allows for specifying build cache size.

```bash
matchlock build -t codex:latest --build-cache-size 30000 examples/codex
```

--------------------------------

### Install Matchlock Python SDK

Source: https://github.com/jingkaihe/matchlock/blob/main/README.md

Installs the Matchlock Python SDK using pip or uv.

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

--------------------------------

### Install Matchlock Python SDK from Source

Source: https://github.com/jingkaihe/matchlock/blob/main/sdk/python/README.md

Install the Matchlock Python SDK from its source directory using pip.

```bash
pip install -e sdk/python
```

--------------------------------

### Install Matchlock SDK

Source: https://github.com/jingkaihe/matchlock/blob/main/sdk/typescript/README.md

Install the Matchlock SDK using npm. Ensure Node.js 22+ and the matchlock CLI are installed.

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

--------------------------------

### Install Locally via Script

Source: https://github.com/jingkaihe/matchlock/blob/main/docs/install.md

If the repository is checked out locally, you can run the install script directly.

```bash
./scripts/install.sh
```

--------------------------------

### Run the Python Exec Modes Example

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/python/exec_modes/README.md

Execute the main script for the Python SDK exec modes example from the repository root.

```bash
uv run examples/python/exec_modes/main.py
```

--------------------------------

### Run Example Script with Optional Flags

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/claude-code-with-docker/README.md

Runs the example script with optional resource allocation flags for CPUs and memory, and specifies a custom Docker image.

```bash
uv run examples/claude-code-with-docker/main.py \
  --cpus 4 --memory 8192 --image claude-code-with-docker:latest
```

--------------------------------

### Debian/Ubuntu Installation

Source: https://github.com/jingkaihe/matchlock/blob/main/README.md

Installs Matchlock on Debian/Ubuntu systems using a .deb package. Includes steps to install dependencies and diagnose setup.

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

--------------------------------

### Install Matchlock Python SDK

Source: https://github.com/jingkaihe/matchlock/blob/main/sdk/python/README.md

Install the Matchlock Python SDK using pip.

```bash
pip install matchlock
```

--------------------------------

### Diagnose Installation

Source: https://github.com/jingkaihe/matchlock/blob/main/docs/install.md

Verify the Matchlock installation on the host.

```bash
matchlock diagnose
```

--------------------------------

### Run Example Script

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/claude-code-with-docker/README.md

Executes the main Python script for the Claude Code with Docker example from the repository root.

```bash
uv run examples/claude-code-with-docker/main.py
```

--------------------------------

### Run Codex Example (Default)

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/codex/README.md

Run the Codex example using the helper script. It defaults to using 'matchlock' from PATH. The repository slug is resolved from the local git remote.

```bash
./examples/codex/matchlock-codex run
```

--------------------------------

### Install Debian/Ubuntu Package

Source: https://github.com/jingkaihe/matchlock/blob/main/docs/install.md

Download the .deb release asset from GitHub Releases and install it using dpkg. For arm64, use the linux_arm64.deb asset.

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

--------------------------------

### Basic Usage Examples

Source: https://github.com/jingkaihe/matchlock/blob/main/README.md

Demonstrates basic Matchlock commands for running processes in containers, interactive shells, and with network restrictions.

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

--------------------------------

### Publish Ports at Startup

Source: https://github.com/jingkaihe/matchlock/blob/main/README.md

Starts a long-lived sandbox and publishes a port from the guest to the host at startup.

```bash
# Publish ports at startup
matchlock run --image alpine:latest --rm=false -p 8080:8080
```

--------------------------------

### Run Claude Code Example

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/claude-code/README.md

Execute the Claude Code example within the Matchlock sandbox. The helper uses 'matchlock' from PATH by default.

```bash
./examples/claude-code/matchlock-claude run
```

--------------------------------

### Build Example Image with Docker

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/claude-code/README.md

Build the 'claude-code' Docker image and import it into Matchlock.

```bash
docker build -t claude-code:latest examples/claude-code
docker save claude-code:latest | matchlock image import claude-code:latest
```

--------------------------------

### Install Specific Release via Script

Source: https://github.com/jingkaihe/matchlock/blob/main/docs/install.md

Install a specific version of Matchlock using the installer script with the --version flag.

```bash
curl -fsSL https://raw.githubusercontent.com/jingkaihe/matchlock/main/scripts/install.sh | bash -s -- --version 0.2.4
```

--------------------------------

### Install Local Tooling with Mise

Source: https://github.com/jingkaihe/matchlock/blob/main/AGENTS.md

One-time command to install local development tools using Mise.

```bash
mise install
```

--------------------------------

### Start VM and Mutate Allow-List (CLI)

Source: https://github.com/jingkaihe/matchlock/blob/main/docs/network-interception.md

Use the Matchlock CLI to start a long-lived VM with network interception enabled and to dynamically add or remove hosts from its runtime allow-list.

```bash
# Start a long-lived VM with interception enabled.
matchlock run --image alpine:latest --rm=false --network-intercept

# Add or remove hosts at runtime (comma-separated values accepted).
matchlock allow-list add <vm-id> api.openai.com,api.anthropic.com
matchlock allow-list delete <vm-id> api.openai.com
```

--------------------------------

### Start VM and Mutate Allow-List (Go SDK)

Source: https://github.com/jingkaihe/matchlock/blob/main/docs/network-interception.md

Utilize the Matchlock Go SDK to launch a VM with network interception and to programmatically add or remove hosts from its runtime allow-list.

```go
client, _ := sdk.NewClient(sdk.DefaultConfig())
def client.Close(0)
def client.Remove()

vm := sdk.New("alpine:latest").WithNetworkInterception()
_, _ = client.Launch(vm)

ctx := context.Background()
added, _ := client.AllowListAdd(ctx, "api.openai.com", "api.anthropic.com")
removed, _ := client.AllowListDelete(ctx, "api.openai.com")

_ = added
_ = removed
```

--------------------------------

### Run Codex Example with Resource Constraints

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/codex/README.md

Run the Codex example with specified CPU and memory limits. This is useful for controlling resource consumption within the sandbox.

```bash
./examples/codex/matchlock-codex run --cpus 4 --memory 8192
```

--------------------------------

### Fedora/RHEL/CentOS Stream Installation

Source: https://github.com/jingkaihe/matchlock/blob/main/README.md

Installs Matchlock on Fedora, RHEL, or CentOS Stream systems using an .rpm package. Includes a step to diagnose setup.

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

--------------------------------

### Run Claude Danger Example

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/claude-danger/README.md

Executes the Claude Danger example script from the repository root. This script launches Claude Code within a Matchlock sandbox.

```bash
./examples/claude-danger/claude-danger
```

--------------------------------

### Build Docker Image with Docker

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/claude-code-with-docker/README.md

Builds the example Docker image using the 'docker build' command. The image is then saved and imported into Matchlock.

```bash
docker build -t claude-code-with-docker:latest examples/claude-code-with-docker
docker save claude-code-with-docker:latest | matchlock image import claude-code-with-docker:latest
```

--------------------------------

### Setup Specific User

Source: https://github.com/jingkaihe/matchlock/blob/main/docs/install.md

Explicitly enroll a specific local user with Matchlock.

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

--------------------------------

### Run Network Interception Example

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/go/network_interception/README.md

Execute the Go network interception example. Ensure the ANTHROPIC_API_KEY environment variable is set. Optionally, specify the path to the Matchlock binary.

```bash
export ANTHROPIC_API_KEY=sk-ant-...
go run ./examples/go/network_interception
```

--------------------------------

### Example Matchlock CLI Commands for Local Image Management

Source: https://github.com/jingkaihe/matchlock/blob/main/adrs/001-local-image-build.md

These commands demonstrate the intended user experience for building, listing, and running local images with Matchlock.

```bash
matchlock build -f Dockerfile -t myapp:latest .
matchlock image ls
matchlock run --image myapp:latest ...
```

--------------------------------

### Run Codex Example with Specific Repo and Task

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/codex/README.md

Run the Codex example for a specified GitHub repository and implement a specific issue. This allows targeting a particular project and task.

```bash
./examples/codex/matchlock-codex run jingkaihe/matchlock "Implement issue #27 codex example"
```

--------------------------------

### Install Fedora/RHEL/CentOS Stream Package

Source: https://github.com/jingkaihe/matchlock/blob/main/docs/install.md

Download the .rpm release asset from GitHub Releases and install it using dnf. For arm64, use the linux_arm64.rpm asset.

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

--------------------------------

### Install via Homebrew (macOS)

Source: https://github.com/jingkaihe/matchlock/blob/main/docs/install.md

Install Matchlock on macOS using Homebrew. Ensure the Homebrew tap is updated.

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

--------------------------------

### Build Example Image with Matchlock

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/claude-code/README.md

Build the 'claude-code' Docker image using Matchlock, with a specified build cache size.

```bash
matchlock build -t claude-code:latest --build-cache-size 30000 examples/claude-code
```

--------------------------------

### Quick Start: Launch Sandbox and Execute Command

Source: https://github.com/jingkaihe/matchlock/blob/main/sdk/typescript/README.md

Launches a sandbox with specified configurations and executes a command within it. The sandbox is automatically closed in the finally block.

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

const sandbox = new Sandbox("alpine:latest")
  .withCPUs(2)
  .withMemory(1024)
  .allowHost("api.openai.com")
  .withNetworkInterception({
    rules: [
      {
        phase: "after",
        hosts: ["api.openai.com"],
        action: "mutate",
        setResponseHeaders: { "x-intercepted": "true" },
      },
    ],
  })
  .addSecret("API_KEY", process.env.API_KEY ?? "", "api.openai.com");

const client = new Client();

try {
  await client.launch(sandbox);
  const result = await client.exec("echo hello from sandbox");
  console.log(result.stdout);
} finally {
  await client.close();
}
```

--------------------------------

### Run Claude Danger Example with Optional Flags

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/claude-danger/README.md

Runs the Claude Danger example script with custom configurations for CPU, memory, image, credentials, and allowed hosts. This allows for fine-grained control over the sandbox environment.

```bash
./examples/claude-danger/claude-danger \
  --cpus 4 \
  --memory 8192 \
  --image claude-danger:latest \
  --credentials-file ~/.claude/.credentials.json \
  --allowed-host api.anthropic.com \
  --allowed-host platform.claude.com
```

--------------------------------

### Run Codex Example in Privileged Mode

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/codex/README.md

Run the Codex example in privileged mode. This grants the sandbox elevated permissions, which should be used with caution.

```bash
./examples/codex/matchlock-codex run --privileged
```

--------------------------------

### Run Claude Code with Repo and Prompt

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/claude-code/README.md

Run the Claude Code example, specifying a GitHub repository and a prompt for adding tests.

```bash
./examples/claude-code/matchlock-claude run jingkaihe/matchlock "Add tests for JSON-RPC cancel flow"
```

--------------------------------

### Run Codex Example with Custom Command

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/codex/README.md

Run the Codex example with a specific command to fix tests. The command is passed as an argument to the helper script.

```bash
./examples/codex/matchlock-codex run "Fix failing tests in pkg/policy and add coverage"
```

--------------------------------

### Build Docker Image with Matchlock

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/claude-danger/README.md

Builds the Docker image for the Claude Danger example using the Matchlock CLI. This is an alternative to using Docker directly.

```bash
matchlock build -t claude-danger:latest --build-cache-size 30000 examples/claude-danger
```

--------------------------------

### Run Containerized Commands

Source: https://github.com/jingkaihe/matchlock/blob/main/AGENTS.md

Examples of running commands within a specified container image using the matchlock CLI.

```bash
matchlock run --image alpine:latest cat /etc/os-release
matchlock run --image alpine:latest -it sh
matchlock run --image alpine:latest --rm=false
```

--------------------------------

### Launch and Execute Commands in Go Sandbox

Source: https://github.com/jingkaihe/matchlock/blob/main/README.md

Launches an Alpine Linux sandbox, installs curl, and executes a curl command to an external API. Demonstrates setting environment variables and streaming output.

```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)
	}
}
```

--------------------------------

### Run Claude Code with Resource Limits

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/claude-code/README.md

Execute the Claude Code example with specified CPU and memory limits.

```bash
./examples/claude-code/matchlock-claude run --cpus 4 --memory 8192
```

--------------------------------

### Run Python Network Interception Example

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/python/network_interception/README.md

Execute the main Python script for network interception from the repository root.

```bash
uv run examples/python/network_interception/main.py
```

--------------------------------

### Run Claude Code with Specific Prompt

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/claude-code/README.md

Run the Claude Code example with a specific prompt for code review.

```bash
./examples/claude-code/matchlock-claude run "Review pkg/policy for error-handling edge cases"
```

--------------------------------

### Build Project on macOS and Linux

Source: https://github.com/jingkaihe/matchlock/blob/main/AGENTS.md

Builds the project for macOS, producing a codesigned binary. For Linux, it builds the binary and performs a one-time setup.

```bash
macOS (usable, codesigned binary for usage and acceptance tests)
mise run build

# Linux (usable binary + one-time setup)
mise run build && sudo ./bin/matchlock setup linux
```

--------------------------------

### Matchlock Client Lifecycle Management

Source: https://github.com/jingkaihe/matchlock/blob/main/sdk/python/README.md

Manage the lifecycle of Matchlock client and sandboxes, including starting the client, launching a sandbox, executing commands, and shutting down/removing the VM.

```python
from matchlock import Client, Sandbox

client = Client()
client.start()

client.launch(Sandbox("alpine:latest"))
print(client.vm_id)  # e.g., "vm-abc12345"

result = client.exec("echo hello")

# Shut down the sandbox VM
client.close()

# Remove the stopped VM's state directory
client.remove()
```

--------------------------------

### Future Dockerfile Build UX Wrapper

Source: https://github.com/jingkaihe/matchlock/blob/main/adrs/001-local-image-build.md

Conceptual example of a future convenience wrapper command for building Dockerfiles, orchestrating a privileged VM with BuildKit.

```bash
# Equivalent to: boot privileged VM with buildkit, run build, extract result
matchlock build -f Dockerfile -t myapp:latest .
```

--------------------------------

### Build Image with Matchlock

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/playwright/README.md

Build the image using matchlock directly, useful if Docker is not installed. The build cache size can be adjusted to manage disk space.

```bash
# --build-cache-size 30000 so that you can repeatly build reliably without running out of device space
# Otherwise you can omit it, and later on introduce it as matchlock automatically grows the disk
matchlock build -t browser-use:latest --build-cache-size 30000 examples/playwright
```

--------------------------------

### Build Docker Image for Claude Danger

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/claude-danger/README.md

Builds the Docker image for the Claude Danger example using Docker. This image is then imported into Matchlock.

```bash
docker build -t claude-danger:latest examples/claude-danger
docker save claude-danger:latest | matchlock image import claude-danger:latest
```

--------------------------------

### Matchlock SDK Development Workflow

Source: https://github.com/jingkaihe/matchlock/blob/main/sdk/typescript/README.md

Commands for developing the Matchlock TypeScript SDK, including installation, type checking, testing, and building.

```bash
cd sdk/typescript
npm install
npm run typecheck
npm test
npm run build
```

--------------------------------

### Build Docker Image using Matchlock

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/docker-in-sandbox/README.md

Builds a Docker image using Matchlock, suitable when Docker is not installed. Includes an option to set build cache size for reliability.

```bash
# --build-cache-size 30000 so that you can repeatedly build reliably without running out of device space
# Otherwise you can omit it, and later on introduce it as matchlock automatically grows the disk
matchlock build -t docker-in-matchlock:latest --build-cache-size 30000 examples/docker-in-sandbox
```

--------------------------------

### Execute Python Script in Matchlock Sandbox

Source: https://github.com/jingkaihe/matchlock/blob/main/README.md

Launches a Python sandbox, installs dependencies, writes a script to execute an Anthropic API call, and streams the output.

```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()
```

--------------------------------

### Client Methods

Source: https://github.com/jingkaihe/matchlock/blob/main/sdk/python/README.md

The Client class provides methods for interacting with Matchlock sandboxes via JSON-RPC. These methods allow for starting, launching, creating, executing commands, streaming output, managing files, and configuring network ports.

```APIDOC
## Client(config: Config | None = None)

JSON-RPC client for interacting with Matchlock sandboxes. All public methods are thread-safe.

### Methods

- `.start()`: Start the matchlock RPC subprocess.
- `.launch(sandbox)`: Create a VM and start image ENTRYPOINT/CMD in detached mode — returns VM ID.
- `.create(opts)`: Create a VM from `CreateOptions` (does not auto-start ENTRYPOINT unless `launch_entrypoint=True`) — returns VM ID.
- `.exec(command, working_dir="")`: Execute a command, returns `ExecResult`.
- `.exec_stream(command, stdout, stderr, working_dir)`: Stream command output, returns `ExecStreamResult`.
- `.log()`: Return the current buffered VM log as `str`.
- `.log_stream(stdout=None)`: Stream VM log output until cancelled.
- `.exec_pipe(command, stdin=None, stdout=None, stderr=None, working_dir="")`: Bidirectional pipe-mode exec (no PTY), returns `ExecPipeResult`.
- `.exec_interactive(command, stdin=None, stdout=None, working_dir="", rows=24, cols=80, resize=None)`: Interactive PTY exec, returns `ExecInteractiveResult`.
- `.write_file(path, content, mode=0o644)`: Write a file into the sandbox.
- `.read_file(path)`: Read a file from the sandbox — returns `bytes`.
- `.list_files(path)`: List directory contents — returns `list[FileInfo]`.
- `.port_forward(*specs)`: Apply one or more `[LOCAL_PORT:]REMOTE_PORT` mappings.
- `.port_forward_with_addresses(addresses, *specs)`: Apply port mappings bound on specific host addresses.
- `.close(timeout=0)`: Shut down the sandbox VM. `timeout` in seconds; 0 = kill immediately.
- `.remove()`: Remove the stopped VM's state directory.
- `.vm_id`: The current VM ID (property).
```

--------------------------------

### Interactive BuildKit Session with Privileged Mode

Source: https://github.com/jingkaihe/matchlock/blob/main/adrs/001-local-image-build.md

Demonstrates how to run an interactive BuildKit session inside a privileged VM, mounting a local context.

```bash
# Interactive BuildKit session
matchlock run --privileged --image moby/buildkit:rootless \
  -v ./context:/workspace -it sh
# Inside VM: buildctl build --frontend dockerfile.v0 --local context=/workspace ...
```

--------------------------------

### Set Anthropic API Key

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/python/network_interception/README.md

Set the ANTHROPIC_API_KEY environment variable before running the example.

```bash
export ANTHROPIC_API_KEY=sk-ant-...
```

--------------------------------

### Pre-build Rootfs from Registry Image

Source: https://github.com/jingkaihe/matchlock/blob/main/README.md

Pre-builds a rootfs from a registry image to cache it for faster subsequent VM startups.

```bash
# Pre-build rootfs from registry image (caches for faster startup)
matchlock build alpine:latest
```

--------------------------------

### Build Docker Image using Docker

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/docker-in-sandbox/README.md

Builds a Docker image locally and imports it into Matchlock. This is the fastest method if Docker is available.

```bash
docker build -t docker-in-matchlock:latest examples/docker-in-sandbox
docker save docker-in-matchlock:latest | matchlock image import docker-in-matchlock:latest
```

--------------------------------

### Build Matchlock Binary

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/claude-code/README.md

Build the local Matchlock binary. Ensure 'matchlock' is in your PATH or set MATCHLOCK_BIN.

```bash
mise run build
```

--------------------------------

### Custom Matchlock Client Configuration

Source: https://github.com/jingkaihe/matchlock/blob/main/sdk/python/README.md

Initialize the Matchlock client with custom configuration, such as specifying the binary path and enabling sudo usage. The binary path can also be set via environment variable.

```python
from matchlock import Client, Config

config = Config(
    binary_path="/usr/local/bin/matchlock",
    use_sudo=True,  # Required for TAP devices on Linux
)

with Client(config) as client:
    ...
```

--------------------------------

### Long-lived Sandboxes

Source: https://github.com/jingkaihe/matchlock/blob/main/README.md

Manages long-lived microVM sandboxes. Shows how to start, detach, attach to, and forward ports for persistent VMs.

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

--------------------------------

### Build and Import Matchlock Image

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/agent-client-protocol/README.md

Builds a Docker image for the agent and imports it into matchlock. Alternatively, matchlock can build the image directly.

```bash
docker build -t acp:latest examples/agent-client-protocol
docker save acp:latest | matchlock image import acp:latest
```

```bash
matchlock build -t acp:latest examples/agent-client-protocol
```

--------------------------------

### Builder API: Configure Sandbox Options

Source: https://github.com/jingkaihe/matchlock/blob/main/sdk/python/README.md

Demonstrates the fluent builder API for configuring various sandbox parameters like CPUs, memory, disk size, timeouts, network access, and secrets.

```python
import os
from matchlock import Client, Sandbox

sandbox = (
    Sandbox("python:3.12-alpine")
    .with_privileged()
    .with_cpus(2)
    .with_memory(512)
    .with_disk_size(2048)
    .with_timeout(300)
    .with_workspace("/home/user/code")
    .allow_host("api.openai.com", "pypi.org")
    .with_port_forward(18080, 8080)
    .with_port_forward_addresses("127.0.0.1")
    .with_network_mtu(1200)
    .block_private_ips()
    .add_secret("API_KEY", os.environ["API_KEY"], "api.openai.com")
)

with Client() as client:
    vm_id = client.launch(sandbox)
    result = client.exec("python3 -c 'print(1+1)'")
    print(result.exit_code)  # 0
    print(result.stdout)     # "2\n"
```

--------------------------------

### Go Error Handling with Sentinel Errors and errx

Source: https://github.com/jingkaihe/matchlock/blob/main/AGENTS.md

Example pattern for defining sentinel errors and wrapping them with context using the errx package.

```go
var ErrParseReference = errors.New("parse image reference")

if err != nil {
    return errx.Wrap(ErrParseReference, err)
}
```

--------------------------------

### Build Docker Image

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/playwright/README.md

Build the Docker image for the browser use case. This is the fastest way to build the image.

```bash
docker build -t browser-use:latest examples/playwright
docker save browser-use:latest | matchlock image import browser-use:latest
```

--------------------------------

### Run Claude Code in Privileged Mode

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/claude-code/README.md

Run the Claude Code example in privileged mode, which grants extended permissions within the sandbox.

```bash
./examples/claude-code/matchlock-claude run --privileged
```

--------------------------------

### Configure Filesystem Mounts

Source: https://github.com/jingkaihe/matchlock/blob/main/sdk/python/README.md

Set up various filesystem mounts for sandboxes, including host directories (read-only and read-write), in-memory filesystems, and overlay filesystems. Supports custom mount types.

```python
from matchlock import Client, Sandbox, MountConfig

sandbox = (
    Sandbox("alpine:latest")
    .mount_host_dir("/workspace/src", "/home/user/project/src")
    .mount_host_dir_readonly("/workspace/config", "/home/user/project/config")
    .mount_memory("/workspace/tmp")
    .mount_overlay("/workspace/data", "/home/user/project/data")
    # Or use the generic mount() method:
    .mount("/workspace/custom", MountConfig(type="host_fs", host_path="/tmp/custom"))
)
```

--------------------------------

### Run in Interactive Mode

Source: https://github.com/jingkaihe/matchlock/blob/main/examples/playwright/README.md

Start an interactive Kodelet session via Toad TUI with Playwright MCP tools available. Requires increased resources.

```bash
matchlock run --image browser-use:latest \
  --cpus 2 --memory 4096 \
  --secret ANTHROPIC_API_KEY@api.anthropic.com \
  --allow-host "*" \
  -it
```

--------------------------------

### Build from Dockerfile

Source: https://github.com/jingkaihe/matchlock/blob/main/README.md

Builds a rootfs image using BuildKit within a microVM, based on a provided Dockerfile.

```bash
# Build from Dockerfile (uses BuildKit-in-VM)
matchlock build -f Dockerfile -t myapp:latest .
```