Files

T

Athena KaminskyandClaude Opus 5 9104c724c4 feat(packaging): move the CLI into nexusos_cli and make the wheel self-sufficient

The CLI shipped from `management/`, which also holds desktop-only pieces (the
Tk control panel, the XFCE panel wiring, the shell wrappers). Packaging that
directory meant the wheel either dragged in tkinter or shipped a broken import.
Split it: `nexusos_cli/` is what the wheel ships and what `nexus`/`ncp`/
`nexusos` dispatch to, `management/` keeps the desktop half.

Alongside the move:

* hatch_build.py decides the interface/web/dist include at build time. dist/
  is gitignored, so a static force-include aborts `pip install -e .` on a
  fresh clone - before the reader reaches the `npm run build` step. Editable
  installs now skip a missing dist; wheels and sdists hard-error naming the
  command to run.
* synapse/proc_util.py gives frontend_manager and ncp process inspection and
  termination without psutil, which became an optional extra when the wheel
  landed. It routes around Windows having no signals, where os.kill(pid, 15)
  is an unblockable TerminateProcess rather than a polite request.
* nexusos_cli/monitor.py adds `ncp monitor`, an ASCII dashboard with no curses
  or rich dependency so it works in Termux, plain SSH and Windows Terminal.
  Collector and renderer are separate so tests feed fixtures, no stack needed.
* tests/test_packaging_deps.py fails the gate when synapse or nexusos_cli
  import a distribution pyproject does not declare, and when an optional
  dependency is imported at module scope instead of lazily.
* bin/check.sh now builds the wheel, twine-checks it, and asserts the compiled
  UI and seed playbooks are actually inside it. A wheel that builds but ships
  no dist/ serves a blank page, which only shows up after release.

tests/test_nexus_api.py moves to tests/ with the module it covers.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-26 08:11:39 -05:00

4.4 KiB

Raw Blame History

NexusOS CLI

The Python package installs three equivalent command names: nexus, ncp, and nexusos. New documentation uses nexus; ncp remains available for existing desktop installs and scripts. Legacy spellings such as ncp web, ncp start -b, ncp refresh, ncp backup, and ncp restore remain supported; checkout-specific operations report a clear error when invoked from a wheel.

Install

From a source checkout. Build the web UI first - it is a Vite artifact, so a fresh clone does not have it, and an install without it serves the API only:

cd interface/web && npm ci && npm run build && cd ../..
python -m pip install -e ".[standard]"
nexus init
nexus doctor

From the package index after a release is published:

python -m pip install "nexusos-ai[standard]"
nexus init
nexus serve

The base install contains the backend, memory service, compiled web UI, CLI, and seed playbooks. Extras keep platform-sensitive dependencies optional:

standard: documents, vector search, web search, and process control
documents: PDF and DOCX ingestion
vector: sqlite-vec semantic indexes
voice: local faster-whisper transcription
process: psutil-backed process and port inspection
desktop: desktop process support and Windows pywebview
search: DuckDuckGo web search for chat
mail: IMAP mail reading
all: every optional capability at once

Common commands

nexus init                         Create writable state and seed playbooks
nexus doctor [--fix] [--json]     Diagnose the install and provider
nexus paths [--json]              Show package, state, and asset locations
nexus status [--json]             Show services and provider reachability
nexus monitor [--once] [--json]   ASCII live dashboard (services, resources, tools)
nexus serve                       Run backend + memory in the foreground
nexus start|stop|restart           Manage background services
nexus open                         Open the compiled web interface
nexus logs [service] --follow      Tail service logs
nexus models list|pull|remove      Manage Ollama-compatible models
nexus config list|get|set|unset    Manage persistent settings

API commands are also available directly:

nexus chat send "Hello"
nexus history list
nexus memory list
nexus playbook list

Run nexus COMMAND --help for command-specific arguments.

Providers

Local desktop installs can allow NexusOS to start and stop a local Ollama:

nexus provider use local

For Termux, containers, or a separate inference machine, configure a remote Ollama-compatible endpoint. NexusOS probes it but never manages its process:

nexus provider use remote --url http://192.168.1.20:11434
nexus provider show --json

State and configuration

Installed wheels never write into site-packages. Writable files use the platform data directory, while configuration uses the platform config directory. Inspect the exact locations with nexus paths.

Environment variables override persisted settings. The most useful are:

Persisted keys are the same names, minus the NEXUS_ prefix - nexus config set home /data/nexus matches NEXUS_HOME. nexus config list shows what is set; nexus config set warns when a change would point NexusOS at a database that does not exist yet (the file is never moved for you).

NEXUS_HOME                 Override the complete writable state root
NEXUS_CONFIG_DIR           Override the config directory
NEXUS_PROVIDER             ollama or ollama-remote
NEXUS_PROVIDER_URL         Ollama-compatible API base URL
NEXUS_BIND_HOST            Backend bind address (loopback by default)
NEXUS_BACKEND_PORT         Backend/web port (default 8000)
NEXUS_MEMORY_PORT          Memory service port (default 8001)

The REST APIs are unauthenticated. nexus serve refuses non-loopback binds unless --allow-lan is given; that flag is an explicit acknowledgement, not an authentication layer.

--allow-lan widens the accepted Host headers and CORS origins to the addresses the bind actually answers on - it does not set them to *. That keeps TrustedHostMiddleware enforcing something, which is what stops a web page you visit from resolving a name it controls to your machine and driving the API through your browser. Export NEXUS_ALLOWED_HOSTS yourself if you genuinely need a blanket, and understand that anyone who can reach the port has full admin and data access.

4.4 KiB Raw Blame History