> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/SynkraAI/aiox-core/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation & Troubleshooting

> Complete guide for installing AIOX and resolving common issues

## Quick Start

```bash theme={null}
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/](https://nodejs.org/) (Download LTS version - includes npm & npx)
* **Git**: [https://git-scm.com/](https://git-scm.com/) (Optional, but recommended)

## Installation Methods

### Method 1: npx (Recommended)

```bash theme={null}
# 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

```bash theme={null}
npx github:SynkraAI/aiox-core install
```

### Method 3: Global Installation

```bash theme={null}
npm install -g aiox-core
aiox-core
```

## Diagnostic Tool

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

### Windows (CMD)

```cmd theme={null}
curl -o diagnose.cmd https://raw.githubusercontent.com/SynkraAI/aiox-core/main/tools/quick-diagnose.cmd && diagnose.cmd
```

### Windows (PowerShell)

```powershell theme={null}
irm https://raw.githubusercontent.com/SynkraAI/aiox-core/main/tools/quick-diagnose.ps1 | iex
```

### macOS/Linux

```bash theme={null}
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/](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:**

```bash theme={null}
# 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):**

```bash theme={null}
# 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):**

```bash theme={null}
# 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:**

   ```bash theme={null}
   npm config get registry
   # Should be: https://registry.npmjs.org/
   ```

2. **Reset registry:**

   ```bash theme={null}
   npm config set registry https://registry.npmjs.org/
   ```

3. **Test connectivity:**

   ```bash theme={null}
   npm ping
   ```

4. **Behind corporate proxy:**

   ```bash theme={null}
   npm config set proxy http://proxy.company.com:8080
   npm config set https-proxy http://proxy.company.com:8080
   ```

5. **Use mirror (China):**

   ```bash theme={null}
   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:**

```powershell theme={null}
# Run as Administrator
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

### Issue 7: "Cannot find module" or "Missing dependencies"

**Solution:**

```bash theme={null}
# 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:**

```bash theme={null}
# 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:**

```bash theme={null}
# 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:

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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](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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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
```