Athena/NexusOS
1
0
Fork 0
forked from enderofwings/NexusOS
Code Pull Requests Activity
Files
55edaa2ebd02aca3f3a10636ca0653e6d78a605c
NexusOS/README.md
T
Athena 26b471d259 Merge origin/main (v1.2.0: Projects, modules, in-app updates) 
Reconciles 17 commits of this session's work (self-alteration tools,
vendored Curry, slash-command dispatch, Windows toolchain/gate fixes)
against origin/main's v1.2.0 sync (Projects/RAG scoping, a new modules/
system for mail and network, in-app updates, the standalone memory
microservice folded into an in-process curator, KDE desktop theme
overhaul). Nine real conflicts, each resolved by hand after reading both
sides' actual diffs rather than picking one side wholesale:

- synapse/tools.py, tests/test_tools.py: origin/main's diff here was
  small and clean (read_file/list_files, two new tests) despite git's
  diff3 flagging the whole file as one conflict blob -- reset to this
  branch's version and hand-spliced their addition in at the same
  points they used, rather than trying to reconcile a false 800-line
  conflict. Found and fixed a real bug while verifying: _list_files
  returned backslash-separated paths on Windows, which don't match the
  forward-slash glob patterns the tool's own schema documents.
- synapse/main.py: kept this branch's cue-based standing advertisement
  of render_preview/run_snippet (independent of any playbook granting
  them) AND adopted origin/main's fix for routed reference playbooks
  not bringing their own tools along -- dropping either would have been
  a real regression, not just a style difference. Also: the standalone
  memory service (port 8001) is gone upstream, so its dead CORS/kill-
  target entries were removed; NEXUS_BACKEND_PORT parameterization and
  the manage_ollama-conditional kill logic (this branch's remote-Ollama
  support) were kept over origin/main's hardcoded equivalents.
- synapse/memory/store.py: kept this branch's _delete_message_vectors
  helper (already reused elsewhere, batches to stay under SQLite's
  variable limit) over origin/main's inline duplicate of the same fix.
- synapse/nexus_config.py, nexusos_cli/ncp.py: dropped the now-dead
  memory-service port/service entries; kept NEXUS_BACKEND_PORT env
  override and the manage_ollama-conditional kill-target list.
- CLAUDE.md, README.md: merged both sides' additions, no real conflict.

Found and fixed three more issues while independently verifying the
merged tree, none of them mine or origin/main's alone -- only visible
once both sides actually ran together:

- modules/ (the new mail+network package) was never added to
  pyproject.toml's wheel `packages` list OR the sdist's `include`
  allowlist, so `from modules.registry import ROUTERS` in main.py would
  ImportError on any wheel install. Fixed both; bin/check.sh's
  packaging gate now asserts modules/ actually ships. tests/
  test_packaging_deps.py's FIRST_PARTY/SHIPPED_PACKAGES sets were
  updated to recognize the new package.
- tests/test_mail_creds.py's 0600-mode assertions are POSIX-only --
  NTFS has no equivalent permission bits, so os.open(path, 0o600) on
  Windows just creates a normal file and stat.S_IMODE reports 0o666
  regardless. Made the assertions platform-aware rather than skip real
  coverage (the temp-file-cleanup and password round-trip checks in the
  same test still run on Windows) or paper over a genuine OS
  limitation with a fake pass.
- tests/test_kde_theme.py used bare Path.read_text() in fifteen places;
  Windows' default locale encoding (cp1252, not UTF-8) can't decode a
  real UTF-8 byte in the QML it reads, and did fail on one of the
  fifteen. Fixed all fifteen, not just the one that happened to trip
  today, since the other fourteen were equally fragile.

Verified: full bin/check.sh reports OK end-to-end on this Windows
checkout -- pytest (tests + management): 295 passed, 0 failed, 9
skipped; eslint clean; frontend node:test 57/57; PowerShell/shell
parse clean; wheel + sdist pass twine check and now correctly carry
modules/ (60 files, up from 52 pre-merge). synapse.main:app builds
with 74 routes (up from 54 pre-merge, matching the new Projects/mail/
network endpoints).
2026-08-26 02:09:23 -05:00

325 lines
15 KiB
Markdown
Raw Blame History

<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, persistent
memory, and a React frontend. No external AI provider is called. Ollama is
local by default; Termux and container installs can explicitly point at a
separately managed endpoint.
</div>
---
## What it is
NexusOS ("Nexus") is a self-hosted assistant you actually own. All inference
runs through **Ollama** on `localhost` by default; 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. A remote Ollama-compatible URL is an explicit configuration
option for lightweight clients; NexusOS never starts or stops that remote
process.
Chat with vision and voice, persistent memory, tool-using playbooks, document
RAG scoped to Projects, gated action tools, and full model management — see
**Flagship features** below for what each of those actually does. Rounding it
out: full conversation history (persist, search, edit, export) and a browser
tail of the service logs.
## Flagship features
### Chat, vision & voice
- **Streaming replies** over SSE, with stop/regenerate/edit-and-resend so a
bad reply doesn't mean retyping the whole message
- **Vision** — attach images and route them to a multimodal Ollama model
- **Voice** — dictate with local Whisper STT instead of typing, and have
replies read back aloud
- **Extended thinking** — a per-message toggle lets a reasoning model show
its work without a round-trip to Settings
### Persistent memory
A dedicated microservice reads every exchange and decides, via its own Ollama
prompt, whether it contains a durable fact worth keeping — a preference, a
name, a standing instruction. Saved facts get layered back into the system
prompt on every future chat, so Nexus remembers you across conversations
without you re-explaining yourself.
### Playbooks
Ordered YAML system-prompt records instead of one static prompt. The first
playbook is the active persona; the rest are automatically routed in as
reference context when relevant. Each playbook can pin its own chat model and
its own tool allowlist, so "coding assistant" and "creative writing partner"
can be genuinely different setups, not just different wording.
### Documents & RAG
Upload PDF, DOCX, TXT, or Markdown; NexusOS chunks and embeds it into a
sqlite-vec index and cites the matching passages back into chat answers.
**Projects** scope this per workspace — switch projects and the model only
draws on that project's documents (or none, in the unscoped "All" view).
### Action tools with an approval gate
- **Read-only, run automatically** — search memory/history/documents, list
models, get the time
- **Gated, need approval** — search the web, fetch a URL, save a fact.
Each one prompts in the chat UI before it runs, so nothing reaches out to
the network or writes to memory without you seeing the request first
### Model management
List, pull, and delete Ollama models from the UI or `ncp`, with hardware-aware
recommendations (GPU detection via Vulkan) so a small-VRAM box isn't offered a
model it can't run.
### Modules
Feature areas beyond the core assistant live as self-contained plugins
instead of being wired into the core app:
- **Mail** — IMAP/SMTP, multiple accounts
- **Network** — connection status, WireGuard toggle, ping targets
A backend module is a folder under `modules/` with a `router.py`; a frontend
module is a folder under `interface/web/src/modules/` with a `module.jsx`
exporting a manifest and a component. Both sides are auto-discovered at
startup/build — dropping in a new module folder is enough to have it mounted
and show up in the UI, no registry file to edit.
## 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.
### Python package and portable CLI
The portable package installs `nexus`, `ncp`, and `nexusos` as equivalent
commands. From a checkout today:
```bash
cd interface/web && npm ci && npm run build && cd ../.. # compile the UI
python -m pip install -e ".[standard]"
nexus init
nexus doctor
nexus serve
```
After a package release, the install becomes `python -m pip install
"nexusos-ai[standard]"`. The wheel includes the compiled web UI and default
playbooks; it keeps writable state outside `site-packages`. See
[the CLI reference](docs/CLI.md) for commands, configuration, and dependency
profiles.
Termux uses the base package with a remote Ollama-compatible provider. Its
bootstrap and the current Android native-wheel gate are documented in
[the Termux guide](docs/TERMUX.md).
### Linux
Nexus was built using an Apple T2 computer running Linux Mint XFCE. The desktop
branding (theme, icons, boot splash) could hypothetically be adapted to any
Linux distro, but I only support the Ubuntu/Linux Mint package base.
```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 (backend :8000 — it 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).
macOS uses `requirements-base.txt` directly, no overlay — see the macOS section
below. `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.
### Windows
```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).
### macOS
Community-supported — no bundled Ollama binary or XFCE desktop branding (that
stage is Linux/XFCE-only and already skips itself here), but the
backend/frontend/Ollama stack itself runs natively, no VM or container needed.
```bash
# 1. Install Homebrew first if you don't have it: https://brew.sh
# 2. Build everything: Homebrew packages (Python, Node, git, Ollama), venv,
# web UI, memory DB.
./install-macos.sh
# 3. Launch (memory :8001, backend :8000 — backend also serves the built UI)
./launch_nexus.sh
```
Ollama here is the Homebrew-installed native binary, not the Linux-only bundled
one — `OllamaManager` already falls back to `ollama` on PATH when
`ollama/bin/ollama` doesn't exist, so **Start AI** in the sidebar (or `ollama
serve` in a terminal) uses it with full Metal GPU acceleration automatically,
no configuration needed.
`./install-macos.sh` is also the update path, same idea as Linux — re-run it
any time to pull the latest and rebuild; `--check` dry-runs it. It's a thin
wrapper over `bin/sync.py restore`, the same code Linux and `ncp restore`
(any platform) run.
### Individual services
```bash
# Linux / macOS
source Promethean/bin/activate
uvicorn synapse.main:sio_app --host 127.0.0.1 --port 8000 --reload # backend (serves the UI too)
# 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
```
```powershell
# Windows — needs the RemoteSigned policy from the Quick start step above
Promethean\Scripts\Activate.ps1
uvicorn synapse.main:sio_app --host 127.0.0.1 --port 8000 --reload # backend (serves the UI too)
```
### Promethean
The name for the Python virtual environment all backend code runs in — keeps
Nexus's dependencies out of the system Python. To add a package, activate it
and `pip install` as usual:
```bash
# Linux / macOS
source Promethean/bin/activate
pip install <package>
```
```powershell
# Windows — needs the RemoteSigned policy from step 0 above, since
# Activate.ps1 is a script PowerShell would otherwise refuse to run
Promethean\Scripts\Activate.ps1
pip install <package>
```
On Linux, the installer also registers a `promethean` alias in `~/.bashrc`
(and an optional "Promethean Terminal" desktop launcher) that drops you
straight into an activated shell. There's no equivalent on Windows yet — use
`Activate.ps1` above, or call `Promethean\Scripts\python.exe -m pip install
<package>` directly without activating at all.
## CLI (`ncp`)
`ncp` stands for Nexus Control Panel. This was the original method of accessing the frontend and backend power switches before the UI was implemented. The CLI itself is the same Python script on both platforms and behaves identically either way — the exception is `ncp panel` (the tkinter GUI), which was tuned for Linux/XFCE and looks noticeably more dated on Windows.
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 [--fix] # diagnostics: venv, Node, imports, Ollama, status
ncp help # see complete help tree
```
## 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` (+ `/chat/approve` for gated tool calls), `/playbooks`, `/memory`, `/models`, `/documents`, `/projects`, `/conversations`, `/stt`, `/logs`, `/settings`, `/ollama`, `/frontend`, `/icons`. Assembles the system prompt: active playbook → reference playbooks → memory facts → relevant past snippets → matching documents → web search results. |
| **Memory** | `synapse/memory/` | In-process, no second service or model: `curator.py` reads a conversation once it goes idle, `extractor.py` asks the chat model what is worth keeping, `store.py` merges it into the SQLite DB. |
| **Documents / RAG** | `synapse/memory/store.py` | PDF/DOCX/TXT/MD ingest, chunked and embedded, retrieved via a sqlite-vec index; scoped per **Project** workspace. |
| **Action tools** | `synapse/tools.py`, `synapse/search.py` | Read-only tools (search memory/history/documents, list models, get time) run automatically; `web_search`, `fetch_url`, and `remember` require per-call approval from the chat UI. |
| **Playbooks** | `synapse/playbooks/` + `data/playbooks/` | Ordered `{id}.yaml` records managed by `PlaybookManager`; each can pin a chat model and a tool list. |
| **Modules** | `modules/` + `interface/web/src/modules/` | Self-contained feature plugins (Mail, Network). Backend: any `modules/*/router.py` is auto-mounted. Frontend: any `interface/web/src/modules/*/module.jsx` is auto-registered in the UI. No registry file to edit. |
| **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, Models, Memory, Documents, Logs, Settings — plus any auto-registered modules (currently Mail, Network). |
### Storage
Most data lives in `synapse/memory/memory.db` (SQLite, WAL) — facts,
conversations, messages, settings, and the document/vector index. Playbooks
are the exception (YAML files in `data/playbooks/`). All paths are defined in
`synapse/nexus_config.py`.
## Layout
- `synapse/` — FastAPI backend + memory curator + playbook/ollama managers
- `modules/` — auto-discovered feature plugins
- `interface/web/` — React + Vite frontend
- `nexusos_cli/` — the portable CLI the wheel ships (`nexus`/`ncp`/`nexusos`)
- `management/` — nexus-cli.sh wrapper, 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
- **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; macOS uses
`requirements-base.txt` with no overlay (Ollama, not this venv, does
inference — natively, with Metal)
## Issues and feature requests
**Bugs** — file in [Issues](https://git.enderofwings.com/enderofwings/NexusOS/issues)
on this repo. Include your OS, GPU vendor, and the relevant slice of
`ncp doctor` output.
**Feature requests and planned work** — these live in
[NexusOS-requests](https://git.enderofwings.com/enderofwings/NexusOS-requests),
not here, so the tracker on this repo stays scoped to things that are broken.
Use the **Requests** tab at the top of the repo, next to Issues and Pull
Requests, or follow the link above.
---
<div align="center"><sub>NexusOS · local AI, self-hosted on <a href="https://git.enderofwings.com/enderofwings/NexusOS">GitNexus</a></sub></div>
View Git Blame Copy Permalink