Content
# 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):
```powershell
# 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
```
```bash
# 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)
<p align="center">
<img src="./docs/assets/github-header-nulla-local.png" alt="Parad0x Labs" width="100%" />
</p>
```
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**:
```powershell
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**:
```bash
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](https://github.com/Parad0x-Labs/dna-x402) | x402 rail: quote → pay → verify → receipt → anchor |
| 🛠️ Build | [dna-x402-builders](https://github.com/Parad0x-Labs/dna-x402-builders) | Hosted kit: turn any API/bot into a paid agent |
| 🕶️ Privacy | [Dark-Null-Protocol](https://github.com/Parad0x-Labs/Dark-Null-Protocol) | Groth16 privacy settlement, published proofs |
| 🗜️ Data | [liquefy](https://github.com/Parad0x-Labs/liquefy) | Columnar compression that beats Zstd |
| 🛡️ Audit | [liquefy-openclaw-integration](https://github.com/Parad0x-Labs/liquefy-openclaw-integration) | Flight recorder: 24 engines + Solana-anchored audit trails |
| 🎬 Media | [nebula-media](https://github.com/Parad0x-Labs/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](https://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:
```bat
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
powershell -ExecutionPolicy Bypass -File .\Install_And_Run_NULLA.ps1
```
### macOS / Linux (one command)
```bash
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
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:
```powershell
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):
```bash
# macOS / Linux
cd ~/nulla-local && .venv/bin/python -m apps.nulla_cli install-profile --set local-max
```
```powershell
# 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** — 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`:
```powershell
# 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
```
```bash
# 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](docs/INSTALL.md)
---
## Run the benchmarks
```bash
# 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`](REPO_MAP.md)
---
## For developers
```bash
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 …`):
```bash
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](docs/PROOF_PATH.md)
Architecture: [docs/SYSTEM_SPINE.md](docs/SYSTEM_SPINE.md) · [docs/CONTROL_PLANE.md](docs/CONTROL_PLANE.md) · [docs/STATUS.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.*
<p align="center">
<img src="./docs/assets/github-footer-parad0xlabs.png" alt="NULLA — Parad0x Labs open source systems" width="100%" />
</p>
