# pydantic/monty architecture

> Architecture diagram of the GitHub repository pydantic/monty, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pydantic/monty
- Repository: https://github.com/pydantic/monty

## Overview

Monty is a Rust-based Python sandbox exposed through Rust, Python, and JavaScript bindings, with a CLI and a protocol-driven worker suitable for local or WebSocket hosting. The README demonstrates the main workflow: a host checks out a session, submits code and inputs, services requested host functions, and receives results. The graph preserves the documented sandbox controls, mounts, snapshots, type checking, and telemetry as capabilities. Internal links are limited where excerpts or indexed references show ownership; other implementation details are not inferred from directory names.

Main entry points: [`crates/monty-proto/src/worker.rs`](https://github.com/pydantic/monty/blob/main/crates/monty-proto/src/worker.rs) (Protocol child), [`crates/monty-python/python/pydantic_monty/__init__.py`](https://github.com/pydantic/monty/blob/main/crates/monty-python/python/pydantic_monty/__init__.py) (Python API), [`crates/monty/src/run.rs`](https://github.com/pydantic/monty/blob/main/crates/monty/src/run.rs) (Python interpreter), [`crates/monty-pool/src/checkout.rs`](https://github.com/pydantic/monty/blob/main/crates/monty-pool/src/checkout.rs) (Worker pool)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Host interfaces"]
  node_rust_api["Rust API<br/>[lib.rs]"]
  node_python_api["Python API<br/>[__init__.py]"]
  node_python_os["Python OS access<br/>[os_access.py]"]
  node_js_api["JavaScript API<br/>[session.ts]"]
  node_cli["CLI entry<br/>[main.rs]"]
  node_cli_run["CLI execution<br/>[run.rs]"]
  node_external_fn["Host functions"]
end

subgraph group_execution["Sandbox execution"]
  node_filesystem["Filesystem mounts<br/>[overlay.rs]"]
  node_typecheck["Type checking<br/>[type_check.rs]"]
  node_types["Sandbox types<br/>[os.rs]"]
  node_engine["Python interpreter<br/>[run.rs]"]
  node_heap[("Object heap<br/>[mod.rs]")]
end

subgraph group_protocol["Worker protocol"]
  node_protocol_child["Protocol child<br/>[worker.rs]"]
  node_wire["Wire encoding<br/>[wire.rs]"]
  node_wasm["WASM runtime<br/>[lib.rs]"]
  node_js_worker["JS worker host<br/>[host.ts]"]
  node_js_serve["Worker dispatch<br/>[serve.ts]"]
  node_js_entry["Browser worker entry"]
  node_js_node_entry["Node worker entry<br/>[nodeWorkerEntry.ts]"]
end

subgraph group_operations["Host operations"]
  node_pool["Worker pool<br/>[checkout.rs]"]
  node_worker["Worker transports<br/>[worker.rs]"]
  node_telemetry["Pool telemetry<br/>[mod.rs]"]
end

node_host(("Host application"))
node_network(("WebSocket host"))

node_host -->|"submits code"| node_python_api
node_host -.->|"runs sandbox"| node_rust_api
node_host -.->|"runs sandbox"| node_js_api
node_host -.->|"runs code"| node_cli
node_python_api -.->|"checks out"| node_pool
node_python_api -->|"handles OS access"| node_python_os
node_cli -->|"starts execution"| node_cli_run
node_pool -->|"drives worker"| node_worker
node_pool -->|"records activity"| node_telemetry
node_worker -->|"exchanges requests"| node_protocol_child
node_protocol_child -->|"decodes messages"| node_wire
node_protocol_child -->|"drives session"| node_engine
node_protocol_child -->|"runs type checks"| node_typecheck
node_engine -.->|"stores objects"| node_heap
node_engine -.->|"uses mounts"| node_filesystem
node_engine -.->|"uses sandbox types"| node_types
node_protocol_child -.->|"serves WASM worker"| node_wasm
node_js_api -.->|"uses worker host"| node_js_worker
node_js_entry -->|"starts dispatch"| node_js_serve
node_js_node_entry -->|"starts dispatch"| node_js_serve
node_js_serve -->|"serves requests"| node_js_worker
node_host -->|"provides callbacks"| node_external_fn
node_python_api -->|"services calls"| node_external_fn
node_network -.->|"connects remotely"| node_worker

click node_rust_api "https://github.com/pydantic/monty/blob/main/crates/monty/src/lib.rs"
click node_python_api "https://github.com/pydantic/monty/blob/main/crates/monty-python/python/pydantic_monty/__init__.py"
click node_python_os "https://github.com/pydantic/monty/blob/main/crates/monty-python/python/pydantic_monty/os_access.py"
click node_js_api "https://github.com/pydantic/monty/blob/main/crates/monty-js/ts/session.ts"
click node_cli "https://github.com/pydantic/monty/blob/main/crates/monty-runtime/src/main.rs"
click node_cli_run "https://github.com/pydantic/monty/blob/main/crates/monty-runtime/src/run.rs"
click node_pool "https://github.com/pydantic/monty/blob/main/crates/monty-pool/src/checkout.rs"
click node_worker "https://github.com/pydantic/monty/blob/main/crates/monty-pool/src/worker.rs"
click node_telemetry "https://github.com/pydantic/monty/blob/main/crates/monty-pool/src/telemetry/mod.rs"
click node_protocol_child "https://github.com/pydantic/monty/blob/main/crates/monty-proto/src/worker.rs"
click node_wire "https://github.com/pydantic/monty/blob/main/crates/monty-proto/src/wire.rs"
click node_wasm "https://github.com/pydantic/monty/blob/main/crates/monty-wasm-runtime/src/lib.rs"
click node_filesystem "https://github.com/pydantic/monty/blob/main/crates/monty-fs/src/overlay.rs"
click node_typecheck "https://github.com/pydantic/monty/blob/main/crates/monty-type-checking/src/type_check.rs"
click node_types "https://github.com/pydantic/monty/blob/main/crates/monty-types/src/os.rs"
click node_engine "https://github.com/pydantic/monty/blob/main/crates/monty/src/run.rs"
click node_heap "https://github.com/pydantic/monty/blob/main/crates/monty/src/heap/mod.rs"
click node_js_worker "https://github.com/pydantic/monty/blob/main/crates/monty-js/ts/worker/host.ts"
click node_js_serve "https://github.com/pydantic/monty/blob/main/crates/monty-js/ts/worker/serve.ts"
click node_js_entry "https://github.com/pydantic/monty/blob/main/crates/monty-js/ts/worker/browserWorkerEntry.ts"
click node_js_node_entry "https://github.com/pydantic/monty/blob/main/crates/monty-js/ts/worker/nodeWorkerEntry.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_rust_api,node_python_api,node_python_os,node_js_api,node_cli,node_cli_run,node_external_fn toneBlue
class node_filesystem,node_typecheck,node_types,node_engine,node_heap toneAmber
class node_protocol_child,node_wire,node_wasm,node_js_worker,node_js_serve,node_js_entry,node_js_node_entry toneMint
class node_pool,node_worker,node_telemetry toneRose
class node_host,node_network toneIndigo
```

## Components

### Host interfaces

- [Rust API](https://github.com/pydantic/monty/blob/main/crates/monty/src/lib.rs): `crates/monty/src/lib.rs`
- [Python API](https://github.com/pydantic/monty/blob/main/crates/monty-python/python/pydantic_monty/__init__.py): `crates/monty-python/python/pydantic_monty/__init__.py`
- [Python OS access](https://github.com/pydantic/monty/blob/main/crates/monty-python/python/pydantic_monty/os_access.py): `crates/monty-python/python/pydantic_monty/os_access.py`
- [JavaScript API](https://github.com/pydantic/monty/blob/main/crates/monty-js/ts/session.ts): `crates/monty-js/ts/session.ts`
- [CLI entry](https://github.com/pydantic/monty/blob/main/crates/monty-runtime/src/main.rs): `crates/monty-runtime/src/main.rs`
- [CLI execution](https://github.com/pydantic/monty/blob/main/crates/monty-runtime/src/run.rs): `crates/monty-runtime/src/run.rs`
- **Host functions**

### Sandbox execution

- [Filesystem mounts](https://github.com/pydantic/monty/blob/main/crates/monty-fs/src/overlay.rs): `crates/monty-fs/src/overlay.rs`
- [Type checking](https://github.com/pydantic/monty/blob/main/crates/monty-type-checking/src/type_check.rs): `crates/monty-type-checking/src/type_check.rs`
- [Sandbox types](https://github.com/pydantic/monty/blob/main/crates/monty-types/src/os.rs): `crates/monty-types/src/os.rs`
- [Python interpreter](https://github.com/pydantic/monty/blob/main/crates/monty/src/run.rs): `crates/monty/src/run.rs`
- [Object heap](https://github.com/pydantic/monty/blob/main/crates/monty/src/heap/mod.rs): `crates/monty/src/heap/mod.rs`

### Worker protocol

- [Protocol child](https://github.com/pydantic/monty/blob/main/crates/monty-proto/src/worker.rs): `crates/monty-proto/src/worker.rs`
- [Wire encoding](https://github.com/pydantic/monty/blob/main/crates/monty-proto/src/wire.rs): `crates/monty-proto/src/wire.rs`
- [WASM runtime](https://github.com/pydantic/monty/blob/main/crates/monty-wasm-runtime/src/lib.rs): `crates/monty-wasm-runtime/src/lib.rs`
- [JS worker host](https://github.com/pydantic/monty/blob/main/crates/monty-js/ts/worker/host.ts): `crates/monty-js/ts/worker/host.ts`
- [Worker dispatch](https://github.com/pydantic/monty/blob/main/crates/monty-js/ts/worker/serve.ts): `crates/monty-js/ts/worker/serve.ts`
- [Browser worker entry](https://github.com/pydantic/monty/blob/main/crates/monty-js/ts/worker/browserWorkerEntry.ts): `crates/monty-js/ts/worker/browserWorkerEntry.ts`
- [Node worker entry](https://github.com/pydantic/monty/blob/main/crates/monty-js/ts/worker/nodeWorkerEntry.ts): `crates/monty-js/ts/worker/nodeWorkerEntry.ts`

### Host operations

- [Worker pool](https://github.com/pydantic/monty/blob/main/crates/monty-pool/src/checkout.rs): `crates/monty-pool/src/checkout.rs`
- [Worker transports](https://github.com/pydantic/monty/blob/main/crates/monty-pool/src/worker.rs): `crates/monty-pool/src/worker.rs`
- [Pool telemetry](https://github.com/pydantic/monty/blob/main/crates/monty-pool/src/telemetry/mod.rs): `crates/monty-pool/src/telemetry/mod.rs`

### Other components

- **Host application**
- **WebSocket host**

## Connections

- Host application → Python API: submits code (evidence: `README.md`)
- Host application → Rust API: runs sandbox (evidence: `README.md`)
- Host application → JavaScript API: runs sandbox (evidence: `README.md`)
- Host application → CLI entry: runs code (evidence: `README.md`)
- Python API → Worker pool: checks out
- Python API → Python OS access: handles OS access (evidence: `crates/monty-python/python/pydantic_monty/os_access.py`)
- CLI entry → CLI execution: starts execution (evidence: `crates/monty-runtime/src/main.rs`)
- Worker pool → Worker transports: drives worker (evidence: `crates/monty-pool/src/worker.rs`)
- Worker pool → Pool telemetry: records activity (evidence: `crates/monty-pool/src/telemetry/mod.rs`)
- Worker transports → Protocol child: exchanges requests (evidence: `crates/monty-pool/src/worker.rs`)
- Protocol child → Wire encoding: decodes messages (evidence: `crates/monty-proto/src/worker.rs`)
- Protocol child → Python interpreter: drives session (evidence: `crates/monty-proto/src/worker.rs`)
- Protocol child → Type checking: runs type checks (evidence: `crates/monty-proto/src/worker.rs`)
- Python interpreter → Object heap: stores objects
- Python interpreter → Filesystem mounts: uses mounts
- Python interpreter → Sandbox types: uses sandbox types
- Protocol child → WASM runtime: serves WASM worker (evidence: `crates/monty-proto/src/worker.rs`)
- JavaScript API → JS worker host: uses worker host
- Browser worker entry → Worker dispatch: starts dispatch (evidence: `crates/monty-js/ts/worker/browserWorkerEntry.ts`)
- Node worker entry → Worker dispatch: starts dispatch (evidence: `crates/monty-js/ts/worker/nodeWorkerEntry.ts`)
- Worker dispatch → JS worker host: serves requests (evidence: `crates/monty-js/ts/worker/nodeWorkerEntry.ts`)
- Host application → Host functions: provides callbacks (evidence: `README.md`)
- Python API → Host functions: services calls (evidence: `README.md`)
- WebSocket host → Worker transports: connects remotely (evidence: `README.md`)