> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/moeru-ai/airi/llms.txt
> Use this file to discover all available pages before exploring further.

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

<CardGroup cols={3}>
  <Card title="Stage Web" icon="globe">
    **Browser-based**

    Best for quick access and portability. Runs entirely in your browser using WebGPU.
  </Card>

  <Card title="Stage Tamagotchi" icon="laptop">
    **Desktop Application**

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

  <Card title="Stage Pocket" icon="mobile">
    **Mobile Apps**

    iOS and Android apps for your AI companion on the go.
  </Card>
</CardGroup>

## System Requirements

<Tabs>
  <Tab title="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 |

    <Note>
      Check WebGPU support at [webgpureport.org](https://webgpureport.org/)
    </Note>
  </Tab>

  <Tab title="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](#linux-dependencies) below
  </Tab>

  <Tab title="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

    <Warning>
      Mobile apps are currently in beta. Local inference is not yet available on mobile platforms.
    </Warning>
  </Tab>
</Tabs>

## Installation Methods

### Stage Web (Browser Version)

The easiest way to get started — no installation required!

<Steps>
  <Step title="Open in browser">
    Navigate to [https://airi.moeru.ai](https://airi.moeru.ai) using Chrome 113+, Edge 113+, or Opera 99+.
  </Step>

  <Step title="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

    <Tip>
      PWA installation allows offline functionality and a cleaner UI without browser chrome.
    </Tip>
  </Step>

  <Step title="Grant permissions">
    When prompted, grant permissions for:

    * **Microphone** (for voice input)
    * **Notifications** (for updates and alerts)
    * **Storage** (for saving conversations and settings)
  </Step>
</Steps>

#### Run Locally from Source

For development or customization:

```bash theme={null}
# 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
```

<Note>
  Requires Node.js 23+ and pnpm. See [Development Setup](#development-setup) below.
</Note>

### Stage Tamagotchi (Desktop Application)

Native desktop application with advanced features and performance optimizations.

<Tabs>
  <Tab title="Windows">
    <Steps>
      <Step title="Download installer">
        Download the latest Windows installer (`.exe`) from the [GitHub Releases](https://github.com/moeru-ai/airi/releases) page.

        Choose the appropriate build:

        * `airi-setup-x64.exe` (64-bit Intel/AMD)
        * `airi-setup-arm64.exe` (ARM64)
      </Step>

      <Step title="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`)
      </Step>

      <Step title="Launch Airi">
        * Use the desktop shortcut, or
        * Search for "Airi" in the Start menu, or
        * Run from installation directory
      </Step>

      <Step title="Install CUDA (optional, for local inference)">
        For NVIDIA GPU acceleration:

        1. Download [CUDA Toolkit 11.8+](https://developer.nvidia.com/cuda-downloads)
        2. Install with default settings
        3. Restart your computer
        4. Verify: Open PowerShell and run `nvidia-smi`

        <Tip>
          CUDA is only needed if you want to run local models with GPU acceleration.
        </Tip>
      </Step>
    </Steps>
  </Tab>

  <Tab title="macOS">
    <Steps>
      <Step title="Download installer">
        Download the latest macOS installer from the [GitHub Releases](https://github.com/moeru-ai/airi/releases) page.

        Choose the appropriate build:

        * `airi-x64.dmg` (Intel Macs)
        * `airi-arm64.dmg` (Apple Silicon M1/M2/M3)
        * `airi-universal.dmg` (Universal binary)
      </Step>

      <Step title="Install the app">
        1. Open the downloaded `.dmg` file
        2. Drag **Airi** to your **Applications** folder
        3. Eject the disk image
      </Step>

      <Step title="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)

        <Note>
          This is normal for apps downloaded outside the Mac App Store. Future launches won't show this warning.
        </Note>
      </Step>

      <Step title="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**
      </Step>
    </Steps>

    #### Using Nix

    If you have Nix with flakes enabled:

    ```bash theme={null}
    nix run github:moeru-ai/airi
    ```
  </Tab>

  <Tab title="Linux">
    <Steps>
      <Step title="Install dependencies">
        <Tabs>
          <Tab title="Ubuntu/Debian">
            ```bash theme={null}
            sudo apt update
            sudo apt install -y \
              libssl-dev \
              libglib2.0-dev \
              libgtk-3-dev \
              libjavascriptcoregtk-4.1-dev \
              libwebkit2gtk-4.1-dev
            ```
          </Tab>

          <Tab title="Fedora">
            ```bash theme={null}
            sudo dnf install -y \
              openssl-devel \
              glib2-devel \
              gtk3-devel \
              webkit2gtk4.1-devel
            ```
          </Tab>

          <Tab title="Arch">
            ```bash theme={null}
            sudo pacman -S --needed \
              openssl \
              glib2 \
              gtk3 \
              webkit2gtk
            ```
          </Tab>
        </Tabs>
      </Step>

      <Step title="Download AppImage or DEB">
        Download from [GitHub Releases](https://github.com/moeru-ai/airi/releases):

        * `airi-x64.AppImage` (Universal, works on all distros)
        * `airi-amd64.deb` (Debian/Ubuntu)
        * `airi-x86_64.rpm` (Fedora/RHEL)
      </Step>

      <Step title="Install and run">
        <Tabs>
          <Tab title="AppImage">
            ```bash theme={null}
            # Make executable
            chmod +x airi-x64.AppImage

            # Run
            ./airi-x64.AppImage
            ```

            <Tip>
              Move to `/usr/local/bin` or `~/bin` for system-wide access.
            </Tip>
          </Tab>

          <Tab title="DEB (Debian/Ubuntu)">
            ```bash theme={null}
            sudo dpkg -i airi-amd64.deb

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

            # Run from application menu or:
            airi
            ```
          </Tab>

          <Tab title="RPM (Fedora/RHEL)">
            ```bash theme={null}
            sudo rpm -i airi-x86_64.rpm

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

            # Run
            airi
            ```
          </Tab>
        </Tabs>
      </Step>

      <Step title="CUDA setup (optional)">
        For NVIDIA GPU acceleration:

        ```bash theme={null}
        # 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
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

#### Build from Source (All Platforms)

For development or customization:

```bash theme={null}
# 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
```

<Warning>
  Building from source requires additional dependencies. See [Development Setup](#development-setup) below.
</Warning>

### Stage Pocket (Mobile)

Mobile apps for iOS and Android.

<Tabs>
  <Tab title="iOS">
    <Warning>
      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.
    </Warning>

    #### TestFlight Beta (Coming Soon)

    1. Join the [Discord community](https://discord.gg/TgQ3Cu2F7A)
    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

    <Steps>
      <Step title="Prerequisites">
        * macOS with Xcode 15+
        * Apple Developer account (free tier works)
        * Node.js 23+ and pnpm
        * CocoaPods: `sudo gem install cocoapods`
      </Step>

      <Step title="Clone and setup">
        ```bash theme={null}
        git clone https://github.com/moeru-ai/airi.git
        cd airi
        corepack enable
        pnpm install
        ```
      </Step>

      <Step title="Start dev server">
        ```bash theme={null}
        pnpm dev:pocket
        ```

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

      <Step title="Open in Xcode">
        ```bash theme={null}
        CAPACITOR_DEV_SERVER_URL=https://<your-ip>:5273 pnpm open:ios
        ```

        Replace `<your-ip>` with your actual IP address.
      </Step>

      <Step title="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
      </Step>

      <Step title="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**
      </Step>
    </Steps>
  </Tab>

  <Tab title="Android">
    <Warning>
      Android app is currently in beta and not yet published to Google Play Store. Build from source or request a beta APK.
    </Warning>

    #### Beta APK (Coming Soon)

    1. Join the [Discord community](https://discord.gg/TgQ3Cu2F7A)
    2. Download the latest beta APK from #announcements
    3. Enable **Install from Unknown Sources** on your device
    4. Install the APK

    #### Build from Source

    <Steps>
      <Step title="Prerequisites">
        * Android Studio Iguana or later
        * Android SDK 26+ (Android 8.0+)
        * Node.js 23+ and pnpm
        * Java 17+
      </Step>

      <Step title="Clone and setup">
        ```bash theme={null}
        git clone https://github.com/moeru-ai/airi.git
        cd airi
        corepack enable
        pnpm install
        ```
      </Step>

      <Step title="Build web assets">
        ```bash theme={null}
        pnpm -F @proj-airi/stage-pocket run build
        ```
      </Step>

      <Step title="Sync Capacitor">
        ```bash theme={null}
        cd apps/stage-pocket
        pnpm exec cap sync android
        pnpm exec cap open android
        ```

        Android Studio will open automatically.
      </Step>

      <Step title="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**
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Development Setup

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

### Prerequisites

<Tabs>
  <Tab title="All Platforms">
    **Required:**

    * [Git](https://git-scm.com/downloads)
    * [Node.js 23+](https://nodejs.org/) (LTS recommended)
    * [pnpm](https://pnpm.io/) via corepack

    ```bash theme={null}
    # Check versions
    node --version   # Should be v23.x.x or higher
    git --version

    # Enable pnpm
    corepack enable
    corepack prepare pnpm@latest --activate
    ```
  </Tab>

  <Tab title="Windows">
    1. Install [Visual Studio 2022](https://visualstudio.microsoft.com/downloads/) with:
       * Desktop development with C++
       * Windows SDK
    2. Install [Rust](https://rustup.rs/) (for native modules):
       ```powershell theme={null}
       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](https://scoop.sh/):
       ```powershell theme={null}
       scoop install nodejs
       ```
  </Tab>

  <Tab title="macOS">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    # 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
    ```
  </Tab>
</Tabs>

### Clone and Install

```bash theme={null}
# 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

```bash theme={null}
# 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
```

<Note>
  For detailed contribution guidelines, see [Contributing](/development/contributing).
</Note>

## Post-Installation Setup

After installing Airi, configure these essential settings:

<Steps>
  <Step title="Configure LLM Provider">
    Go to **Settings** → **Providers** → **Text Generation** and add your API key. See [Quickstart](/quickstart#step-2-configure-your-llm-provider) for detailed instructions.
  </Step>

  <Step title="Set up Voice Synthesis (optional)">
    For voice chat, configure TTS in **Settings** → **Providers** → **Speech Synthesis**.
  </Step>

  <Step title="Import Character Model (optional)">
    Add a Live2D or VRM model in **Settings** → **Character** → **Import Model**.
  </Step>

  <Step title="Enable Memory (optional)">
    For persistent conversations, enable memory in **Settings** → **Memory** → **Enable Persistent Memory**.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Windows: 'MSVCP140.dll is missing'">
    Install [Microsoft Visual C++ Redistributable](https://aka.ms/vs/17/release/vc_redist.x64.exe).
  </Accordion>

  <Accordion title="macOS: 'App is damaged and can't be opened'">
    Remove the quarantine attribute:

    ```bash theme={null}
    xattr -cr /Applications/Airi.app
    ```
  </Accordion>

  <Accordion title="Linux: 'error while loading shared libraries'">
    Install missing dependencies:

    ```bash theme={null}
    sudo apt-get install -f  # Debian/Ubuntu
    sudo dnf install <missing-package>  # Fedora
    ```
  </Accordion>

  <Accordion title="Build fails: 'Cannot find module'">
    Clean and reinstall:

    ```bash theme={null}
    rm -rf node_modules pnpm-lock.yaml
    pnpm install
    pnpm build:packages
    ```
  </Accordion>

  <Accordion title="Electron won't start: 'GPU process crashed'">
    Disable GPU acceleration:

    ```bash theme={null}
    # Add to environment or launch with:
    ELECTRON_DISABLE_GPU=1 pnpm dev:tamagotchi
    ```
  </Accordion>

  <Accordion title="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]**
  </Accordion>
</AccordionGroup>

## Updating Airi

<Tabs>
  <Tab title="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**
  </Tab>

  <Tab title="Web (PWA)">
    Updates are automatic. Refresh the page or restart the PWA to get the latest version.
  </Tab>

  <Tab title="Source Installation">
    ```bash theme={null}
    # Update to latest main branch
    git checkout main
    git pull origin main

    # Update dependencies
    pnpm install

    # Rebuild packages
    pnpm build:packages
    ```
  </Tab>
</Tabs>

## Uninstalling

<Tabs>
  <Tab title="Windows">
    * **Settings** → **Apps** → **Installed Apps** → Search for "Airi" → **Uninstall**
    * Or use the uninstaller in the installation directory
    * User data: `%APPDATA%\airi`
  </Tab>

  <Tab title="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`
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    # 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
    ```
  </Tab>
</Tabs>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart Guide" icon="rocket" href="/quickstart">
    Get up and running with your first conversation
  </Card>

  <Card title="Configure Providers" icon="sliders" href="/features/llm-providers">
    Set up LLM, TTS, and STT providers
  </Card>

  <Card title="Import Characters" icon="user" href="/features/character-models">
    Add Live2D or VRM models
  </Card>

  <Card title="Join Discord" icon="discord" href="https://discord.gg/TgQ3Cu2F7A">
    Get help from the community
  </Card>
</CardGroup>