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-time MafSandboxWslcExperimentalWarning; suppress it with warnings.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 SandboxRouter
from maf_sandbox_wslc import WslcSandboxBackend, WslcSandboxConfig

router = SandboxRouter([WslcSandboxBackend(WslcSandboxConfig())])

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 VM-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, so SandboxRouter(..., deployed=True) refuses this backend outright, at construction. That refusal is the feature: this is a backend for the machine you are already sitting at, and the router will not be argued into treating it as anything else. Use a VM-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:

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.