langchain-hyperlight 0.1.0__py3-none-any.whl

langchain_hyperlight/__init__.py

@@ -0,0 +1,33 @@
+"""LangChain integration for Microsoft Hyperlight micro VMs.
+
+Exposes a LangChain tool that executes untrusted code inside a hardware-isolated
+Hyperlight micro virtual machine (KVM / MSHV / Hyper-V).
+
+.. warning::
+    This package is **vibe-coded (AI-generated)** and experimental. It has only
+    been tested on **Linux (x86_64)** and is **not tested on Windows or macOS**.
+    Use at your own risk.
+
+Example:
+    >>> from langchain_hyperlight import HyperlightSandboxTool
+    >>> tool = HyperlightSandboxTool(host_tools={"add": lambda a=0, b=0: a + b})
+    >>> tool.invoke({"code": "print(call_tool('add', a=3, b=4))"})
+"""
+
+from .tool import (
+    AllowedDomain,
+    FileMount,
+    HyperlightSandboxTool,
+    SandboxCodeInput,
+    create_hyperlight_tool,
+)
+
+__all__ = [
+    "AllowedDomain",
+    "FileMount",
+    "HyperlightSandboxTool",
+    "SandboxCodeInput",
+    "create_hyperlight_tool",
+]
+
+__version__ = "0.1.0"

langchain_hyperlight/tool.py

@@ -0,0 +1,545 @@
+"""LangChain tool that executes untrusted code inside a Hyperlight micro VM.
+
+This module bridges LangChain's tool interface to the Hyperlight Sandbox
+Python SDK (https://github.com/hyperlight-dev/hyperlight-sandbox).  The
+resulting tool can be handed to any LangChain agent so that an LLM can run
+arbitrary, untrusted code in a hardware-isolated micro virtual machine
+(KVM / MSHV / Hyper-V) instead of on the host.
+
+The API intentionally mirrors Microsoft's canonical ``agent-framework-hyperlight``
+package (https://github.com/microsoft/agent-framework) so the concepts transfer
+directly, but this tool targets LangChain's ``BaseTool`` interface.
+
+Thread-safety note
+------------------
+The Hyperlight ``WasmSandbox`` is declared ``unsendable`` in PyO3: it may only be
+accessed *and dropped* from the OS thread that created it.  Touching it from any
+other thread triggers an uncatchable Rust panic.  To honor that invariant, all
+sandbox access is routed through a single-threaded worker (see
+:class:`_SandboxWorker`), so the tool is safe to call from arbitrary threads and
+event loops.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import shutil
+import tempfile
+from collections.abc import Callable, Sequence
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path, PurePosixPath
+from typing import Any, NamedTuple
+from urllib.parse import urlparse
+
+from hyperlight_sandbox import ExecutionResult, Sandbox
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field, PrivateAttr, field_validator
+
+__all__ = [
+    "AllowedDomain",
+    "FileMount",
+    "HyperlightSandboxTool",
+    "SandboxCodeInput",
+    "create_hyperlight_tool",
+]
+
+
+class SandboxCodeInput(BaseModel):
+    """Arguments accepted by :class:`HyperlightSandboxTool`."""
+
+    code: str = Field(
+        description=(
+            "The full source code to execute inside the Hyperlight micro VM. "
+            "The sandbox runs Python by default."
+        )
+    )
+
+
+class FileMount(NamedTuple):
+    """Map a host file or directory into the sandbox ``/input`` tree."""
+
+    host_path: str | Path
+    mount_path: str
+
+
+class AllowedDomain(NamedTuple):
+    """Allow outbound requests to one target, optionally restricted to HTTP methods."""
+
+    target: str
+    methods: tuple[str, ...] | None = None
+
+
+DEFAULT_DESCRIPTION = """\
+Execute untrusted code inside a hardware-isolated Hyperlight micro virtual machine (micro VM).
+
+The code runs in a fresh, OS-free sandbox with no access to the host filesystem or network
+unless explicitly granted. Use this tool to safely run code that may be untrusted, to perform
+computations, or to process data in isolation.
+
+The sandbox runs Python by default. Inside the sandbox the following built-in functions are
+available:
+- call_tool(name, **kwargs): invoke a host-registered tool by name with keyword arguments.
+- http_get(url) / http_post(url, body=...): make HTTP requests to allow-listed domains only.
+- read_file(path) / write_file(path, data): read from the /input directory and write to the
+  /output directory (capability-based file access).
+
+Provide the full source code to execute. The tool returns the program's stdout, stderr, and
+exit code. A non-zero exit code or any stderr output indicates an error.
+"""
+
+
+# --------------------------------------------------------------------------- #
+# Input normalization (mirrors microsoft/agent-framework hyperlight package)
+# --------------------------------------------------------------------------- #
+
+def _normalize_domain(target: str) -> str:
+    """Normalize a domain to a lowercase host (no scheme, no trailing slash).
+
+    Accepts an optional ``scheme://`` prefix and strips it, returning just the
+    netloc/path in lowercase.  Raises ``ValueError`` for empty input.
+    """
+    candidate = target.strip()
+    if not candidate:
+        raise ValueError("Allowed domain entries must not be empty.")
+    parsed = urlparse(candidate if "://" in candidate else f"//{candidate}")
+    normalized = (parsed.netloc or parsed.path).strip().rstrip("/")
+    if not normalized:
+        raise ValueError(f"Could not normalize allowed domain entry: {target!r}.")
+    return normalized.lower()
+
+
+def _normalize_methods(methods: str | Sequence[str] | None) -> tuple[str, ...] | None:
+    """Normalize HTTP method(s) to a sorted tuple of uppercase strings.
+
+    Accepts a single string or a sequence of strings.  Returns ``None`` for
+    ``None`` input (meaning "all methods allowed").  Raises ``ValueError`` if
+    the result is empty.
+    """
+    if methods is None:
+        return None
+    if isinstance(methods, str):
+        methods = [methods]
+    normalized = {m.strip().upper() for m in methods if m.strip()}
+    if not normalized:
+        raise ValueError("Allowed domain methods must not be empty when provided.")
+    return tuple(sorted(normalized))
+
+
+def _normalize_allowed_domain(value: Any) -> AllowedDomain:
+    """Coerce a flexible allowed-domain input into a normalized :class:`AllowedDomain`.
+
+    Accepts a domain string, a ``(target, methods)`` tuple, or an
+    :class:`AllowedDomain`.  Raises ``ValueError`` for any other shape.
+    """
+    if isinstance(value, str):
+        return AllowedDomain(target=_normalize_domain(value), methods=None)
+    if isinstance(value, AllowedDomain):
+        return AllowedDomain(
+            target=_normalize_domain(value.target),
+            methods=_normalize_methods(value.methods),
+        )
+    if isinstance(value, tuple) and len(value) == 2:
+        target, methods = value
+        return AllowedDomain(
+            target=_normalize_domain(target),
+            methods=_normalize_methods(methods),
+        )
+    raise ValueError(f"Invalid allowed domain entry: {value!r}.")
+
+
+def _normalize_mount_path(mount_path: str) -> str:
+    """Normalize a sandbox mount path to a relative POSIX path under ``/input``.
+
+    Strips a leading ``/input`` component, rejects ``..`` traversal, and returns
+    a ``/``-joined relative path.  Raises ``ValueError`` for empty or escaping
+    paths.
+    """
+    raw = mount_path.strip().replace("\\", "/")
+    if not raw:
+        raise ValueError("mount_path must not be empty.")
+    parts = [p for p in PurePosixPath(raw).parts if p not in {"", "/", "."}]
+    if parts and parts[0] == "input":
+        parts = parts[1:]
+    if any(p == ".." for p in parts):
+        raise ValueError("mount_path must stay within /input.")
+    if not parts:
+        raise ValueError("mount_path must point to a concrete path under /input.")
+    return "/".join(parts)
+
+
+def _normalize_file_mount(value: Any) -> FileMount:
+    """Coerce a flexible file-mount input into a normalized :class:`FileMount`.
+
+    Accepts a path string (same path on host and in sandbox), a
+    ``(host_path, mount_path)`` tuple, or a :class:`FileMount`.  Resolves the
+    host path and validates that it exists.
+    """
+    if isinstance(value, str):
+        host_path, mount_path = value, value
+    elif isinstance(value, FileMount):
+        host_path, mount_path = value.host_path, value.mount_path
+    elif isinstance(value, tuple) and len(value) == 2:
+        host_path, mount_path = value
+    else:
+        raise ValueError(f"Invalid file mount entry: {value!r}.")
+    host = Path(host_path).expanduser().resolve()
+    if not host.exists():
+        raise ValueError(f"File mount host path does not exist: {host}")
+    return FileMount(host_path=host, mount_path=_normalize_mount_path(mount_path))
+
+
+# --------------------------------------------------------------------------- #
+# Thread-confined sandbox worker
+# --------------------------------------------------------------------------- #
+
+class _SandboxWorker:
+    """Single-threaded owner of the Hyperlight sandbox.
+
+    The Hyperlight ``WasmSandbox`` (and its snapshots) are ``unsendable`` in
+    PyO3: they can only be accessed and dropped from the OS thread that created
+    them.  This actor routes every operation through a dedicated single-thread
+    executor so the sandbox is always touched on its owner thread, and the
+    unsendable objects never escape to caller threads.
+
+    Exceptions raised inside worker closures have their traceback dropped on the
+    worker thread (so any PyO3 unsendable locals are released there) and a
+    sanitized copy is re-raised on the caller.
+    """
+
+    __slots__ = ("_executor", "_sandbox", "_snapshot", "_initialized")
+
+    def __init__(self) -> None:
+        """Create the worker with a single-thread executor and no sandbox yet."""
+        self._executor = ThreadPoolExecutor(max_workers=1, thread_name_prefix="hyperlight")
+        self._sandbox: Sandbox | None = None
+        self._snapshot: Any = None
+        self._initialized = False
+
+    def _submit(self, fn: Callable[[], Any]) -> Any:
+        """Run ``fn`` on the owner thread and return its result.
+
+        Exceptions raised inside ``fn`` have their traceback dropped on the
+        worker thread (so any PyO3 unsendable locals are released there) and a
+        sanitized copy is re-raised on the caller.
+        """
+        def _wrapped() -> tuple[bool, Any]:
+            """Run ``fn`` and sanitize any exception's traceback on the worker thread."""
+            try:
+                return True, fn()
+            except BaseException as exc:  # noqa: BLE001 - sanitize and re-raise
+                exc_type = type(exc)
+                exc_args = tuple(str(a) for a in exc.args) if exc.args else (str(exc),)
+                exc.__traceback__ = None
+                del exc
+                return False, (exc_type, exc_args)
+
+        ok, payload = self._executor.submit(_wrapped).result()
+        if ok:
+            return payload
+        exc_type, exc_args = payload
+        try:
+            raise exc_type(*exc_args)
+        except TypeError:
+            raise RuntimeError(f"{exc_type.__name__}: {exc_args}") from None
+
+    def initialize(self, build_fn: Callable[[], Sandbox]) -> None:
+        """Build and install the sandbox on the owner thread.
+
+        ``build_fn`` is invoked with no arguments on the worker thread and must
+        return the :class:`Sandbox` to own.
+        """
+        def _init() -> None:
+            """Build the sandbox and mark the worker initialized (runs on owner thread)."""
+            self._sandbox = build_fn()
+            self._initialized = True
+
+        self._submit(_init)
+
+    def run(self, code: str) -> ExecutionResult:
+        """Run ``code`` in the sandbox on the owner thread and return the result."""
+        return self._submit(lambda: self._sandbox.run(code))  # type: ignore[union-attr]
+
+    def snapshot(self) -> None:
+        """Capture the current state, stored worker-locally for a later restore."""
+        self._submit(lambda: setattr(self, "_snapshot", self._sandbox.snapshot()))  # type: ignore[union-attr]
+
+    def restore(self) -> None:
+        """Restore the most recently captured snapshot on the owner thread."""
+        self._submit(lambda: self._sandbox.restore(self._snapshot))  # type: ignore[union-attr]
+
+    def get_output_files(self) -> list[str]:
+        """List output filenames written by the guest, on the owner thread."""
+        return self._submit(lambda: list(self._sandbox.get_output_files()))  # type: ignore[union-attr]
+
+    def output_path(self) -> str | None:
+        """Return the host output directory path, on the owner thread."""
+        return self._submit(lambda: self._sandbox.output_path())  # type: ignore[union-attr]
+
+    def _dispose_on_worker(self) -> None:
+        """Drop the unsendable sandbox/snapshot on the owner thread."""
+        sandbox = self._sandbox
+        self._sandbox = None
+        self._snapshot = None
+        close = getattr(sandbox, "close", None) or getattr(sandbox, "shutdown", None)
+        if callable(close):
+            try:
+                close()
+            except Exception:  # noqa: BLE001 - best-effort teardown
+                pass
+        del sandbox
+
+    def dispose(self) -> None:
+        """Release the sandbox on its owner thread (blocking; for explicit close)."""
+        if self._initialized:
+            try:
+                self._executor.submit(self._dispose_on_worker).result()
+            except RuntimeError:
+                pass
+            finally:
+                self._initialized = False
+        self._executor.shutdown(wait=False, cancel_futures=False)
+
+    def __del__(self) -> None:
+        """Route the unsendable sandbox drop to its owner thread, non-blocking.
+
+        Without this, when the worker is garbage-collected on an arbitrary thread
+        (e.g. the main thread at script exit), the PyO3 ``WasmSandbox`` would be
+        dropped on the wrong thread and raise ``RuntimeError: ... unsendable ...``.
+        """
+        if getattr(self, "_initialized", False):
+            executor = getattr(self, "_executor", None)
+            if executor is not None:
+                try:
+                    executor.submit(self._dispose_on_worker)
+                except Exception:  # noqa: BLE001 - interpreter may be shutting down
+                    pass
+                try:
+                    executor.shutdown(wait=False, cancel_futures=False)
+                except Exception:  # noqa: BLE001
+                    pass
+
+
+# --------------------------------------------------------------------------- #
+# The LangChain tool
+# --------------------------------------------------------------------------- #
+
+class HyperlightSandboxTool(BaseTool):
+    """A LangChain tool that runs code in a Hyperlight micro VM.
+
+    Parameters mirror the :class:`hyperlight_sandbox.Sandbox` constructor plus
+    LangChain-friendly conveniences.  The underlying sandbox is created lazily on
+    the first invocation and reused for subsequent calls (cold-start latency is
+    paid once).
+
+    Examples:
+        >>> tool = HyperlightSandboxTool(host_tools={"add": lambda a=0, b=0: a + b})
+        >>> tool.invoke({"code": "print(call_tool('add', a=3, b=4))"})
+    """
+
+    name: str = "execute_code"
+    description: str = DEFAULT_DESCRIPTION
+    args_schema: type[BaseModel] = SandboxCodeInput
+
+    # --- Sandbox configuration (forwarded to hyperlight_sandbox.Sandbox) ---
+    backend: str = "wasm"
+    module: str = "python_guest.path"
+    module_path: str | None = None
+    input_dir: str | None = None
+    output_dir: str | None = None
+    temp_output: bool = False
+    heap_size: str | None = None
+    stack_size: str | None = None
+
+    # --- Host capabilities exposed to the guest ---
+    host_tools: dict[str, Callable[..., Any]] = Field(default_factory=dict, exclude=True)
+    allowed_domains: dict[str, tuple[str, ...] | None] = Field(default_factory=dict)
+    file_mounts: dict[str, str] = Field(default_factory=dict)
+
+    _worker: _SandboxWorker | None = PrivateAttr(default=None)
+    _staged_input_dir: Any = PrivateAttr(default=None)
+
+    @field_validator("allowed_domains", mode="before")
+    @classmethod
+    def _coerce_allowed_domains(cls, value: Any) -> dict[str, tuple[str, ...] | None]:
+        """Pydantic ``before`` validator: normalize flexible allowed-domain input.
+
+        Accepts a dict, a single entry, or a sequence of entries (string, tuple,
+        or :class:`AllowedDomain`) and returns a normalized ``{target: methods}``
+        dict.
+        """
+        if value is None:
+            return {}
+        if isinstance(value, dict):
+            return {
+                _normalize_domain(k): _normalize_methods(v)
+                for k, v in value.items()
+            }
+        if isinstance(value, (str, AllowedDomain, tuple)):
+            value = [value]
+        result: dict[str, tuple[str, ...] | None] = {}
+        for entry in value:
+            domain = _normalize_allowed_domain(entry)
+            result[domain.target] = domain.methods
+        return result
+
+    @field_validator("file_mounts", mode="before")
+    @classmethod
+    def _coerce_file_mounts(cls, value: Any) -> dict[str, str]:
+        """Pydantic ``before`` validator: normalize flexible file-mount input.
+
+        Accepts a dict, a single entry, or a sequence of entries (string, tuple,
+        or :class:`FileMount`) and returns a normalized ``{mount_path: host_path}``
+        dict.
+        """
+        if value is None:
+            return {}
+        if isinstance(value, dict):
+            return {_normalize_mount_path(k): str(Path(v).expanduser().resolve()) for k, v in value.items()}
+        if isinstance(value, (str, FileMount, tuple)):
+            value = [value]
+        result: dict[str, str] = {}
+        for entry in value:
+            mount = _normalize_file_mount(entry)
+            result[mount.mount_path] = str(mount.host_path)
+        return result
+
+    # -- worker / sandbox lifecycle -----------------------------------------
+
+    def _get_worker(self) -> _SandboxWorker:
+        """Return the (lazily created) thread-confined worker.
+
+        On first call, creates the worker and builds the sandbox on its owner
+        thread.  Subsequent calls return the same worker.
+        """
+        if self._worker is None:
+            self._worker = _SandboxWorker()
+            self._worker.initialize(self._build_sandbox)
+        return self._worker
+
+    def _build_sandbox(self) -> Sandbox:
+        """Build and configure the sandbox.  Runs on the worker thread."""
+        input_dir = self.input_dir
+        if self.file_mounts:
+            input_dir = self._stage_file_mounts()
+
+        sandbox = Sandbox(
+            backend=self.backend,
+            module=self.module,
+            module_path=self.module_path,
+            input_dir=input_dir,
+            output_dir=self.output_dir,
+            temp_output=self.temp_output,
+            heap_size=self.heap_size,
+            stack_size=self.stack_size,
+        )
+        for name, fn in self.host_tools.items():
+            sandbox.register_tool(name, fn)
+        for target, methods in self.allowed_domains.items():
+            sandbox.allow_domain(target, list(methods) if methods is not None else None)
+        return sandbox
+
+    def _stage_file_mounts(self) -> str:
+        """Copy mounted host paths into a managed temporary ``/input`` tree."""
+        staged = tempfile.mkdtemp(prefix="hyperlight-input-")
+        self._staged_input_dir = staged
+        for mount_path, host_path in self.file_mounts.items():
+            src = Path(host_path)
+            dst = Path(staged) / mount_path
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            if src.is_dir():
+                shutil.copytree(src, dst, dirs_exist_ok=True)
+            else:
+                shutil.copy2(src, dst)
+        return staged
+
+    # -- BaseTool interface --------------------------------------------------
+
+    def _run(self, code: str) -> str:
+        """Execute ``code`` in the micro VM and return a formatted result."""
+        result = self._get_worker().run(code)
+        return self._format_result(result)
+
+    async def _arun(self, code: str) -> str:
+        """Async variant; the native sandbox call is blocking, so run in a thread."""
+        return await asyncio.to_thread(self._run, code)
+
+    @staticmethod
+    def _format_result(result: ExecutionResult) -> str:
+        """Render an :class:`ExecutionResult` as a stable, human-readable string."""
+        parts: list[str] = []
+        if result.stdout:
+            parts.append(f"[stdout]\n{result.stdout.rstrip()}")
+        if result.stderr:
+            parts.append(f"[stderr]\n{result.stderr.rstrip()}")
+        parts.append(f"[exit_code] {result.exit_code}")
+        return "\n".join(parts)
+
+    # -- Convenience helpers -------------------------------------------------
+
+    def snapshot(self) -> None:
+        """Capture the current sandbox state for a later :meth:`restore`.
+
+        The snapshot is held worker-locally (it is a PyO3 ``unsendable`` object),
+        so it is never exposed to the caller.
+        """
+        self._get_worker().snapshot()
+
+    def restore(self) -> None:
+        """Restore the most recently captured snapshot."""
+        self._get_worker().restore()
+
+    def get_output_files(self) -> list[str]:
+        """List filenames written by the guest to the output directory."""
+        return self._get_worker().get_output_files()
+
+    def output_path(self) -> str | None:
+        """Return the host path of the sandbox output directory (if configured)."""
+        return self._get_worker().output_path()
+
+    def close(self) -> None:
+        """Release the sandbox on its owner thread and clean up staged files."""
+        if self._worker is not None:
+            self._worker.dispose()
+            self._worker = None
+        if self._staged_input_dir is not None:
+            shutil.rmtree(self._staged_input_dir, ignore_errors=True)
+            self._staged_input_dir = None
+
+
+def create_hyperlight_tool(
+    *,
+    name: str = "execute_code",
+    description: str | None = None,
+    host_tools: dict[str, Callable[..., Any]] | None = None,
+    allowed_domains: Any = None,
+    file_mounts: Any = None,
+    **sandbox_kwargs: Any,
+) -> HyperlightSandboxTool:
+    """Create a :class:`HyperlightSandboxTool` from configuration.
+
+    The sandbox is always created and owned by the tool on a dedicated thread,
+    which is required because the Hyperlight ``WasmSandbox`` is ``unsendable``
+    (it may only be touched from the thread that created it).
+
+    Args:
+        name: Tool name exposed to the agent.
+        description: Optional override for the tool description.
+        host_tools: Mapping of tool name -> host callable, registered with the sandbox.
+        allowed_domains: A domain string, ``(target, methods)`` tuple, ``AllowedDomain``,
+            or a sequence of any of these.
+        file_mounts: A path string, ``(host_path, mount_path)`` tuple, ``FileMount``,
+            or a sequence of any of these.
+        **sandbox_kwargs: Forwarded to :class:`hyperlight_sandbox.Sandbox`
+            (e.g. ``backend``, ``module``, ``input_dir``, ``output_dir``).
+
+    Returns:
+        A configured :class:`HyperlightSandboxTool`.
+    """
+    return HyperlightSandboxTool(
+        name=name,
+        description=description or DEFAULT_DESCRIPTION,
+        host_tools=host_tools or {},
+        allowed_domains=allowed_domains,
+        file_mounts=file_mounts,
+        **sandbox_kwargs,
+    )

langchain_hyperlight-0.1.0.dist-info/METADATA

@@ -0,0 +1,304 @@
+Metadata-Version: 2.5
+Name: langchain-hyperlight
+Version: 0.1.0
+Summary: LangChain tool for executing untrusted code in Microsoft Hyperlight micro VMs (experimental, AI-generated)
+Project-URL: Homepage, https://github.com/wildaces215/langchain-hyperlight
+Project-URL: Repository, https://github.com/wildaces215/langchain-hyperlight
+Project-URL: Documentation, https://github.com/wildaces215/langchain-hyperlight#readme
+Author: theph03*nix215
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: code-execution,hyperlight,langchain,micro-vm,sandbox,wasm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: hyperlight-sandbox[python-guest,wasm]>=0.5.0
+Requires-Dist: langchain-core>=0.3.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: js
+Requires-Dist: hyperlight-sandbox[hyperlight-js,javascript-guest]>=0.5.0; extra == 'js'
+Description-Content-Type: text/markdown
+
+> ⚠️ **VIBE-CODED — AI-GENERATED, NOT PRODUCTION-READY**
+>
+> This project was written by an AI ("vibe coded"). It is **experimental** and has had
+> **no security review, fuzzing, or adversarial testing**. It has only been smoke-tested
+> on **Linux (x86_64)**. **Use at your own risk** — do not rely on it for anything
+> security-sensitive or mission-critical. See [Limitations](#limitations).
+
+# langchain-hyperlight
+
+A [LangChain](https://www.langchain.com/) tool that executes untrusted code inside a
+[Microsoft Hyperlight](https://github.com/hyperlight-dev/hyperlight) **micro virtual machine**.
+
+Hyperlight is a lightweight Virtual Machine Manager (VMM) designed to be embedded within
+applications. It runs untrusted code in hardware-isolated micro VMs (KVM, MSHV, or Hyper-V)
+with very low latency and minimal overhead. This package exposes that capability to LangChain
+agents as a standard tool, so an LLM can safely run arbitrary code without touching the host.
+
+## Features
+
+- **Hardware isolation** — code runs in a micro VM, not on the host.
+- **Host tool dispatch** — register host callables that guest code invokes by name with
+  schema-validated arguments (`call_tool(...)`).
+- **Capability-based file access** — read-only `/input`, writable `/output`, strict path isolation.
+- **Network allow-listing** — network is off by default; opt in per-domain and per-HTTP-verb.
+- **Snapshot / restore** — capture and rewind sandbox state.
+- **Lazy sandbox creation** — constructing the tool is cheap; the micro VM boots on first use.
+
+## Limitations
+
+This is an early-stage, AI-generated integration. Be aware of the following before adopting it.
+
+### Platform
+
+- **x86_64 only.** Hyperlight currently targets x86_64; there are no `aarch64` (ARM) wheels.
+  Raspberry Pi, Apple Silicon, and AWS Graviton are unsupported.
+- **glibc 2.34+.** The Rust backend ships `manylinux_2_34_x86_64` wheels, so it needs a recent
+  glibc. Works on Ubuntu 22.04+, Debian 12+, Fedora 36+, RHEL 9+. Does **not** work on
+  Ubuntu 20.04, Debian 11, RHEL 8, or musl-based distros (Alpine, Void) without building the
+  Rust backend from source.
+- **Python 3.10–3.14.**
+- **A hypervisor is required at runtime:** KVM (`/dev/kvm`) or MSHV on Linux.
+- **Tested on Linux only.** This package has only been tested on **Linux (x86_64)**. It is
+  **not tested on Windows or macOS** — use on those platforms at your own risk.
+
+### Security model
+
+- The micro VM isolates the *guest code* you run, but any **host tools you register via
+  `host_tools` run with full host privileges** inside the sandbox's `call_tool(...)`. Only
+  register callables you trust, and treat their inputs as untrusted.
+- Network is off by default and gated by `allowed_domains`, but an allow-listed domain is
+  reachable by any code running in the sandbox.
+- This package has **not** been security-reviewed. Do not treat it as a hardened sandbox
+  boundary without your own audit.
+
+### Maturity
+
+- **Alpha / vibe-coded.** No fuzzing, no adversarial testing, no cross-platform CI matrix.
+- The thread-confinement worker (required because the `WasmSandbox` is `unsendable` in PyO3)
+  is correct for the tested paths but has not been stress-tested under heavy concurrency.
+- `host_tools` accepts plain Python callables only — it does not yet wrap LangChain
+  `BaseTool` instances directly.
+
+## Installation
+
+> **Platform support:** this package is **tested on Linux (x86_64) only**. It is
+> **not tested on Windows or macOS** — install and use on those platforms at your own risk.
+
+```shell
+pip install langchain-hyperlight
+```
+
+This pulls in `langchain-core` and `hyperlight-sandbox[wasm,python_guest]`.
+
+> **Prerequisite:** a working hypervisor is required at *runtime* (not at install time):
+>
+> - **Linux:** KVM (`/dev/kvm`) or MSHV (`/dev/mshv`)
+
+## Quick start
+
+```python
+from langchain_hyperlight import HyperlightSandboxTool
+
+tool = HyperlightSandboxTool(
+    host_tools={
+        "add": lambda a=0, b=0: a + b,
+        "greet": lambda name="world": f"Hello, {name}!",
+    },
+    allowed_domains={"https://httpbin.org": ["GET"]},
+)
+
+result = tool.invoke({
+    "code": """
+total = call_tool('add', a=3, b=4)
+greeting = call_tool('greet', name='James')
+print(f"3 + 4 = {total}")
+print(greeting)
+""",
+})
+print(result)
+```
+
+### Using it inside an agent
+
+```python
+from langchain_core.tools import create_agent  # or your agent of choice
+
+agent = create_agent(model, tools=[tool])
+```
+
+The tool is a standard `langchain_core.tools.BaseTool`, so it works with any LangChain agent
+runtime (LangGraph, `create_agent`, `AgentExecutor`, etc.).
+
+## Relationship to Microsoft's Agent Framework
+
+Microsoft ships an official Hyperlight integration for *its own* Agent Framework:
+[`agent-framework-hyperlight`](https://github.com/microsoft/agent-framework/tree/main/python/packages/hyperlight)
+(`HyperlightExecuteCodeTool` / `HyperlightCodeActProvider`). This package is the **LangChain**
+equivalent: it targets `langchain_core.tools.BaseTool` and mirrors the same concepts — the
+`execute_code` tool name, `file_mounts`, `allowed_domains`, and host-tool dispatch via
+`call_tool(...)` — so the mental model transfers directly.
+
+### Thread safety
+
+The Hyperlight `WasmSandbox` is `unsendable` in PyO3: it may only be accessed and dropped from
+the OS thread that created it, or it panics. This tool routes every sandbox operation through a
+dedicated single-threaded worker, so it is safe to call from arbitrary threads and event loops
+(including LangChain's async `ainvoke`).
+
+## Guest environment
+
+By default the sandbox runs **Python**. Inside the guest, these built-ins are available:
+
+| Function | Purpose |
+| --- | --- |
+| `call_tool(name, **kwargs)` | Invoke a host-registered tool by name |
+| `http_get(url)` / `http_post(url, body=...)` | HTTP to allow-listed domains only |
+| `read_file(path)` / `write_file(path, data)` | Capability-based file I/O (`/input`, `/output`) |
+
+## Configuration
+
+`HyperlightSandboxTool` forwards its constructor arguments to
+[`hyperlight_sandbox.Sandbox`](https://github.com/hyperlight-dev/hyperlight-sandbox):
+
+| Argument | Default | Description |
+| --- | --- | --- |
+| `backend` | `"wasm"` | `"wasm"` (Python/JS guest) or `"hyperlight-js"` |
+| `module` | `"python_guest.path"` | Packaged guest module reference |
+| `module_path` | `None` | Explicit path to a `.aot`/`.wasm` guest |
+| `input_dir` / `output_dir` | `None` | Host directories mounted into the guest |
+| `temp_output` | `False` | Use a temporary output directory |
+| `heap_size` / `stack_size` | `None` | Guest memory limits (e.g. `"25Mi"`) |
+| `host_tools` | `{}` | `{name: callable}` exposed to the guest |
+| `allowed_domains` | `{}` | Network allow-list (see below) |
+| `file_mounts` | `{}` | Host paths staged into the guest `/input` tree (see below) |
+
+`allowed_domains` accepts a domain string, a `(target, methods)` tuple, an `AllowedDomain`, or a
+sequence of any of these:
+
+```python
+from langchain_hyperlight import AllowedDomain
+
+tool = HyperlightSandboxTool(
+    allowed_domains=[
+        "api.github.com",                              # all methods
+        ("internal.example.com", "GET"),               # GET only
+        AllowedDomain("https://httpbin.org", ("GET", "POST")),
+    ],
+)
+```
+
+`file_mounts` accepts a path string (same path on host and in the sandbox), a
+`(host_path, mount_path)` tuple, a `FileMount`, or a sequence of any of these. Mounted files are
+staged into a managed temporary `/input` tree and are readable in the guest via `read_file(...)`:
+
+```python
+from langchain_hyperlight import FileMount
+
+tool = HyperlightSandboxTool(
+    file_mounts=[
+        "/host/data",                                  # -> /input/data
+        ("/host/models", "models"),                    # -> /input/models
+        FileMount("/host/config", "config"),           # -> /input/config
+    ],
+)
+```
+
+The `create_hyperlight_tool()` factory is a thin convenience over the same constructor:
+
+```python
+from langchain_hyperlight import create_hyperlight_tool
+
+tool = create_hyperlight_tool(
+    host_tools={"add": lambda a=0, b=0: a + b},
+    allowed_domains=["api.github.com"],
+)
+```
+
+> **Note:** the tool always creates and owns its sandbox on a dedicated thread. Do not
+> construct a `hyperlight_sandbox.Sandbox` yourself and try to share it across threads — the
+> underlying `WasmSandbox` is `unsendable` and will panic if touched from a different thread
+> than the one that created it. The tool manages this confinement for you.
+
+## Running on Bluefin / Fedora Silverblue (immutable)
+
+Bluefin is an immutable Fedora (Silverblue) image. The package itself installs normally into a
+virtual environment, but the **KVM hypervisor** must be available on the host:
+
+1. **Verify virtualization is enabled** in firmware (AMD-V / Intel VT-x):
+
+   ```shell
+   grep -E 'vmx|svm' /proc/cpuinfo
+   ```
+
+2. **Ensure the KVM device exists** (the `kvm_amd`/`kvm_intel` module is loaded):
+
+   ```shell
+   ls -l /dev/kvm
+   ```
+
+   If it is missing, the module is not loaded. On Bluefin this is usually a firmware/BIOS
+   setting (enable SVM/VT-x) rather than a package issue, since the kernel ships KVM.
+
+3. **Add your user to the `kvm` group** so you can open `/dev/kvm` without root:
+
+   ```shell
+   sudo usermod -aG kvm $USER
+   # log out and back in, then verify:
+   groups
+   ```
+
+4. **Install the package in a venv** (never layer Python packages system-wide on an immutable
+   image — use `uv`, `pipx`, or a `distrobox`/`toolbox` container):
+
+   ```shell
+   uv venv .venv
+   uv pip install --python .venv/bin/python langchain-hyperlight
+   ```
+
+   For a fully isolated dev environment, `distrobox` is the idiomatic Bluefin approach:
+
+   ```shell
+   distrobox create --name hyperlight-dev --image fedora:latest
+   distrobox enter hyperlight-dev
+   ```
+
+## Development
+
+```shell
+uv venv .venv
+uv pip install --python .venv/bin/python -e ".[dev]"
+.venv/bin/pytest
+```
+
+Tests that require a hypervisor are skipped automatically when `/dev/kvm` (or `/dev/mshv`) is
+unavailable.
+
+## References
+
+- [Hyperlight project site](https://hyperlight.org/) — official docs and getting-started guide
+- [hyperlight-dev/hyperlight](https://github.com/hyperlight-dev/hyperlight) — the VMM itself
+- [hyperlight-dev/hyperlight-sandbox](https://github.com/hyperlight-dev/hyperlight-sandbox) — the
+  multi-backend sandbox framework this tool wraps
+- [hyperlight-dev/hyperlight-wasm](https://github.com/hyperlight-dev/hyperlight-wasm) — the Wasm
+  component backend
+- [Microsoft Agent Framework Hyperlight integration](https://github.com/microsoft/agent-framework/tree/main/python/packages/hyperlight) —
+  the canonical `agent-framework-hyperlight` package this tool mirrors
+- [Microsoft Learn: Hyperlight integration](https://learn.microsoft.com/en-us/agent-framework/integrations/hyperlight)
+- [`hyperlight-sandbox` on PyPI](https://pypi.org/project/hyperlight-sandbox/)
+
+## License
+
+Apache-2.0. Hyperlight is a [CNCF](https://cncf.io/) sandbox project.

langchain_hyperlight-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+langchain_hyperlight/__init__.py,sha256=j_0iVrivN_JYBU7t8kTCsiPVBjmfvJEQDuzsB6fBX-g,919
+langchain_hyperlight/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langchain_hyperlight/tool.py,sha256=02CTVY58JnLP5WCANn7KFAbo2oHm1m4SB2Woc0zw1o8,22219
+langchain_hyperlight-0.1.0.dist-info/METADATA,sha256=ymj4o-PbHI1Q8hDlWMx9mXndpX2KYhBI9HJCBQfB8m0,12525
+langchain_hyperlight-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+langchain_hyperlight-0.1.0.dist-info/licenses/LICENSE,sha256=fs2M4dMLiqJiMvXHyHjMpTvCc1R85S8WePlVFUdG5k8,709
+langchain_hyperlight-0.1.0.dist-info/RECORD,,

langchain_hyperlight-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

langchain_hyperlight-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,15 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.