Metadata-Version: 2.4
Name: maf-sandbox-wslc
Version: 0.23.1
Summary: WSL containers (wslc) as a developer-machine sandbox backend for Microsoft Agent Framework agents.
Keywords: wsl,containers,sandbox,agent-framework,microsoft-agent-framework,isolation
Author: SOKOLAI BV
Author-email: SOKOLAI BV <info@sokolai.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Typing :: Typed
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Software Development :: Testing
Requires-Dist: maf-sandbox>=0.42.0,<0.43
Requires-Python: >=3.12, <3.15
Project-URL: Homepage, https://www.sokol.ai
Project-URL: Source, https://github.com/sokolaidev/maf-extensions
Project-URL: Issues, https://github.com/sokolaidev/maf-extensions/issues
Description-Content-Type: text/markdown

# maf-sandbox-wslc

[![PyPI](https://img.shields.io/pypi/v/maf-sandbox-wslc)](https://pypi.org/project/maf-sandbox-wslc/) [![Python](https://img.shields.io/pypi/pyversions/maf-sandbox-wslc)](https://pypi.org/project/maf-sandbox-wslc/) [![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/sokolaidev/maf-extensions/blob/main/LICENSE)

> **Experimental.** Releases before 1.0 may change or remove APIs. Importing this package emits `MafSandboxWslcExperimentalWarning`.

Run sandbox commands in Linux containers managed by `wslc`, the container CLI included with WSL. This backend transfers input files and returns command output. It has no Azure dependency.

This is an independent package, not a Microsoft product.

## Quickstart

```bash
pip install maf-sandbox-wslc
```

```python
from maf_sandbox import Isolation, SandboxRouter
from maf_sandbox_wslc import WslcSandboxBackend, WslcSandboxConfig

backend = WslcSandboxBackend(WslcSandboxConfig())
router = SandboxRouter([backend], min_isolation=Isolation.CONTAINER)
```

Containers share the WSL kernel. The explicit minimum permits container isolation, below the router's default microVM minimum.

Use Windows with WSL 2.9.3 or later. `wsl --version` reports the installed version. The backend's CLI contract has been measured on WSLC 2.9.4.0 and 2.9.12.0.

The Python event loop must support subprocesses. Windows' default Proactor loop does; `WindowsSelectorEventLoopPolicy` does not.

See the [Bicep sample](https://github.com/sokolaidev/maf-extensions/tree/main/samples/02_wslc_bicep) or [CodeAct sample](https://github.com/sokolaidev/maf-extensions/tree/main/samples/04_wslc_codeact) for complete applications.

## Supported operations

| Setting | Behavior |
|---|---|
| Isolation | `CONTAINER` |
| Capabilities | `EXEC`, `FILES_IN` |
| Guest OS | POSIX |
| Network | `CLOSED`; `ALLOWLIST` with a configured proxy |
| Lifetime | Conversation or separate sandbox per call |
| Transfer ceiling | 8 MiB per file, 32 MiB total, 64 files per direction |
| Cleanup | Disposal; no reclaim or snapshot reset |

Output reads, directory listing, file deletion, runtime `run_code` and host-tool calls are unavailable. A kind requiring one is refused before attachment.

Acquisition checks `sh` for commands. Input transfer also needs the external `test` command and a resolved image user. Failed prerequisite checks are retryable.

## Input files and their limits

Acquisition prepares the storage base for workloads using commands or files. `work_dir=None` selects `/maf-sandbox/work`; an explicit path requests that exact base. Existing directories keep their contents, ownership and modes.

Files and missing directories at or below `working_directory` receive the image user's UID/GID. An unset `Config.User` means root. Named users or an omitted group need working `id` commands. Unresolved ownership refuses writes and creation of a missing base.

**The copy acts with root authority, and its path check is separate from the write.** A guest can replace a checked parent with a symlink before extraction. That can redirect bytes outside the working directory, including into a root-owned directory the guest cannot write itself.

The same race affects creation of missing directories and work-directory repair during acquisition. Setting tar ownership does not reduce placement authority. Cancellation after copy submission can leave partial writes.

Some path classification runs inside the guest. It does not hold the checked filesystem state or provide a trusted freeze. Choose another transfer mechanism or backend if concurrent guest changes must not escape the checked directory.

Path inspection can also copy an existing guest file into a private host temporary directory. **Its disk use is not bounded by input limits or stdout limits.** Normal exits remove the temporary copy, but a host crash or cleanup failure can leave it behind. Use an enforced temporary-filesystem quota when that consumption is unacceptable.

See the [backend guide](https://github.com/sokolaidev/maf-extensions/blob/main/docs/sandbox/backends/wslc.md) for the precise file contract and remaining limits.

## Network access

Without a proxy, only `Egress.CLOSED` is supported. Containers use `--network none`, and an allowlist request is refused.

Build the packaged proxy and select it in configuration:

```python
from maf_sandbox_wslc import WslcSandboxConfig, proxy_build_context

print(f"wslc build -t maf-egress-proxy:local {proxy_build_context()}")
config = WslcSandboxConfig(egress_proxy_image="maf-egress-proxy:local")
```

Each allowlisted sandbox gets an internal network and a filtering proxy. The proxy is its only route out and permits only the spec's hosts. TLS is not decrypted. Unrestricted access and method-scoped rules are unsupported.

The router's observer can receive proxy decisions after confirmed removal. Failed removal can leave a window unreported. See [observability](https://github.com/sokolaidev/maf-extensions/blob/main/docs/sandbox/observability.md).

<a id="operator-retention"></a>

## Cleanup and retention

Router-managed calls dispose their sandbox even when a kind claims to keep changes inside its call directory. WSLC cannot establish the ancestry needed for privileged reclaim and declares no snapshot reset.

`dispose(key, kind=...)` removes a selected kind and its infrastructure. `dispose_scope(scope, thread_id)` discovers conversation resources through engine labels, not only process memory.

An operator can clean up stopped workloads and orphan infrastructure:

```python
from datetime import timedelta

result = await backend.reap(timedelta(hours=24), scope="my-app")
print(result.disposed, result.proxies_removed, result.networks_removed)
for failure in result.failures:
    print(failure)
```

Run this under the Windows account that owns the WSLC engine. The backend starts no timer. An external scheduler must select the environment, prevent overlapping sweeps and monitor failures.

Pause and drain acquisition, restarts and other resource changes in the selected scope before sweeping. Engine rechecks cannot make name-based network deletion atomic. Keep Windows and WSL clocks synchronized.

| Resource | Age used for retention |
|---|---|
| Stopped workload | Time since its inspected stop; a restart and stop resets it. |
| Never-started workload | Creation time. |
| Proxy without a workload | Creation time, including for a running orphan proxy. |
| Network alone | Its backend creation-time label; missing labels retain it for manual handling. |

Running or uncertain workload states retain their whole group. Resources exactly at the cutoff are retained. An incomplete inventory prevents deletion; individual failures are reported. Retention does not infer that a host has died or impose a maximum running lifetime.

See [operations](https://github.com/sokolaidev/maf-extensions/blob/main/docs/sandbox/operations.md) for scheduling and cleanup ownership. The [live suite](https://github.com/sokolaidev/maf-extensions/blob/main/packages/maf-sandbox-wslc/tests/test_wslc_e2e.py) covers writes, networks and separate-process retention using explicitly configured images.

Maintained by [SOKOLAI BV](https://www.sokol.ai).
