# langchain-ai/langchain-sandbox architecture

> Architecture diagram of the GitHub repository langchain-ai/langchain-sandbox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/langchain-ai/langchain-sandbox
- Repository: https://github.com/langchain-ai/langchain-sandbox

## Overview

##### Project type and purpose
- This is a language-agnostic sandboxing library (“LangChain Sandbox”) that allows Python code to run securely in a local, in-memory Pyodide (WebAssembly) environment invoked from Python via a Deno-based JavaScript/TypeScript module.
- It exposes a Python API (`PyodideSandbox`, `PyodideSandboxTool`) and integrates with LangChain/LangGraph agents as a tool for safe execution of untrusted code.

##### File structure
- Top-level: `.github/` (CI, lint, release workflows), `examples/`, `libs/`.
- `libs/pyodide-sandbox-js`: a standalone Deno project (TypeScript) implementing the core WebAssembly sandbox.
- `libs/sandbox-py`: a Python package wrapping and driving the JS sandbox via subprocess calls. Contains `langchain_sandbox/pyodide.py` (wrapper logic), `pyproject.toml`, and unit tests.

##### README for additional insights
- Two main components:
- **pyodide-sandbox-js** (Deno + TypeScript + Pyodide WASM)
- **sandbox-py** (Python wrapper, uses subprocess to invoke the JS sandbox)
- Usage patterns: direct Python API, LangChain tool, LangGraph agent integration (stateful vs. stateless).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client/Application" 
        direction TB
        CodeAct["CodeAct Agent<br/>(examples/codeact_agent.py)"]:::external
        ReactAgent["React Agent<br/>(examples/react_agent.py)"]:::external
    end

    %% Python Wrapper Layer
    subgraph "Python Wrapper (sandbox-py)" 
        direction TB
        Init["__init__.py"]:::python
        PyodideSandbox["PyodideSandbox<br/>(pyodide.py)"]:::python
        PyodideSandboxTool["PyodideSandboxTool<br/>(pyodide.py)"]:::python
        Pyproject["pyproject.toml"]:::data
        WrapperReadme["README.md"]:::data
        Tests["test_pyodide_sandbox.py"]:::python
        SessionState["Session State Store<br/>(pickle bytes)"]:::data
    end

    %% Subprocess Bridge
    Bridge["Subprocess Bridge<br/>(JSON over std-io)"]:::external

    %% Deno Sandbox Layer
    subgraph "Deno Sandbox (pyodide-sandbox-js)"
        direction TB
        MainTS["main.ts"]:::js
        DenoConfig["deno.json"]:::js
        JSPkg["package.json"]:::js
        JSReadme["README.md"]:::data
        MainTest["main_test.ts"]:::js
        subgraph "Pyodide WASM Runtime"
            direction TB
            PyodideWASM["Pyodide WebAssembly Module"]:::wasm
        end
        ExternalNet["httpx AsyncClient<br/>(if allow_net)"]:::external
    end

    %% Flow Connections
    CodeAct -->|"calls API"| PyodideSandboxTool
    ReactAgent -->|"calls API"| PyodideSandboxTool
    PyodideSandboxTool -->|"wraps"| PyodideSandbox
    PyodideSandbox -->|"spawns deno subprocess"| Bridge
    Bridge -->|"JSON over std-io"| MainTS
    MainTS -->|"loads"| PyodideWASM
    MainTS -->|"executes code"| PyodideWASM
    PyodideWASM -->|"return result"| MainTS
    MainTS -->|"returns JSON"| Bridge
    Bridge -->|"reads JSON"| PyodideSandbox
    PyodideSandbox -->|"returns result, session_bytes"| SessionState
    PyodideSandbox -->|"returns result"| PyodideSandboxTool

    %% Click Events
    click CodeAct "https://github.com/langchain-ai/langchain-sandbox/blob/main/examples/codeact_agent.py"
    click ReactAgent "https://github.com/langchain-ai/langchain-sandbox/blob/main/examples/react_agent.py"
    click Init "https://github.com/langchain-ai/langchain-sandbox/blob/main/libs/sandbox-py/langchain_sandbox/__init__.py"
    click PyodideSandbox "https://github.com/langchain-ai/langchain-sandbox/blob/main/libs/sandbox-py/langchain_sandbox/pyodide.py"
    click PyodideSandboxTool "https://github.com/langchain-ai/langchain-sandbox/blob/main/libs/sandbox-py/langchain_sandbox/pyodide.py"
    click Pyproject "https://github.com/langchain-ai/langchain-sandbox/blob/main/libs/sandbox-py/pyproject.toml"
    click WrapperReadme "https://github.com/langchain-ai/langchain-sandbox/blob/main/libs/sandbox-py/README.md"
    click Tests "https://github.com/langchain-ai/langchain-sandbox/blob/main/libs/sandbox-py/tests/unit_tests/test_pyodide_sandbox.py"
    click MainTS "https://github.com/langchain-ai/langchain-sandbox/blob/main/libs/pyodide-sandbox-js/main.ts"
    click DenoConfig "https://github.com/langchain-ai/langchain-sandbox/blob/main/libs/pyodide-sandbox-js/deno.json"
    click JSPkg "https://github.com/langchain-ai/langchain-sandbox/blob/main/libs/pyodide-sandbox-js/package.json"
    click JSReadme "https://github.com/langchain-ai/langchain-sandbox/blob/main/libs/pyodide-sandbox-js/README.md"
    click MainTest "https://github.com/langchain-ai/langchain-sandbox/blob/main/libs/pyodide-sandbox-js/main_test.ts"

    %% Styles
    classDef python fill:#B3DDF2,stroke:#1F77B4,color:#1F77B4
    classDef js fill:#F2D1B3,stroke:#FF7F0E,color:#FF7F0E
    classDef wasm fill:#D6D6D6,stroke:#7F7F7F,color:#7F7F7F
    classDef external fill:#E2F2B3,stroke:#2CA02C,color:#2CA02C
    classDef data fill:#F2B3D6,stroke:#D62728,color:#D62728
```
