Quickstart

Get started with Airi in 5 minutes - from installation to your first conversation

Get your AI companion up and running in minutes. This guide will take you from installation through your first conversation.

Prerequisites

Before you begin, make sure you have:

Modern Browser

Chrome, Edge, or another Chromium-based browser with WebGPU support (for web version)

LLM API Key

API key from OpenAI, Anthropic, or another supported provider

Don’t have an API key? You can use local models with Ollama or try the free tier from providers like OpenRouter.

Choose Your Installation Method

Web (Fastest)

1. Open Airi Web

   Visit https://airi.moeru.ai in your browser.

   No installation required! The web version runs entirely in your browser.

2. Grant Permissions

   When prompted, allow microphone access for voice chat (optional but recommended).

Desktop (Recommended)

1. Download

   Download the latest release for your platform:

   Windows

   # Download from GitHub releases
   https://github.com/moeru-ai/airi/releases/latest
   
   # Or use winget
   winget install MoeruAI.Airi
   
2. Install

   Run the installer for your platform. On macOS, drag Airi to your Applications folder.

3. Launch

   Open Airi from your applications menu or desktop shortcut.

Build from Source

1. Clone Repository

   git clone https://github.com/moeru-ai/airi.git
   cd airi
   
2. Install Dependencies

   # Install pnpm if you haven't already
   npm install -g pnpm
   
   # Install project dependencies
   pnpm install
   
3. Run Development Server

   Web

   pnpm dev:web
   

Configure Your LLM Provider

1. Open Settings

   Click the Settings icon in the sidebar or press Cmd/Ctrl + ,.

2. Navigate to Providers

   Go to Providers → LLM Providers in the settings panel.

3. Add Your Provider

   OpenAI

   {
     "provider": "openai",
     "apiKey": "sk-...",
     "model": "gpt-4-turbo-preview",
     "baseURL": "https://api.openai.com/v1"
   }
   

   Get your API key

   1. Visit platform.openai.com
   2. Sign up or log in
   3. Navigate to API Keys
   4. Click Create new secret key
   5. Copy and save your key securely

   Anthropic Claude

   {
     "provider": "anthropic",
     "apiKey": "sk-ant-...",
     "model": "claude-3-opus-20240229"
   }
   

   Get your API key

   1. Visit console.anthropic.com
   2. Sign up or log in
   3. Navigate to API Keys
   4. Click Create Key
   5. Copy your key

   OpenRouter

   {
     "provider": "openrouter",
     "apiKey": "sk-or-...",
     "model": "anthropic/claude-3.5-sonnet",
     "baseURL": "https://openrouter.ai/api/v1"
   }
   

   Get your API key

   1. Visit openrouter.ai
   2. Sign up or log in
   3. Navigate to Keys
   4. Create a new key
   5. Fund your account with credits (many models have free tiers!)

   Ollama (Local)

   {
     "provider": "ollama",
     "baseURL": "http://localhost:11434",
     "model": "llama3.2:latest"
   }
   

   Install Ollama

   1. Install Ollama from ollama.ai
   2. Pull a model: ollama pull llama3.2
   3. Verify it’s running: ollama list
   4. Use http://localhost:11434 as the base URL
4. Test Connection

   Click Test Connection to verify your configuration. You should see a success message.

   If the test fails, double-check your API key and base URL. Make sure there are no extra spaces or characters.

Optional: Configure Voice Synthesis

For voice chat, set up a text-to-speech provider:

1. Navigate to Voice Settings

   In Settings → Voice → Speech Synthesis.

2. Choose a Provider

   ElevenLabs (Best Quality)

   {
     "provider": "elevenlabs",
     "apiKey": "...",
     "voiceId": "21m00Tcm4TlvDq8ikWAM",
     "model": "eleven_turbo_v2"
   }
   

   Free tier: 10,000 characters/month

   OpenAI TTS

   {
     "provider": "openai",
     "apiKey": "sk-...",
     "voice": "alloy",
     "model": "tts-1"
   }
   

   Uses your OpenAI API key

   Browser TTS (Free)

   {
     "provider": "browser",
     "voice": "Google US English"
   }
   

   Built-in browser voices (free, no API key needed)

3. Test Voice

   Click Test Voice to hear a sample. Adjust settings like speed and pitch if needed.

Have Your First Conversation

1. Navigate to Chat

   Click the Chat icon in the sidebar or press Cmd/Ctrl + 1.

2. Start Talking

   Text Chat

   Type your message in the input box and press Enter:

   Hi! Tell me about yourself.
   

   Voice Chat

   1. Click the microphone icon
   2. Grant microphone permission if prompted
   3. Start speaking naturally
   4. Airi will respond with voice
3. Try Different Commands

   Experiment with various interactions:

   • What can you help me with?
   • Tell me a joke
   • What's the weather like? (requires integration)
   • Remember that my favorite color is blue

Your conversation history is saved locally and will persist across sessions. Airi uses this context to remember your preferences and previous discussions.

Troubleshooting

API key not working

• Verify your API key is correct (no extra spaces)
• Check that your account has credits/quota remaining
• For OpenAI, ensure billing is set up
• Try regenerating your API key

Voice chat not working

• Ensure microphone permissions are granted
• Check your browser supports Web Audio API
• Verify TTS provider is configured
• Try the Browser TTS provider as a fallback

Slow responses

• Some models are slower than others (try GPT-3.5-turbo or Claude Haiku)
• Check your internet connection
• For local models, ensure adequate GPU/CPU resources

Desktop app won't launch

• On macOS, right-click and select “Open” to bypass Gatekeeper
• On Windows, SmartScreen may require clicking “More info” → “Run anyway”
• On Linux, ensure the AppImage is executable: chmod +x airi.AppImage

Next Steps

Customize Your Character

Import Live2D or VRM models and customize personality

Explore Integrations

Connect to Discord, Telegram, or Minecraft

Configure Memory

Set up persistent memory and context management

Join Community

Get help and share your experience on Discord