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 with glibc 2.35 or newer (Ubuntu 22.04 and later, including the Linux distribution behind WSL), and Windows x64. Older glibc releases and musl distributions are outside this baseline: use a newer distribution or build from source. macOS on Apple Silicon and Intel is partially supported (see the note below).

Note

Linux and Windows/WSL are the supported platforms for this release. macOS is partially supported: since 0.1.8 the npm install works on Apple Silicon and Intel Macs, and we test that the install succeeds and nexus --version runs on both. Running the daemon, agents, the gateway and the web console on macOS is not tested yet. The macOS binaries are ad-hoc signed, not notarized.

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

On Windows the installer prints a user-scoped PowerShell command instead:

$nexusBin = (npm prefix --global); $userPath = [Environment]::GetEnvironmentVariable('Path', 'User'); [Environment]::SetEnvironmentVariable('Path', (($userPath + ';' + $nexusBin).Trim(';')), 'User')

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

npm is the only install route today. To build the CLI and daemon yourself instead, see Building from source.

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 limited-privilege scheduled task on Windows. It reports success only once the daemon is live and healthy. On macOS it registers a per-user LaunchAgent instead; that path is not tested yet.

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 makes sure the daemon and gateway are running, starting them if they are not, then 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 a Cargo-managed binary, and updates only the pieces you actually installed. The Cargo path pulls from crates.io, so it cannot fetch a release until the crate is published there. 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 API:

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

dev serves the gateway API only. The web console has its own script:

pnpm --dir gateway webconsole: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.