Installation

This guide will help you install and configure AIV Platform on your system.

Prerequisites

• Node.js 18.0 or higher
• npm 9.0 or higher (comes with Node.js)
• Git (for cloning the repository)

Optional Dependencies

• Docker - For running containerized agents
• Azure CLI - For Azure OpenAI integration

Installation Methods

Method 1: npm (Recommended)

# Install globally
npm install -g @aiversum/aiv

# Verify installation
aiv --version

Method 2: From Source

# Clone the repository
git clone https://github.com/aiversum/aiv.git
cd aiv

# Install dependencies
npm install

# Build
npm run build

# Link globally
npm link

Method 3: Development Mode

# Clone and install
git clone https://github.com/aiversum/aiv.git
cd aiv
npm install

# Run in development mode
npm run dev

Initial Setup

After installation, run the onboarding wizard:

aiv --setup

The wizard will guide you through:

1. Provider Configuration - Set up Anthropic, Azure, or OpenRouter
2. Workspace Setup - Configure your working directory
3. MCP Servers - Enable optional integrations
4. Validation - Test your configuration

Manual Configuration

If you prefer manual setup, create these files:

~/.aiv/config.json

{
  "defaultProvider": "anthropic",
  "anthropic": {
    "model": "claude-sonnet-4-20250514"
  },
  "workspace": "/path/to/your/workspace"
}

~/.aiv/.env

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...

# Or Azure OpenAI
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_KEY=...

# Or OpenRouter
OPENROUTER_API_KEY=sk-or-...

Security

The .env file should have restricted permissions:

chmod 600 ~/.aiv/.env

Verify Installation

Run the following commands to verify everything is working:

# Check version
aiv --version

# Test provider connection
aiv "Hello, world!"

# Check configuration
aiv
> /config

Next Steps

• Quick Start Guide - Run your first agent
• Configuration Reference - All config options
• First Agent Tutorial - Create a custom agent

Troubleshooting

Common Issues

"ANTHROPIC_API_KEY not found"

# Check if .env file exists and has the key
cat ~/.aiv/.env

# Or export directly
export ANTHROPIC_API_KEY=sk-ant-...

"Permission denied"

# Fix permissions
chmod 700 ~/.aiv
chmod 600 ~/.aiv/.env
chmod 600 ~/.aiv/config.json

"Node.js version too old"

# Check version
node --version

# Use nvm to install newer version
nvm install 20
nvm use 20

Getting Help

• Run aiv --help for command-line options
• Check GitHub Issues
• Join our community chat