Matchlock Python SDK

A Python client for Matchlock — a lightweight micro-VM sandbox for running AI-generated code securely with network interception and secret protection.

Requirements

• Python 3.10+
• The matchlock CLI binary installed and available on $PATH (or specify its path via Config)

Installation

pip install matchlock

Or install from source:

pip install -e sdk/python

Quick Start

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"

Usage

Builder API

The Sandbox class provides a fluent builder for configuring sandboxes:

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"

Streaming Output

Use exec_stream for real-time stdout/stderr streaming:

import sys
from matchlock import Client, Sandbox

with Client() as client:
    client.launch(Sandbox("alpine:latest"))

    result = client.exec_stream(
        "for i in 1 2 3; do echo $i; sleep 1; done",
        stdout=sys.stdout,
        stderr=sys.stderr,
    )
    print(f"Exit code: {result.exit_code}")
    print(f"Duration: {result.duration_ms}ms")

File Operations

Read, write, and list files inside the sandbox:

from matchlock import Client, Sandbox

with Client() as client:
    client.launch(Sandbox("alpine:latest"))

    # Write a file
    client.write_file("/workspace/hello.txt", "Hello, world!")
    client.write_file("/workspace/script.sh", "#!/bin/sh\necho hi", mode=0o755)

    # Read a file
    content = client.read_file("/workspace/hello.txt")
    print(content.decode())  # "Hello, world!"

    # List files
    files = client.list_files("/workspace")
    for f in files:
        print(f"{f.name} ({f.size} bytes, dir={f.is_dir})")

Network Policy & Secrets

Control network access and inject secrets securely:

import os
from matchlock import Client, Sandbox

sandbox = (
    Sandbox("python:3.12-alpine")
    # Only allow these hosts
    .allow_host("api.anthropic.com", "pypi.org", "files.pythonhosted.org")
    # Optional MTU override
    .with_network_mtu(1200)
    # Explicitly block or allow private IPs (10.x, 172.16.x, 192.168.x)
    .with_block_private_ips(True)
    # Inject secret — the MITM proxy replaces the placeholder with the real
    # value only when requests go to the specified host
    .add_secret("ANTHROPIC_API_KEY", os.environ["ANTHROPIC_API_KEY"], "api.anthropic.com")
)

with Client() as client:
    client.launch(sandbox)
    result = client.exec("python3 call_api.py")

    # Optional: forward local 18080 -> guest 8080 after VM creation
    bindings = client.port_forward("18080:8080")
    print(bindings[0].address, bindings[0].local_port, bindings[0].remote_port)

Private-IP behavior in the Python SDK:

• Default (unset): private IPs are blocked whenever a network config is sent.
• Explicit block: .block_private_ips() or .with_block_private_ips(True).
• Explicit allow: .allow_private_ips() or .with_block_private_ips(False).
• Reset to default behavior: .unset_block_private_ips().

If you use CreateOptions(...) directly instead of the builder, set both:

• block_private_ips_set=True
• block_private_ips=<True|False>

For fully offline sandboxes (no guest NIC / no egress), use:

• Builder: .with_no_network()
• Direct options: CreateOptions(no_network=True)

Network Interception Rules

Use typed network hook rules for host-side request/response mutation:

from matchlock import (
    NetworkBodyTransform,
    NetworkHookRule,
    NetworkInterceptionConfig,
    Sandbox,
)

sandbox = Sandbox("alpine:latest").with_network_interception(
    NetworkInterceptionConfig(
        rules=[
            NetworkHookRule(
                phase="after",
                hosts=["api.example.com"],
                action="mutate",
                set_response_headers={"X-Intercepted": "true"},
                body_replacements=[NetworkBodyTransform(find="foo", replace="bar")],
            )
        ]
    )
)

Callback-based interception:

from matchlock import (
    NetworkHookRequest,
    NetworkHookResult,
    NetworkHookResponseMutation,
    NetworkHookRule,
    NetworkInterceptionConfig,
    Sandbox,
)

def after_hook(req: NetworkHookRequest) -> NetworkHookResult | None:
    if req.status_code != 200:
        return None
    return NetworkHookResult(
        action="mutate",
        response=NetworkHookResponseMutation(
            headers={"X-Intercepted": ["callback"]},
            set_body=b'{"msg":"from-callback"}',
        ),
    )

sandbox = Sandbox("alpine:latest").with_network_interception(
    NetworkInterceptionConfig(
        rules=[
            NetworkHookRule(
                phase="after",
                hosts=["api.example.com"],
                hook=after_hook,
                timeout_ms=1500,
            )
        ]
    )
)

Filesystem Mounts

Mount host directories or use in-memory/snapshot filesystems:

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"))
)

Pass owner_uid and/or owner_gid to have all files in the mount appear owned by a specific user inside the VM. This is useful when the sandbox runs as a non-root user (via .with_user()). Both values must be integers in [0, 4294967295]; a ValueError is raised otherwise. Only host_fs mounts support this option:

sandbox = (
    Sandbox("alpine:latest")
    .with_user("1000:1000")
    .mount_host_dir("/workspace/src", "/home/user/project/src", owner_uid=1000, owner_gid=1000)
    .mount_host_dir_readonly("/workspace/config", "/home/user/project/config", owner_uid=1000)
)

Custom Configuration

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:
    ...

The binary path can also be set via the MATCHLOCK_BIN environment variable.

Lifecycle Management

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

Error Handling

from matchlock import Client, Sandbox, MatchlockError, RPCError

with Client() as client:
    try:
        client.launch(Sandbox("alpine:latest"))
        result = client.exec("exit 1")
        if result.exit_code != 0:
            print(f"Command failed: {result.stderr}")
    except RPCError as e:
        print(f"RPC error [{e.code}]: {e.message}")
        if e.is_vm_error():
            print("VM-level failure")
        elif e.is_exec_error():
            print("Execution failure")
        elif e.is_file_error():
            print("File operation failure")
    except MatchlockError as e:
        print(f"Matchlock error: {e}")

API Reference

Sandbox(image: str)

Fluent builder for sandbox configuration.

Client(config: Config | None = None)

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

Types

License

MIT