Skip to main content

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

Guest Filesystem and File Operations

Files live on the guest's native filesystem, not in a shared host directory. The writable root filesystem belongs to the sandbox; copy out results before removing it, or use a managed block volume for persistent data. File operations are explicit transfers over the SDK's JSON-RPC connection and the guest-agent vsock service. They do not expose a host filesystem or install filesystem hooks.

/workspace is an ordinary guest path, not an automatically mounted directory. Create it before using it. Commands use the image's WORKDIR by default; pass working_dir to select an existing guest directory for a particular execution.

from matchlock import Client, Sandbox

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

    client.exec("mkdir -p /workspace")

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

    result = client.exec("./script.sh", working_dir="/workspace")
    print(result.stdout)  # "hi\n"

Copying Files and Directories

copy_in copies a host file or directory into the guest and copy_out copies one back to the host. A source ending in /. copies the directory's contents, and a destination ending in / must be an existing directory. Relative host paths are resolved against the current directory; pass them as str, because pathlib.Path drops a trailing / or /..

client.copy_in("./src/.", "/workspace")  # contents of ./src into /workspace
client.copy_out("/workspace/dist", "./out")

Copied files are owned by the sandbox user unless you pass owner, or archive=True to keep the source's uid/gid. copy_out writes at most 10 GiB and 1,000,000 entries by default (set max_size/max_files; 0 means unlimited) and is not available with use_sudo, which would leave root-owned files on the host.

Stdin/Stdout File Transfers

Use exec_pipe to send an input stream to a guest process and receive its output without a PTY. This example uploads a local file while streaming its contents back to another local file:

import sys
from matchlock import Client, Sandbox

with Client() as client:
    client.launch(Sandbox("alpine:latest"))
    client.exec("mkdir -p /workspace")

    with open("input.bin", "rb") as source, open("output.bin", "wb") as output:
        result = client.exec_pipe(
            "tee /workspace/input.bin",
            stdin=source,
            stdout=output,
            stderr=sys.stderr,
        )
        if result.exit_code != 0:
            raise RuntimeError(f"File transfer exited with {result.exit_code}")

Output writers opened in binary mode (such as open(path, "wb") or io.BytesIO) receive the exact bytes; text writers receive decoded text. read_file is limited to 16 MiB, so stream larger files to a binary writer instead. write_file accepts bytes or str.

Managed Block Volumes

Named volumes are managed ext4 disk images, separate from the sandbox's writable root filesystem. When attached, the guest accesses them as block devices; they are not shared host directories. They persist independently of a VM until removed.

from matchlock import Client

client = Client()
volume = client.volume_create("sdk-data", size_mb=1024)
print(volume.name, volume.size, volume.path)
for existing in client.volume_list():
    print(existing.name)

# When the volume is no longer attached or needed:
# client.volume_remove("sdk-data")

These helpers manage volumes without creating a VM. VolumeInfo.path is the host path of the backing disk image, not a directory exposed to the guest. The Python builder and CreateOptions do not currently expose block-disk attachment. Use the CLI's --disk option to launch a VM with a volume created above:

matchlock run --image alpine:latest --disk @sdk-data:/data -- sh -c 'echo persisted > /data/hello.txt'

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,
            )
        ]
    )
)

Custom Configuration

from matchlock import Client, Config

config = Config(
    binary_path="/usr/local/bin/matchlock",
    use_sudo=False,  # Run as your normal user after Linux setup
)

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.

Method Description
.with_cpus(n) Set number of vCPUs (supports fractional values, e.g. 0.5)
.with_privileged() Enable privileged mode (skip in-guest seccomp/cap-drop/no_new_privs)
.with_memory(mb) Set memory in MB
.with_disk_size(mb) Set disk size in MB
.with_timeout(seconds) Set max execution time
.allow_host(*hosts) Add allowed network hosts (supports wildcards)
.block_private_ips() Block access to private IP ranges
.with_block_private_ips(enabled) Explicitly set private IP blocking true/false
.allow_private_ips() Explicitly allow private IP ranges
.unset_block_private_ips() Reset private IP behavior to SDK default semantics
.with_network_mtu(mtu) Override guest network stack/interface MTU
.with_no_network() Disable guest network egress entirely
.with_port_forward(local_port, remote_port) Add a host-to-guest port mapping
.with_port_forward_addresses(*addresses) Set bind addresses for configured port mappings
.with_network_interception(config=None) Force interception and optionally apply typed network hook rules
.add_secret(name, value, *hosts) Inject a secret for specific hosts
.with_user(user) Set the guest execution user
.with_image_config(config) Merge image metadata, including working_dir; does not create directories
.options() Return the built CreateOptions

Client(config: Config | None = None)

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

Method Description
.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=None, stderr=None, 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="", timeout=None, user="") Pipe stdin/stdout/stderr (no PTY) as an optional user (uid, uid:gid, or username), returns ExecPipeResult
.exec_interactive(command, stdin=None, stdout=None, working_dir="", rows=24, cols=80, resize=None, timeout=None, user="") Interactive PTY exec as an optional user (uid, uid:gid, or username), returns ExecInteractiveResult
.write_file(path, content, mode=0o644) Write a file into the sandbox
.read_file(path) Read a file (up to 16 MiB) from the sandbox — returns bytes
.list_files(path) List directory contents — returns list[FileInfo]
.copy_in(src, dest, *, owner="", archive=False, follow_link=False, exclude=None, timeout=None) Copy a host file or directory into the sandbox
.copy_out(src, dest, *, follow_link=False, exclude=None, max_size=None, max_files=None, timeout=None) Copy a sandbox file or directory to the host; not available with use_sudo
.volume_create(name, size_mb=10240) Create a named ext4 block volume — returns VolumeInfo
.volume_list() List managed block volumes — returns list[VolumeInfo]
.volume_remove(name) Delete a managed block volume that is no longer in use
.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)

Types

Type Fields
Config binary_path: str, use_sudo: bool
CreateOptions image, kernel_ref, privileged, cpus, memory_mb, disk_size_mb, timeout_seconds, allowed_hosts, add_hosts, block_private_ips, block_private_ips_set, no_network, force_interception, network_interception, env, secrets, dns_servers, hostname, network_mtu, port_forwards, port_forward_addresses, image_config, launch_entrypoint
ImageConfig user, working_dir, entrypoint, cmd, env
ExecResult exit_code: int, stdout: str, stderr: str, duration_ms: int
ExecStreamResult exit_code: int, duration_ms: int
ExecPipeResult exit_code: int, duration_ms: int
ExecInteractiveResult exit_code: int, duration_ms: int
FileInfo name: str, size: int, mode: int, is_dir: bool
VolumeInfo name: str, size: str, path: str (backing ext4 image)
PortForward local_port: int, remote_port: int
PortForwardBinding address: str, local_port: int, remote_port: int
Secret name: str, value: str, hosts: list[str]
MatchlockError Base exception for all Matchlock errors
RPCError RPC error with code: int and message: str

License

MIT

Metadata

Release files for matchlock 0.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for matchlock 0.3.1
File Size Uploaded Provenance Actions
matchlock-0.3.1.tar.gz 33.1 kB With provenance Details for matchlock-0.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for matchlock 0.3.1
File Interpreter ABI Platform Actions
matchlock-0.3.1-py3-none-any.whl Python 3 none any Details for matchlock-0.3.1-py3-none-any.whl

Total release size: 56.5 kB

Release files / matchlock-0.3.1.tar.gz

Download URL matchlock-0.3.1.tar.gz
Size 33.1 kB
Tags Source
SHA-256 checksum
How to use checksums
cd5b606387b06ecabdbe3ee5e6ebacefedbd04efd063a6cc2658e4127fcd539a
BLAKE2b-256 checksum
How to use checksums
effa8161c12b0ac627e24d69500c09812ba8e756808bb6f42e2be32b6a95be34
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.

Transparency log

Release files / matchlock-0.3.1-py3-none-any.whl

Download URL matchlock-0.3.1-py3-none-any.whl
Size 23.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fd268460798e065d9ed6b06c5372ab14997a53be47e91641a931101ffe333f78
BLAKE2b-256 checksum
How to use checksums
76517fe0d9196ec3aaba1e86c279cb2b499b352983b911d0427dc9205db33080
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.

Transparency log

Security for matchlock 0.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for matchlock-0.3.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page