langchain-backend-microsandbox 0.1.0__tar.gz

langchain_backend_microsandbox-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 LangChain
+Copyright (c) 2026 dod-ia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

langchain_backend_microsandbox-0.1.0/PKG-INFO

@@ -0,0 +1,264 @@
+Metadata-Version: 2.5
+Name: langchain-backend-microsandbox
+Version: 0.1.0
+Summary: Microsandbox backend integration for DeepAgents and LangChain.
+Project-URL: Homepage, https://github.com/dod-ia/langchain-backend-microsandbox
+Project-URL: Repository, https://github.com/dod-ia/langchain-backend-microsandbox
+Project-URL: Issues, https://github.com/dod-ia/langchain-backend-microsandbox/issues
+Project-URL: Changelog, https://github.com/dod-ia/langchain-backend-microsandbox/CHANGELOG.md
+Author: dod-ia
+License-Expression: MIT
+License-File: LICENSE
+Keywords: deepagents,langchain,microsandbox,microvm,sandbox
+Requires-Python: >=3.12
+Requires-Dist: deepagents<0.8.0,>=0.7.35
+Requires-Dist: microsandbox<0.8.0,>=0.7.14
+Description-Content-Type: text/markdown
+
+# langchain-backend-microsandbox
+
+**A [Microsandbox](https://github.com/superradcompany/microsandbox) backend for [LangChain Deep Agents](https://github.com/langchain-ai/deepagents), bringing isolated microVM execution to autonomous AI agents.**
+
+Run agent-generated commands and manage files inside lightweight, isolated virtual machines through Deep Agents' native BaseSandbox interface.
+
+Built on Microsandbox, this integration provides a seamless bridge between Deep Agents and Microsandbox's asynchronous execution and filesystem APIs.
+
+Inspired by `kenwoodjw/langchain-microsandbox`, this implementation extends the original approach with a focus on compatibility, predictable behavior, and closer adherence to the BaseSandbox contract.
+
+## Why Microsandbox?
+
+AI agents increasingly need to execute code, manipulate files, and interact with shell environments to accomplish complex tasks.
+
+Running these operations directly on the host introduces unnecessary security risks.
+
+Microsandbox addresses this challenge by providing isolated microVM environments in which agent workloads can execute independently of the host system.
+
+langchain-backend-microsandbox brings this isolation model to LangChain Deep Agents, allowing developers to use Microsandbox as their agent execution backend without implementing their own sandbox integration.
+
+**The result: a standardized Deep Agents backend with isolated execution and native filesystem support.**
+
+## Features
+
+| Feature | Description |
+|---|---|
+| **Deep Agents integration** | Implements the `BaseSandbox` interface. |
+| **Contract compliance** | Designed to closely follow the `BaseSandbox` behavior and expectations. |
+| **Isolated execution** | Runs agent-generated commands inside Microsandbox microVMs. |
+| **Async & sync execution** | Supports both synchronous and asynchronous command execution. |
+| **Native file transfers** | Binary-safe file uploads and downloads through Microsandbox's filesystem API. |
+| **Filesystem operations** | Inherits `read`, `write`, `edit`, `delete`, `ls`, `grep`, and `glob` from `BaseSandbox`. |
+| **Timeout management** | Configurable execution timeouts with standardized timeout exit codes. |
+| **Error normalization** | Maps filesystem exceptions to Deep Agents-compatible error codes. |
+| **Atomic file uploads** | Uses temporary files and filesystem rename operations to avoid exposing partially written files. |
+
+## Architecture & Compatibility
+
+MicrosandboxSandbox acts as an adapter between LangChain Deep Agents and an existing Microsandbox instance.
+
+It implements the backend-specific operations while relying on BaseSandbox for the higher-level filesystem functionality.
+
+### Inherited BaseSandbox operations
+
+The following operations are inherited directly from LangChain Deep Agents:
+
+* `read()`, `write()`, `edit()`, `delete()`
+* `ls()`, `grep()`, `glob()`
+
+This approach avoids reimplementing filesystem behavior and helps maintain consistency with other Deep Agents sandbox backends.
+
+### BaseSandbox behavior
+
+#### Grep directory exclusions
+
+Directories listed in `grep_exclude_dirs` are excluded from recursive searches, regardless of their depth in the directory tree.
+
+However, explicitly specifying an excluded directory as the search root overrides this exclusion.
+
+In other words:
+- Searching from a parent directory skips excluded directories.
+- Explicitly targeting an excluded directory still searches its contents.
+
+This allows common directories such as `.git` to be excluded from general searches without preventing developers or agents from inspecting them when needed.
+
+Reference: [BaseSandbox.grep_exclude_dirs](https://reference.langchain.com/python/deepagents/backends/sandbox/BaseSandbox/grep_exclude_dirs)
+
+#### Command execution timeouts
+
+Timeout behavior follows the `SandboxBackendProtocol` conventions:
+
+- `None` uses the default timeout configured when creating the adapter.
+- `0` disables the execution timeout.
+- Negative values are rejected with a `ValueError`.
+- When a command exceeds its configured timeout, the backend returns exit code `124`.
+
+Reference: [SandboxBackendProtocol.execute](https://reference.langchain.com/python/deepagents/backends/protocol/SandboxBackendProtocol/execute)
+
+#### Python runtime requirement
+
+The Microsandbox VM must have Python 3 installed and available in `PATH`.
+
+This is a requirement of the inherited `BaseSandbox` filesystem operations, which rely on Python scripts executed inside the sandbox.
+
+Having Python installed on the host machine is not sufficient: the interpreter must be available inside the Microsandbox VM.
+
+Make sure your sandbox image includes a compatible Python installation before initializing the backend.
+  
+## Requirements
+
+- Python >= 3.12
+- [Deep Agents](https://github.com/langchain-ai/deepagents) >= 0.7.35, < 0.8.0
+- [Microsandbox](https://github.com/superradcompany/microsandbox) >= 0.7.14, < 0.8.0
+- A supported Microsandbox runtime environment.
+
+Microsandbox requires hardware virtualization support:
+- **Linux**: KVM
+- **macOS**: Apple Silicon virtualization support
+- **Windows**: Windows Hypervisor Platform (WHP)
+
+On **debian/ubuntu system**, you can install KVM  by installing:
+
+`sudo apt install qemu-system libvirt-daemon-system`
+
+## Installation from sources
+
+Clone the repository and install the package:
+
+```bash
+git clone https://github.com/dod-ia/langchain-backend-microsandbox.git
+
+cd langchain-backend-microsandbox
+
+uv sync
+```
+
+## Get started
+
+The adapter wraps an existing Microsandbox instance and exposes it as a Deep Agents backend.
+
+Since Microsandbox provides an asynchronous API, sandbox creation and adapter initialization must be performed asynchronously.
+
+### Basic example
+
+```python
+from microsandbox import Sandbox
+from langchain_backend_microsandbox import MicrosandboxSandbox
+from deepagents import create_deep_agent
+
+model = init_chat_model("YOUR_MODEL")
+
+
+async def main():
+    # Create a sandbox from MicroSandbox API
+    sandbox = await Sandbox.create(
+        "deep-agent",
+        image="python:3.13",
+        memory=1024,
+        cpus=2,
+        ephemeral=True,
+    )
+
+    # Create a DeepAgent MicroSandbox Backend
+    backend = await MicrosandboxSandbox.create(
+        sandbox,
+        timeout=1800,
+    )
+
+    try:
+        agent = create_deep_agent(model=model, backend=backend)
+        result = await agent.ainvoke(
+            {
+                "messages": [
+                    {
+                        "role": "user",
+                        "content": "Write 'Hi !' in the /tmp/test.txt",
+                    }
+                ]
+            },
+        )
+    finally:
+        content_file = await backend.adownload_files(["/tmp/test.txt"])
+        print(content_file)
+        # [FileDownloadResponse(path='/tmp/test', content=b'Hi !', error=None)]
+
+        # Sandbox lifecycle management remains the caller's responsibility.
+        await sandbox.stop()
+```
+
+### Sandbox lifecyle
+
+**The adapter does not create, start, stop, or destroy virtual machines.**
+
+The calling application remains responsible for:
+
+* Creating and configuring the Microsandbox instance.
+* Managing its lifecycle.
+* Defining its persistence policy.
+* Stopping and cleaning up the sandbox when execution is complete.
+
+Setting `ephemeral=True` when creating the sandbox allows Microsandbox to apply its ephemeral VM lifecycle policy (destroyed after stopping).
+
+The adapter wraps an existing Microsandbox instance. Sandbox creation, lifecycle management and persistence remain the responsibility of the calling application.
+
+> [!WARNING]
+> The Microsandbox VM must have **Python 3 installed and available in PATH**. Without it, inherited `BaseSandbox` filesystem operations may fail.
+
+## Configuration
+
+`MicrosandboxSandbox.create()` accepts the following parameters:
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `sandbox` | `Sandbox` | Required | Existing Microsandbox instance. |
+| `timeout` | `int` | `1800` | Default command execution timeout in seconds. Use `0` to disable it. Must be positive. |
+| `enable_capture_offload` | `bool` | `False` | Enables capture-at-source offloading for large command outputs. Enabling it requires a compatible shell environment and the utilities expected by Deep Agents' capture wrapper. |
+| `grep_exclude_dirs` | `tuple[str, ...]` | `(".git",)` | Directory names excluded from recursive grep searches. |
+
+### Example
+
+```python
+backend = await MicrosandboxSandbox.create(
+    sandbox,
+    timeout=600,
+    enable_capture_offload=False,
+    grep_exclude_dirs=(".git", "__pycache__", ".venv"),
+)
+```
+
+## Testing
+
+Tests use a real Microsandbox VM.
+
+**A working Microsandbox runtime and hardware virtualization support are required.**
+
+### Install development dependencies:
+
+```bash
+uv sync --group dev
+```
+
+### Run the test suite:
+
+```bash
+uv run pytest
+```
+
+### Run with verbose output and coverage
+
+```bash
+uv run pytest -v -s --tb=short --cov --cov-report=term-missing
+```
+
+## License
+
+This project is distributed under the MIT License.
+
+## Acknowledgements
+
+This project builds upon the `BaseSandbox` interface provided by
+[LangChain Deep Agents](https://github.com/langchain-ai/deepagents).
+
+It is inspired by `kenwoodjw/langchain-microsandbox`, whose work helped establish the initial integration approach.
+
+Deep Agents is distributed under the MIT License.
+
+`langchain-backend-microsandbox` is an **independent community integration** and is not affiliated with, endorsed by, or officially supported by LangChain.

langchain_backend_microsandbox-0.1.0/README.md

@@ -0,0 +1,247 @@
+# langchain-backend-microsandbox
+
+**A [Microsandbox](https://github.com/superradcompany/microsandbox) backend for [LangChain Deep Agents](https://github.com/langchain-ai/deepagents), bringing isolated microVM execution to autonomous AI agents.**
+
+Run agent-generated commands and manage files inside lightweight, isolated virtual machines through Deep Agents' native BaseSandbox interface.
+
+Built on Microsandbox, this integration provides a seamless bridge between Deep Agents and Microsandbox's asynchronous execution and filesystem APIs.
+
+Inspired by `kenwoodjw/langchain-microsandbox`, this implementation extends the original approach with a focus on compatibility, predictable behavior, and closer adherence to the BaseSandbox contract.
+
+## Why Microsandbox?
+
+AI agents increasingly need to execute code, manipulate files, and interact with shell environments to accomplish complex tasks.
+
+Running these operations directly on the host introduces unnecessary security risks.
+
+Microsandbox addresses this challenge by providing isolated microVM environments in which agent workloads can execute independently of the host system.
+
+langchain-backend-microsandbox brings this isolation model to LangChain Deep Agents, allowing developers to use Microsandbox as their agent execution backend without implementing their own sandbox integration.
+
+**The result: a standardized Deep Agents backend with isolated execution and native filesystem support.**
+
+## Features
+
+| Feature | Description |
+|---|---|
+| **Deep Agents integration** | Implements the `BaseSandbox` interface. |
+| **Contract compliance** | Designed to closely follow the `BaseSandbox` behavior and expectations. |
+| **Isolated execution** | Runs agent-generated commands inside Microsandbox microVMs. |
+| **Async & sync execution** | Supports both synchronous and asynchronous command execution. |
+| **Native file transfers** | Binary-safe file uploads and downloads through Microsandbox's filesystem API. |
+| **Filesystem operations** | Inherits `read`, `write`, `edit`, `delete`, `ls`, `grep`, and `glob` from `BaseSandbox`. |
+| **Timeout management** | Configurable execution timeouts with standardized timeout exit codes. |
+| **Error normalization** | Maps filesystem exceptions to Deep Agents-compatible error codes. |
+| **Atomic file uploads** | Uses temporary files and filesystem rename operations to avoid exposing partially written files. |
+
+## Architecture & Compatibility
+
+MicrosandboxSandbox acts as an adapter between LangChain Deep Agents and an existing Microsandbox instance.
+
+It implements the backend-specific operations while relying on BaseSandbox for the higher-level filesystem functionality.
+
+### Inherited BaseSandbox operations
+
+The following operations are inherited directly from LangChain Deep Agents:
+
+* `read()`, `write()`, `edit()`, `delete()`
+* `ls()`, `grep()`, `glob()`
+
+This approach avoids reimplementing filesystem behavior and helps maintain consistency with other Deep Agents sandbox backends.
+
+### BaseSandbox behavior
+
+#### Grep directory exclusions
+
+Directories listed in `grep_exclude_dirs` are excluded from recursive searches, regardless of their depth in the directory tree.
+
+However, explicitly specifying an excluded directory as the search root overrides this exclusion.
+
+In other words:
+- Searching from a parent directory skips excluded directories.
+- Explicitly targeting an excluded directory still searches its contents.
+
+This allows common directories such as `.git` to be excluded from general searches without preventing developers or agents from inspecting them when needed.
+
+Reference: [BaseSandbox.grep_exclude_dirs](https://reference.langchain.com/python/deepagents/backends/sandbox/BaseSandbox/grep_exclude_dirs)
+
+#### Command execution timeouts
+
+Timeout behavior follows the `SandboxBackendProtocol` conventions:
+
+- `None` uses the default timeout configured when creating the adapter.
+- `0` disables the execution timeout.
+- Negative values are rejected with a `ValueError`.
+- When a command exceeds its configured timeout, the backend returns exit code `124`.
+
+Reference: [SandboxBackendProtocol.execute](https://reference.langchain.com/python/deepagents/backends/protocol/SandboxBackendProtocol/execute)
+
+#### Python runtime requirement
+
+The Microsandbox VM must have Python 3 installed and available in `PATH`.
+
+This is a requirement of the inherited `BaseSandbox` filesystem operations, which rely on Python scripts executed inside the sandbox.
+
+Having Python installed on the host machine is not sufficient: the interpreter must be available inside the Microsandbox VM.
+
+Make sure your sandbox image includes a compatible Python installation before initializing the backend.
+  
+## Requirements
+
+- Python >= 3.12
+- [Deep Agents](https://github.com/langchain-ai/deepagents) >= 0.7.35, < 0.8.0
+- [Microsandbox](https://github.com/superradcompany/microsandbox) >= 0.7.14, < 0.8.0
+- A supported Microsandbox runtime environment.
+
+Microsandbox requires hardware virtualization support:
+- **Linux**: KVM
+- **macOS**: Apple Silicon virtualization support
+- **Windows**: Windows Hypervisor Platform (WHP)
+
+On **debian/ubuntu system**, you can install KVM  by installing:
+
+`sudo apt install qemu-system libvirt-daemon-system`
+
+## Installation from sources
+
+Clone the repository and install the package:
+
+```bash
+git clone https://github.com/dod-ia/langchain-backend-microsandbox.git
+
+cd langchain-backend-microsandbox
+
+uv sync
+```
+
+## Get started
+
+The adapter wraps an existing Microsandbox instance and exposes it as a Deep Agents backend.
+
+Since Microsandbox provides an asynchronous API, sandbox creation and adapter initialization must be performed asynchronously.
+
+### Basic example
+
+```python
+from microsandbox import Sandbox
+from langchain_backend_microsandbox import MicrosandboxSandbox
+from deepagents import create_deep_agent
+
+model = init_chat_model("YOUR_MODEL")
+
+
+async def main():
+    # Create a sandbox from MicroSandbox API
+    sandbox = await Sandbox.create(
+        "deep-agent",
+        image="python:3.13",
+        memory=1024,
+        cpus=2,
+        ephemeral=True,
+    )
+
+    # Create a DeepAgent MicroSandbox Backend
+    backend = await MicrosandboxSandbox.create(
+        sandbox,
+        timeout=1800,
+    )
+
+    try:
+        agent = create_deep_agent(model=model, backend=backend)
+        result = await agent.ainvoke(
+            {
+                "messages": [
+                    {
+                        "role": "user",
+                        "content": "Write 'Hi !' in the /tmp/test.txt",
+                    }
+                ]
+            },
+        )
+    finally:
+        content_file = await backend.adownload_files(["/tmp/test.txt"])
+        print(content_file)
+        # [FileDownloadResponse(path='/tmp/test', content=b'Hi !', error=None)]
+
+        # Sandbox lifecycle management remains the caller's responsibility.
+        await sandbox.stop()
+```
+
+### Sandbox lifecyle
+
+**The adapter does not create, start, stop, or destroy virtual machines.**
+
+The calling application remains responsible for:
+
+* Creating and configuring the Microsandbox instance.
+* Managing its lifecycle.
+* Defining its persistence policy.
+* Stopping and cleaning up the sandbox when execution is complete.
+
+Setting `ephemeral=True` when creating the sandbox allows Microsandbox to apply its ephemeral VM lifecycle policy (destroyed after stopping).
+
+The adapter wraps an existing Microsandbox instance. Sandbox creation, lifecycle management and persistence remain the responsibility of the calling application.
+
+> [!WARNING]
+> The Microsandbox VM must have **Python 3 installed and available in PATH**. Without it, inherited `BaseSandbox` filesystem operations may fail.
+
+## Configuration
+
+`MicrosandboxSandbox.create()` accepts the following parameters:
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `sandbox` | `Sandbox` | Required | Existing Microsandbox instance. |
+| `timeout` | `int` | `1800` | Default command execution timeout in seconds. Use `0` to disable it. Must be positive. |
+| `enable_capture_offload` | `bool` | `False` | Enables capture-at-source offloading for large command outputs. Enabling it requires a compatible shell environment and the utilities expected by Deep Agents' capture wrapper. |
+| `grep_exclude_dirs` | `tuple[str, ...]` | `(".git",)` | Directory names excluded from recursive grep searches. |
+
+### Example
+
+```python
+backend = await MicrosandboxSandbox.create(
+    sandbox,
+    timeout=600,
+    enable_capture_offload=False,
+    grep_exclude_dirs=(".git", "__pycache__", ".venv"),
+)
+```
+
+## Testing
+
+Tests use a real Microsandbox VM.
+
+**A working Microsandbox runtime and hardware virtualization support are required.**
+
+### Install development dependencies:
+
+```bash
+uv sync --group dev
+```
+
+### Run the test suite:
+
+```bash
+uv run pytest
+```
+
+### Run with verbose output and coverage
+
+```bash
+uv run pytest -v -s --tb=short --cov --cov-report=term-missing
+```
+
+## License
+
+This project is distributed under the MIT License.
+
+## Acknowledgements
+
+This project builds upon the `BaseSandbox` interface provided by
+[LangChain Deep Agents](https://github.com/langchain-ai/deepagents).
+
+It is inspired by `kenwoodjw/langchain-microsandbox`, whose work helped establish the initial integration approach.
+
+Deep Agents is distributed under the MIT License.
+
+`langchain-backend-microsandbox` is an **independent community integration** and is not affiliated with, endorsed by, or officially supported by LangChain.

langchain_backend_microsandbox-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-backend-microsandbox"
+version = "0.1.0"
+description = "Microsandbox backend integration for DeepAgents and LangChain."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["deepagents", "langchain", "microsandbox", "sandbox", "microvm"]
+authors = [{ name = "dod-ia"}]
+requires-python = ">=3.12"
+dependencies = [
+    "deepagents>=0.7.35,<0.8.0",
+    "microsandbox>=0.7.14,<0.8.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/dod-ia/langchain-backend-microsandbox"
+Repository = "https://github.com/dod-ia/langchain-backend-microsandbox"
+Issues = "https://github.com/dod-ia/langchain-backend-microsandbox/issues"
+Changelog = "https://github.com/dod-ia/langchain-backend-microsandbox/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/langchain_backend_microsandbox"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/",
+    "README.md",
+    "LICENSE",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.2.0",
+    "pytest-asyncio>=1.4.1.post1",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.17.4",
+]
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812",  # Messes with the formatter
+    "ISC001",  # Messes with the formatter
+    "ASYNC109", # Timeout is delegated to microVM framework
+    "TRY003"
+]
+extend-safe-fixes = ["PLR6201"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+ignore-var-parameters = true
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+[tool.ruff]
+extend-exclude = ["tests"]

langchain_backend_microsandbox-0.1.0/src/langchain_backend_microsandbox/__init__.py

@@ -0,0 +1,9 @@
+# Original work Copyright (c) 2026 LangChain
+# Modifications Copyright (c) 2026 dod-ia
+# SPDX-License-Identifier: MIT
+
+"""Microsandbox integration for Deep Agents."""
+
+from langchain_backend_microsandbox.backend import MicrosandboxSandbox
+
+__all__ = ["MicrosandboxSandbox"]

langchain_backend_microsandbox-0.1.0/src/langchain_backend_microsandbox/backend.py

@@ -0,0 +1,471 @@
+# Original work Copyright (c) 2026 LangChain
+# Modifications Copyright (c) 2026 dod-ia
+# SPDX-License-Identifier: MIT
+
+"""Microsandbox backend integration for LangChain Deep Agents.
+
+Provides a BaseSandbox implementation backed by Microsandbox.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import suppress
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, cast
+
+from deepagents.backends.protocol import (
+    FILE_NOT_FOUND,
+    INVALID_PATH,
+    IS_DIRECTORY,
+    PERMISSION_DENIED,
+    ExecuteResponse,
+    FileDownloadResponse,
+    FileOperationError,
+    FileUploadResponse,
+)
+from deepagents.backends.sandbox import BaseSandbox
+from microsandbox import (
+    ExecTimeoutError,
+    FilesystemError,
+    PathNotFoundError,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable, Coroutine
+    from concurrent.futures import Future
+
+    from microsandbox import ExecOutput, Sandbox
+
+_TIMEOUT_EXIT_CODE = 124
+
+
+class MicrosandboxSandbox(BaseSandbox):
+    """Sandbox backend implementation powered by Microsandbox.
+
+    Wraps an existing Microsandbox instance to expose the synchronous and
+    asynchronous interfaces expected by Deep Agents (conforming to `SandboxBackendProtocol`).
+
+    The adapter does not manage the sandbox lifecycle. The caller remains
+    responsible for starting, stopping, and configuring the sandbox, as well
+    as defining its persistence and cleanup policies.
+    """
+
+    def __init__(
+        self,
+        *,
+        sandbox: Sandbox,
+        sandbox_id: str,
+        timeout: int,
+        enable_capture_offload: bool = False,
+        grep_exclude_dirs: tuple[str, ...] = (".git",),
+    ) -> None:
+        """Initialize the adapter with an existing Microsandbox instance.
+
+        Prefer using the asynchronous `create()` factory, which resolves the
+        sandbox identifier before constructing the adapter.
+
+        Args:
+            sandbox: Microsandbox instance to wrap.
+            sandbox_id: Resolved name of the sandbox, cached for synchronous access
+                through the `id` property.
+            timeout: Default command execution timeout in seconds. Must be
+                non-negative. A value of zero disables the execution timeout.
+            enable_capture_offload: Whether to enable Deep Agents' capture-at-source
+                mechanism for large command outputs. Requires a compatible shell
+                environment and the utilities used by the capture wrapper.
+            grep_exclude_dirs: Directory names excluded from grep searches,
+                regardless of their depth in the directory tree.
+        """
+        self._sandbox = sandbox
+        self._id = sandbox_id
+        self._default_timeout = timeout
+        self.enable_capture_offload = enable_capture_offload
+        self.grep_exclude_dirs = grep_exclude_dirs
+
+    @classmethod
+    async def create(
+        cls,
+        sandbox: Sandbox,
+        *,
+        timeout: int = 30 * 60,
+        enable_capture_offload: bool = False,
+        grep_exclude_dirs: tuple[str, ...] = (".git",),
+    ) -> MicrosandboxSandbox:
+        """Asynchronously create an adapter around an existing Microsandbox instance.
+
+        Resolves the sandbox name through the provider API and caches it for
+        subsequent synchronous access through the `id` property.
+
+        The sandbox image must provide Python 3 in PATH, as inherited BaseSandbox
+        operations execute Python scripts inside the sandbox.
+
+        Capture offloading is disabled by default. Enabling it requires a
+        compatible shell environment and the utilities expected by Deep Agents'
+        capture wrapper.
+
+        Args:
+            sandbox: Microsandbox instance to wrap.
+            timeout: Default command execution timeout in seconds.
+                Defaults to 1800 seconds. A value of zero disables the timeout.
+            enable_capture_offload: Whether to enable capture-at-source offloading
+                for large command outputs. Requires a compatible shell and
+                coreutils environment.
+            grep_exclude_dirs: Directory names excluded from grep searches at
+                any depth. Defaults to (".git",).
+
+        Returns:
+            An initialized MicrosandboxSandbox adapter.
+
+        Raises:
+            ValueError: If `timeout` is negative.
+        """
+        if timeout < 0:
+            msg = f"timeout must be non-negative, got {timeout}"
+            raise ValueError(msg)
+        # v0.6.12 exposes an awaitable property at runtime even though its stub
+        # declares an async method; accept both forms across the supported range.
+        name: object = sandbox.name
+        if callable(name):
+            name_factory = cast("Callable[[], Awaitable[str]]", name)
+            sandbox_id = await name_factory()
+        else:
+            sandbox_id = await cast("Awaitable[str]", name)
+        return cls(
+            sandbox=sandbox,
+            sandbox_id=sandbox_id,
+            timeout=timeout,
+            enable_capture_offload=enable_capture_offload,
+            grep_exclude_dirs=grep_exclude_dirs,
+        )
+
+    @property
+    def id(self) -> str:
+        """Return the cached name of the underlying Microsandbox instance.
+
+        The identifier is resolved asynchronously during adapter creation,
+        allowing it to be exposed through the synchronous BaseSandbox interface.
+
+        Returns:
+            The sandbox name.
+        """
+        return self._id
+
+    def execute(self, command: str, *, timeout: int | None = None) -> ExecuteResponse:
+        """Execute a shell command through the synchronous backend interface.
+
+        Delegates execution to `aexecute()` and bridges the asynchronous provider
+        API to the synchronous interface.
+
+        Args:
+            command: Shell command to execute inside the sandbox.
+            timeout: Maximum execution time in seconds. If `None`, uses the
+                default timeout configured when the adapter was created.
+                A value of zero disables the timeout. Must be positive.
+
+        Returns:
+            An ExecuteResponse containing the combined command output and
+            its exit status.
+        """
+        return _run_sync(lambda: self.aexecute(command, timeout=timeout))
+
+    async def aexecute(
+        self, command: str, *, timeout: int | None = None
+    ) -> ExecuteResponse:
+        """Execute a shell command using Microsandbox's asynchronous API.
+
+        Uses the configured default timeout unless an execution-specific timeout
+        is provided. A timeout of zero disables the provider-side timeout.
+
+        Provider execution timeouts are converted into an ExecuteResponse with
+        exit code 124, matching the behavior of other Deep Agents sandbox
+        integrations.
+
+        Args:
+            command: Shell command to execute inside the sandbox.
+            timeout: Maximum execution time in seconds. If `None`, uses the
+                default timeout configured when the adapter was created.
+                A value of zero disables the timeout. Must be positive.
+
+        Returns:
+            An ExecuteResponse containing the combined command output and its exit status.
+
+        Raises:
+            ValueError: If the effective timeout is negative.
+        """
+        effective_timeout = self._default_timeout if timeout is None else timeout
+
+        if effective_timeout < 0:
+            msg = f"timeout must be non-negative, got {effective_timeout}"
+            raise ValueError(msg)
+
+        effective_timeout = None if effective_timeout == 0 else float(effective_timeout)
+
+        try:
+            output = await self._sandbox.shell(command, timeout=effective_timeout)
+        except ExecTimeoutError:
+            msg = f"Command timed out after {effective_timeout} seconds"
+            return ExecuteResponse(
+                output=msg, exit_code=_TIMEOUT_EXIT_CODE, truncated=False
+            )
+        return _map_execute_output(output)
+
+    def upload_files(self, files: list[tuple[str, bytes]]) -> list[FileUploadResponse]:
+        """Upload files through the synchronous backend interface.
+
+        Delegates file uploads to `aupload_files()` and bridges the asynchronous
+        filesystem API to the synchronous BaseSandbox interface.
+
+        Args:
+            files: List of pairs containing an absolute sandbox path and the
+                corresponding file contents as bytes.
+
+        Returns:
+            A list of FileUploadResponse objects, preserving the input order.
+            Individual upload failures are reported in their corresponding
+            response rather than raised.
+        """
+        return _run_sync(lambda: self.aupload_files(files))
+
+    async def aupload_files(
+        self, files: list[tuple[str, bytes]]
+    ) -> list[FileUploadResponse]:
+        """Upload multiple files using Microsandbox's asynchronous filesystem API.
+
+        Processes files sequentially and delegates each upload to `_aupload_file()`.
+
+        Each file is handled independently: a failed upload does not prevent
+        subsequent files from being processed.
+
+        Args:
+            files: List of pairs containing an absolute sandbox path and the
+                corresponding file contents as bytes.
+
+        Returns:
+            A list of FileUploadResponse objects, preserving the input order.
+            Each response contains either a successful upload result or an
+            error describing the failure.
+        """
+        return [await self._aupload_file(path, content) for path, content in files]
+
+    async def _aupload_file(self, path: str, content: bytes) -> FileUploadResponse:
+        """Upload a single file atomically to the sandbox filesystem.
+
+        Creates the parent directory when necessary, writes the content to a
+        temporary file in the destination directory, then renames it to the
+        requested path.
+
+        Using a temporary file prevents readers from observing partially
+        written file contents when the underlying filesystem supports atomic
+        rename operations.
+
+        The temporary file is removed on a best-effort basis, including when
+        the upload fails.
+
+        Args:
+            path: Absolute destination path inside the sandbox.
+            content: File contents to upload.
+
+        Returns:
+            A FileUploadResponse containing the destination path and either
+            `None` on success or a normalized filesystem error.
+        """
+        if not path.startswith("/") or "\x00" in path:
+            return FileUploadResponse(path=path, error=INVALID_PATH)
+
+        temp_path = None
+        try:
+            parent = str(PurePosixPath(path).parent)
+            if parent != "/":
+                await self._sandbox.fs.mkdir(parent)
+            temp_path = f"{path}.{uuid.uuid4().hex}.tmp"
+            await self._sandbox.fs.write(temp_path, content)
+            # `rename` is based on tokio::fs::rename (crates/agentd/lib/fs.rs)
+            # This function is based on Linux rename so it is atomic in a Linux system.
+            await self._sandbox.fs.rename(temp_path, path)
+        except Exception as exc:  # noqa: BLE001
+            return FileUploadResponse(path=path, error=_map_file_error(exc))
+        finally:
+            if temp_path is not None:
+                with suppress(Exception):
+                    await self._sandbox.fs.remove(temp_path)
+        return FileUploadResponse(path=path, error=None)
+
+    def download_files(self, paths: list[str]) -> list[FileDownloadResponse]:
+        """Download files through the synchronous backend interface.
+
+        Delegates file downloads to `adownload_files()` and bridges the
+        asynchronous filesystem API to the synchronous BaseSandbox interface.
+
+        Args:
+            paths: List of absolute sandbox paths to download.
+
+        Returns:
+            A list of FileDownloadResponse objects, preserving the input order.
+            Individual download failures are reported in their corresponding
+            response rather than raised.
+        """
+        return _run_sync(lambda: self.adownload_files(paths))
+
+    async def adownload_files(self, paths: list[str]) -> list[FileDownloadResponse]:
+        """Download multiple files using Microsandbox's asynchronous filesystem API.
+
+        Processes paths sequentially and delegates each download to
+        `_adownload_file()`.
+
+        Each path is handled independently: a failed download does not prevent
+        subsequent paths from being processed.
+
+        Args:
+            paths: List of absolute sandbox paths to download.
+
+        Returns:
+            A list of FileDownloadResponse objects, preserving the input order.
+            Each response contains the file contents on success or a normalized
+            error when the download fails.
+        """
+        return [await self._adownload_file(path) for path in paths]
+
+    async def _adownload_file(self, path: str) -> FileDownloadResponse:
+        """Download a single file from the sandbox filesystem.
+
+        Reads the requested path using Microsandbox's asynchronous filesystem API.
+
+        Args:
+            path: Absolute path of the file to download inside the sandbox.
+
+        Returns:
+            A FileDownloadResponse containing the file contents on success.
+            If the path is invalid or the filesystem operation fails, the
+            response contains `None` as its content and a corresponding error.
+        """
+        if not path.startswith("/") or "\x00" in path:
+            return FileDownloadResponse(path=path, content=None, error=INVALID_PATH)
+
+        try:
+            content = await self._sandbox.fs.read(path)
+        except Exception as exc:  # noqa: BLE001
+            return FileDownloadResponse(
+                path=path, content=None, error=_map_file_error(exc)
+            )
+        return FileDownloadResponse(path=path, content=content, error=None)
+
+
+def _map_execute_output(output: ExecOutput) -> ExecuteResponse:
+    """Convert a Microsandbox execution result into a Deep Agents response.
+
+    Decodes stdout and stderr as UTF-8, replacing invalid byte sequences
+    instead of raising decoding errors.
+
+    Stdout is preserved as the primary output. When stderr is not empty,
+    it is appended using `<stderr>` tags, with a newline separator when
+    necessary.
+
+    The provider's exit code is preserved. Output truncation is not
+    performed by this adapter.
+
+    Args:
+        output: Execution result returned by Microsandbox.
+
+    Returns:
+        An ExecuteResponse containing the combined output, the provider's
+        exit code, and a `truncated` flag set to False.
+    """
+    stdout = bytes(output.stdout_bytes).decode("utf-8", errors="replace")
+    stderr = bytes(output.stderr_bytes).decode("utf-8", errors="replace")
+
+    combined = stdout
+    if stderr:
+        separator = "" if not stdout or stdout.endswith(("\n", "\r")) else "\n"
+        combined += f"{separator}<stderr>{stderr}</stderr>"
+    return ExecuteResponse(output=combined, exit_code=output.exit_code, truncated=False)
+
+
+def _map_file_error(exc: Exception) -> FileOperationError | str:  # noqa: PLR0911
+    """Normalize filesystem exceptions into Deep Agents file operation errors.
+
+    Maps known Python and Microsandbox filesystem exceptions to the
+    corresponding FileOperationError constants.
+
+    For provider exceptions that do not expose structured error types,
+    the exception message is inspected to identify common filesystem
+    failures, such as permission errors, missing files, and invalid paths.
+
+    Unrecognized exceptions are preserved as descriptive strings so that
+    callers retain access to the original error information.
+
+    Args:
+        exc: Exception raised by a filesystem operation.
+
+    Returns:
+        A normalized FileOperationError when the failure matches a known
+        category, otherwise a string containing the exception type and
+        its message.
+    """
+    if isinstance(exc, PermissionError):
+        return PERMISSION_DENIED
+    if isinstance(exc, IsADirectoryError):
+        return IS_DIRECTORY
+    if isinstance(exc, NotADirectoryError):
+        return INVALID_PATH
+    if isinstance(exc, (FileNotFoundError, PathNotFoundError)):
+        return FILE_NOT_FOUND
+
+    if isinstance(exc, FilesystemError):
+        message = str(exc).lower()
+        substring_errors: tuple[tuple[tuple[str, ...], FileOperationError], ...] = (
+            (("permission denied", "access denied", "forbidden"), PERMISSION_DENIED),
+            (("is a directory",), IS_DIRECTORY),
+            (("not a directory", "invalid path"), INVALID_PATH),
+            (("no such file", "not found"), FILE_NOT_FOUND),
+        )
+        for needles, error in substring_errors:
+            if any(needle in message for needle in needles):
+                return error
+    detail = str(exc).strip()
+    if detail:
+        return f"{type(exc).__name__}: {detail}"
+    return type(exc).__name__
+
+
+def _run_sync[T](factory: Callable[[], Coroutine[object, object, T]]) -> T:
+    """Run an asynchronous provider operation from synchronous code.
+
+    Bridges an asynchronous coroutine factory to the synchronous
+    BaseSandbox interface.
+
+    When no event loop is running in the calling thread, the coroutine
+    is executed directly using `asyncio.run()`.
+
+    When an event loop is already running, execution is delegated to a
+    dedicated worker thread with its own event loop. This avoids attempting
+    to nest `asyncio.run()` inside an existing event loop.
+
+    The coroutine is created and executed in the same thread, ensuring
+    that coroutine-bound resources are not transferred between threads.
+
+    Args:
+        factory: Zero-argument callable that creates the coroutine to execute.
+
+    Returns:
+        The result produced by the asynchronous operation.
+
+    Raises:
+        Exception: Any exception raised by the asynchronous operation is
+            propagated to the synchronous caller.
+    """
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(factory())
+
+    def run_in_thread() -> T:
+        return asyncio.run(factory())
+
+    with ThreadPoolExecutor(
+        max_workers=1, thread_name_prefix="microsandbox-sync"
+    ) as executor:
+        future: Future[T] = executor.submit(run_in_thread)
+        return future.result()