Nulla Local

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](docs/STATUS.md).

[](LICENSE) [](docs/STATUS.md) [](https://python.org) [](https://github.com/Parad0x-Labs/nulla-local/actions/workflows/ci.yml)

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](#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):

| | Score | Notes | |---|---|---| | NULLA (14b + tools + loop) | 5/5 | Iterates, fixes, verifies | | Ollama 14b single-shot | 4/5 | Fails cross-file rename — no iteration |

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):

| Mode | Recall | Peak tokens | |---|---|---| | Raw (no compression) | 5/5 (100%) | 528 | | Sliding window (10) | 0/5 (0%) | 362 (-31%) | | NULLA ContextWindow | 5/5 (100%) | 335 (-36%) |

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).

| Layer | Repo | Does | |---|---|---| | 💸 Payments | dna-x402 | x402 rail: quote → pay → verify → receipt → anchor | | 🛠️ Build | dna-x402-builders | Hosted kit: turn any API/bot into a paid agent | | 🕶️ Privacy | Dark-Null-Protocol | Groth16 privacy settlement, published proofs | | 🗜️ Data | liquefy | Columnar compression that beats Zstd | | 🛡️ Audit | liquefy-openclaw-integration | Flight recorder: 24 engines + Solana-anchored audit trails | | 🎬 Media | nebula-media | Proof-carrying media compression — scene-aware + on-chain receipts | | 🧠 Local AI | nulla-local (this repo) | Local-first agent runtime — your machine, your memory |

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](docs/INSTALL.md)

Platform support

| OS | Inference | Job sandbox | Launchers | |---|---|---|---| | macOS (Apple Silicon) | Metal GPU via Ollama | kernel-enforced (sandbox-exec) | .command | | Linux | Ollama + native llama.cpp | kernel-enforced (bwrap/unshare/firejail) | .sh | | Windows (native host) | Ollama (CPU; consumer-GPU lane coming) | static command guard only (no kernel backend) | .bat / PowerShell | | Windows + WSL2/Linux | Ollama + native llama.cpp | kernel-enforced (bwrap/unshare/firejail) | .sh inside WSL2 |

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](docs/INSTALL.md#web-access-opt-in).

• 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](docs/INSTALL.md#remote-dial-opt-in).

---

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 — pri

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Parad0x-Labs
• Source: Parad0x-Labs/nulla-local
• License: MIT

Install and usage instructions live in the source repository linked above.