NexusOS # 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 Requires Python 3, Node, and a GPU is optional (CPU works). ```bash # 1. Install deps into the Promethean venv (auto-selects AMD/NVIDIA/CPU) ./bin/install.sh # 2. Launch the full stack (memory :8001, backend :8000, frontend :5173) ./launch_nexus.sh ``` Python deps are layered: `requirements-base.txt` (GPU-agnostic core) plus one overlay — `requirements-amd.txt` (ROCm), `requirements-nvidia.txt` (CUDA), or `requirements-wsl.txt` (CPU-only). `bin/install.sh` picks the right one for the host. ### Individual services ```bash source Promethean/bin/activate uvicorn synapse.main:sio_app --host 0.0.0.0 --port 8000 --reload # backend uvicorn synapse.memory.service:app --host 0.0.0.0 --port 8001 --reload # memory cd interface/web && npm run dev # frontend ``` ## CLI (`ncp`) Start/stop services and drive the same features as the web UI over the REST API: ```bash ./management/nexus-cli.sh start # backend + frontend (--backend|--frontend|--memory) ./management/nexus-cli.sh stop ncp chat "" # stream a reply ncp memory list | add | rm ncp playbook list | show # 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. 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/wsl overlay | ---
NexusOS · local AI, self-hosted on GitNexus