Appearance

Installation ​

This guide walks you through installing and setting up Nexus - the combined system of Conductor (orchestration) + AI Learning Service (continuous improvement).

Try Before Installing

See Zeron systems in action:

Prerequisites ​

Before installing Nexus, ensure you have:

  • Node.js 18.0.0 or higher
  • Redis 6.0 or higher (for Conductor state management)
  • Claude Code CLI (claude command available in PATH)
  • Jira account with API access
  • Git repository for your project(s)
  • Python 3.8+ (optional - for AI Learning Service)

Verify Prerequisites ​

bash
# Check Node.js version
node --version
# Should output v18.0.0 or higher

# Check Redis
redis-cli ping
# Should output: PONG

# Check Claude Code CLI
which claude
# Should output path to claude executable

# Check Git
git --version

Install Nexus ​

1. Access Nexus ​

Contact us about accessing Nexus for your organization.

2. Install Conductor (Orchestration Engine) ​

bash
cd conductor
npm install

This will install:

  • VitePress and Vue (for documentation)
  • TypeDoc (for API documentation)
  • TypeScript and build tools
  • Conductor dependencies (Redis, Anthropic SDK, etc.)

3. Install AI Learning Service (Optional but Recommended) ​

bash
cd ../learning-service
npm install

This enables continuous improvement as Nexus learns from each completed ticket.

4. Configure Environment Variables ​

Create a .env file in the conductor directory:

bash
cp .env.example .env

Edit .env and add your credentials:

bash
# Anthropic API Key (required)
ANTHROPIC_API_KEY=your-anthropic-api-key-here

# Redis Configuration (defaults shown)
REDIS_HOST=localhost
REDIS_PORT=6379

# Jira Configuration (required)
JIRA_TOKEN=your-jira-token-here
JIRA_EMAIL=your-email@company.com

# Claude Code Path (optional, defaults to 'claude' in PATH)
CLAUDE_CODE_PATH=claude

Getting Your API Keys ​

Anthropic API Key:

  1. Go to https://console.anthropic.com/settings/keys
  2. Create a new API key
  3. Copy and paste into .env

Jira API Token:

  1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
  2. Click "Create API token"
  3. Give it a label (e.g., "Nexus" or "Conductor")
  4. Copy the token and paste into .env as JIRA_TOKEN

Security Warning

Never commit credentials to version control!

  • ✅ Keep .env in .gitignore (already configured)
  • ✅ Use .env.example as a template without real values
  • ✅ Rotate API keys regularly (monthly recommended)
  • ✅ Use read-only keys when possible
  • ❌ Never share API keys in chat, email, or documentation
  • ❌ Never commit .env files to Git
  • ❌ Never use production keys in development

If you accidentally commit credentials:

  1. Immediately revoke the exposed keys
  2. Generate new keys
  3. Update .env with new credentials
  4. Use git filter-repo or BFG Repo-Cleaner to remove from history

5. Start Redis ​

If Redis isn't already running:

bash
# macOS with Homebrew
brew services start redis

# Linux with systemd
sudo systemctl start redis

# Docker
docker run -d --name redis -p 6379:6379 redis:latest

# Verify Redis is running
redis-cli ping
# Should output: PONG

6. Build Nexus Components ​

bash
# Build Conductor
cd conductor
npm run build

# Build AI Learning Service (if installed)
cd ../learning-service
npm run build

This compiles TypeScript to JavaScript in the dist/ directory.

7. Verify Installation ​

Run health checks:

bash
# Start Conductor dev server
cd conductor
npm run dev

# In another terminal, check Conductor health
curl http://localhost:3000/health

Expected response:

json
{
  "status": "healthy",
  "timestamp": "2025-10-17T...",
  "redis": {
    "connected": true
  }
}

If you installed the AI Learning Service:

bash
# Start Learning Service
cd learning-service
npm run dev

# Check Learning Service health
curl http://localhost:8000/health

Optional: Build Go Process Spawner ​

If you plan to use CLI mode (legacy) for agent spawning:

bash
cd spawn
go build conductor-spawn.go
chmod +x conductor-spawn

# Verify
./conductor-spawn --version

SDK Mode Recommended

The modern SDK mode (use_sdk_agents: true) is recommended for new projects. It doesn't require the Go spawner and provides better control.

Next Steps ​

Now that Nexus is installed:

  1. Quick Start Guide - Configure your first project
  2. Learn about self-healing
  3. Enable AI Learning for continuous improvement
  4. Explore live demos - See other Zeron systems in action

Troubleshooting Installation ​

npm install fails ​

Error: EACCES: permission denied

Solution:

bash
# Don't use sudo! Fix npm permissions instead:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Redis connection fails ​

Error: Could not connect to Redis at localhost:6379

Solutions:

  1. Ensure Redis is running: brew services list or systemctl status redis
  2. Check Redis port: lsof -i :6379
  3. Try connecting manually: redis-cli ping

Claude Code not found ​

Error: Command not found: claude

Solution:

bash
# Install Claude Code CLI
npm install -g @anthropic-ai/claude-code

# Or set custom path in .env
CLAUDE_CODE_PATH=/path/to/your/claude

TypeScript build errors ​

Error: Various TypeScript compilation errors

Solution:

bash
# Clean and rebuild
npm run clean
npm install
npm run build

# Check TypeScript version
npx tsc --version
# Should be 5.3.3 or higher

Upgrading Nexus ​

To upgrade to the latest version:

bash
cd zeron

# Pull latest changes
git pull origin main

# Upgrade Conductor
cd conductor
npm install
npm run build

# Upgrade AI Learning Service (if installed)
cd ../learning-service
npm install
npm run build

# Restart services
npm run dev

Uninstalling ​

To completely remove Nexus:

bash
# Stop services if running
pkill -f "conductor"
pkill -f "vitepress"
pkill -f "learning-service"

# Remove files
cd ..
rm -rf zeron

# Stop Redis if no longer needed
brew services stop redis  # macOS
sudo systemctl stop redis  # Linux

Part of the Zeron Platform | Built with VitePress

Copyright © 2025 Zeron