NULLA

A private AI agent that runs on your machine — and proves what it actually did.

NULLA runs a real tool-using agent loop on your own hardware: it reads files, runs tests, writes code, searches the web, and remembers across sessions — and nothing leaves your box unless you say so. What nothing else ships: every turn it signs a receipt of what it claimed vs. what actually ran — Ed25519-signed, hash-chained, and verifiable by anyone, offline.

Verify it yourself in 10 seconds — no signup, no server. Clone and run the demo (Windows uses py; macOS/Linux uses python3 — plain python may be a broken Store stub on Windows):

# Windows (PowerShell)
if (!(Test-Path nulla-local)) { git clone https://github.com/Parad0x-Labs/nulla-local }; cd nulla-local
py -m pip install cryptography
py -m core.honesty_receipt demo

# macOS / Linux
[ -d nulla-local ] || git clone https://github.com/Parad0x-Labs/nulla-local; cd nulla-local
python3 -m pip install cryptography
python3 -m core.honesty_receipt demo

It signs a clean receipt and a caught-lying one, verifies both, then shows two forgery attempts fail — all offline. (py -m core.honesty_receipt verify-last then checks your own agent's last real session.)

Local. Private. Never phones home. You cannot forge a receipt.

Current state: Alpha — runtime, memory, tool loop, and signed honesty receipts working on main; part of the wider Web0 direction (agent task-market + x402 settlement) that's still hardening. See docs/STATUS.md.

local NULLA agent → memory + tools → optional trusted helpers → mesh task market → results

⚡ Install in one command

Windows

1. Press the Start button, type PowerShell, and open Windows PowerShell.
2. Paste the line below and press Enter:

Invoke-WebRequest https://raw.githubusercontent.com/Parad0x-Labs/nulla-local/main/installer/bootstrap_nulla.ps1 -OutFile bootstrap_nulla.ps1; powershell -ExecutionPolicy Bypass -File .\bootstrap_nulla.ps1

That's the whole install. It sets everything up for you — including Python if your PC doesn't have it — downloads the local AI model, and opens a chat window in your browser. No sign-up, no accounts, no API keys.

macOS / Linux

Open your Terminal app (on a Mac: press Cmd+Space, type Terminal), paste the line below, and press Enter:

curl -fsSLo bootstrap_nulla.sh https://raw.githubusercontent.com/Parad0x-Labs/nulla-local/main/installer/bootstrap_nulla.sh && bash bootstrap_nulla.sh

(On macOS/Linux you need Python 3.10+ already installed — most machines have it.)

What to expect: the first run downloads a few gigabytes — the local AI model — so the window can look like it's just sitting there for several minutes. That's normal; leave it open. When it's done, your browser opens by itself with NULLA ready to chat.

Want to pick a model size, use the click-through installer, or install from a repo you already cloned? See Install options below.

What makes NULLA different

Tool-use agent loop — not prompt theater

NULLA runs a real agent loop: call LLM → parse tool intent → execute (read files, run tests, write code, search web) → feed result back → repeat until done. It doesn't hand you a one-shot guess and call it a day.

Benchmark on real engineering tasks (5 tasks requiring tool use):

Tasks were specifically designed to be impossible without tool use: bugs only visible at runtime, multi-file changes that require reading before editing. The benchmark is in tests/benchmarks/agent_capability_bench.py — run it yourself.

Tiered machine tools — read freely, mutate with consent

The agent acts on your machine through a typed tool registry, tiered by risk so a model can never quietly do something destructive:

• Read-only (runs freely): list/read files, machine specs, disk space, recent Windows Event Log errors, top processes by memory, web fetch / search / browser render.
• Local writes (policy-gated, off by default): write files, create directories.
• Destructive (explicit OS consent): e.g. move/rename a file or folder — refuses protected system and wallet locations outright, then requires a live Windows Hello / credential prompt before touching anything. Fail-closed everywhere.

Every tool declares its side_effect_class and approval_requirement; the model can only fulfil a gate's preconditions, never bypass it. (Built + tested.)

Safety you control — kill switches + OS-gated spends

NULLA touches a real Solana wallet, so control is first-class:

• Emergency brakes. /stopx402 freezes the wallet's .null-registration lane instantly, and the USDC x402 spend lane is disabled in this build (internal dogfood) — so no x402 payment or .null registration can go through — while the assistant keeps running (/startx402 resumes). /stopall, and a red Stop NULLA desktop button, hard-stop every NULLA process and disable auto-restart. The desktop button works even if the agent is hung.
• The model can't move money on its own. Every spend is gated by an OS-native consent prompt (Windows Hello / credential dialog) that names the exact amount and wallet, fail-closed — a prompt-injected or mistaken "yes" in chat cannot satisfy it.
• Spend policy. Per-transaction, daily, and weekly caps plus a panic freeze, HMAC-authenticated on disk so a tampered policy fails closed.
• Updates never touch your wallet. The self-updater swaps only code; data/ (wallet, keys, tx history, x402 receipts) is preserved by construction — proven with adversarial tests that a malicious release shipping its own data/ still cannot overwrite your originals.

(All built + tested. The wallet/x402 settlement itself is stub/devnet today — see "What works right now".)

Three-tier memory that actually works

Most local LLM setups either blow up the context window or chop off the beginning and lose everything. NULLA compresses without forgetting.

Memory benchmark (30-turn conversation, 5 facts planted early):

Sliding window is the naive approach every other local stack uses. It cuts tokens by just forgetting everything old — including your passwords, deadlines, and API keys. NULLA cuts 36% of tokens and remembers everything.

The three tiers:

• L1 — recent turns verbatim (always in context)
• L2 — LLM-compressed structured summary of older turns (Key Facts / Decisions / Open Questions / Context — exact values preserved word-for-word)
• L3 — semantic memory nodes in SQLite, retrieved by embedding similarity with nomic-embed-text

Smart retrieval: before injecting L3 nodes, NULLA checks whether the content is already covered in L2. No token bloat from re-injecting facts the summary already has.

Importance scoring

Every turn gets scored before being stored in L3:

password / API key  → 0.6–0.95
port / date         → 0.45–0.50
decision / deadline → 0.40–0.45
generic explanation → 0.20

High-importance turns are prioritised during retrieval. Your sk-prod-xxxx stays findable. "Can you explain async/await?" does not crowd it out.

Semantic search with real embeddings

Plugs into nomic-embed-text via Ollama (274MB, 768-dim). Falls back to a hash bag-of-words if not installed. The same embedding service backs L3 retrieval across sessions — ask something in session 2, get a relevant fact from session 1.

Capability reporting

GET /api/runtime/capabilities reports, per feature, whether it is implemented, simulated, or disabled — so payments show as simulated, WAN mesh as experimental, and live web lookup as opt-in and off in the local-only profile (enable it on a non-local-only profile). /healthz reports commit + dirty bit. The runtime surfaces its own status.

How this fits the Parad0x stack

Parad0x Labs builds Web0 on Solana — money and agents that settle themselves. You are here: 🧠 Local AI (the runtime that consumes every layer).

See it live: parad0xlabs.com

Install options

The one-line command at the top of this README is all most people need. This section
covers the extras: choosing a model tier, the GUI installer, other platforms, and
installing from a repo you've already cloned.

Windows (already cloned the repo?)

Double-click Install_And_Run_NULLA.bat in the repo root. It installs and
launches everything in one shot — Python itself if it's missing, the venv +
dependencies, Ollama and the model for the auto-selected profile, the OpenClaw
bridge, DB migrations, and a logon task — then opens the OpenClaw UI at
http://127.0.0.1:18789 and the NULLA trace rail at http://127.0.0.1:11435/trace.

Requirements: Windows 10/11 and an internet connection on the first run — nothing
needs to be pre-installed. If Python 3.10+ isn't already present, the installer sets
it up per-user (no admin required); it also downloads Ollama, the model, and Playwright.

Pick a profile instead of the auto-recommended one:

Install_And_Run_NULLA.bat /INSTALLPROFILE=local-only

Valid profiles: auto-recommended (default), local-only, local-max. The profile
is set during install — there is no separate step. GUI alternative with a profile
dropdown and install-folder picker:

powershell -ExecutionPolicy Bypass -File .\Install_And_Run_NULLA.ps1

macOS / Linux (one command)

curl -fsSLo bootstrap_nulla.sh https://raw.githubusercontent.com/Parad0x-Labs/nulla-local/main/installer/bootstrap_nulla.sh
bash bootstrap_nulla.sh

This creates the venv, installs dependencies and Ollama, pulls the model, wires
OpenClaw, and starts the API on http://127.0.0.1:11435. Choose a profile inline
(set and persisted during install — no second command):

bash bootstrap_nulla.sh --install-profile local-only   # smaller machines, no remote dependency (alias: ollama-only)
bash bootstrap_nulla.sh --install-profile local-max     # 24 GiB+ unified memory or equivalent (alias: ollama-max)

Omit the flag and the installer auto-selects a profile from your hardware. Pass
--no-start to install without launching.

Advanced

Remote Windows bootstrap without a local checkout:

Invoke-WebRequest https://raw.githubusercontent.com/Parad0x-Labs/nulla-local/main/installer/bootstrap_nulla.ps1 -OutFile bootstrap_nulla.ps1
powershell -ExecutionPolicy Bypass -File .\bootstrap_nulla.ps1 -InstallProfile local-only

Change the active profile after install (optional; restart NULLA to apply):

# macOS / Linux
cd ~/nulla-local && .venv/bin/python -m apps.nulla_cli install-profile --set local-max

# Windows
.venv\Scripts\python.exe -m apps.nulla_cli install-profile --set local-max

Full install docs: docs/INSTALL.md

Platform support

Apple Silicon is the primary development target. Temp paths, signal handling, chat,
three-tier memory, the OpenClaw UI bridge, local Ollama inference, and the workspace
tools all run on a native Windows host today.

Full capability — kernel-enforced no-network job sandbox and live web lookup —
wants WSL2/Linux plus a non-local-only profile:

• Kernel sandbox: native Windows has no kernel network-namespace backend, so a
  no-network job fails closed by default. Run under WSL2/Linux for bwrap/unshare/firejail
  kernel enforcement, or set network_isolation_mode="heuristic_only" on a native host as an
  explicit, informed override (static command guard only, no kernel isolation).
• Live web lookup: opt-in and OFF in the local-only profile. Enable it on a non-local-only
  profile (and/or NULLA_ENABLE_WEB=1 when not local-only). See Web Access.
• Remote null:// dial: opt-in and OFF by default. A null:// request runs locally unless
  dial is enabled with NULLA_ENABLE_NULL_DIAL=1, at which point it can reach the named .null
  agent's x402 endpoint and return that agent's result. Payment is separately gated by
  --allow-spend within a cap. An SSRF guard rejects internal/loopback endpoints. See
  Remote dial.

What works right now

• Agent loop — LLM → tool call → execute → iterate → done. Not a single-shot wrapper.
• Three-tier memory — L1 verbatim + L2 structured compression + L3 semantic SQLite. 36% fewer tokens, 100% recall.
• Embedding service — nomic-embed-text (768-dim) with hash-BoW fallback. Cross-session retrieval.
• Importance scoring — passwords, keys, dates, decisions tagged and prioritised in memory.
• Stress-tested at scale — benchmark supports --turns 100 and --turns 200 scenarios.
• Persistent memory across sessions — NullaMemory SQLite backend.
• Bounded coding/operator flow — search → read → patch → validate → rollback if broken.
• Append-only task/proof spine — every repair and orchestration step is inspectable, not locked inside the executor.
• Mesh task market — decompose → escrow → offer → claim → execute → review → reward. Ed25519-signed credit settlement. Single-node and loopback verified end-to-end.
• 3-layer anti-cheat proof-of-work credits — challenge-response, staking, ZK-proof path. The stake-before-work / slash-on-cheat guard is built and self-tests green (wrong, late, and cheating workers are slashed).
• Multi-result consensus validator — cross-validates worker answers, spawns a verification job on disagreement (built + tested).
• Capability-token authorization — signed, scoped, single-use, expiring task tokens gate who may run what (built + tested).
• Contribution-proof receipt chain + proof-of-execution + proof manifest — hash-canonical contribution receipts and a git-source proof manifest, distinct from the task/proof event spine (built + tested).
• Compute-rental market — prices your real hardware, welds x402 receipt hash into tamper-evident WorkProof. The rent() → _pay_x402() pay-upfront path is wired and integration-tested (315-LOC end-to-end test; stub/devnet modes — live mainnet anchor pending).
• DNA x402 payment bridge + wallet manager — simulated USDC→credit purchase path (1 USDC = 1000 credits) against a local SQLite wallet; settlement is simulated today (stub/devnet), live on-chain settlement coming. A local on-chain receipt verifier gates real settlement so reputation can't be self-claimed (built + tested).
• Directory-less peer discovery — Kademlia DHT routing table (k=20 buckets) + verified-endpoint liveness index; nodes find each other without a central directory (built + tested).
• Role-aware, local-first provider routing — drone vs synthesis lanes; local llama.cpp, vLLM, and Kimi lanes when configured. Self-healing: if the exact model tag you asked for isn't installed it serves the best available local model instead of going dark, and never fails open to a paid cloud lane (cost/safety constraints stay enforced). When nothing can serve, the trace names the gap (empty registry / disabled / missing license) rather than a generic error.
• Kill switches + OS-gated spends — /stopx402 freezes the .null-registration lane, /stopall and a desktop Stop button hard-stop everything; the SOL .null-registration spend is gated by a fail-closed Windows Hello / credential prompt with HMAC-authenticated per-tx / daily / weekly caps + panic freeze on disk; the USDC x402 spend lane is disabled in this build and must be re-wired to that persisted policy before any public release (built + tested).
• Tiered machine tools — read-only disk / Windows Event Log errors / process / file inspection run freely; writes are policy-gated; move/rename is gated by a protected-path denylist and OS consent (built + tested).
• Wallet-safe self-update — consent-gated in-chat update that swaps only code and preserves data/ (wallet, keys, tx history, receipts); adversarial tests prove a malicious release can't overwrite them (built + tested; release signing pending).
• Capability-reporting API — GET /api/runtime/capabilities — implemented / simulated / disabled, per feature.
• CI — sharded local regression + GitHub Actions + fast LLM acceptance suite.

Built core, still partial (real implementations with tests, but thinner coverage):

• Credit DEX / order book — P2P, cheapest-first marketplace for compute credits (built core; thin).
• Sybil / collusion fraud detection — reputation graph + closed-loop collusion detection + score decay (built core, covered by test_fraud_and_timeouts).
• Encrypted P2P transport + NAT traversal — TLS streams plus STUN, hole-punching, and relay fallback (built core, covered by transport test suite; some helpers thin).
• Sandboxed helper-worker isolation — runs untrusted mesh jobs behind filesystem, network, and resource guards (built core).

Try It

No terminal needed to see the proof: after installing, double-click Verify_NULLA.bat (Windows) or run ./Verify_NULLA.sh (macOS/Linux) — it runs the signed honesty-receipt demo and shows the green verdict, then tells you how to verify your own agent's last session.

After install, start the API and chat. On Windows use py (the launcher);
python3 is not a valid command there and the Windows Store python shim can be a
stub — prefer py:

# Windows (PowerShell) — note the launcher and quote any path with spaces
py -m apps.nulla_api_server        # local API on :11435
py -m apps.nulla_agent --interactive
curl http://127.0.0.1:11435/api/runtime/capabilities

# macOS / Linux
python3 -m apps.nulla_api_server        # local API on :11435
python3 -m apps.nulla_agent --interactive
curl http://127.0.0.1:11435/api/runtime/capabilities

Full install docs: docs/INSTALL.md

Run the benchmarks

# Agent capability: NULLA tool loop vs Ollama single-shot
python -m tests.benchmarks.agent_capability_bench

# Memory compression: recall vs token budget at 30 / 100 / 200 turns
python -m tests.benchmarks.memory_compression_bench
python -m tests.benchmarks.memory_compression_bench --turns 100
python -m tests.benchmarks.memory_compression_bench --turns 200

# Provider comparison across 4 models × 4 task categories
python -m tests.benchmarks.nulla_vs_standard

Repo map

• core/ — agent runtime, memory, tools, mesh, credits, compute, Hive, web
  • core/context_window.py — three-tier memory manager
  • core/conversation_summarizer.py — structured LLM compression
  • core/embedding_service.py — nomic-embed-text + hash-BoW fallback
  • core/nulla_memory.py — SQLite-backed persistent memory
  • core/agent_runtime/ — turn loop, fast paths, research loop
• apps/ — API server, CLI, agent entrypoints
• tests/ — regression coverage + benchmarks
• installer/ — one-click setup
• docs/ — architecture, status, trust, runbooks

Full map: REPO_MAP.md

For developers

git clone https://github.com/Parad0x-Labs/nulla-local.git
cd nulla-local
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,runtime]"
python3 -m apps.nulla_api_server

Useful entry points (Windows: use py -m … instead of python3 -m …):

python3 -m apps.nulla_api_server        # local API on :11435  (Windows: py -m …)
python3 -m apps.nulla_agent --interactive
curl http://127.0.0.1:11435/api/runtime/capabilities

Proof path for skeptics: docs/PROOF_PATH.md

Architecture: docs/SYSTEM_SPINE.md · docs/CONTROL_PLANE.md · docs/STATUS.md

NULLA is alpha. The core runtime and memory system are real and working on main. Payments are simulated, WAN mesh is experimental, and live settlement is still hardening. GET /api/runtime/capabilities reports the current per-feature status at any moment.