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)

# 0. Allow scripts to run (PowerShell blocks unsigned scripts by default, which
#    stops Nexus's CLI from working). Process scope covers only this window;
#    LocalMachine makes it permanent so ncp works from every future shell (run
#    PowerShell as Administrator for the LocalMachine line).
Set-ExecutionPolicy -Scope Process       -ExecutionPolicy Bypass -Force
Set-ExecutionPolicy -Scope LocalMachine  -ExecutionPolicy RemoteSigned -Force

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

Roadmap

Rough plan, not promises. Ordered by how soon and how much it touches.

Soon

• Inference knobs in Settings — expose temperature, context length, and num_gpu in the UI. The backend already passes options to Ollama; there's no UI for them yet, and small-VRAM boxes need num_gpu=0 today via env only.
• Chat controls — stop generation, regenerate last reply, edit-and-resend. History editing exists; live regeneration doesn't.
• Per-playbook model — playbooks set the persona but not the model; let a playbook pin its own chat model (Settings already splits chat vs. memory model).

Eventually

• Document ingest / RAG — the embedding stack (nomic-embed-text, message_vectors, cosine recall) already retrieves past conversations. Extend it to uploaded files and notes so chats can cite your own documents.
• Vision chat — attach images to a message and route to a multimodal Ollama model. The stream path is text-only today.
• Real vector index — recall does a brute-force cosine scan over JSON blobs in SQLite. Fine at current scale; swap in a proper index (e.g. sqlite-vec) before the DB grows.

Far future

• macOS support — POSIX process control already works; needs a sync.py platform fork, ROCm-free requirements, and an installer. Waiting on a Mac.
• Voice I/O — local speech-to-text in, text-to-speech out.
• Fine-tuning loop — conversations already export as ShareGPT; close the loop into a local fine-tune. The ML stack was stripped from the runtime venv but the requirements files restore it.
• Tool-using playbooks — function calling so a playbook can take actions, not just shape the prompt.
• Machine learning & gameplay — the original goal: an agent that learns to play games alongside me (it started as "teach it to play Lego Star Wars"). Screen capture in, controller/input out, trained by playing. The whole reason this project exists.

---

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