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

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/.

better-sqlite3

Five memory backends (agentic, adaptive, typed, mobimem, decay) use better-sqlite3 for persistent storage. It is included as a regular dependency and installed automatically with pnpm install. If it fails to compile (requires native build tools), basic session and belief memory still work without it.

Run nexus-agents doctor to check if it’s available under “Checking data storage”.

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 two deprecation warnings. Both are benign, expected, and safe to ignore — they come from transitive dependencies of upstream packages, not from anything in the nexus-agents runtime:

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