# 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)
```powershell
# 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):
```powershell
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
```bash
# 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
```bash
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:
```bash
ncp start # backend + frontend (--backend|--frontend|--memory)
ncp stop
ncp chat "