Runtime Documentation

Installation

One command installs Sofuu on macOS (Apple Silicon), Linux (x86_64 and arm64), or Windows (x64) — a single static executable with zero dependencies, shipping with QTSQ encrypted local persistence. The one-line installer puts sofuu on your PATH so it works from any terminal in any project.

# Install globally onto your PATH — macOS, Linux, or Windows
$ curl -fsSL https://sofuu.xyz/install | sh
# Then, from any directory:
$ sofuu run app.ts
# or via npm — the same binary, verified against its published sha256
$ npx sofuu

Quickstart Guide

Sofuu runs .js files on an embedded QuickJS engine — instant boot, no JIT warmup, no install step. Here is a complete edge server that streams a local LLM to the browser:

// app.js — an edge server that streams a local LLM to the browser
const server = sofuu.http.createServer((req, res) => {
  if (req.url === "/chat") {
    const stream = sofuu.ai.stream("Explain quantum mechanics.", {
      provider: "ollama", model: "llama3"
    });
    res.writeHead(200, { "Content-Type": "text/event-stream" });
    
    // chunks arrive from the native polling layer — the loop never blocks
    for await (const chunk of stream) res.write(chunk.text);
    res.end();
  } else {
    res.writeHead(200);
    res.end("AI Edge Runtime Active");
  }
});
server.listen(8080, "0.0.0.0");
console.log("Server bound on port 8080.");

Run it from your terminal: $ sofuu run app.js. Point provider at any local or cloud LLM — configuration lives in /provider inside the chat, or pass it per call as shown.

CLI Commands

One binary is the whole toolchain: runtime, package manager, agent host, and REPL.

Chat & the Agent

sofuu chat is a full coding agent in your terminal: streaming answers and a built-in tool belt — read, write, edit, grep, glob, list_dir, and bash — with sessions that persist locally as encrypted .qtsq containers. Nothing leaves your machine except the model calls themselves.

# Start the interactive agent
$ sofuu chat
# Pick a provider and model on first run, then just talk to it.
# It can read and edit files, search code, and it remembers
# across sessions in an encrypted local store.

The most useful slash commands:

Global Sandbox

Primitives injected into the root scope of every script — no import needed.

sofuu.ai

The AI bridge: talk to local models (Ollama) or cloud providers (OpenAI, Anthropic, OpenRouter, …) through one API. Streaming and SSE parsing happen in native worker threads, never on the JS loop.

Headless SDK: sofuu_embed_local / batch / image / info and sofuu_voice_transcribe / speak C ABI (libsofuu) with Swift/Kotlin wrappers — same spaces, no JSON. Image recipe: open a store with (path, 64, 'image-projector-v1'),remember image vectors with captions, recall with a text vector.

sofuu.http & fetch

sofuu.fs & processes

sofuu.web

Web access for scripts and the agent — the same primitives the assistant uses when you ask it to look something up.

sofuu.memory & sofuu.kv

Durable, local persistence backed by the QTSQ encrypted store — the same layer behind chat sessions and long-term memory. Everything stays on your disk, sealed with post-quantum cryptography (ML-KEM-768).

sofuu.tools & sofuu.agent

The agent loop is scriptable: give a model a goal and let it drive the same tool belt the chat uses, with every step emitted as events you can render or log.

Advanced: MCP · RLM · ML

Experimental surfaces — available in the binary but still evolving; expect changes between releases.

The five context-economy gates (freshness, compaction, relevance, supervisor, alloc) are tiny offline models — 6–9k parameters each, deterministic, zero API calls. Each is graded on held-out content families against two references: a constant predictor and a logistic regression on the same features. All five beat both.

Compaction is the one irreversible thing the chat does, so it runs under guards that do not trust the model: a per-pass cap (a quarter of turn blocks, two always survive) and a lexical floor that protects any turn where you asked a question, gave an instruction, or recorded a decision. Stated plainly: these gates are trained on synthetic data with mechanical labels, so the table shows they are learnable on the distribution we generate — not that they are correct on your traffic. The honest test is a shadow A/B on real sessions, and we have not built it yet.

Embedding benchmarks

Measured on public datasets, not estimated. Reproduce with scripts/bench/fetch_datasets.sh + ml-train bench. Apple M2 Pro, release build, single thread, no network.

The BM25 row is the calibration check: our implementation lands at the ~0.665 published for SciFact, so the harness agrees with the literature. The default embedder reaches 62% of that with zero parameters, zero bytes and no model file — the trade against a hosted embedder is quality for a network round-trip, a key and cents per million documents. The 64-dim learned spaces are in-domain optimizers, not general retrievers; we publish the gap rather than hide it.

Embed the runtime in your app

The CLI above is the free developer surface. To put the runtime inside your own app — a private agent with an encrypted local memory, no cloud account, no API key in your binary, no telemetry — the same engine ships as a library. QuickJS is a pure interpreter, so there is no JIT and the iOS App Store executable-memory policy is satisfied by construction.

// Package.swift  (or:  pod 'Sofuu')
.package(url: "https://github.com/sofuu-runtime/sofuu.git", from: "0.2.0")
// App code - a private agent with a memory the user owns
import Sofuu
let sofuu = try Sofuu()
let vec  = try sofuu.embed("the sky is blue")  // 768-dim, offline, no model file
let brain = try Brain.openDefault(sofuu: sofuu)  // encrypted, local, yours
try brain.remember("the sky is blue")
for hit in try brain.recall("what colour is the sky?", k: 3) {
  print(hit.text, hit.score)
}

Everything above runs on-device. Embeddings ship with no model file at all (0 bytes), the brain is encrypted on disk and exportable, and the full C ABI is behind one header. The full contract, the streaming event schema, and the error model are documented in the repo under docs/EMBEDDING.md.