Skip to main content

maf-sandbox-deepagents

PyPI Python License

Experimental. The API may change without notice. Importing the package emits MafSandboxDeepagentsExperimentalWarning.

Use a SandboxRouter as a Deep Agents sandbox. MafSandbox connects Deep Agents' command and file tools to a backend such as Docker or ACAS. The router enforces the host's isolation floor and the spec's capabilities and network policy.

This is a third-party integration, not a product of or endorsed by LangChain, Inc. or Microsoft.

deepagents  ->  maf_sandbox_deepagents  ->  maf_sandbox (router)  ->  a backend  ->  the sandbox

Quickstart

pip install maf-sandbox-deepagents maf-sandbox-docker
from deepagents import create_deep_agent
from maf_sandbox import Isolation, SandboxKey, SandboxRouter
from maf_sandbox_deepagents import MafSandbox, deepagents_spec
from maf_sandbox_docker import DockerSandboxBackend, DockerSandboxConfig

router = SandboxRouter([DockerSandboxBackend(DockerSandboxConfig())], min_isolation=Isolation.CONTAINER)
spec = deepagents_spec("python:3.12-alpine")

# Derive these identifiers from trusted host request context.
sandbox = MafSandbox(router, SandboxKey(scope="tenant-a", thread_id="thread-1", agent_id="coder"), spec)

agent = create_deep_agent(model=..., backend=sandbox, system_prompt=f"Work under {spec.work_dir}.")

Use a host-derived key per agent and conversation. The adapter requires conversation scope and an empty key.call_id. Its default kind is deepagents, separate from packaged kinds using the same conversation.

deepagents_spec requires EXEC, FILES_IN and FILES_OUT. An empty egress_allow selects CLOSED; named hosts select ALLOWLIST. UNRESTRICTED is refused, including on a manually constructed spec.

The working directory must be an explicit absolute POSIX path. work_dir=None is refused because the host must tell the model where its files live. Construction checks the spec and router; the first operation acquires the actual sandbox.

sandbox.id identifies the adapter using the key, kind, backend and network policy. It is not the physical instance ID used by the operator console.

Commands

Setting Contract
Execution Model-supplied shell string through BoundedExec.exec_bounded
Working directory ".", resolved by the backend to the configured base
Default deadline 120 seconds, including admission and cold acquisition
Default output cap 1 MiB combined stdout/stderr, enforced by the backend before buffering
Result Text with guest stderr prefixed by [stderr], or producer-owned stderr by [note]; rendering that exceeds the cap is dropped
Overflow Drop the output and return truncated=True; never return a partial successful result

A backend without BoundedExec runs no command. Provider details stay in host logs; failures returned to the model use fixed messages. A timeout means the wait ended, not that guest execution is known to have stopped.

The model controls the shell. Backend isolation and network policy apply, but the packaged kinds' fixed-command behavior does not. Keep credentials out of the image.

Files and paths

Deep Agents' file tools use absolute guest paths. Adapter uploads and downloads also accept relative paths beneath the configured base.

Path Upload Download
Inside the base write_file stat_file, then read_file
Outside the base write_file_over_exec read_file_over_exec

The outside-base route supports paths such as /conversation_history/ and /tmp/. It uses the same guest authority already available to execute. Uploads stage chunks in a sibling file, then move the completed file into place.

Both routes enforce spec.files_in or spec.files_out. A batch above max_files is refused whole. A file above its per-file cap or remaining total budget is refused individually. Downloads refuse oversize results rather than truncate them.

File condition Response
Missing file file_not_found
Directory requested as a file is_directory
Link under the base, invalid traversal or non-directory parent invalid_path
Unsearchable parent or unreadable file permission_denied

A native stat/read timeout fails that file alone and leaves the sandbox available. An unfinished write or shell transfer requires disposal. An unfinished upload invalidates the batch; an unfinished shell download stops the remaining downloads.

Lifetime and cleanup

Operations enter the router's shared call lifecycle, then acquire or reuse the conversation sandbox. Successful operations release admission and leave it warm. An unfinished command or transfer queues exact-instance disposal. Already admitted sibling calls finish before the queued delete runs; later calls wait for cleanup before starting cold. Explicit close takes exclusive admission and disposes the instance this adapter acquired. Conversation purge is the host's recovery path.

Successful operations keep the sandbox warm across conversation turns. Timeout, backend output overflow, cancellation or a missing command result queues disposal because guest completion is uncertain. Overflow caused only by formatting a completed result drops that result without requiring disposal.

The router coordinates overlapping calls. Adapter-queued deletion waits for the last call already allowed to run, and later calls wait for cleanup. A backend can independently invalidate the whole sandbox on failure; its own timeout and cancellation contract still applies.

After unfinished work, release and cleanup run on the process-owned SyncRunner loop. They can outlive the caller's loop and do not extend its response wait. Failed cleanup is not permission to reuse the instance.

await sandbox.aclose() takes exclusive admission, then disposes the exact instance this adapter acquired. It returns False when closure cannot be confirmed. Before acquisition, there is nothing to delete. Other kinds and replacements remain separate.

Wire router.dispose_scope(scope, thread_id) into the host's conversation-delete path. LangGraph thread deletion does not call it automatically. The adapter uses disposal, not per-operation reclamation or reset.

Async methods are native. Synchronous methods run the same coroutines through one shared SyncRunner thread and event loop per process. A forked child starts its own runner.

Requirements and limits

  • Python 3.12–3.14 and Deep Agents 0.7.x.
  • A backend declaring EXEC, FILES_IN and FILES_OUT, with bounded execution. Docker and ACAS provide this; WSLC lacks output reads.
  • Guest commands sh, mkdir, mv, rm, base64 and wc for outside-base transfers. Missing commands can fail at transfer time.
  • python3 for Deep Agents' derived ls, read_file, write_file, edit_file, glob and grep tools. Without it, direct execution, shell deletion and adapter uploads/downloads remain available.

This adapter does not supply MAF information-flow labels, automatic hiding, per-call guest directories, declared outputs with a landing sink, or guest-to-host tool calls. Those are the packaged kinds' contracts.

The Docker Bicep sample shows the complete integration with a model.

Metadata

Release files for maf-sandbox-deepagents 0.7.2

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

Source distribution (sdist)

Source distribution for maf-sandbox-deepagents 0.7.2
File Size Uploaded Provenance Actions
maf_sandbox_deepagents-0.7.2.tar.gz 18.0 kB With provenance Details for maf_sandbox_deepagents-0.7.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for maf-sandbox-deepagents 0.7.2
File Interpreter ABI Platform Actions
maf_sandbox_deepagents-0.7.2-py3-none-any.whl Python 3 none any Details for maf_sandbox_deepagents-0.7.2-py3-none-any.whl

Total release size: 36.5 kB

Release files / maf_sandbox_deepagents-0.7.2.tar.gz

Download URL maf_sandbox_deepagents-0.7.2.tar.gz
Size 18.0 kB
Tags Source
SHA-256 checksum
How to use checksums
66d7f209be8dad5cba3964113700162b5410fe22c79080676a9c9b0b875b8fa1
BLAKE2b-256 checksum
How to use checksums
c86df3e452602982dfb8d6b2323c4a377e24576981a1f771c539e16605c24410
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 Nov 6, 2026.

Transparency log

Release files / maf_sandbox_deepagents-0.7.2-py3-none-any.whl

Download URL maf_sandbox_deepagents-0.7.2-py3-none-any.whl
Size 18.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c8b485581786dae0443743ea18e7ec1d2e9b4a00d517f15975f52ecf4fce3b5f
BLAKE2b-256 checksum
How to use checksums
da8e3c70b432efc5162558a637b389c75c5c17f076f9b5f8a6e4bc42a3220ca1
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 Nov 6, 2026.

Transparency log

Security for maf-sandbox-deepagents 0.7.2

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 maf_sandbox_deepagents-0.7.2.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 Nov 6, 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.

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