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)
Desktop (Recommended)
Build from Source
Open Airi Web
Visit https://airi.moeru.ai in your browser. No installation required! The web version runs entirely in your browser.
Grant Permissions
When prompted, allow microphone access for voice chat (optional but recommended).
Download
Download the latest release for your platform: # Download from GitHub releases https://github.com/moeru-ai/airi/releases/latest # Or use winget winget install MoeruAI.Airi
Install
Run the installer for your platform. On macOS, drag Airi to your Applications folder.
Launch
Open Airi from your applications menu or desktop shortcut.
Clone Repository
git clone https://github.com/moeru-ai/airi.git cd airi
Install Dependencies
# Install pnpm if you haven't already npm install -g pnpm # Install project dependencies pnpm install
Open Settings
Click the Settings icon in the sidebar or press Cmd/Ctrl + ,.
Navigate to Providers
Go to Providers → LLM Providers in the settings panel.
Add Your Provider
OpenAI
Anthropic Claude
OpenRouter
Ollama (Local)
{ "provider" : "openai" , "apiKey" : "sk-..." , "model" : "gpt-4-turbo-preview" , "baseURL" : "https://api.openai.com/v1" }
Visit platform.openai.com
Sign up or log in
Navigate to API Keys
Click Create new secret key
Copy and save your key securely
{ "provider" : "anthropic" , "apiKey" : "sk-ant-..." , "model" : "claude-3-opus-20240229" }
{ "provider" : "openrouter" , "apiKey" : "sk-or-..." , "model" : "anthropic/claude-3.5-sonnet" , "baseURL" : "https://openrouter.ai/api/v1" }
Visit openrouter.ai
Sign up or log in
Navigate to Keys
Create a new key
Fund your account with credits (many models have free tiers!)
{ "provider" : "ollama" , "baseURL" : "http://localhost:11434" , "model" : "llama3.2:latest" }
Install Ollama from ollama.ai
Pull a model: ollama pull llama3.2
Verify it’s running: ollama list
Use http://localhost:11434 as the base URL
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.
For voice chat, set up a text-to-speech provider:
Navigate to Voice Settings
In Settings → Voice → Speech Synthesis .
Choose a Provider
{ "provider" : "elevenlabs" , "apiKey" : "..." , "voiceId" : "21m00Tcm4TlvDq8ikWAM" , "model" : "eleven_turbo_v2" }
Free tier: 10,000 characters/month { "provider" : "openai" , "apiKey" : "sk-..." , "voice" : "alloy" , "model" : "tts-1" }
Uses your OpenAI API key { "provider" : "browser" , "voice" : "Google US English" }
Built-in browser voices (free, no API key needed)
Test Voice
Click Test Voice to hear a sample. Adjust settings like speed and pitch if needed.
Have Your First Conversation
Navigate to Chat
Click the Chat icon in the sidebar or press Cmd/Ctrl + 1.
Start Talking
Type your message in the input box and press Enter: Hi! Tell me about yourself.
Click the microphone icon
Grant microphone permission if prompted
Start speaking naturally
Airi will respond with voice
Try Different Commands
Experiment with various interactions:
What can you help me with?Tell me a jokeWhat'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
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
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
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
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
