Instalação no Windows

Passo a passo para instalar no Windows

7 min de leitura
instalaçãowindows

Windows Installation Guide for Synkra AIOX

🌐 EN | PT | ES

Supported Versions

| Windows Version | Status | Notes | | ------------------- | ------------------- | ----------------------- | | Windows 11 | ✅ Fully Supported | Recommended | | Windows 10 (22H2+) | ✅ Fully Supported | Requires latest updates | | Windows 10 (older) | ⚠️ Limited Support | Update recommended | | Windows Server 2022 | ✅ Fully Supported | | | Windows Server 2019 | ⚠️ Community Tested | |

Prerequisites

1. Node.js (v20 or higher)

Option A: Using the Official Installer (Recommended)

  1. Download from nodejs.org
  2. Choose the LTS version (20.x or higher)
  3. Run the installer with default options
  4. Verify installation in PowerShell:
node --version  # Should show v20.x.x
npm --version

Option B: Using winget

# Install via Windows Package Manager
winget install OpenJS.NodeJS.LTS

# Restart PowerShell, then verify
node --version

Option C: Using Chocolatey

# Install Chocolatey first (if not installed)
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Install Node.js
choco install nodejs-lts -y

# Restart PowerShell
node --version

Option D: Using nvm-windows

# Download nvm-windows from: https://github.com/coreybutler/nvm-windows/releases
# Install the latest nvm-setup.exe

# After installation, open new PowerShell:
nvm install 20
nvm use 20

2. Git for Windows

Using Official Installer (Recommended)

  1. Download from git-scm.com
  2. Run installer with these recommended options:
    • ✅ Git from the command line and also from 3rd-party software
    • ✅ Use bundled OpenSSH
    • ✅ Checkout Windows-style, commit Unix-style line endings
    • ✅ Use Windows' default console window

Using winget

winget install Git.Git

Using Chocolatey

choco install git -y

Verify installation:

git --version

3. GitHub CLI

Using winget (Recommended)

winget install GitHub.cli

Using Chocolatey

choco install gh -y

Using Official Installer

Download from cli.github.com

Authenticate:

gh auth login
# Follow prompts, choose "Login with a web browser"

4. Windows Terminal (Recommended)

For the best experience, use Windows Terminal:

winget install Microsoft.WindowsTerminal

Installation

Quick Install

  1. Open PowerShell or Windows Terminal

  2. Navigate to your project directory:

    cd C:\Users\YourName\projects\my-project

  3. Run the installer:

    npx github:SynkraAI/aiox-core install

What the Installer Does

The installer automatically:

  • ✅ Detects Windows and applies platform-specific configurations
  • ✅ Creates necessary directories with proper permissions
  • ✅ Configures IDE paths for Windows locations:
    • Cursor: %APPDATA%\Cursor\
    • Claude: %USERPROFILE%\.claude\
  • ✅ Handles Windows path separators (backslashes)
  • ✅ Configures line endings correctly (CRLF for batch, LF for scripts)
  • ✅ Sets up npm scripts compatible with cmd.exe and PowerShell

IDE-Specific Setup

Cursor

  1. Download from cursor.sh
  2. Run the installer
  3. IDE rules are installed to .cursor\rules\
  4. Keyboard shortcut: Ctrl+L to open chat
  5. Use @agent-name to activate agents

Claude Code (CLI)

  1. Install Claude Code:

    npm install -g @anthropic-ai/claude-code

  2. Commands are installed to .claude\commands\AIOX\

  3. Use /agent-name to activate agents

  4. Run the installer

  5. Use @agent-name to activate agents

VS Code

  1. Install Continue extension from marketplace
  2. AIOX can integrate via .continue\ configuration

Troubleshooting

Execution Policy Error

If you see running scripts is disabled:

# Check current policy
Get-ExecutionPolicy

# Set to allow local scripts (recommended)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Or temporarily bypass for current session
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process

npm EACCES or Permission Errors

# Fix npm cache permissions
npm cache clean --force

# Set npm prefix to user directory
npm config set prefix "$env:APPDATA\npm"

# Add to PATH (permanent)
[Environment]::SetEnvironmentVariable(
    "Path",
    [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:APPDATA\npm",
    "User"
)

Long Path Issues

Windows has a 260 character path limit by default. To enable long paths:

  1. Open Group Policy Editor (gpedit.msc)
  2. Navigate to: Computer Configuration → Administrative Templates → System → Filesystem
  3. Enable "Enable Win32 long paths"

Or via PowerShell (requires admin):

# Run as Administrator
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

SSL/Certificate Errors

# If npm shows SSL errors
npm config set strict-ssl false

# Better: Update certificates
npm config set cafile ""
npm config delete cafile

Node.js Not Found After Install

# Refresh environment variables
$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")

# Or restart PowerShell/Terminal

Antivirus Blocking npm

Some antivirus software blocks npm operations:

  1. Add exclusions for:

    • %APPDATA%\npm
    • %APPDATA%\npm-cache
    • %USERPROFILE%\node_modules
    • Your project directory

  2. Temporarily disable real-time scanning during install (not recommended for production)

Git Line Ending Issues

# Configure Git for Windows
git config --global core.autocrlf true
git config --global core.eol crlf

# For specific project (Unix-style)
git config core.autocrlf input

GitHub CLI Authentication

# Check status
gh auth status

# Re-authenticate
gh auth login --web

# If behind corporate proxy
$env:HTTPS_PROXY = "http://proxy.company.com:8080"
gh auth login

PowerShell Profile Issues

If commands aren't found, check your profile:

# View profile path
$PROFILE

# Create profile if it doesn't exist
if (!(Test-Path -Path $PROFILE)) {
    New-Item -ItemType File -Path $PROFILE -Force
}

# Add npm global path
Add-Content $PROFILE "`n`$env:Path += `";$env:APPDATA\npm`""

WSL Integration (Optional)

For users who prefer Linux tools within Windows:

Install WSL2

# Run as Administrator
wsl --install

# Install Ubuntu (default)
wsl --install -d Ubuntu

# Restart computer when prompted

Configure AIOX with WSL

# Inside WSL, follow the Linux installation guide
# See: docs/installation/linux.md

# Access Windows files from WSL
cd /mnt/c/Users/YourName/projects/my-project

# For best performance, keep projects in Linux filesystem
# Use: ~/projects/ instead of /mnt/c/

Cross-Environment Tips

  • Windows IDE + WSL Terminal: Point IDE to WSL paths
  • Git: Configure both environments consistently
  • npm: Install in the environment where you'll run commands

Corporate/Enterprise Setup

Behind a Proxy

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

# Set git proxy
git config --global http.proxy http://proxy.company.com:8080

# Set environment variable
$env:HTTP_PROXY = "http://proxy.company.com:8080"
$env:HTTPS_PROXY = "http://proxy.company.com:8080"

Using Internal npm Registry

# Set custom registry
npm config set registry https://npm.company.com/

# Or scope-specific
npm config set @company:registry https://npm.company.com/

Domain Joined Machines

If your machine is domain-joined and has restricted policies:

  1. Contact IT for Node.js/npm approval
  2. Request exceptions for:
    • %APPDATA%\npm
    • %USERPROFILE%\.claude
    • Project directories

Updating

To update an existing installation:

# Using npx (recommended)
npx github:SynkraAI/aiox-core install

# The updater will:
# - Detect existing installation
# - Back up customizations to .aiox-backup\
# - Update only changed files
# - Preserve configurations

Uninstallation

See the complete Uninstallation Guide for detailed steps.

Quick uninstall via PowerShell:

# Remove AIOX from project
Remove-Item -Recurse -Force .aiox-core
Remove-Item -Recurse -Force .claude\commands\AIOX

# Remove global npm packages
npm uninstall -g @synkra/aiox

System Requirements

| Requirement | Minimum | Recommended | | ----------- | --------- | ----------- | | Windows | 10 (22H2) | 11 | | RAM | 4GB | 8GB | | Disk Space | 1GB | 5GB | | Node.js | 18.x | 20.x LTS | | npm | 9.x | 10.x | | PowerShell | 5.1 | 7.x (Core) |

PowerShell vs Command Prompt

| Feature | PowerShell | Command Prompt | | -------------- | ------------- | ----------------- | | Recommended | ✅ Yes | ⚠️ Basic support | | npm support | ✅ Full | ✅ Full | | Git support | ✅ Full | ✅ Full | | Tab completion | ✅ Advanced | ⚠️ Limited | | Script support | ✅ .ps1 files | ⚠️ .bat/.cmd only |

Recommendation: Use PowerShell 7 or Windows Terminal for the best experience.

Next Steps

  1. Configure your IDE (see IDE-specific setup above)
  2. Run *help in your AI agent to see available commands
  3. Start with the User Guide
  4. Join our Discord Community for help

Additional Resources

Falar com o Time