NOUS is a privacy-first, locally-hosted personal AI system. All data stays on your own hardware — nothing leaves your network unless you explicitly choose to use an external AI provider via the built-in external API feature.
- RAG over your documents — ingest PDFs, Word files and text, query them in natural language
- Voice interface — wake-word detection → Whisper STT → local LLM → Piper TTS
- Web cockpit — browser UI with wings (topic-based document collections), analysis mode, and scraper jobs
- Scope system — documents tagged SECRET / PRIVATE / SWARM / PUBLIC with enforced access controls
- Optional external AI — send queries to Anthropic, OpenAI, Groq or a custom endpoint; key stays in browser session only
- Multi-user — admin user plus family profiles with configurable wing access
- Compute lending — swarm nodes can delegate inference to idle peers during off-hours; SECRET/PRIVATE scope is hardcoded never to leave the originating node; credit system tracks contribution on both sides; automatic local fallback on peer failure
- GBrain — graph inference over the Kuzu knowledge base; identifies alienation patterns and source-concentration across extracted facts
- Swarm shadow observer — read-only telemetry agent verified over 24 h with zero boundary violations; monitors health, Qdrant, and isolation gates every minute
The system is designed for a two-device LAN setup, but can run on a single machine:
| Device | Role | Tested on |
|---|---|---|
| Primary host (Pi 5 recommended) | API, RAG, ingest, web UI, proxy | Raspberry Pi 5 16GB |
| Inference host | LLM + STT | Jetson Orin NX 16GB |
| Swarm + compute node | Peer inference, knowledge sharing | Jetson Orin NX 8GB (permanent swarm node) |
Single-machine: point NOUS_OLLAMA_URL and NOUS_WHISPER_URL at localhost.
NOUS uses specialised agents for different domains (household, legal, legacy). Each agent is designed to run its own model, but on constrained hardware models are shared intelligently:
- Daily use (supervisor, household, children): qwen2.5:7b — kept permanently in memory for instant response
- Night analysis (legal, inconsistency): qwen3:14b — loads on-demand
When hardware with larger unified memory (32GB+) becomes available, or domain-specific models are released as GGUF, each agent can be configured with its own specialised model without architectural changes.
cd /srv/nous
docker compose up -d # starts Qdrant + SearXNGpython3 -m venv pipeline/.venv
source pipeline/.venv/bin/activate
pip install -r pipeline/requirements.txt # fastapi uvicorn httpx qdrant-client ...cp .env.example .env
# Edit .env — set NOUS_OWNER_NAME and network addresses
cp config/wings.example.json config/wings.json
# Edit wings.json — define your document collectionscd /srv/nous/api
uvicorn main:app --host 0.0.0.0 --port 8000Open web/index.html in a browser (or serve it via nginx — see docs/CREDITS.md).
sudo cp api/nous-api.service /etc/systemd/system/
sudo systemctl enable --now nous-api.serviceWings are named document collections. Each wing has a scope:
| Scope | Who can see it | PII anonymization on export |
|---|---|---|
| SECRET | Admin only | None |
| PRIVATE | Admin only | None |
| SWARM | All users | All PII masked |
| PUBLIC | Everyone | CPR, phone, address, email masked |
Non-admin users can be blocked from specific wings via blockedWings in web/index.html → USERS.
Drop files into incoming/<wing-name>/ for automatic ingest (picked up within ~10 seconds by the file watcher).
Requires: any USB microphone, Piper TTS model, Whisper running on inference host.
Optional hardware: ReSpeaker/XVF3800 users may install their vendor control tools separately — NOUS auto-detects the device by name. See your hardware vendor's documentation.
# Download Danish Piper TTS model
mkdir -p models/tts
# Place da.onnx and da.onnx.json in models/tts/
# Test voice pipeline
bash scripts/voice_test.shSee CLAUDE.md for full architecture details.
The web cockpit includes an optional external AI panel (🌐) in Analyse and Assistant modes. When enabled, queries are sent to Anthropic / OpenAI / Groq / custom endpoint after scope confirmation. The API key is never stored — it lives only in the browser session.
PRIVATE wings require one confirmation click. SECRET wings require typing a confirmation phrase (configurable in web/index.html) before sending.
api/ FastAPI backend
config/ wings.json, scraper_jobs.json (gitignored — use *.example.json)
docs/ Architecture notes, credits
models/ TTS + embedding models (gitignored)
pipeline/ Ingest pipeline, privacy guard, task router
proxy/ Lightweight internet proxy for LAN-isolated inference host
scripts/ CLI tools: voice_chat.py, nous_chat.py, promote.py, ...
web/ Single-file cockpit UI (index.html)
- Compute lending: swarm peers can serve delegated inference with scope-guard and credit tracking
- GBrain: graph inference over Kuzu DB for pattern detection across facts
- Swarm shadow observer: 24 h read-only telemetry verification with zero boundary violations
- Jetson Orin NX 8GB added as permanent swarm + compute node
- Initial release: RAG, voice, cockpit UI, scope system, swarm knowledge sharing, night pipeline
AGPL-3.0 — see LICENSE.