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

Execution policy: Windows blocks unsigned .ps1 scripts by default, so run them with -ExecutionPolicy Bypass as shown (a one-run override — nothing permanent). Double-clicking install-windows.ps1 or running .\install-windows.ps1 bare will fail with "running scripts is disabled on this system". The installer self-elevates (a UAC prompt will appear).

To allow scripts persistently instead (then you can run .\...ps1 directly):

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Then double-click the NexusOS desktop icon (the shortcut already passes the bypass), or launch from a shell with:

powershell -ExecutionPolicy Bypass -File .\launch_nexus.ps1

The app opens at :8000; click Start AI to launch Ollama. The installer uses requirements-wsl.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 and the Ollama binary.
./install.sh

# 2. Launch (memory :8001, backend :8000 — backend also serves the built UI)
./launch_nexus.sh

Python deps are layered: requirements-base.txt (GPU-agnostic core) plus one GPU overlay — requirements-amd.txt (ROCm) or requirements-nvidia.txt (CUDA). requirements-wsl.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

Architecture

Component	Location	Role
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

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-wsl.txt = standalone CPU runtime

---

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