# Nulla Local

> Local-first AI agent that proves what it did — signs an offline-verifiable receipt for every action. Runs on your machine, private, never phones home. Alpha.

- **Type:** MCP server
- **Install:** `agentstack add mcp-parad0x-labs-nulla-local`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Parad0x-Labs](https://agentstack.voostack.com/s/parad0x-labs)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Parad0x-Labs](https://github.com/Parad0x-Labs)
- **Source:** https://github.com/Parad0x-Labs/nulla-local

## Install

```sh
agentstack add mcp-parad0x-labs-nulla-local
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

  

```
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** — 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](https://github.com/Parad0x-Labs)
- **Source:** [Parad0x-Labs/nulla-local](https://github.com/Parad0x-Labs/nulla-local)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-parad0x-labs-nulla-local
- Seller: https://agentstack.voostack.com/s/parad0x-labs
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.