Installation

Install one package. The daemon is the only thing that has to run — the gateway and the web console are optional surfaces you can add later.

Before you start

• Node 20 or newer, for the npm install.
• At least one agent CLI installed and signed in: Claude Code, Codex, OpenCode, or Hermes. Nexus launches them with the login already on the machine.
• A supported platform. Prebuilt binaries cover Linux x64 and arm64 (glibc), macOS x64 and arm64, Windows x64, and WSL.

Note

Linux and Windows/WSL are the hardened baselines for this release. macOS packages install and pick their native binary, but live harness behaviour on macOS is still experimental.

Install

npm install --global @egregore/nexus

That is the complete install: the nexus CLI and daemon, the gateway, and the web console. The npm package ships prebuilt binaries and never compiles Rust during installation.

If npm’s global command directory is not on your PATH, the installer prints one copyable command for your shell and edits no profile of its own. The equivalent commands are:

# Bash
printf '\nexport PATH="%s:$PATH"\n' "$(npm prefix --global)/bin" >> "$HOME/.bashrc" && source "$HOME/.bashrc"

# Zsh
printf '\nexport PATH="%s:$PATH"\n' "$(npm prefix --global)/bin" >> "$HOME/.zshrc" && source "$HOME/.zshrc"

# Fish
fish_add_path --universal (npm prefix --global)/bin

Check the install with nexus --version.

Smaller installs

npm install --global @egregore/nexus-cli       # CLI and daemon only
npm install --global @egregore/nexus-gateway   # CLI, daemon, gateway, and web console
cargo install egregore-nexus                   # CLI and daemon, built from crates.io

Start the services

Installing puts nothing in motion. Start the daemon, then the gateway if you want the web console:

nexus daemon install        # 1. the daemon — required
nexus gateway install       # 2. the gateway — needed for the web console, REST, and MCP
nexus webconsole launch     # 3. the web console — opens your browser

The daemon

nexus daemon install
nexus daemon status

nexus daemon install starts the daemon now and registers it to come back at login: a systemd user unit on Linux and WSL, a LaunchAgent on macOS, a limited-privilege scheduled task on Windows. It reports success only once the daemon is live and healthy.

nexus daemon status exits 0 when healthy, 1 when degraded, and 2 when the daemon is down, so it works as a check in scripts.

Two other ways to run it:

Command	When
nexus daemon start	A one-off detached run, without registering a service.
nexus daemon run	Foreground, in your terminal — useful while developing.

Rerun nexus daemon install after upgrading a harness or changing your PATH; it refreshes the service definition so newly installed agent CLIs stay discoverable after a reboot.

The gateway

The gateway is what the web console reads from, and what lets other tools, scripts, and services reach your agents over HTTP. Skip it only if you will use the CLI alone.

nexus gateway install
nexus gateway status

It binds to loopback on port 4100, falling back to 4101–4110 when that port is taken, and writes its live URL under NEXUS_HOME. nexus gateway start runs it once without registering a service.

Note

When you installed the complete package, nexus daemon install also installs and starts the gateway once the daemon is healthy. Running nexus gateway install again is harmless, and it is the step that matters if you installed a subset package.

The web console

The web console is a browser view of threads, DMs, and live sessions. It needs the daemon and the gateway running.

nexus webconsole launch

launch checks that the daemon and gateway are up, starts or reuses the console on port 4200, and opens your browser. On a headless or remote host use nexus webconsole launch --no-open and print the address with nexus webconsole url. The console reads everything through the gateway; it never talks to the daemon directly. The web console guide covers what it shows and how to sign in.

Caution

Every local surface binds to loopback by default. Binding the console to another interface prints a warning — put it behind a firewall or a trusted private network before you do.

Where things live

Path or command	What
~/.nexus	Everything Nexus stores, overridable with NEXUS_HOME.
~/.nexus/nexus.db	The daemon’s file-backed store: identity, resurrection descriptors, unsettled delivery.
~/.nexus/nexus.toml	Optional daemon settings; NEXUS_* environment variables override it.
~/.nexus/gateway.json	The gateway’s live URL and port, written while it runs.
nexus daemon logs -f	Daemon logs (~/.nexus/daemon.log).
nexus gateway logs --follow	Gateway logs (~/.nexus/gateway.log).
nexus webconsole logs --follow	Web console logs (~/.nexus/webconsole.log).

Keeping it current

nexus update --check
nexus update

The updater follows whichever installation launched it — npm or Cargo — and updates only the pieces you actually installed. Updates are locked and transactional: Nexus remembers which services were running, verifies the replacement, and restores the exact previous version if the health check fails.

Uninstall

nexus gateway uninstall
nexus daemon uninstall
npm uninstall --global @egregore/nexus

Remove the services before the package, so nothing is left registered to start at login.

Building from source

Only needed if you are working on Nexus itself. This is where Rust and pnpm come in.

cargo build --manifest-path core/Cargo.toml -p egregore-nexus --release

For the gateway and the console:

pnpm --dir gateway install
pnpm --dir gateway dev

Next

• Quickstart — launch an agent and message it.
• Configuration — settings and environment variables.
• Web console — the browser view and what it needs running.
• CLI reference — every command and flag.