nanocodex

Rust · JavaScript · Python · Capabilities · Install · Desktop app · Examples

Nanocodex is a Rust library for embedding frontier agents in products, services, and developer tools. OpenAI and Claude harnesses share an owned lifecycle while keeping their provider-native transports, histories, and tools. Your application controls the interface, authentication, data, infrastructure, and policy.

Rust: start here

Add the Rust crate:

cargo add nanocodex

Configure a reusable runtime, spawn an agent, and await typed turn results:

use nanocodex::{CodexHarness, Nanocodex, OpenAi};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let openai = OpenAi::new(std::env::var("OPENAI_API_KEY")?)?;
    let nano = Nanocodex::builder()
        .openai(CodexHarness::new(openai)
            .code_mode(true)
            .workspace(std::env::current_dir()?))
        .instructions(
            "You are a Rust coding agent. Preserve unrelated work and run relevant tests.",
        )
        .build()?;

    let (agent, _events) = nano.spawn().build().await?;
    let turn = agent.prompt("Find and fix the failing parser test.").await?;
    let result = turn.await?;
    println!("{}", result.final_message());

    nano.shutdown().await?;
    Ok(())
}

Configure both CodexHarness and ClaudeHarness on the same runtime to spawn agents from either family. Each harness owns its tool configuration, Code Mode setting, and workspace defaults; each agent retains an independent conversation. See two harnesses, one runtime for a complete example with model selection, checkpoints, and resume.

The first await accepts and orders the prompt. The returned Turn is both an independently awaitable future for TurnResult and an optional per-turn event stream. The separate AgentEvents value is the session-wide stream; neither stream has to be drained for the result to complete.

Follow-on prompts reuse the same retained typed history, persistent Responses WebSocket, response chain, cache identity, tools, Code Mode worker, and shell sessions. agent.clone() is a constant-time command capability to that same session. shutdown() cancels unfinished work and joins model, tool, transport, and process cleanup.

The runnable source is examples/minimal.rs. For event streaming, steering, cancellation, clean spawning, historical forks, and snapshots, see examples/lifecycle.rs, examples/follow_on.rs, and examples/resume.rs.

Nanocodex supports OpenAI gpt-6.1-sol, gpt-6-luna, and gpt-6-astra. New local (ncl) and managed (nanocodex) conversations default to Sol with xhigh reasoning and fast mode enabled. SDK and account-app conversations default to Astra. Sponsored homepage sessions use Luna. Astra requires at least low reasoning. Nanocodex owns the typed Responses WebSocket behavior for this closed model family. An API-key gateway may prefix the on-wire model identifier with NANOCODEX_MODEL_ID_PREFIX, but that does not create an alternate-provider or arbitrary-model API. See GPT-6 model contracts and upstream sources.

JavaScript: Node, browser, and WASM

The repository's nanocodex package exposes a reusable Nanocodex factory alongside Agent, Actions, and Transport namespaces for Node and browser hosts. The reusable factory and newer browser-tool and subagent exports shown below require a pinned checkout until the next package release. The current registry release contains the core root, Node, browser, and WASM entrypoints. The Rust/WASM engine still owns prompt ordering, history, tool calls, branching, snapshots, and cleanup; JavaScript owns WebSocket creation, credentials, UI, persistence, and ordinary application tools.

Node.js

import { Nanocodex, Transport } from "nanocodex/node";

const nano = await Nanocodex.create({
  backends: {
    codex: {
      transport: Transport.openAi({ apiKey: process.env.OPENAI_API_KEY }),
      workspace: process.cwd(),
      codeMode: true,
      tools: [{
        name: "lookup_issue",
        description: "Return one issue by number.",
        parameters: {
          type: "object",
          properties: { number: { type: "integer" } },
          required: ["number"],
          additionalProperties: false,
        },
        handler: ({ number }) => issueTracker.get(number),
      }],
    },
  },
  instructions: "You are a coding agent. Make focused changes and verify them.",
});

const agent = await nano.spawn();

try {
  const turn = agent.turn.prompt({ input: "Fix issue 42." });
  try {
    const result = await turn.result();
    try {
      console.log(result.finalMessage, await result.usage());
    } finally {
      result.dispose();
    }
  } finally {
    turn.dispose();
  }
} finally {
  await nano.shutdown();
}

Spawn more agents with nano.spawn({ instructions, model, thinking }); each has its own conversation and inherits the configured runtime defaults. Each backend configures its own tools, Code Mode, and workspace. A JS workspace path supplies working-directory context; a filesystem adapter supplies actual rooted file access. Sharing an adapter intentionally shares files. Agent.create remains available for direct single-agent construction.

Use Transport.chatGpt({ subscription }) for a caller-owned ChatGPT subscription or Transport.mpp({ session }) for a caller-owned MPP session. Transport constructors are explicit immutable configurations; Nanocodex does not infer provider portability from them. See the complete JavaScript guide and runnable Node session.

A complete coding workspace in a browser

The browser entrypoint runs the same Rust agent in a Worker. It can open a persistent origin-private filesystem (OPFS) workspace and compose a lazy WASM-backed shell with Python through Pyodide, C/C++ through wasm-clang, browser Git, bounded file commands, web and image tools, artifacts, and the optional Rust subagent tree:

import { Agent, Subagents, Transport } from "nanocodex/browser";
import { browser } from "nanocodex/tools/browser";

const runtime = await browser({
  threadId: "project-42",
  recentImages,
  rememberImage,
});

const agent = await Agent.create({
  transport: Transport.hostManaged({
    websocketUrl: "/api/responses",
    createWebSocket: (url) => new WebSocket(url),
  }),
  filesystem: runtime.filesystem,
  instructions: runtime.instructions,
  executionEnvironment: {
    currentDate: "2026-08-19",
    timezone: "America/Los_Angeles",
    projectInstructions: runtime.projectInstructions,
  },
  tools: [...runtime.tools, ...Subagents.create({ maxConcurrency: 8 })],
});

This is a browser-native workspace: files persist across page, Worker, and agent restarts, and coding can happen without provisioning a server-side sandbox. It is not a claim that OPFS or in-browser execution is an untrusted-code security sandbox. Products that need stronger isolation should provide remote caller-defined tools or use one of the VM/container consumers below.

Browser WebSockets cannot attach OpenAI's authorization header, so Transport.hostManaged expects an application-authorized same-origin relay; the API key stays out of the page and WASM artifact. The one-file browser-cdn consumer needs no bundler or framework. The React + Vite example keeps one persistent agent in a module Worker and forwards ordered events into React.

The package also exposes composable browser-safe web search, image generation, public Parquet/JSONL/Hugging Face dataset queries, and live React artifact tools. Read their exact contracts and bounds in js/nanocodex/README.md.

Bring any terminal or product interface

To attach to a running nanocodex or ncl TUI, use tui list --json and tui connect INSTANCE_UUID --stdio. The rich terminal protocol provides authenticated local/SSH control, replayable events, draft-preserving commands, and UI state.

agent.events.watch() and the intentionally narrow nanocodex-react Context and hooks expose ordered typed data independently from Turn.result(). The SDK does not make a DOM transcript or terminal emulator authoritative. UI frameworks and terminal renderers consume Agent events directly and remain application code. Those events can feed wterm, xterm.js, Ink, a design-system transcript, persistence, or telemetry without adding a UI protocol to the SDK.

The application owns event reduction, ANSI presentation, line editing, prompt history, steering, cancellation, and terminal subscriptions alongside the agent, tools, transport, persistence, authorization, and shutdown. The [Vercel Workflow example](examples/vercel-workflows/READM