Nanocodex

Nanocodex is an open-source, headless SDK authored by gakonst that embeds a complete OpenAI Responses agent loop directly into Rust, JavaScript, and Python applications. Released under MIT OR Apache-2.0, version 0.5.0 shipped on August 12, 2026, and the repository has accumulated 430 stars and 50 forks since its creation in July 2026. It is not a provider abstraction or an app server — the public product is an embeddable agent with an owned lifecycle that callers drive through a cheap, cloneable command handle.

What It Is

Nanocodex is a multi-language agent SDK that wraps the OpenAI Responses WebSocket API into a fully managed, owned lifecycle. The core is written in Rust and exposed to JavaScript (Node, browser, WASM) and Python via native bindings. The key design premise is that callers should not have to rebuild prompt ordering, response-ID threading, tool-result routing, compaction, reconnect replay, or subprocess cleanup — Nanocodex owns all of that. The caller keeps the interface, data, memory, infrastructure, and policy. Supported models are the gpt-5.6-sol family (sol default, terra, and luna selections).

Architecture and Module Boundaries

The crate is structured as an Alloy-style facade (nanocodex) over focused lower-level crates:

• nanocodex-agent — owned driver, turns, results, events, history policy, snapshots, compaction, branches, and cancellation
• nanocodex-oai-api — OpenAI auth, typed Responses and Realtime boundaries, persistent transports, managed context, retry, pricing, and Tower client
• nanocodex-tools — tool contract, standard workspace tools, shell/process lifecycle, Code Mode, deferred BM25 tool search, MCP (stdio and Streamable HTTP), and remote dispatch
• nanocodex-observability — optional full-fidelity tracing and application-owned OpenTelemetry/OTLP initialization
• nanocodex-durability — optional append-only execution journal with memory, SQLite, and Postgres stores

Applications that only need a managed OpenAI conversation can use the lower-level OpenAi → Session → ResponseTurn → Response API without adopting agent policy.

Multi-Language Deployment Model

Each language path runs the same Rust-owned agent lifecycle:

• Rust: cargo add nanocodex; the primary surface with the full API
• Node.js 22.13+: npm install nanocodex; viem-style Agent, Actions, and Transport namespaces
• Browser/WASM: runs the Rust agent in a Worker with OPFS filesystem persistence, Pyodide, wasm-clang, browser Git, and optional subagent trees
• Python 3.11+: native PyO3 binding built with Maturin; blocking result waits release the GIL
• Native CLI/TUI: installable on Apple Silicon macOS and x86-64 glibc Linux via a curl installer; built on Ratatui

The JavaScript and Python bindings expose the same turn results, typed events, history, snapshots, branches, and shutdown semantics as the Rust API.

Tools, Code Mode, and MCP

Tools are caller-owned capabilities registered via the typed Tool trait or the #[tool] attribute macro on async Rust functions. The default native workspace runtime supplies bounded exec_command, retained write_stdin sessions, Rust-verified apply_patch, view_image, planning, web search, and image generation. Code Mode presents one compositional JavaScript execution tool to the model; inside a cell, code can loop, branch, fan out with Promise.all, and call typed tools through await tools.<name>(...). MCP is part of the native tools crate — stdio and Streamable HTTP servers are discovered in the background, deferred tools are found with BM25 tool_search, and OAuth persistence, allow/deny lists, bounded concurrent startup, and hot reload are managed at that boundary.

Update: v0.5.0

Version 0.5.0 was published to crates.io on August 12, 2026, and is 100% documented on docs.rs. The release stabilizes the four published crates (nanocodex, nanocodex-agent, nanocodex-oai-api, nanocodex-tools) and the optional nanocodex-observability. Experimental crates — browser, VM, voice, egress, and eval — remain workspace members passing all CI gates but are not yet published to crates.io. The repository's retained benchmark evidence includes a PR #50 release gate where the project reports 39/39 latency gates passed and a 97.879% model-time ratio across a paired 10-turn plus three-fork workload.