Installation & Troubleshooting

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 [email protected]

# 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:

Download Node.js LTS from https://nodejs.org/
Install and restart your terminal
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):

Find npm prefix: npm config get prefix
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
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:

Check npm registry:

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

Reset registry:

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

Test connectivity:
```
npm ping
```

Behind corporate proxy:

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

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 [email protected]

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+)
x.x (or v9+)
x.x (same as npm)
2.0
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

Open your IDE (Claude Code, Cursor, etc.)
Activate an agent: @dev
Run help command: *help
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:

GitHub Issues: https://github.com/SynkraAI/aiox-core/issues
Run diagnostics: npx aiox-core@latest doctor
Check system info: npx aiox-core@latest info
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 [email protected] --force

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

Getting Started

Development

Extensions

​Quick Start

​System Requirements

​Download Links

​Installation Methods

​Method 1: npx (Recommended)

​Method 2: From GitHub

​Method 3: Global Installation

​Diagnostic Tool

​Windows (CMD)

​Windows (PowerShell)

​macOS/Linux

​Common Issues & Solutions

​Issue 1: “Node.js version too old”

​Issue 2: “npm version too old”

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

​Issue 4: “EACCES: permission denied”

​Issue 5: “ETIMEDOUT” or “ECONNREFUSED”

​Issue 6: “PowerShell execution policy” (Windows)

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

​Issue 8: “SSL/Certificate errors”

​Issue 9: Package shows old version

​Environment Verification Checklist

​Post-Installation Verification

​Verify AIOX Installation

​Test Agent Activation

​Brownfield Installation

​Installing in Existing Projects

​What AIOX Adds

​Safety Guarantees

​Getting Help

​When Reporting Issues

​Quick Reference

​Platform-Specific Notes

​Windows

​macOS

​Linux

​Advanced Troubleshooting

​Clear All Caches

​Network Debugging

​Version Conflicts

Build docs developers (and LLMs) love

Quick Start

System Requirements

Download Links

Installation Methods

Method 1: npx (Recommended)

Method 2: From GitHub

Method 3: Global Installation

Diagnostic Tool

Windows (CMD)

Windows (PowerShell)

macOS/Linux

Common Issues & Solutions

Issue 1: “Node.js version too old”

Issue 2: “npm version too old”

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

Issue 4: “EACCES: permission denied”

Issue 5: “ETIMEDOUT” or “ECONNREFUSED”

Issue 6: “PowerShell execution policy” (Windows)

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

Issue 8: “SSL/Certificate errors”

Issue 9: Package shows old version

Environment Verification Checklist

Post-Installation Verification

Verify AIOX Installation

Test Agent Activation

Brownfield Installation

Installing in Existing Projects

What AIOX Adds

Safety Guarantees

Getting Help

When Reporting Issues

Quick Reference

Platform-Specific Notes

Windows

macOS

Linux

Advanced Troubleshooting

Clear All Caches

Network Debugging

Version Conflicts