The Hybrid, Agent-Native Worker Runtime

1. Mental Model & Architecture

Traditional runtimes (Node.js, Deno, Bun) are designed for heavy server runtimes with deep dependency graphs, long startup times, and hundreds of megabytes of node_modules.

nio-js reimagines workers for the AI agent era:

• Engine Core: Embedded QuickJS-NG (rquickjs 0.14) inside an asynchronous multi-threaded Tokio / Hyper Rust host.
• Sub-Millisecond Cold Starts: Boots in < 1 ms with a clean baseline under 15 MB of RAM.
• Hybrid Compute Offloading: JavaScript handles routing and JSON orchestration. Heavy loops escape to native Rust machine code (/** @native */) or in-process Python AI algorithms via PyO3.
• Zero node_modules: Modules are imported by HTTPS URL (esm.sh / UNPKG) with cryptographic SHA-256 lockfile pinning.
• Tamper-Proof Capsules: Ship a production app in one portable .njs file containing verified bytecode/source, asset tables, and permission envelopes.

┌────────────────────────────────────────────────────────────────────────┐
│                          nio-js Host (Rust)                            │
│                                                                        │
│  ┌───────────────────────┐          ┌───────────────────────────────┐  │
│  │    Tokio HTTP Core    │          │   Multi-Worker Thread Pool    │  │
│  │ (Reusable Port Socket)│          │   (Pinned per CPU Core)       │  │
│  └───────────┬───────────┘          └───────────────┬───────────────┘  │
│              │                                      │                  │
│              ▼                                      ▼                  │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │                       QuickJS Runtime                            │  │
│  │   • Ultra-fast routing ('nio.js')                                │  │
│  │   • Direct string & zero-alloc JSON serialization                │  │
│  └───────────┬──────────────────────────────────────┬───────────────┘  │
│              │                                      │                  │
│              ▼                                      ▼                  │
│  ┌────────────────────────┐              ┌──────────────────────────┐  │
│  │   /** @native */       │              │    In-Process Python     │  │
│  │   Rust Offloading      │              │  (PyO3 CPython Engine)   │  │
│  └────────────────────────┘              └──────────────────────────┘  │
└────────────────────────────────────────────────────────────────────────┘

2. Installation & Quickstart

Automated One-Line Install

For macOS, Linux, and Android (Termux):

curl -fsSL https://raw.githubusercontent.com/nio-labs/nio-js/main/install.sh | bash

For Windows (PowerShell):

irm https://raw.githubusercontent.com/nio-labs/nio-js/main/install.ps1 | iex

Using the NPM Launcher

# Run without installing:
npx @nio-labs/nio-js --help

# Or install globally:
npm install -g @nio-labs/nio-js

Building from Source

git clone https://github.com/nio-labs/nio-js.git
cd nio-js
cargo build --release
sudo install -m 755 target/release/nio-js /usr/local/bin/nio-js

3. CLI Command Reference

4. Route Registration

Services import methods directly from 'nio.js'. Supported verbs include get, post, put, del, patch, head, and options:

import { get, post, del } from 'nio.js';

// 1. Zero-JS constant route: evaluated once, served instantly from Rust host
get('/', 'Hello from nio-js!');

// 2. Synchronous handler
get('/health', () => ({ status: 'ok', uptime: 104 }));

// 3. Asynchronous handler
get('/stats', async () => {
  const dbData = await fetchExternalData();
  return { data: dbData };
});

5. Requests, Responses & Status Codes

Handlers can return primitive values, plain JSON objects, binary buffers, or explicitly formatted responses via reply():

import { post, reply } from 'nio.js';

post('/api/orders', async ({ json }) => {
  const order = await json();
  if (!order.item) {
    return reply(
      { error: 'Field "item" is required' },
      { status: 400, headers: { 'x-service-error': 'VALIDATION_ERR' } }
    );
  }

  return reply({ orderId: 'ord_99', status: 'created' }, { status: 201 });
});

Response Type Coercion Table

6. Parameters & Query Strings

Route parameters use :param syntax and are accessed via req.params. Query strings are parsed into req.query:

import { get, reply } from 'nio.js';

// Matches /api/v1/users/usr_101
get('/api/v1/users/:id', ({ params }) => {
  return { requestedUser: params.id };
});

// Matches /search?role=admin&limit=20
get('/search', ({ query }) => {
  const role = query.role || 'all';
  const limit = Number(query.limit || 10);
  return { role, limit };
});

7. Body Parsing (JSON & Multipart)

Request bodies can be consumed exactly once via .json(), .text(), .blob(), or .formData():

import { post, reply } from 'nio.js';

// 1. JSON Body Parsing
post('/api/users', async ({ json }) => {
  const body = await json();
  return reply({ created: body.name }, { status: 201 });
});

// 2. File & Multipart Uploads
post('/api/upload', async ({ formData }) => {
  const form = await formData();
  const file = form.get('file');

  if (!(file instanceof File)) {
    return reply({ error: 'Missing uploaded file' }, { status: 400 });
  }

  return {
    filename: file.name,
    bytes: file.size,
    preview: (await file.text()).slice(0, 100)
  };
});

8. Native Acceleration (/** @native */)

For CPU-intensive tasks, nio-js provides the /** @native */ directive. Functions marked with this directive bypass QuickJS execution overhead and run compiled Rust machine code:

import { get } from 'nio.js';

/** @native */
function calculateChecksum(iterations: number): number {
  let acc = 0;
  for (let i = 0; i < iterations; i++) {
    acc = (acc * 31 + i) & 0x7fffffff;
  }
  return acc;
}

get('/metrics/compute', ({ query }) => {
  const rounds = Number(query.rounds || 100000);
  return {
    rounds,
    result: calculateChecksum(rounds)
  };
});

9. Multi-Core Worker Pinning

Scale across all CPU cores effortlessly. Every worker maintains its own isolated QuickJS runtime and thread-safe engine instance sharing a single socket listener:

# Run pinned to 8 worker threads on port 3000
nio-js run app.ts --port 3000 --workers 8

10. In-Process Python AI (PyO3)

Execute machine learning, data transforms, and Python algorithms in-process with zero IPC, zero sockets, and zero child processes:

1. Define Python Model (kernel.py)

def classify(query: str) -> str:
    q = query.lower()
    if any(k in q for k in ["bug", "error", "crash", "fix"]):
        return "debugging"
    return "general_task"

2. Import & Execute in TypeScript (server.ts)

import { get } from 'nio.js';
import { classify } from './kernel.py';

get('/classify', ({ query }) => {
  const prompt = query.prompt || 'How do I fix this panic?';
  const category = classify(prompt);
  return { prompt, category };
});

11. Benchmark Highlights (Bare Metal)

Measured on bare-metal Apple Silicon (macOS ARM64, 8-core CPU) across 3 reproducible rounds with warm filesystem caches against Node.js, Bun, and Deno:

Detailed benchmark reproduction instructions and test harness scripts are available in benchmarks/README.md.

12. Zero-Node Dependencies & Lockfiles

No package.json install steps or bloated node_modules. Import standard ES modules over HTTPS:

import { get } from 'nio.js';
import { z } from 'https://esm.sh/zod@3.23.8?target=es2022';

const Schema = z.object({ id: z.string() });
get('/validate', ({ query }) => ({ valid: Schema.safeParse(query).success }));

Lockfile Lifecycle

# Build and generate or update nio.lock
nio-js build app.ts --update -o app.njs

# Strictly enforce cached hashes in CI/CD (fails if checksum mismatch)
nio-js build app.ts --frozen -o app.njs

# Offline & air-gapped production builds (zero network requests)
nio-js build app.ts --offline --frozen -o app.njs

13. Single-File Capsules (.njs)

A capsule bundles the complete graph, assets, cryptographic hashes, and capability envelope into a portable artifact:

# 1. Build capsule with embedded assets
nio-js build app.ts --asset logo.svg=assets/logo.svg -o dist/app.njs

# 2. Inspect graph and metadata
nio-js inspect dist/app.njs

# 3. Cryptographically verify
nio-js verify dist/app.njs

# 4. Run standalone in production
nio-js run dist/app.njs --port 8080

14. Agent Diagnostics & Stdio MCP

Engineered specifically to support autonomous agents like Antigravity, Claude, and Cursor:

Fast Structured Diagnostics (nio-js check)

nio-js check src/app.ts --format=agent-json

{
  "valid": true,
  "modules_count": 4,
  "errors": []
}

Stdio Model Context Protocol (nio-js mcp)

Expose compile, syntax check, and isolated code evaluation tools directly to AI coding agents over standard JSON-RPC:

nio-js mcp

15. Real-World Production Examples

Explore production-tested code directly inside the repository:

• REST API Gateway (examples/api-gateway): Dynamic routing, query filtering, JSON validations, and native loop checksum acceleration.
• AI Agent Worker (examples/ai-agent-service): Intent classification, RAG context scoring, and structured task planning powered by in-process Python.

16. Ecosystem Roadmap to v1.0.0

nio-js is engineered to operate seamlessly as the execution tier of the wider Nio platform:

For deep technical details on the roadmap, see the full ROADMAP_V1.md document.

17. Security, Limits & FAQ