Installation

Detailed installation instructions for nexus-agents across all platforms, Docker, and CI/CD environments.

System Requirements

Required

Optional

API Keys

You need at least one model provider API key:

For local models via Ollama, no API key is required. Ollama support requires configuration of the OLLAMA_HOST environment variable.

Installation Methods

npm (Recommended)

Install globally for CLI access:

npm install -g nexus-agents

Linux / macOS without nvm or asdf? A bare npm install -g will fail with EACCES: permission denied, mkdir '/usr/local/lib/node_modules/...' because the system npm prefix is not user-writable. Do not run sudo npm install -g — npm itself recommends against it. Instead, configure a user-local prefix once:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc   # or ~/.zshrc
source ~/.bashrc
npm install -g nexus-agents

If you can’t or don’t want to change the prefix, use npx nexus-agents (see below) — every invocation works without a global install.

After install, you’ll see a hint to run setup. Configure everything:

nexus-agents setup    # Configures MCP, hooks, data dirs, OpenCode, config

Verify installation:

nexus-agents doctor        # Checks CLIs, API keys, sqlite, data dirs
nexus-agents doctor --fix  # Auto-fix missing data dirs and config
nexus-agents auth status   # Show per-CLI auth state + login fix instructions

pnpm

If you prefer pnpm:

pnpm add -g nexus-agents

pnpm installs an older version than npm does, by design. pnpm’s minimumReleaseAge setting defaults to 1440 minutes: a version is not resolvable until it has been on the registry for a day. nexus-agents publishes several times on a busy day, so pnpm add -g nexus-agents (and pnpm update -g nexus-agents) silently resolves latest to the newest version that is at least a day old — measured in a clean node:22 container with pnpm 11.25: npm installed 8.9.4, pnpm installed 8.3.0, no warning either way. To install the newest version through pnpm, opt out for that command:

pnpm add -g nexus-agents --config.minimumReleaseAge=0

or set minimumReleaseAge: 0 in your global pnpm config. The one-day delay is a supply-chain safeguard; keep it unless you need a fix that shipped today.

npx (No Install)

Run without installing:

npx nexus-agents doctor
npx nexus-agents --help

From Source

For development or customization:

# Clone the repository
git clone https://github.com/nexus-substrate/nexus-agents.git
cd nexus-agents

# Install dependencies
pnpm install

# Build
pnpm build

# Link globally
pnpm link --global

Docker

Run in a container:

# Pull the image
docker pull ghcr.io/nexus-substrate/nexus-agents:latest

# Run with API key
docker run -e ANTHROPIC_API_KEY="sk-ant-..." \
  ghcr.io/nexus-substrate/nexus-agents:latest

Or build locally:

docker build -t nexus-agents .
docker run -e ANTHROPIC_API_KEY="sk-ant-..." nexus-agents

Platform-Specific Instructions

macOS

# Install Node.js 22 via Homebrew
brew install node@22

# Add to PATH
echo 'export PATH="/opt/homebrew/opt/node@22/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Install nexus-agents
npm install -g nexus-agents

# Verify
nexus-agents doctor

Linux (Ubuntu/Debian)

# Install Node.js 22 via NodeSource
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install nexus-agents
npm install -g nexus-agents

# Verify
nexus-agents doctor

Linux (Fedora/RHEL)

# Install Node.js 22
sudo dnf module enable nodejs:22
sudo dnf install nodejs

# Install nexus-agents
npm install -g nexus-agents

# Verify
nexus-agents doctor

Windows

# Install Node.js 22 via winget
winget install OpenJS.NodeJS.LTS

# Or via Chocolatey
choco install nodejs-lts

# Install nexus-agents
npm install -g nexus-agents

# Verify
nexus-agents doctor

Windows (WSL)

Follow the Linux instructions inside WSL. This is the recommended approach for Windows users.

Installing Optional CLIs

The external CLI adapters provide enhanced capabilities:

Claude CLI

npm install -g @anthropic-ai/claude-code
claude auth login

Gemini CLI

npm install -g @google/gemini-cli
gemini auth login

Codex CLI

npm install -g @openai/codex
codex auth login

OpenCode CLI

npm install -g opencode-ai

OpenCode supports custom OpenAI-compatible endpoints, enabling routing to any hosted model that exposes an OpenAI-compatible API.

MCP Client Configuration

Claude Desktop

Add to your MCP configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Linux: ~/.config/claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "nexus-agents": {
      "command": "nexus-agents",
      "args": ["--mode=server"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-your-key-here"
      }
    }
  }
}

Restart Claude Desktop to load the configuration.

Claude CLI

Add to .mcp.json in your project root (or run nexus-agents setup for automatic configuration):

{
  "mcpServers": {
    "nexus-agents": {
      "command": "nexus-agents",
      "args": ["--mode=server"]
    }
  }
}

Data Storage

As of epic #2872, nexus-agents splits runtime data into two roots when run inside a git repo:

• Per-repo state (tied to one codebase’s work) → <repo>/.nexus-agents/ (auto-gitignored)
• Cross-repo state (shared across all your projects) → ~/.nexus-agents/

Run nexus-agents setup to pre-create this structure, or it will be created lazily on first use. nexus-agents doctor reports the resolved location of every subdir. Override the whole split with NEXUS_DATA_DIR=<path>, or opt out entirely with NEXUS_REPO_PREFERRED=0 (all state in ~/.nexus-agents/). In a sandbox without a writable ~, cross-repo state transparently falls back to <repo>/.nexus-agents/.

Native code and install scripts

Nothing in nexus-agents needs to compile at install time, and the CLI works with install scripts blocked. Both halves are gated, not asserted — see below.

Persistent memory (agentic, adaptive, typed, mobimem, decay) runs on node:sqlite, a Node builtin, since #5388 — which is why engines requires Node ≥ 22.5.0. It replaced better-sqlite3, whose install script built a native binding: where install scripts were blocked, npm install still exited 0 and the CLI then died with Could not locate the bindings file. A builtin has no install script to skip.

The polyglot (Python/Go) security scanner does load native tree-sitter grammars, from @ast-grep/lang-python and @ast-grep/lang-go. Those ship prebuilt .so files inside their own npm tarballs for Linux, macOS (x64 + arm64) and Windows x64, so they neither download nor compile anything on a supported platform.

Three production packages declare an install script: @ast-grep/lang-go, @ast-grep/lang-python and @google/genai. Every one is inert for this package’s purposes. Two verify a grammar that already ships in their tarball, and one is literally echo. (Through 8.82.1, a fourth, protobufjs@7, arrived through @google/genai. The repository’s security floor now lifts the bundled copy to 8.x, which has no install script, #6488.) That claim is enforced rather than trusted (#5427):

• scripts/check-install-scripts.ts installs the packed tarball with npm and fails if any install script appears that is not in scripts/install-script-allowlist.json, if an allowlisted one changes what it runs, or if an allowlisted entry no longer exists.
• scripts/verify-npm-install.sh installs with --ignore-scripts in a container with no compiler present, then proves the SQLite path and the polyglot scanner both still work. The scanner has to return two named findings from a fixture, so “found nothing” cannot pass for “clean”.

Run nexus-agents verify to see both checks, SQLite Storage and Native Grammars, reported by name.

These dependencies ship inside the nexus-agents tarball

A package cannot pre-approve its dependencies’ install scripts. npm’s allowScripts and pnpm’s approve-builds are settings on your side. So on releases up to and including 8.82.0, a consent-gated package manager asked you about those four packages, and in two configurations that blocked the install (#6481):

Later releases list @ast-grep/lang-go, @ast-grep/lang-python, @google/genai and @modelcontextprotocol/sdk in bundleDependencies. They arrive inside the nexus-agents tarball rather than as separate installs. npm 12 (default and strict) and pnpm 12 (in a terminal or not) then install with no prompt, no warning and no script executed, and the grammars still load. npm 10 and 11 run a bundled package’s script exactly as they ran it before.

@modelcontextprotocol/sdk has no install script. It is bundled because @google/genai declares it as an optional peer, and npm’s installer treats a bundled package’s peers as part of the bundle. Leave it out and a consumer install gets empty directories for about 90 packages, and the CLI cannot start. scripts/stage-publish.ts refuses to stage a tarball in that state.

The trade: a bundled package is fixed at the version resolved when nexus-agents was released. npm audit still reports it, but a fix reaches you through a nexus-agents release, not through npm update of the dependency.

If you are stuck on 8.82.0 or earlier, either upgrade, or approve the four packages once:

CI/CD Integration

GitHub Actions

name: CI with nexus-agents

on: [push, pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Install nexus-agents
        run: npm install -g nexus-agents

      - name: Run code review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          nexus-agents orchestrate "Review the changes in this PR" \
            --format json > review.json

GitLab CI

code-review:
  image: node:22
  script:
    - npm install -g nexus-agents
    - nexus-agents orchestrate "Review this merge request"
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY

Jenkins

pipeline {
    agent {
        docker { image 'node:22' }
    }
    environment {
        ANTHROPIC_API_KEY = credentials('anthropic-api-key')
    }
    stages {
        stage('Review') {
            steps {
                sh 'npm install -g nexus-agents'
                sh 'nexus-agents orchestrate "Review this build"'
            }
        }
    }
}

Docker Compose

For development environments:

version: '3.8'

services:
  nexus-agents:
    image: ghcr.io/nexus-substrate/nexus-agents:latest
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - NEXUS_LOG_LEVEL=debug
    volumes:
      - ./nexus-agents.yaml:/app/nexus-agents.yaml:ro
      - ./workflows:/app/workflows:ro
    ports:
      - '3000:3000' # REST API

Verifying Installation

After installation, run the doctor command:

nexus-agents doctor

Illustrative example output for a complete setup (your versions and details will differ):

Nexus Agents Doctor
===================

Checking CLI installations...

✓ Claude CLI
  Version: 2.0.76 (supported)
  Auth: OAuth
  Capacity: 85% remaining

✓ Gemini CLI
  Version: 0.22.5 (supported)
  Auth: ADC configured

✓ Codex CLI
  Version: 0.77.0 (supported)
  Auth: OAuth

Checking MCP configuration...

✓ MCP Server mode: Ready
✓ MCP Client mode: Ready (Codex mcp-server)

Summary: All systems operational

Updating

npm

npm update -g nexus-agents

pnpm

pnpm update -g nexus-agents

From Source

cd nexus-agents
git pull
pnpm install
pnpm build

Uninstalling

npm

npm uninstall -g nexus-agents

pnpm

pnpm remove -g nexus-agents

Clean Configuration

Remove configuration files:

# Remove config
rm -rf ~/.config/nexus-agents

# Remove MCP entry from Claude Desktop config
# Edit ~/Library/Application Support/Claude/claude_desktop_config.json

Troubleshooting

npm warn deprecated on install (benign — no action needed)

Installing nexus-agents prints one deprecation warning. It is benign, expected, and safe to ignore — it comes from a transitive dependency of an upstream package, not from anything in the nexus-agents runtime.

(The prebuild-install@…: No longer maintained warning listed here previously came from better-sqlite3 and no longer appears at all: #5388 removed that dependency.)

Neither can currently be removed by upgrading: both persist in the latest versions of those upstream packages, and a library’s overrides do not propagate to consumers. They will clear once the upstream maintainers drop the deprecated transitive deps; the linked issues track that.

“Cannot find module” errors

Clear the npm cache and reinstall:

npm cache clean --force
npm install -g nexus-agents

Permission errors on Linux/macOS

Fix npm permissions:

# Option 1: Use a node version manager (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
nvm use 22

# Option 2: Change npm prefix
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

PATH not configured

Find and add the npm bin directory:

# Find the directory
npm config get prefix

# Add to PATH (bash)
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Add to PATH (zsh)
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Docker permission denied

Add your user to the docker group:

sudo usermod -aG docker $USER
# Log out and back in

Related Documentation

• Configuration - Set up models, experts, and routing
• Sandboxed Usage - Docker / restricted-FS / team-distribution flows
• Quick Start - Try your first orchestration
• CLI Usage - Learn all CLI commands