Installation

Overview

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

Stage Web

Browser-basedBest for quick access and portability. Runs entirely in your browser using WebGPU.

Stage Tamagotchi

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

Stage Pocket

Mobile AppsiOS and Android apps for your AI companion on the go.

System Requirements

Web
Desktop
Mobile

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

Installation Methods

Stage Web (Browser Version)

The easiest way to get started — no installation required!

Open in browser

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

Install as PWA (optional)

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

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

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

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
macOS
Linux

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)

Run installer

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

Launch Airi

Use the desktop shortcut, or
Search for “Airi” in the Start menu, or
Run from installation directory

Install CUDA (optional, for local inference)

For NVIDIA GPU acceleration:

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

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

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)

Install the app

Open the downloaded .dmg file
Drag Airi to your Applications folder
Eject the disk image

First launch

Open Applications and double-click Airi
macOS may show “Airi is from an unidentified developer”
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.

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

Install dependencies

Ubuntu/Debian
Fedora
Arch

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

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

sudo pacman -S --needed \
  openssl \
  glib2 \
  gtk3 \
  webkit2gtk

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)

Install and run

AppImage
DEB (Debian/Ubuntu)
RPM (Fedora/RHEL)

# Make executable
chmod +x airi-x64.AppImage

# Run
./airi-x64.AppImage

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

sudo dpkg -i airi-amd64.deb

# If there are dependency errors
sudo apt-get install -f

# Run from application menu or:
airi

sudo rpm -i airi-x86_64.rpm

# Or using dnf
sudo dnf install ./airi-x86_64.rpm

# Run
airi

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
Android

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)

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

Build from Source

Prerequisites

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

Clone and setup

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

Start dev server

pnpm dev:pocket

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

Open in Xcode

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

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

Configure signing

In Xcode, select the project in the navigator
Select the App target
Go to Signing & Capabilities
Select your Team (personal or organization)
Xcode will automatically generate provisioning profiles

Build and run

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

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)

Join the Discord community
Download the latest beta APK from #announcements
Enable Install from Unknown Sources on your device
Install the APK

Build from Source

Prerequisites

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

Clone and setup

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

Build web assets

pnpm -F @proj-airi/stage-pocket run build

Sync Capacitor

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

Android Studio will open automatically.

Build and install

In Android Studio:

Wait for Gradle sync to complete
Connect your Android device via USB (or use an emulator)
Enable Developer Options and USB Debugging on your device
Click Run (▶️) or press Shift+F10
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
Windows
macOS
Linux

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

Install Visual Studio 2022 with:
- Desktop development with C++
- Windows SDK

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

Install Node.js via scoop:
```
scoop install nodejs
```

# 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

# 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:

Configure LLM Provider

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

Set up Voice Synthesis (optional)

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

Import Character Model (optional)

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

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:

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

Updating Airi

Desktop (Installed)
Web (PWA)
Source Installation

Airi checks for updates automatically on launch:

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

Manual check: Settings → About → Check for Updates

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

# Update dependencies
pnpm install

# Rebuild packages
pnpm build:packages

Uninstalling

Windows
macOS
Linux

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

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

# 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

Get Started

Core Features

Platforms

Integrations

Configuration

Development

​Overview

Stage Web

Stage Tamagotchi

Stage Pocket

​System Requirements

​Minimum Requirements

​Browser Compatibility

​Windows

​macOS

​Linux

​iOS

​Android

​Installation Methods

​Stage Web (Browser Version)

​Run Locally from Source

​Stage Tamagotchi (Desktop Application)

​Using Nix

​Build from Source (All Platforms)

​Stage Pocket (Mobile)

​TestFlight Beta (Coming Soon)

​Build from Source

​Beta APK (Coming Soon)

​Build from Source

​Development Setup

​Prerequisites

​Clone and Install

​Development Commands

​Post-Installation Setup

​Troubleshooting

​Updating Airi

​Uninstalling

​Next Steps

Quickstart Guide

Configure Providers

Import Characters

Join Discord

Build docs developers (and LLMs) love

Overview

System Requirements

Minimum Requirements

Browser Compatibility

Windows

macOS

Linux

iOS

Android

Installation Methods

Stage Web (Browser Version)

Run Locally from Source

Stage Tamagotchi (Desktop Application)

Using Nix

Build from Source (All Platforms)

Stage Pocket (Mobile)

TestFlight Beta (Coming Soon)

Build from Source

Beta APK (Coming Soon)

Build from Source

Development Setup

Prerequisites

Clone and Install

Development Commands

Post-Installation Setup

Troubleshooting

Updating Airi

Uninstalling

Next Steps