enderofwingsandClaude Sonnet 5
ec8f2e08f6
- install-windows.ps1: warn about a leftover profile-based ncp() that would shadow ncp.cmd; the "press any key to close" footer now skips the wait when stdin is redirected (was hanging indefinitely) and exits cleanly instead of Stop-Process when it owns the window; pulls nomic-embed-text alongside the chat/memory models. - management/ncp.py: ncp start / start -b bring Ollama up automatically; longer timeout + real error message on a slow model warm. - synapse/nexus_config.py: DEFAULT_EMBED_MODEL, single source of truth alongside DEFAULT_CHAT_MODEL/DEFAULT_MEMORY_MODEL. - synapse/ollama_manager.py: is_available() cached instead of spawning a process per /status poll; is_running() timeout dropped 2s -> 0.5s so a healthy backend stops reading as dead; embed() reads the new default instead of a hardcoded string; de-duplicated serve-env setup. Ported via bin/publish.sh from NexusOS-jon. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
159 lines
6.8 KiB
Markdown
159 lines
6.8 KiB
Markdown
<div align="center">
|
|
|
|
<img src="assets/n-small.png" alt="NexusOS" width="96">
|
|
|
|
# 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.
|
|
|
|
</div>
|
|
|
|
---
|
|
|
|
## 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 "<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 |
|
|
|
|
---
|
|
|
|
<div align="center"><sub>NexusOS · local AI, self-hosted on <a href="https://git.enderofwings.com/enderofwings/NexusOS">GitNexus</a></sub></div>
|
GitNexus · part of the Nexus stack