NeXuS Compass — 2026-08-15¶
App Registry · NNCC · Security HUD · Timeline Additions¶
Session type: Infrastructure + Integration
Status: ✅ TESTED — all changes live and verified
Written by: Claude (Sonnet 4.6) + Anon
Think of this compass like an instruction manual. Every change is explained: what it is, why we did it, and how it works. If you read this, you should be able to understand everything that happened today — even if you weren't there.
🔧 FIX 1 — NeXuS Dashboard (wtfutil) Not Launching¶
What broke¶
The NeXuS Dashboard uses a program called wtfutil to show a live info panel.
When you ran the launch script, it said:
Why it broke¶
The launch script was starting wtfutil like this:
The-c flag with a space after it is the OLD way. The version of wtfutil installed
on this machine is a "dev" build that only accepts the flag written like this:
When it saw -c with a space, it thought the file path was a command name. It was confused.
What we changed¶
File: ~/scripts/nexus-dashboard.sh
Old line:
New line:
Two things changed: the flag name (long form --config= instead of -c), and the
path uses $HOME instead of ~ (more reliable in scripts).
🛡️ FIX 2 — OSSEC Not Wired Into Security HUD¶
What was missing¶
The Security HUD (~/scripts/nexus-security-hud.sh) watches for intruders and
shows alerts. It was supposed to read from OSSEC (our host intrusion detector),
but the OSSEC block was completely missing from the code. The HUD watched for
PSAD, Suricata, and Fail2ban — but silently ignored OSSEC entirely.
Why OSSEC is tricky¶
OSSEC saves its alert log at /var/ossec/logs/alerts/alerts.log but only root
can read it. Regular users can't open that file.
The solution: the user account is in the wheel group, and /var/log/messages
is readable by wheel. OSSEC writes there too. Even better, we can add the user
to the ossecr group (OSSEC's read-only group) to read the alerts file directly.
What we added¶
File: ~/scripts/nexus-security-hud.sh
We added a new block inside the check_alerts() function. It:
1. Tries to read the last 30 lines of the OSSEC alerts log
2. Pulls out: the source IP (srcip:), the alert level (a number 1-15), and the rule description
3. If level is 10 or above → RED threat. Below 10 → ORANGE.
4. Alerts without a source IP (like file integrity checks) just appear in the feed without raising the threat level
5. If the log file can't be read at all, it shows a one-time warning in the feed so you know OSSEC isn't connected
How to fully activate OSSEC in the HUD¶
Run this (needs a TTY):
Then log out and back in. After that, the HUD reads OSSEC alerts automatically.📜 UPDATE 3 — NeXuS Living Timeline Gets New Entries¶
What the Timeline is¶
The Living Timeline (~/NeXuS/timeline/NEXUS_TIMELINE.md) is NeXuS history.
Every milestone, every diagram, every big decision goes in there. It renders
as a beautiful webpage at https://127.0.0.1:8443/timeline.
What we added today¶
Entry 1: The Sovereign Synergy diagram (Aug 14) NotebookLM generated a diagram showing how NeXuS and DivaChain work together. The key idea: your computer (Private NeXuS) does all the work locally. When it's time to prove that work happened, it packages everything into a "Golden Ticket" (a ZK-proof — math that proves "I did valid work" without showing WHAT the work was). That ticket travels through I2P (anonymous internet) and lands on DivaChain, which checks the math. DivaChain never sees who you are. The timeline entry explains this as "The Highway Analogy" — the toll booth verifies the toll was paid without knowing who drove.
Entry 2: Architecture of Sovereignty + meWEwowow infinity heart (Aug 15) Two more NotebookLM diagrams appeared: - An infinity symbol shaped like a heart, with people working at a table beneath it. This is meWEwowow — the doctrine — made visual. - A full breakdown of every NeXuS layer: Foundation → Inner → Perimeter → Upper → Atmosphere. Every component named: PERMITTI Ring, Ghost Gate, The Explosion, The Wick, Narcplonk, etc.
Both images were copied to ~/NeXuS/timeline/images/ and added to the timeline.
Rule confirmed this session¶
NO YELLOW in documents. This applies to all NeXuS docs going forward.
🗺️ DISCOVERY 4 — Mapping All NeXuS Frontend/Backend Apps¶
What we found¶
Using NXS-Search and grep, we discovered there are 13-14 different apps in the
NeXuS stack, each with their own web interface and/or API server. They were all
running on different ports with no central coordination. Some used their own
python3 -m http.server to serve their UI — a simple but limited approach.
The full list¶
| App | Port | What it does |
|---|---|---|
| NeXuS Web Server | 8443 | The main HTTPS hub — serves everything |
| NNCC API | 8801 | Controls darknet networks (Tor, I2P, etc.) |
| NNCC Web UI | 8880 | Dashboard for the darknet controls |
| NXS Search | 5000 | Search 530K+ files on the system |
| Beautiful Wiki (nb) | 6789 | Note-taking and wiki |
| PNG² / CharCard | 7420 | Edit AI character cards |
| Conduit Matrix | 6167 | Sovereign chat server |
| aichat bus | 3030 | AI model connection hub |
| txt Blogger | 8091 | Darknet text blog |
| AI Foundry | 7432 | AI workspace API |
| MkDocs | 8000 | Documentation site |
| Gopher server | 8080 | Darknet alt protocol |
🏗️ BUILD 5 — The App Registry (The Big Fix)¶
The problem we were solving¶
Every time we wanted to add a new app to the NeXuS web server, someone had to
write new Python code. If you wanted /nncc/ to work, you'd add an if path == '/nncc/':
block. If you wanted /search/ to work, another block. This is called "hardcoding" —
it's like having to rebuild your house every time you want a new door.
The solution: a registry¶
Instead of writing code for each app, we made the web server read a list of apps from environment variables. Think of it like a phone book — you just add a name and number to the book, and calls get routed automatically.
How it works:
In ~/NeXuS/secrets/nexus.env, you add three lines per app:
NEXUS_APP_NNCC_prefix=/nncc # what URL it lives at
NEXUS_APP_NNCC_static=/path/to/files # where its web files are (optional)
NEXUS_APP_NNCC_backend=http://127.0.0.1:8801 # where its API is (optional)
NEXUS_APP_NNCC_api_prefix=/api # only proxy paths that start with this (optional)
When the web server starts, it reads all the NEXUS_APP_* lines and builds a routing
table automatically. To add a new app: add three lines, restart the server. No code changes. Ever.
What the routing logic does¶
When a request comes in for /nncc/api/networks:
1. Server checks: does any registered app have a prefix that matches /nncc? Yes — NNCC.
2. What's left after removing /nncc? → /api/networks
3. Does /api/networks start with the api_prefix /api? Yes → proxy to backend.
4. Makes a request to http://127.0.0.1:8801/api/networks and returns the result.
When a request comes in for /nncc/css/nexus.css:
1. Matches NNCC.
2. What's left? → /css/nexus.css
3. Does it start with /api? No → serve static file.
4. Opens ~/nexus-network/web/css/nexus.css and sends it to the browser.
Files changed¶
~/Projects/nexus-web-server/nexus_web_server.py— added_build_app_registry(),_match_registry(),_dispatch_registry(),_registry_proxy(),_registry_static(). Also addeddo_PATCH(),do_DELETE(),do_PUT()handlers.~/NeXuS/secrets/nexus.env— added registry block with 9 apps.~/NeXuS/docs/NEXUS_APP_REGISTRY.md— new doc explaining the system.
The bug we hit (and fixed)¶
The registry was reading os.environ (the system environment variables), but
nexus.env isn't in the system environment — the web server reads it itself
using its own _env_dict() function. So at startup, when the registry was built,
the nexus.env vars hadn't been read yet.
Fix: Changed _build_app_registry() to use _env_dict() which reads nexus.env
directly, merged with any system env vars:
🌐 BUILD 6 — NNCC Wired Into NeXuS Web Server¶
What NNCC is¶
The NeXuS Network Command Center (NNCC) is a dashboard for controlling darknet
services: Tor, I2P, Yggdrasil, Reticulum, IPFS, Snowflake. It has:
- A frontend (web UI at ~/nexus-network/web/) — the pretty dashboard you see
- A backend (FastAPI server at :8801) — the brains that actually talks to the services
Before today, the UI was served by a bare python3 -m http.server on port 8880.
After today, everything goes through the NeXuS web server.
Changes to the frontend (app.js)¶
The JavaScript used to hardcode http://127.0.0.1:8801 everywhere — the address
of the backend API. This is like telling everyone "our office is at 123 Main St"
but then moving the office and having to tell everyone the new address.
We changed it to be smart about where it is:
const _NNCC_PREFIX = window.location.pathname.startsWith('/nncc') ? '/nncc' : '';
const API_BASE = window.location.origin + _NNCC_PREFIX;
Translation: "If this page is being served from /nncc/, add /nncc to all API calls.
If it's being served directly (like the old way), don't add anything."
This means the NNCC works whether served from the NeXuS web server OR from the old standalone server — one codebase, two deployment options.
The nexus-nncc.sh management script¶
We wrote a new script (~/scripts/nexus-nncc.sh) to manage the NNCC backend,
following the same pattern as nexus-api-proxy.sh. Commands:
nexus-nncc.sh start # start the API in a tmux session
nexus-nncc.sh stop # stop it
nexus-nncc.sh restart # stop then start
nexus-nncc.sh logs # attach to the tmux session to see live output
nexus-nncc.sh status # show what's running and whether the API responds
The script also: - Checks that the venv exists before trying to start - Waits up to 15 seconds for the API to respond before declaring failure - Self-backs up on every launch (NeXuS standard) - Uses env vars for paths (no hardcoding)
Bugs we hit and fixed¶
Bug 1: Wrong path in start-nncc.sh
The old startup script had a hardcoded path:
~/Projects/nexus-network-stack/command-center/.
Fixed to use an env var with a sensible default:
Bug 2: exec with a pipe breaks logging
The nexus-nncc.sh script used exec uvicorn ... | tee logfile.
The exec command replaces the shell process — so the pipe to tee gets orphaned.
The log file stays empty. Fixed by removing exec:
# broken:
exec '$UVICORN' main:app ... 2>&1 | tee '$LOG_FILE'
# fixed:
'$UVICORN' main:app ... 2>&1 | tee '$LOG_FILE'; read
Bug 3: Hardcoded data path in config.py The NNCC backend's config had:
But/home/user/claude/configs/nexus-stack already exists as a file — not a
directory. When the backend tried to create it as a directory, it failed.
Fixed to use the NeXuS standard location:
Also created ~/NeXuS/data/nncc/ so it exists before the server starts.
Bug 4: Python 3.14 vs pydantic-core
The requirements.txt pinned pydantic==2.5.3 which requires pydantic-core==2.14.6.
But the system runs Python 3.14, and pydantic-core 2.14.6 was written before Python 3.14
existed. A Python 3.14 API change (ForwardRef._evaluate() needs a recursive_guard
argument now) causes the Rust build to fail with a Python error.
Fixed by unpinning pydantic and requiring a minimum version:
Pydantic 2.8+ supports Python 3.14 and has pre-built binary wheels (no compilation needed).📋 WHAT STILL NEEDS DOING¶
| Task | Notes |
|---|---|
doas addgroup user ossecr |
Activates OSSEC in the Security HUD |
api-proxy restart after any nexus.env change |
Registry rebuilds at startup |
Add nncc alias to fish config |
alias nncc='~/scripts/nexus-nncc.sh' |
| Fossil commit — nexus-web-server | Registry changes not yet committed |
| Fossil commit — nexus-nncc.sh | New script not yet in Fossil |
| ArticFrost VM (Antigravity SDK) | Pending from prior session |
| iPXE darkstack boot | 90% built, pending from prior session |
🔑 KEY LESSONS FROM TODAY¶
1. Registry over hardcoding. When you find yourself writing the same pattern more than twice (if path == '/this', if path == '/that'), stop and make it data-driven. The App Registry is the NeXuS solution: one pattern, all apps, config in nexus.env.
2. Check where env vars come from. Python's os.environ only has what the
shell passes in. If your program loads secrets from a file, make sure the code that
READS those secrets uses the same file-reading function, not os.environ directly.
3. exec with a pipe is a trap. exec replaces the current process. If you
pipe exec ... | something, the pipe's right side never connects properly. Use the
command without exec when you need piping.
4. Python version matters for Rust packages. Packages like pydantic-core compile
Rust code against the Python C API. When Python 3.14 changed an internal API, old
versions of pydantic-core broke. The fix: don't pin to exact versions of Rust-based
packages — use >= and let pip find a version with pre-built wheels for your Python.
📁 FILES CHANGED THIS SESSION¶
~/scripts/nexus-dashboard.sh — wtfutil flag fix
~/scripts/nexus-security-hud.sh — OSSEC block added
~/scripts/nexus-nncc.sh — NEW management script
~/nexus-network/start-nncc.sh — paths fixed, http.server removed
~/nexus-network/web/js/app.js — API_BASE made dynamic
~/nexus-network/web/index.html — docs iframe src fixed
~/Projects/nexus-web-server/nexus_web_server.py — App Registry added
~/Projects/nexus-network-stack/command-center/config.py — data_dir hardcoding removed
~/Projects/nexus-network-stack/command-center/requirements.txt — pydantic unpinned
~/NeXuS/secrets/nexus.env — 9 apps registered
~/NeXuS/docs/NEXUS_APP_REGISTRY.md — NEW registry doc
~/NeXuS/timeline/NEXUS_TIMELINE.md — 3 new entries added
~/NeXuS/timeline/images/diagrams/2026-08-14_nexus-divachain-sovereign-synergy.png — NEW
~/NeXuS/timeline/images/diagrams/2026-08-15_nexus-architecture-of-sovereignty.png — NEW
~/NeXuS/timeline/images/art/2026-08-15_meWEwowow-infinity-collective.png — NEW
~/NeXuS/data/nncc/ — NEW directory created
🐾 CAT REPORT¶
| Cat | Activity |
|---|---|
| Luna | Mom. Had a scrape on nose bridge. Treatment: saline only — NO Neosporin on cat faces |
| Wookie (Tury) | Keyboard napper. Responsible for jjjjjjjjjjj |
| Mid | The mastermind. Orchestrated keyboard ops |
| BigMaN | Unhinged sidekick. Backslash avalanche confirmed |
| Peewee | Field operative. Possibly responsible for Luna's nose |
The NeXuS cat collective contributed more characters to this session than most sessions have code.
Sane · Simple · Secure · Stealthy · Beautiful · Sustainable
The table outlasts every king. meWEwowow 💥