NexusOS/README.md

NexusOS

A local-first AI assistant platform. Runs entirely on your machine — a Python/FastAPI backend, a bundled Ollama instance for inference, a persistent memory service, and a React frontend. No external AI provider is called.

---

What it is

NexusOS ("Nexus") is a self-hosted assistant you actually own. All inference runs through a locally bundled Ollama on localhost; conversations, facts, and settings live in local SQLite. It ships with desktop branding (XFCE theme, icons, boot splash) so it can be run as a full assistant environment on Linux, not just a web app.

• Chat — streaming responses from local Ollama models (SSE).
• Persistent memory — a dedicated service auto-extracts durable facts from each exchange and layers them into future prompts.
• Playbooks — ordered YAML system-prompt records; the first is the active persona, the rest are injected as reference context.
• Model management — list, pull, and delete Ollama models from the UI/CLI.
• History — full conversation persistence, search, edit, export.

Quick start

NexusOS runs single-process: the backend on :8000 serves the built web UI itself, so there's no separate frontend server at runtime. Ollama is started manually from the app (Start AI in the sidebar), not at boot.

Windows (recommended)

# 1. Install Git, then clone (public repo, no account/token needed):
winget install Git.Git
# open a NEW PowerShell window, then:
git clone https://git.enderofwings.com/enderofwings/NexusOS.git nexus-core
cd nexus-core

# 2. Native install — winget Python/Node/Ollama, venv, pip, web build, desktop icon
powershell -ExecutionPolicy Bypass -File .\install-windows.ps1

Then double-click the NexusOS desktop icon, or launch from a new shell (PATH is read at process start, so already-open windows won't have ncp yet):

ncp web

The installer needs -ExecutionPolicy Bypass because Windows blocks unsigned .ps1 by default; it's a one-run override, nothing permanent. It self-elevates, so a UAC prompt appears. ncp itself is management\ncp.cmd on the machine PATH — a .cmd, so no execution-policy change is ever needed, and it works from cmd and Task Scheduler as well as PowerShell.

The app opens at :8000; click Start AI to launch Ollama. The installer uses requirements-windows.txt (CPU-only, pure-Python — no ML stack, since Ollama does all inference over HTTP).

Linux

# 1. Build everything: venv (auto-selects AMD/NVIDIA/CPU), web UI, memory DB,
#    system packages, Ollama binary and the XFCE desktop wiring.
./install.sh

# 2. Launch (memory :8001, backend :8000 — backend also serves the built UI)
#    The install symlinks ncp into /usr/local/bin (sudo); open a new shell first.
ncp web

Python deps are layered: requirements-base.txt (GPU-agnostic core) plus one GPU overlay — requirements-amd.txt (ROCm) or requirements-nvidia.txt (CUDA). requirements-windows.txt is the standalone CPU-only runtime (no base overlay). bin/sync.py picks the right one for the host.

./install.sh is also the update path — re-run it any time to pull the latest and rebuild. --check dry-runs it; --no-desktop skips the XFCE panel/theme wiring (that stage is auto-skipped off XFCE anyway). It's a thin wrapper over bin/sync.py restore, the same code the Windows box runs.

Individual services

source Promethean/bin/activate

uvicorn synapse.main:sio_app          --host 0.0.0.0 --port 8000 --reload   # backend (serves the UI too)
uvicorn synapse.memory.service:app    --host 0.0.0.0 --port 8001 --reload   # memory

# Frontend dev server (hot-reload) — only needed when editing the UI;
# production serves the built dist/ from the backend at :8000.
cd interface/web && npm run dev

CLI (ncp)

Start/stop services and drive the same features as the web UI over the REST API:

ncp start        # backend + frontend (--backend|--frontend|--memory)
ncp stop

ncp chat "<message>"                   # stream a reply
ncp memory list | add <text> | rm <id>
ncp playbook list | show <id>          # first playbook (*) = active system prompt
ncp history [query]                    # recent conversations
ncp doctor                             # diagnostics: venv, Node, imports, Ollama, status

Architecture

Component	Location	Role
Promethean (venv)	Promethean/	The Python venv all backend code runs in — source Promethean/bin/activate (Linux) / Promethean\Scripts\python.exe (Windows). Keeps deps out of the system Python.
Synapse (backend)	synapse/	FastAPI app. /chat/stream, /playbooks, /memory, /models, /conversations, /settings, /ollama, /icons. Assembles the system prompt: active playbook → reference playbooks → memory facts → relevant past snippets.
Memory service	synapse/memory/	Separate FastAPI app (:8001). /memories/extract uses an Ollama prompt to decide what to persist. Shares the SQLite DB with the backend.
Playbooks	synapse/playbooks/ + data/playbooks/	Ordered {id}.yaml records managed by PlaybookManager.
Ollama	ollama/bin/ollama	Bundled binary; OllamaManager handles lifecycle + model selection (Vulkan GPU detection). HTTP API at 127.0.0.1:11434.
Frontend	interface/web/	React 19 + Vite. Built to dist/ and served by the backend at :8000 (single-process). Pages: Chat, Playbooks, History, Models, Memory, Settings.

Storage

Most data lives in synapse/memory/memory.db (SQLite, WAL) — facts, conversations, messages, settings. Playbooks are the exception (YAML files in data/playbooks/). All paths are defined in synapse/nexus_config.py.

Layout

synapse/          FastAPI backend + memory service + playbook/ollama managers
interface/web/    React + Vite frontend
management/       nexus-cli.sh, ncp API client, control panel, desktop theme
bin/              install, backup/restore, panel + provisioning scripts
assets/           branding: icons, boot splash, XFCE/GTK theme
data/playbooks/   active playbook YAML
Promethean/       Python venv (gitignored, built by the installer)

Configuration

Concern	Location
Ollama host	OLLAMA_HOST env (default http://127.0.0.1:11434)
Filesystem paths	synapse/nexus_config.py
Frontend API base URL	interface/web/src/config.js
Python deps	requirements-base.txt + amd/nvidia GPU overlay; requirements-windows.txt = standalone CPU runtime

---

_{NexusOS · local AI, self-hosted on GitNexus}