Installation

Complete installation guide for Airi across Web, Desktop, and Mobile platforms

Overview

Airi supports three deployment platforms, each optimized for different use cases. Choose the platform that best fits your needs:

Stage Web

Browser-based

Best for quick access and portability. Runs entirely in your browser using WebGPU.

Stage Tamagotchi

Desktop Application

Native app with CUDA/Metal support for maximum performance and system integration.

Stage Pocket

Mobile Apps

iOS and Android apps for your AI companion on the go.

System Requirements

Web

Minimum Requirements

• Browser: Chrome 113+, Edge 113+, or Opera 99+
• RAM: 4GB minimum, 8GB recommended
• GPU: WebGPU-compatible graphics card
• Internet: For cloud LLM providers (not required for Ollama)

Browser Compatibility

Browser	Version	WebGPU Support	Status
Chrome	113+	✅ Yes	Recommended
Edge	113+	✅ Yes	Recommended
Opera	99+	✅ Yes	Supported
Safari	Any	❌ Limited	Not supported
Firefox	Any	❌ Limited	Not supported

Check WebGPU support at webgpureport.org

Desktop

Windows

• OS: Windows 10 (64-bit) or later
• RAM: 8GB minimum, 16GB recommended
• GPU: NVIDIA GPU with CUDA support (optional, for local inference)
• Disk Space: 500MB for app, additional for models
• Dependencies: Visual Studio 2022 build tools (for development)

macOS

• OS: macOS 11 (Big Sur) or later
• RAM: 8GB minimum, 16GB recommended (Apple Silicon)
• GPU: Metal-compatible GPU (all modern Macs)
• Disk Space: 500MB for app, additional for models
• Architecture: Intel (x64) or Apple Silicon (arm64)

Linux

• OS: Ubuntu 20.04+, Debian 11+, Fedora 36+, or equivalent
• RAM: 8GB minimum, 16GB recommended
• GPU: NVIDIA GPU with CUDA 11.8+ (optional)
• Disk Space: 500MB for app, additional for models
• Dependencies: See Linux Dependencies below

Mobile

iOS

• OS: iOS 14.0 or later
• Device: iPhone 8 or newer
• Storage: 200MB for app, additional for data
• Internet: Required for cloud LLM providers

Android

• OS: Android 8.0 (Oreo) or later
• Device: 4GB RAM minimum
• Storage: 200MB for app, additional for data
• Internet: Required for cloud LLM providers

Mobile apps are currently in beta. Local inference is not yet available on mobile platforms.

Installation Methods

Stage Web (Browser Version)

The easiest way to get started — no installation required!

1. Open in browser

   Navigate to https://airi.moeru.ai using Chrome 113+, Edge 113+, or Opera 99+.

2. Install as PWA (optional)

   For a more app-like experience, install as a Progressive Web App:

   1. Click the install icon in your browser’s address bar
   2. Or click the menu (⋮) → Install Airi
   3. Airi will now launch as a standalone app

   PWA installation allows offline functionality and a cleaner UI without browser chrome.

3. Grant permissions

   When prompted, grant permissions for:

   • Microphone (for voice input)
   • Notifications (for updates and alerts)
   • Storage (for saving conversations and settings)

Run Locally from Source

For development or customization:

# Clone the repository
git clone https://github.com/moeru-ai/airi.git
cd airi

# Install dependencies
corepack enable
pnpm install

# Start development server
pnpm dev

# Open http://localhost:5173

Requires Node.js 23+ and pnpm. See Development Setup below.

Stage Tamagotchi (Desktop Application)

Native desktop application with advanced features and performance optimizations.

Windows

1. Download installer

   Download the latest Windows installer (.exe) from the GitHub Releases page.

   Choose the appropriate build:

   • airi-setup-x64.exe (64-bit Intel/AMD)
   • airi-setup-arm64.exe (ARM64)
2. Run installer

   1. Double-click the downloaded .exe file
   2. Windows SmartScreen may show a warning (click “More info” → “Run anyway”)
   3. Follow the installation wizard
   4. Choose installation location (default: C:\Program Files\Airi)
3. Launch Airi

   • Use the desktop shortcut, or
   • Search for “Airi” in the Start menu, or
   • Run from installation directory
4. Install CUDA (optional, for local inference)

   For NVIDIA GPU acceleration:

   1. Download CUDA Toolkit 11.8+
   2. Install with default settings
   3. Restart your computer
   4. Verify: Open PowerShell and run nvidia-smi

   CUDA is only needed if you want to run local models with GPU acceleration.

macOS

1. Download installer

   Download the latest macOS installer from the GitHub Releases page.

   Choose the appropriate build:

   • airi-x64.dmg (Intel Macs)
   • airi-arm64.dmg (Apple Silicon M1/M2/M3)
   • airi-universal.dmg (Universal binary)
2. Install the app

   1. Open the downloaded .dmg file
   2. Drag Airi to your Applications folder
   3. Eject the disk image
3. First launch

   1. Open Applications and double-click Airi
   2. macOS may show “Airi is from an unidentified developer”
   3. Right-click Airi → Open → Open (first time only)

   This is normal for apps downloaded outside the Mac App Store. Future launches won’t show this warning.

4. Grant permissions

   macOS will prompt you to grant permissions:

   • Microphone (for voice input)
   • Screen Recording (for screen sharing features)
   • Notifications (for alerts)

   Grant these in System Settings → Privacy & Security

Using Nix

If you have Nix with flakes enabled:

nix run github:moeru-ai/airi

Linux

1. Install dependencies

   Ubuntu/Debian

   sudo apt update
   sudo apt install -y \
     libssl-dev \
     libglib2.0-dev \
     libgtk-3-dev \
     libjavascriptcoregtk-4.1-dev \
     libwebkit2gtk-4.1-dev
   

   Fedora

   sudo dnf install -y \
     openssl-devel \
     glib2-devel \
     gtk3-devel \
     webkit2gtk4.1-devel
   

   Arch

   sudo pacman -S --needed \
     openssl \
     glib2 \
     gtk3 \
     webkit2gtk
   
2. Download AppImage or DEB

   Download from GitHub Releases:

   • airi-x64.AppImage (Universal, works on all distros)
   • airi-amd64.deb (Debian/Ubuntu)
   • airi-x86_64.rpm (Fedora/RHEL)
3. Install and run

   AppImage

   # Make executable
   chmod +x airi-x64.AppImage
   
   # Run
   ./airi-x64.AppImage
   

   Move to /usr/local/bin or ~/bin for system-wide access.

   DEB (Debian/Ubuntu)

   sudo dpkg -i airi-amd64.deb
   
   # If there are dependency errors
   sudo apt-get install -f
   
   # Run from application menu or:
   airi
   

   RPM (Fedora/RHEL)

   sudo rpm -i airi-x86_64.rpm
   
   # Or using dnf
   sudo dnf install ./airi-x86_64.rpm
   
   # Run
   airi
   
4. CUDA setup (optional)

   For NVIDIA GPU acceleration:

   # Add NVIDIA repository
   wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.0-1_all.deb
   sudo dpkg -i cuda-keyring_1.0-1_all.deb
   sudo apt-get update
   
   # Install CUDA toolkit
   sudo apt-get install -y cuda-toolkit-11-8
   
   # Add to PATH
   echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc
   source ~/.bashrc
   
   # Verify
   nvidia-smi
   

Build from Source (All Platforms)

For development or customization:

# Clone repository
git clone https://github.com/moeru-ai/airi.git
cd airi

# Install dependencies
corepack enable
pnpm install

# Development mode (hot reload)
pnpm dev:tamagotchi

# Build for production
pnpm build:tamagotchi

# Build installer packages
pnpm -F @proj-airi/stage-tamagotchi run build:win   # Windows
pnpm -F @proj-airi/stage-tamagotchi run build:mac   # macOS
pnpm -F @proj-airi/stage-tamagotchi run build:linux # Linux

Building from source requires additional dependencies. See Development Setup below.

Stage Pocket (Mobile)

Mobile apps for iOS and Android.

iOS

iOS app is currently in beta and not yet published to the App Store. You need to build from source or join the TestFlight beta.

TestFlight Beta (Coming Soon)

1. Join the Discord community
2. Request TestFlight access in #beta-testing
3. You’ll receive an invite link via email
4. Install TestFlight from the App Store
5. Open the invite link and install Airi

Build from Source

1. Prerequisites

   • macOS with Xcode 15+
   • Apple Developer account (free tier works)
   • Node.js 23+ and pnpm
   • CocoaPods: sudo gem install cocoapods
2. Clone and setup

   git clone https://github.com/moeru-ai/airi.git
   cd airi
   corepack enable
   pnpm install
   
3. Start dev server

   pnpm dev:pocket
   

   Note your local IP address from the output (e.g., https://192.168.1.100:5273).

4. Open in Xcode

   CAPACITOR_DEV_SERVER_URL=https://<your-ip>:5273 pnpm open:ios
   

   Replace <your-ip> with your actual IP address.

5. Configure signing

   1. In Xcode, select the project in the navigator
   2. Select the App target
   3. Go to Signing & Capabilities
   4. Select your Team (personal or organization)
   5. Xcode will automatically generate provisioning profiles
6. Build and run

   1. Connect your iPhone via USB
   2. Select your device in the Xcode toolbar
   3. Click the Run button (▶️) or press Cmd+R
   4. First time: Trust your developer certificate on the device
      • Settings → General → VPN & Device Management
      • Tap your developer account → Trust

Android

Android app is currently in beta and not yet published to Google Play Store. Build from source or request a beta APK.

Beta APK (Coming Soon)

1. Join the Discord community
2. Download the latest beta APK from #announcements
3. Enable Install from Unknown Sources on your device
4. Install the APK

Build from Source

1. Prerequisites

   • Android Studio Iguana or later
   • Android SDK 26+ (Android 8.0+)
   • Node.js 23+ and pnpm
   • Java 17+
2. Clone and setup

   git clone https://github.com/moeru-ai/airi.git
   cd airi
   corepack enable
   pnpm install
   
3. Build web assets

   pnpm -F @proj-airi/stage-pocket run build
   
4. Sync Capacitor

   cd apps/stage-pocket
   pnpm exec cap sync android
   pnpm exec cap open android
   

   Android Studio will open automatically.

5. Build and install

   In Android Studio:

   1. Wait for Gradle sync to complete
   2. Connect your Android device via USB (or use an emulator)
   3. Enable Developer Options and USB Debugging on your device
   4. Click Run (▶️) or press Shift+F10
   5. Select your device and click OK

Development Setup

For contributors and advanced users who want to build from source or develop custom features.

Prerequisites

All Platforms

Required:

• Git
• Node.js 23+ (LTS recommended)
• pnpm via corepack

# Check versions
node --version   # Should be v23.x.x or higher
git --version

# Enable pnpm
corepack enable
corepack prepare pnpm@latest --activate

Windows

1. Install Visual Studio 2022 with:
   • Desktop development with C++
   • Windows SDK
2. Install Rust (for native modules):
   rustup-init.exe
   rustup toolchain install stable-x86_64-pc-windows-msvc
   rustup default stable-x86_64-pc-windows-msvc
   
3. Install Node.js via scoop:
   scoop install nodejs
   

macOS

# Install Xcode Command Line Tools
xcode-select --install

# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install git node

# Optional: Rust for native modules
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Linux

# Install Node.js 23
curl -fsSL https://deb.nodesource.com/setup_23.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install Git
sudo apt-get install -y git

# Install build dependencies
sudo apt-get install -y \
  build-essential \
  libssl-dev \
  libglib2.0-dev \
  libgtk-3-dev \
  libjavascriptcoregtk-4.1-dev \
  libwebkit2gtk-4.1-dev

# Optional: Rust for native modules
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Clone and Install

# Clone repository
git clone https://github.com/moeru-ai/airi.git
cd airi

# Create a new branch (for contributions)
git checkout -b your-name/feature-name

# Install dependencies
corepack enable
pnpm install

# Build packages
pnpm build:packages

Development Commands

# Web development
pnpm dev                    # Start Stage Web (browser)
pnpm dev:web                # Alias for the above

# Desktop development  
pnpm dev:tamagotchi         # Start Stage Tamagotchi (Electron)

# Mobile development
pnpm dev:pocket             # Start web server for mobile
pnpm open:ios               # Open in Xcode

# Documentation
pnpm dev:docs               # Preview docs site

# Testing
pnpm test                   # Run all tests with coverage
pnpm test:run               # Run tests once without watch

# Linting & Type checking
pnpm lint                   # Check for lint errors
pnpm lint:fix               # Auto-fix lint errors
pnpm typecheck              # Run TypeScript compiler

# Building
pnpm build                  # Build all packages and apps
pnpm build:web              # Build web version only
pnpm build:tamagotchi       # Build desktop app installers

For detailed contribution guidelines, see Contributing.

Post-Installation Setup

After installing Airi, configure these essential settings:

1. Configure LLM Provider

   Go to Settings → Providers → Text Generation and add your API key. See Quickstart for detailed instructions.

2. Set up Voice Synthesis (optional)

   For voice chat, configure TTS in Settings → Providers → Speech Synthesis.

3. Import Character Model (optional)

   Add a Live2D or VRM model in Settings → Character → Import Model.

4. Enable Memory (optional)

   For persistent conversations, enable memory in Settings → Memory → Enable Persistent Memory.

Troubleshooting

Windows: 'MSVCP140.dll is missing'

Install Microsoft Visual C++ Redistributable.

macOS: 'App is damaged and can't be opened'

Remove the quarantine attribute:

xattr -cr /Applications/Airi.app

Linux: 'error while loading shared libraries'

Install missing dependencies:

sudo apt-get install -f  # Debian/Ubuntu
sudo dnf install <missing-package>  # Fedora

Build fails: 'Cannot find module'

Clean and reinstall:

rm -rf node_modules pnpm-lock.yaml
pnpm install
pnpm build:packages

Electron won't start: 'GPU process crashed'

Disable GPU acceleration:

# Add to environment or launch with:
ELECTRON_DISABLE_GPU=1 pnpm dev:tamagotchi

iOS: 'Developer certificate not trusted'

On your iPhone:

1. Go to Settings → General → VPN & Device Management
2. Tap your developer certificate
3. Tap Trust [Your Name]

Updating Airi

Desktop (Installed)

Airi checks for updates automatically on launch:

1. If an update is available, you’ll see a notification
2. Click Download and Install
3. Airi will download the update in the background
4. Restart to apply the update

Manual check: Settings → About → Check for Updates

Web (PWA)

Updates are automatic. Refresh the page or restart the PWA to get the latest version.

Source Installation

# Update to latest main branch
git checkout main
git pull origin main

# Update dependencies
pnpm install

# Rebuild packages
pnpm build:packages

Uninstalling

Windows

• Settings → Apps → Installed Apps → Search for “Airi” → Uninstall
• Or use the uninstaller in the installation directory
• User data: %APPDATA%\airi

macOS

1. Drag Airi from Applications to Trash
2. Remove user data: ~/Library/Application Support/ai.moeru.airi
3. Remove caches: ~/Library/Caches/ai.moeru.airi

Linux

# DEB
sudo apt remove airi

# RPM
sudo dnf remove airi

# AppImage
rm ~/airi-x64.AppImage

# Remove user data
rm -rf ~/.config/airi
rm -rf ~/.local/share/airi

Next Steps

Quickstart Guide

Get up and running with your first conversation

Configure Providers

Set up LLM, TTS, and STT providers

Import Characters

Add Live2D or VRM models

Join Discord

Get help from the community