nanocodex

Rust · JavaScript · Python · Capabilities · Desktop apps · Evaluation · Deployments · Status

Nanocodex is a headless, library-first SDK for building products around one deliberately supported OpenAI coding-agent stack. It is not a provider abstraction and it is not an app server. The public product is an embeddable agent with an owned lifecycle; the native CLI/TUI, browser apps, Python and JavaScript packages, durable actors, sandboxes, voice client, and evaluation harness are consumers that prove the same contract.

The important difference from assembling a model client and a loop is what the caller does not have to rebuild:

• no passing previous messages, response IDs, or tool results back on every turn;
• no separate state machine for prompt ordering, steering, compaction, reconnect replay, or partially completed responses;
• no coupling between receiving a typed result and consuming an event stream;
• no orphaned shell sessions or subprocess trees when a turn is cancelled; and
• no second orchestration runtime when an agent forks or delegates work.

The interface is deliberately not part of that list. Consume ordered typed events in a native TUI, wterm, xterm.js, React, logs, or something that only your product could have. The included renderers are complete consumers, not a UI protocol every embedding must adopt.

Desktop app

The native SwiftUI/AppKit macOS app is Nanocodex's only desktop app. It owns the tiled workspace, persistent sidebar or top tabs, streamed conversations, agent activity menu bar, and automatic background Mac Hand. Choosing a folder and sending automatically connects compute for that thread. Its managed-agent transport and local, VM, and cloud Hand lifecycle live in @nanocodex/desktop-runtime. The separate mobile Inbox targets iPhone and iPad only.

Build the desktop app with pnpm build:macos after preparing the documented bundled Node runtime. The macOS README describes account setup, native controls, and real-service verification.

Install

Choose the host language; each path runs the Rust-owned agent lifecycle. The Rust crates and core JavaScript nanocodex binding are registry releases. The Python binding and JavaScript companion packages under js/ are currently built from the repository checkout.

# Rust
cargo add nanocodex

# Node.js 22.13+
npm install nanocodex

# Python 3.11+ (from a checkout)
uv venv --python 3.11 py/bindings/.venv
uv pip install --python py/bindings/.venv/bin/python 'maturin>=1.9,<2'
VIRTUAL_ENV="$PWD/py/bindings/.venv" \
  py/bindings/.venv/bin/maturin develop --manifest-path py/bindings/Cargo.toml

The Node.js 22.13+ line is the published package's consumer floor. Developing from this repository uses Rust 1.97, the wasm32-unknown-unknown target, wasm-bindgen-cli 0.2.126, Node.js 24 from .node-version, and pnpm 11.25.0 from the root packageManager field:

rustup toolchain install 1.97
rustup target add wasm32-unknown-unknown --toolchain 1.97
cargo +1.97 install --locked wasm-bindgen-cli --version 0.2.126
corepack enable
pnpm install --frozen-lockfile
pnpm build
pnpm dev

pnpm dev starts the complete Turbo stack through Portless. Local HTTPS needs one-time certificate trust, and binding port 443 may also need administrator approval on macOS. PORTLESS_PORT=1355 pnpm dev avoids the privileged bind and serves the same names with :1355 appended. Portless's proxy is user-global, while app routes, processes, and Wrangler state remain isolated per checkout and worktree.

Or install the native CLI/TUI on Apple Silicon macOS or x86-64 glibc Linux:

curl -fsSL https://nanocodex.paradigm.xyz | bash
nanocodex

The CLI is a production consumer and a useful way to try the agent, not a process protocol that applications must adopt. See bin/nanocodex, the examples index, and the release switcher documentation.

For managed agents, nanocodex2 login signs in with an SMS code and saves an account key; nanocodex2 status verifies it, and nanocodex2 logout removes the local login. nanocodex account login/status/logout manages the same saved account. Account keys are separate from nanocodex auth (ChatGPT provider credentials) and nanocodex login/connect/status/logout (Connect installation grants). See the CLI account sign-in guide for environment overrides, storage, and key revocation.

Linux Hands and VM factories

From a host already signed in to your Nanocodex account:

nanocodex hand add ubuntu@your-server
# SSH configuration aliases and --port work too.

Or install and authenticate directly on the Linux device:

curl -fsSL https://nanocodex.paradigm.xyz | bash
nanocodex update --nightly
nanocodex account login # existing SMS OTP flow
nanocodex hand setup

Both commands install the same native Hand, private desktop, and account-scoped VM factory. Setup currently supports x86-64 Debian/Ubuntu with systemd and sudo. On-device setup can prompt for your administrator password; SSH enrollment uses your existing SSH keys/configuration and requires passwordless sudo. KVM is required for a factory. Use --native-only for a native Hand on a host without KVM. The default factory selector is linux-<hostname>; override it with --factory-name. The default pool has four VMs, each with two vCPUs, 4 GiB RAM, and a retained 16 GiB root disk. --max-vms, --vm-cpus, and --vm-memory-mib configure physical capacity.

The installer verifies release checksums, keeps credentials out of command arguments, and waits for remote registration and the native desktop catalog. nanocodex-hand.service and nanocodex-factory.service start at boot and reconnect independently of SSH. Re-running setup reuses identities and private VM roots under /srv/nanocodex; it never replaces a retained workspace. A setup already enrolled to another account or origin is rejected. --artifacts DIR accepts matching locally built Linux host/guest executables for development.

Rust: start here

Build one agent, submit ordered prompts through its cheap handle, and await a typed result:

use nanocodex::{Nanocodex, OpenAi};

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

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

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

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-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, and gpt-6-astra. Sol remains the SDK default. The managed nanocodex2 terminal and account app select Astra directly for new conversations, as does the native CLI when using ChatGPT authentication. Native API-key and generic SDK defaults remain Sol; sponsored homepage sessions remain 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.

One agent, owned end to end

your application
  ├─ cheap Nanocodex command handle ── prompt / steer / cancel / fork
  ├─ optional typed events ─────────── UI / persistence / telemetry
  ├─ caller-defined tools ──────────── your data and capabilities
  ├─ optional durability layer ─────── total state / recovery / stores
  └─ private driver
       ├─ ordered turns and typed committed history
       ├