Installation & Troubleshooting

Complete guide for installing AIOX and resolving common issues

Quick Start

npx aiox-core@latest

This command downloads and runs the latest version of AIOX-Core installer.

System Requirements

Requirement	Minimum Version	Check Command
Node.js	v18.0.0+	node --version
npm	v9.0.0+	npm --version
npx	(included with npm)	npx --version
Git	Any recent version	git --version

Download Links

• Node.js: https://nodejs.org/ (Download LTS version - includes npm & npx)
• Git: https://git-scm.com/ (Optional, but recommended)

Installation Methods

Method 1: npx (Recommended)

# Install in current directory
npx aiox-core@latest

# Install with specific version
npx aiox-core@2.2.0

# Show version
npx aiox-core@latest --version

# Show help
npx aiox-core@latest --help

Method 2: From GitHub

npx github:SynkraAI/aiox-core install

Method 3: Global Installation

npm install -g aiox-core
aiox-core

Diagnostic Tool

If you’re having installation issues, run our diagnostic tool:

Windows (CMD)

curl -o diagnose.cmd https://raw.githubusercontent.com/SynkraAI/aiox-core/main/tools/quick-diagnose.cmd && diagnose.cmd

Windows (PowerShell)

irm https://raw.githubusercontent.com/SynkraAI/aiox-core/main/tools/quick-diagnose.ps1 | iex

macOS/Linux

curl -fsSL https://raw.githubusercontent.com/SynkraAI/aiox-core/main/tools/diagnose-installation.js | node

Common Issues & Solutions

Issue 1: “Node.js version too old”

Error:

error engine Unsupported engine
error notsup Required: {"node":">=18.0.0"}

Solution:

1. Download Node.js LTS from https://nodejs.org/
2. Install and restart your terminal
3. Verify: node --version (should show v18+ or v20+)

Issue 2: “npm version too old”

Error:

npm ERR! Required: {"npm":">=9.0.0"}

Solution:

# Update npm globally
npm install -g npm@latest

# Verify
npm --version

Issue 3: “npx not found” or “npx command not recognized”

Cause: npm bin folder not in system PATH

Solution (Windows):

1. Find npm prefix: npm config get prefix
2. Add to PATH:
   • Press Win+X → System → Advanced system settings → Environment Variables
   • Edit “Path” under User variables
   • Add: C:\Users\YOUR_USERNAME\AppData\Roaming\npm
3. Restart terminal

Solution (macOS/Linux):

# Add to ~/.bashrc or ~/.zshrc
export PATH="$PATH:$(npm config get prefix)/bin"

# Reload
source ~/.bashrc

Issue 4: “EACCES: permission denied”

Solution (Windows):

Run terminal as Administrator

Solution (macOS/Linux):

# Fix npm permissions (recommended)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

# Or use nvm (best practice)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

Issue 5: “ETIMEDOUT” or “ECONNREFUSED”

Cause: Network/firewall blocking npm registry

Solutions:

1. Check npm registry:

   npm config get registry
   # Should be: https://registry.npmjs.org/
   

2. Reset registry:

   npm config set registry https://registry.npmjs.org/
   

3. Test connectivity:

   npm ping
   

4. Behind corporate proxy:

   npm config set proxy http://proxy.company.com:8080
   npm config set https-proxy http://proxy.company.com:8080
   

5. Use mirror (China):

   npm config set registry https://registry.npmmirror.com
   

Issue 6: “PowerShell execution policy” (Windows)

Error:

File cannot be loaded because running scripts is disabled on this system

Solution:

# Run as Administrator
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Issue 7: “Cannot find module” or “Missing dependencies”

Solution:

# Clear npm cache
npm cache clean --force

# Remove node_modules if exists
rm -rf node_modules

# Try again
npx aiox-core@latest

Issue 8: “SSL/Certificate errors”

Solution:

# Temporarily disable strict SSL (not recommended for production)
npm config set strict-ssl false

# Better: Update certificates
npm config set cafile /path/to/certificate.pem

Issue 9: Package shows old version

Cause: npm cache serving old version

Solution:

# Clear npx cache
npx clear-npx-cache

# Or force fresh download
npx --ignore-existing aiox-core@latest

# Or use specific version
npx aiox-core@2.2.0

Environment Verification Checklist

Run these commands to verify your environment:

# 1. Check Node.js (need v18+)
node --version

# 2. Check npm (need v9+)
npm --version

# 3. Check npx
npx --version

# 4. Check npm registry access
npm view aiox-core version

# 5. Test installation
npx aiox-core@latest --version

Expected output:

v22.x.x (or v18+/v20+)
11.x.x (or v9+)
11.x.x (same as npm)
2.2.0
2.2.0

Post-Installation Verification

Verify AIOX Installation

# Run AIOX doctor
npx aiox-core doctor

# Check system info
npx aiox-core info

# List installed agents
aiox agents list

Test Agent Activation

1. Open your IDE (Claude Code, Cursor, etc.)
2. Activate an agent: @dev
3. Run help command: *help
4. Verify you see agent commands

Brownfield Installation

Installing in Existing Projects

# Navigate to your existing project
cd my-existing-project

# Install AIOX (non-destructive)
npx aiox-core install

# Run doctor to verify compatibility
npx aiox-core doctor

What AIOX Adds

• .aiox-core/ directory with framework files
• IDE integration files (.claude/, .codex/, etc.)
• docs/stories/ directory for development stories
• npm scripts for quality gates and sync

Safety Guarantees

• Non-destructive: AIOX creates files, never overwrites existing
• Rollback: git checkout HEAD~1 -- . restores pre-AIOX state
• Config preservation: Your .eslintrc, tsconfig.json, etc. stay intact

Getting Help

If you’re still having issues:

1. GitHub Issues: https://github.com/SynkraAI/aiox-core/issues
2. Run diagnostics: npx aiox-core@latest doctor
3. Check system info: npx aiox-core@latest info
4. Discord: Join our community for support

When Reporting Issues

Please include:

• Operating system and version
• Node.js version (node --version)
• npm version (npm --version)
• Full error message
• Output of diagnostic tool

Quick Reference

Command	Description
npx aiox-core@latest	Install/run wizard
npx aiox-core@latest --version	Show version
npx aiox-core@latest --help	Show help
npx aiox-core@latest install	Install in current
npx aiox-core@latest init <name>	Create new project
npx aiox-core@latest doctor	Run diagnostics
npx aiox-core@latest info	Show system info

Platform-Specific Notes

Windows

• Use PowerShell or Git Bash for best compatibility
• Some commands may require running as Administrator
• Path separators use backslash (\) or forward slash (/)

macOS

• May need to install Xcode Command Line Tools
• Use Homebrew for Node.js: brew install node
• Path issues rare with modern Node.js installers

Linux

• Avoid using sudo with npm - use nvm instead
• May need to install build-essential: sudo apt install build-essential
• Permissions issues common - use nvm or fix npm permissions

Advanced Troubleshooting

Clear All Caches

# Clear npm cache
npm cache clean --force

# Clear npx cache
npx clear-npx-cache

# Remove node_modules
rm -rf node_modules package-lock.json

# Reinstall
npm install

Network Debugging

# Test npm registry connectivity
npm ping

# Check current registry
npm config get registry

# Test with verbose logging
npm install aiox-core --verbose

# Check proxy settings
npm config get proxy
npm config get https-proxy

Version Conflicts

# Check installed version
npm list aiox-core

# Force specific version
npm install aiox-core@2.2.0 --force

# Remove and reinstall
npm uninstall aiox-core
npm install aiox-core@latest