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
matchlockCLI binary installed and available on$PATH(or specify its path viaConfig)
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
networkconfig 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=Trueblock_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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.