maf-sandbox-wslc
Experimental. This package is early-stage (pre-1.0,
Development Status :: 4 - Beta) — its API may change or be removed in a future release without notice. Importing it emits a one-timeMafSandboxWslcExperimentalWarning; suppress it withwarnings.filterwarnings("ignore", category=maf_sandbox_wslc.MafSandboxWslcExperimentalWarning)once you've read the notice.
This package is not affiliated with, endorsed by, or a product of Microsoft — it is a third-party reference implementation of microsoft/agent-framework#7568 for Microsoft Agent Framework.
app -> maf_sandbox -> maf_sandbox_wslc -> the container
The developer-machine sandbox backend: a container created by wslc, the container CLI that ships with WSL, in about half a second — no subscription, no daemon, no login, and no dependency but maf-sandbox itself. A workload written against the protocol runs here unchanged, which is what makes it a workload rather than an integration.
Quickstart
pip install maf-sandbox-wslc
from maf_sandbox import Isolation, SandboxRouter
from maf_sandbox_wslc import WslcSandboxBackend, WslcSandboxConfig
router = SandboxRouter([WslcSandboxBackend(WslcSandboxConfig())], min_isolation=Isolation.CONTAINER)
samples/02_wslc_bicep runs those two lines end to end: a one-turn agent that validates a Bicep file against the compiler and takes the container down afterwards. Its sibling samples/01_acas_bicep is the same program on a microVM-isolated Azure backend, and the diff between them is two imports and one constructor.
Requirements
Windows with WSL 2.9.3 or later. wslc is part of WSL; wsl --version reports the version and wsl --update moves it forward. There is nothing else to install. The command-line contract this backend depends on — argv passed to exec natively, cp from a tar on stdin, label filters on list, WSLC_E_* codes on stderr — was verified against wslc 2.9.4.0. Every call spawns wslc.exe, so the host's event loop has to be one that can start subprocesses — asyncio's default Proactor loop on Windows does, and a host that installs WindowsSelectorEventLoopPolicy has to undo that first, or every acquire fails with a message saying so.
What this backend declares
Isolation.CONTAINER. A container shares the host kernel and sits next to whatever the host process holds, below SandboxRouter's default min_isolation=Isolation.MICROVM floor — construct the router with min_isolation=Isolation.CONTAINER and it admits this backend; leave the floor at its default and construction raises SandboxBackendNotPermitted. That refusal is the feature: this is a backend for the machine you are already sitting at, and opting the floor down is the one thing that lets you use it — there is no flag left to forget. Use a microVM-isolated backend where a deployment's credentials are in the picture.
Egress.CLOSED by default, Egress.ALLOWLIST on request. With no proxy configured every container is created --network none: the CLI cannot allow one host and deny the rest, so a spec's allowlist is honoured by denying everything — confining more than a workload asked for, which the router permits with a warning precisely because the failure is loud, and a workload built for this reports the shortfall rather than passing an incomplete result off as a clean one.
Set egress_proxy_image and the declaration becomes ALLOWLIST: each sandbox gets its own internal network and a dual-homed filtering proxy, and the spec's allowlist is enforced by topology — the container has no route out except the proxy, which opens a CONNECT tunnel only to the hosts the spec names. TLS is not decrypted, and the sandbox never resolves an external name itself. The proxy is shipped as source, not as an image you must trust: build it from the packaged recipe, whose only pinned dependency is its Azure Linux base.
from pathlib import Path
from maf_sandbox_wslc import proxy_build_context, WslcSandboxConfig
print(f"wslc build -t maf-egress-proxy:local {proxy_build_context()}") # run this once
config = WslcSandboxConfig(egress_proxy_image="maf-egress-proxy:local")
The backend
WslcSandboxBackend implements maf_sandbox.SandboxBackend:
acquire(key, spec) |
get-or-create, keyed (scope, thread, agent). A running container is reused, a stopped one started, a missing one created — so a fix-round loop does not pay a cold start per iteration |
write_file(path, content, *, working_directory) |
a confined one-entry tar on stdin to cp - <container>:/, which creates the parent directories from the entry name |
dispose(key) |
remove -f on the one container the key names |
dispose_scope(scope, thread) |
delete every container for a conversation — by label, read back from wslc, not from process memory |
isolation |
container — below the router's default microvm floor, so a host opts down explicitly with min_isolation=Isolation.CONTAINER |
egress |
closed, or allowlist when egress_proxy_image is set — an internal network behind a filtering proxy, torn down with the sandbox |
capabilities |
{EXEC, FILES_IN} — a command line and files written in; nothing more |
Container names are derived from the key rather than remembered, so acquire and dispose agree on one without a registry to keep in sync. Labels are the durable record dispose_scope selects on, and their values are digested when they are long or carry a separator — the same mapping on both sides, because transforming one and not the other makes a purge quietly select nothing.
stop is never used. A container whose init process ignores SIGTERM takes ten seconds to stop and under a quarter of a second to remove, and there is nothing in a sandbox worth waiting for.
Maintained by SOKOLAI BV.
1 maintainer
Release files for maf-sandbox-wslc 0.10.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| maf_sandbox_wslc-0.10.0.tar.gz | 22.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| maf_sandbox_wslc-0.10.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 47.6 kB
Release files / maf_sandbox_wslc-0.10.0.tar.gz
| Download URL | maf_sandbox_wslc-0.10.0.tar.gz |
|---|---|
| Size | 22.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
496ca4b998f41490b3c5107fd63031a15a3cdfeff85b6a5fa7ae0985ff32746c
|
|
BLAKE2b-256 checksum How to use checksums |
cf111f699bcb3de7bff79a19b8082b2121a44d4320078bd246702947f085672d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Aug 21, 2026.
Transparency logRelease files / maf_sandbox_wslc-0.10.0-py3-none-any.whl
| Download URL | maf_sandbox_wslc-0.10.0-py3-none-any.whl |
|---|---|
| Size | 25.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2853e3730a1f9850f38e8c6bfd81635ae2bf694cbb8898ff9dfcb2541f3bb6eb
|
|
BLAKE2b-256 checksum How to use checksums |
f85b3828c02db59f11c5dcf45403c1376f43c2abe831eefada7df19a6fec517d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Aug 21, 2026.
Transparency log
