# Project AIRI User Guide

Project AIRI is an open-source **cyber living being** — a self-hostable AI companion (sometimes called a "cyber waifu," digital pet, or AI VTuber) that you can talk to, that can see your screen, and that can play games with you. It is an open-source re-creation of [Neuro-sama](https://www.youtube.com/@Neurosama) and an open alternative to closed companion products, built so that **you own your digital life — easily, anywhere, anytime.**

AIRI renders an animated character (a 2D Live2D model or a 3D VRM model), drives it with a large language model of your choice, gives it a voice through text-to-speech, lets it hear you through speech recognition, and connects it to the outside world through Discord, Telegram, Minecraft, your code editor, and more. It runs in three places: in your **web browser**, as a **desktop companion** that floats on your screen, and on your **phone**.

> [!NOTE]
> AIRI is developed by [@moeru-ai](https://github.com/moeru-ai) and is under active, early-stage development. Features marked "WIP" or "not yet released" in this guide reflect the state of the documented release (`v0.10.2`). The always-current online version of this guide lives at [moeru-ai/airi](/moeru-ai/airi/).

---

## Table of Contents

1. [What You Can Do With AIRI](#1-what-you-can-do-with-airi)
2. [Choosing a Version: Web, Desktop, or Mobile](#2-choosing-a-version-web-desktop-or-mobile)
3. [Quick Start](#3-quick-start)
4. [Installation](#4-installation)
5. [First-Time Setup](#5-first-time-setup)
6. [The Desktop Companion Interface](#6-the-desktop-companion-interface)
7. [Settings Reference](#7-settings-reference)
8. [Everyday Tasks](#8-everyday-tasks)
9. [Connecting AIRI to Other Apps](#9-connecting-airi-to-other-apps)
10. [Supported AI Service Providers](#10-supported-ai-service-providers)
11. [Working With Character Models](#11-working-with-character-models)
12. [How AIRI Works (Concepts)](#12-how-airi-works-concepts)
13. [Troubleshooting](#13-troubleshooting)
14. [Frequently Asked Questions](#14-frequently-asked-questions)
15. [Reference](#15-reference)

---

## 1. What You Can Do With AIRI

AIRI is organized around a simple metaphor: it has a **brain**, **ears**, a **mouth**, and a **body**. Each capability is something you can turn on, configure, and use.

| Capability | What it means for you | Status |
|---|---|---|
| **Brain — Chat** | Hold a conversation with a character powered by an LLM (ChatGPT, Claude, Gemini, DeepSeek, local models, and many more). | Available |
| **Brain — Play games** | AIRI can play [Minecraft](https://www.minecraft.net) and (proof-of-concept) [Factorio](https://www.factorio.com); Kerbal Space Program is demoed. | Minecraft available; others WIP |
| **Brain — Memory** | In-browser database memory (DuckDB WASM / `pglite`). A long-term "Memory Alaya" system is in progress. | Partial |
| **Ears — Hearing** | Speak to AIRI using your microphone; client-side speech recognition turns your voice into text. Also supports listening in a Discord voice channel. | Available |
| **Mouth — Voice** | AIRI speaks back using multi-provider text-to-speech (ElevenLabs, Azure Speech, OpenAI-compatible TTS, Alibaba Cloud, and local Kokoro). | Available |
| **Eyes — Vision** | AIRI can capture your screen and "see" what you are doing, then react to it. | Available (desktop, opt-in) |
| **Body — Models** | Display AIRI as a 2D Live2D character or a 3D VRM character, with automatic blinking, idle eye movement, and look-at behavior. | Available |
| **Artistry** | AIRI can generate images on demand through a third-party image-generation service. | Available |

> [!TIP]
> You do not have to enable everything. Many people start with just **Chat** (a single LLM API key) and a character model, then add voice, hearing, and vision later.

---

## 2. Choosing a Version: Web, Desktop, or Mobile

AIRI ships as three products that share the same core. Pick the one that fits how you want to use it.

| Version | Best for | How you get it |
|---|---|---|
| **Web** (`stage-web`) | Trying AIRI instantly with nothing to install; quick chats from any computer. | Open [airi.moeru.ai](https://airi.moeru.ai) in a browser |
| **Desktop** (`stage-tamagotchi`) | A companion that floats on your desktop; VTuber streaming; computer/screen awareness; running **local** LLMs so you don't pay per token. | Download an installer for Windows / macOS / Linux |
| **Mobile** (`stage-pocket`) | Carrying AIRI on your phone. | Install the web app as a PWA, or build from source |

> [!NOTE]
> The web version is intentionally limited to what browsers allow. The **desktop version is the most capable**: it can use native NVIDIA CUDA and Apple Metal acceleration for local inference, capture your screen, and open raw network connections (for example, to a Discord voice channel or a Minecraft/Factorio server) that browsers forbid.

> [!TIP]
> You can run the desktop version as a **WebSocket server** and connect the mobile (Pocket) version to it over your local network, so your phone drives the same AIRI brain running on your PC. See [Section 9](#9-connecting-airi-to-other-apps).

---

## 3. Quick Start

The fastest way to meet AIRI is the web version — no installation, no account required to start.

1. Open **[airi.moeru.ai](https://airi.moeru.ai)** in a modern browser (Chrome, Edge, or any Chromium-based browser is recommended for full WebGPU support).
2. Choose your language.
3. Click **setup with your provider**.
4. Pick an AI service source (for example, OpenAI, DeepSeek, or OpenRouter), paste your **API key**, and click **Next**.
5. Choose a **model** and click **Save and continue**.
6. Type a message in the chat box and talk to AIRI.

```text
You: Hello! Who are you?
AIRI: Hi there! I'm AIRI — your cyber companion. Ask me anything,
      or we can just hang out. ✨
```

> [!IMPORTANT]
> You need at least one **LLM API key** from a service provider before AIRI can chat. Getting a key is done on the provider's website (for example, the OpenAI or DeepSeek dashboard), not inside AIRI. Keep your key private. See [Section 10](#10-supported-ai-service-providers).

---

## 4. Installation

### 4.1 Web (no installation)

Open [airi.moeru.ai](https://airi.moeru.ai). The web app also supports being installed as a **Progressive Web App (PWA)** — use your browser's "Install app" option to add it to your home screen or app launcher, including on mobile devices.

### 4.2 Desktop

Pick whichever method matches your operating system. All methods install the same desktop application.

=== "Windows (winget)"

    ```powershell
    winget install MoeruAI.AIRI
    ```

=== "Windows (Scoop)"

    ```powershell
    scoop bucket add airi https://github.com/moeru-ai/airi
    scoop install airi/airi
    ```

=== "macOS (Homebrew Cask)"

    ```sh
    brew install --cask airi
    ```

=== "Manual download (all platforms)"

    1. Go to the [releases page](https://github.com/moeru-ai/airi/releases/latest).
    2. Open the **Assets** section for the latest release.
    3. Download the file for your system:
       - Windows: `AIRI-<version>-windows-x64-setup.exe`
       - macOS (Apple Silicon): `AIRI-<version>-darwin-arm64.dmg`
       - Linux: the AppImage / archive listed under assets
    4. Run the installer (Windows/macOS) or make the AppImage executable and launch it (Linux).

=== "Nix"

    ```sh
    nix run github:moeru-ai/airi
    ```

> [!NOTE]
> On Windows, you may need to click **Show all assets** on the release page to reveal every download. The number of releases and assets shown on GitHub will differ from any example.

> [!TIP]
> AIRI has an automatic updater built in. You can check for updates from the **About** page inside the app, and switch update channels (`stable`, `beta`, `alpha`, `nightly`) if you want early builds.

### 4.3 Mobile

The simplest path is to open [airi.moeru.ai](https://airi.moeru.ai) on your phone and use your browser's **Add to Home Screen / Install** option to install it as a PWA. Native iOS and Android builds (via Capacitor) exist in the project but are primarily for developers; see the [Admin Guide](/moeru-ai/airi/admin-guide/) for building from source.

### 4.4 System requirements

| Item | Requirement |
|---|---|
| Browser (web/PWA) | A modern, up-to-date browser. WebGPU support is recommended for 3D models and in-browser inference. |
| Desktop OS | Windows 10/11 (x64), macOS (Apple Silicon `arm64` or Intel `x86_64`), or modern Linux (x64). |
| GPU (optional) | NVIDIA (CUDA) or Apple (Metal) GPU enables fast **local** model inference on desktop. Cloud providers need no GPU. |
| Network | Internet access to reach your chosen AI provider (unless you run models locally). |

---

## 5. First-Time Setup

When you launch AIRI for the first time (desktop or web), an onboarding flow walks you through connecting an AI provider.

1. **Open AIRI.** The desktop app usually opens automatically after installation.
2. **Select your language** in the main window.
3. Click **setup with your provider**. (You can alternatively click **Login** to use an AIRI account — optional.)
4. **Select your service source** (your AI provider) and click **Next**.
5. **Enter your API key** and click **Next**.
6. Click **Next** again to confirm.
7. **Select the model** you want to use, then click **Save and continue**.

You have now completed initial configuration. AIRI is ready to chat.

> [!TIP]
> If your provider isn't listed, choose **OpenAI Compatible API**. The vast majority of AI services expose an OpenAI-compatible endpoint, and this option lets you point AIRI at any of them by entering the base URL and key.

> [!WARNING]
> Keep your API key safe and never share it. Anyone with your key can spend money on your account.

---

## 6. The Desktop Companion Interface

The desktop companion ("Stage Tamagotchi") is a floating window that shows your character. This section describes its on-screen controls and system-tray menu.

### 6.1 The main window

The main window displays your character model. Three buttons sit in the bottom-right corner:

- **Expand** — reveals more options (see below).
- **Open hearing control** — lets you speak to AIRI (requires a speech-to-text service to be configured).
- **Move** — long-press and drag to reposition the window.

Clicking **Expand** reveals a login button plus eight quick actions:

| Action | What it does |
|---|---|
| **Login** | Sign in to your AIRI account (optional). |
| **Open settings** | Opens the settings window. |
| **Switch character** | Switch between character cards. |
| **Open chat** | Opens the chat window. |
| **Refresh** | Refreshes the main window (also a fix for a startup glitch — see Troubleshooting). |
| **Switch to dark mode** | Toggles light/dark theme. |
| **Unpin** | Stops the window from staying always-on-top. |
| **Always show / Hide on hover** | Lets clicks pass *through* the window. |
| **Close** | Closes AIRI. |

### 6.2 The system-tray menu

Right-click the AIRI icon in your system tray (on Windows you may need **Show hidden icons**) for window management:

- **Show** — bring up the main window.
- **Adjust size** — set the window size: *Recommended (450×600)*, *Full height*, *Half height*, or *Full screen*.
- **Align to** — snap the window to *Center*, *Top left*, *Top right*, *Bottom left*, or *Bottom right*.
- **Settings** — open the settings window.
- **About** — version and update information.
- **Open quick actions / Open widgets** — utility panels.
- **Open caption** — show subtitles of what AIRI says (requires a TTS service; hidden on hover by default).
- **Caption overlay** — *Follow window* (caption tracks the main window) or *Reset position*.
- **Quit** — close AIRI.

### 6.3 The chat window

Click **Expand → Open chat** to open the chat window, where you type messages and read AIRI's replies. The chat window has a scrollable conversation history on top and an input box at the bottom.

---

## 7. Settings Reference

Open settings from **Expand → Open settings** or by right-clicking the tray icon and choosing **Settings**. The settings window has nine sections.

> [!NOTE]
> A recurring pattern across settings: when you configure a model-backed feature (chat, voice, hearing, vision, artistry), you first pick a **service source** (your provider) and then pick a **model** from that provider. If you have many sources and the tabs overflow, hover a tab, hold the **middle mouse button**, and drag left/right to scroll them.

### 7.1 AIRI Character Card

Upload, create, or modify the character's personality. To create a new card, the recommended order is:

1. **Identity** — name, nickname, description, and creator's notes. *Name* and *description* matter most: the nickname (if set) is used first, and the description defines the personality.
2. **Behavior** — personality, scenario, and greeting.
3. **Modules** — character-specific body modules (optional).
4. **Artistry** — set up image generation for this character (optional).
5. **Settings** — system prompt, history-prompt instructions, and version.
6. Click **Create**, then **activate** the card (click the circle in the card's bottom-right corner, or select the card and click **Activate**).

> [!WARNING]
> Newly created character cards are **not** enabled by default. You must activate one manually before it takes effect.

### 7.2 Body Modules

Turn individual capabilities on and configure them. Modules include: **Consciousness** (chat brain), **Vocalization** (voice), **Hearing**, **Vision**, **Short-term Memory** (not yet released), **Long-term Memory** (not yet released), **Discord**, **X/Twitter**, **Minecraft**, **Factorio**, **MCP Server**, and **Rhythm Game**.

#### Consciousness (the chat brain)

1. Select a service source (or add a new one).
2. Select a model.

#### Vocalization (text-to-speech)

1. Select a service source (or add one).
2. Select a model.
3. Select a voice.
4. Choose **None** if you don't want AIRI to speak.
5. Type sample text at the bottom and click **Test voice** to preview.

> [!NOTE]
> Configuration differs slightly per provider, and for some services the **Pitch** control may have no effect.

#### Hearing (speech-to-text)

1. Select your audio input device.
2. Select a service source (or add one) and a model.
3. Optionally enable **Auto-send transcribed text**, or disable it to edit transcripts before sending, and tune the **Auto-send delay**.

To test: click **start monitoring** to check the microphone (adjust **Sensitivity** if needed), or **start speech-to-text** to verify transcription.

#### Vision

1. Select a service source (or add one) and a model.
2. Optionally set a **Capture interval** to control how often AIRI looks.

> [!IMPORTANT]
> Vision requires **screen capture** to be enabled first under **System → Developer → vision capture**, and your operating system must grant AIRI screen-recording permission.

#### Artistry

Configures AIRI's image-generation capability through a third-party AI image service. This is distinct from any drawing behavior; it produces detailed AI-generated images on request.

#### Discord / X (Twitter) / Minecraft / Factorio / MCP Server / Rhythm Game

These modules connect AIRI to external apps. Most require a **separate bot/service** that is not bundled in the installer — you run it from the source code. See [Section 9](#9-connecting-airi-to-other-apps).

### 7.3 Scene

Sets the background behind your character. Two presets are included; hover a preset and click its checkmark to enable it. Use **Upload to Gallery** to add your own background image, or **Clear Default** to remove the scene.

### 7.4 Character Model

Choose and tune the character's appearance. AIRI supports **Live2D** (2D) and **VRM** (3D) models.

To switch models: click **select model**, pick one (the build ships with two Live2D and two VRM models by default), and click **confirm**. To add your own, click **add**.

For a **Live2D** model you can expand:

- **Zoom & Position** — adjust size and on-screen position (x = horizontal, y = vertical).
- **Parameters** — mouse tracking, idle animation, frame rate, Auto Blink, Force Auto Blink (fallback timer), shadow, reset-to-default, clear model cache, and any model-specific parameters.
- **Expressions** — enable the Expression System.

For a **VRM** model, expand **Scene** to set model position, camera angle and distance, model orientation (Y-axis rotation), and gaze direction.

> [!WARNING]
> Importing a model:
> - Live2D models must be modern (`*.moc3`); old formats are not supported.
> - Compress the Live2D model folder into a `*.zip` before importing.
> - There is also an experimental **Godot Stage** rendering option; it is in early development.

### 7.5 Memory Bank

Not yet released.

### 7.6 Service Sources

Central place to configure **Chat (LLM)**, **Speech (TTS)**, **Transcription (STT)**, and **Artistry** providers. Select a category, choose a prepared source, and fill in its details. You can filter sources by **Pricing** (All / Free / Paid) and **Deployment** (All / Local / Cloud).

> [!TIP]
> If a specific provider's configuration screen misbehaves, try the **OpenAI Compatible API** option instead — it works with any service that exposes an OpenAI-compatible endpoint.

### 7.7 Data

Manage AIRI's stored data, organized into boxes:

1. **Open app data folder** (desktop only).
2. Import/export chat history, or delete all chat sessions.
3. Delete imported models, or reset module preferences and credentials.
4. Reset desktop settings and state (desktop only).
5. Reset all provider settings and credentials, or wipe every local setting, provider config, and model.

> [!CAUTION]
> Everything in the Data section is **destructive and cannot be undone**. Double-check before deleting or resetting anything.

### 7.8 Connection

Configure the **WebSocket server address** AIRI connects to. This is how the mobile and desktop versions link to a shared AIRI server channel. See [Section 9.5](#95-link-mobile-to-desktop-server-channel).

### 7.9 System

- **General** — theme (light/dark), interface language, control-island icon size, and whether to allow anonymous usage/crash-report collection (with a link to the privacy policy).
- **Color Scheme** — change the theme color; enable **RGB** to cycle colors; pick from presets (click the circles, not the squares).
- **Window Shortcuts** — *(see caution below)*.
- **Developer** — advanced tools: open developer tools (like browser F12), Markdown stress test, IO Tracer, Lag visualization, stage transition animation toggle, page-specific cutscenes, plus developer utilities such as **useElectronWindowMouse**, **Displays**, **widgets calling**, **Context Flow** (inspect how plugin context flows into chat), **beat sync visualizer**, **WebSocket Inspector**, **Plugin Host Debug**, **Updater**, **Screen Capture**, and **vision capture**.

> [!WARNING]
> Do **not** open **System → Window Shortcuts**. In this release it has no content and no back button — if you enter it, you must close and reopen the settings window to get out.

---

## 8. Everyday Tasks

### 8.1 Have a conversation

Open the chat window (desktop) or use the chat box (web), type a message, and send it. In the web version, the three buttons below the input box let you manage **Conversations** (independent chat sessions), choose your **Send method** (how Enter behaves), and **enable voice input**.

### 8.2 Talk to AIRI with your voice

1. Configure a **Hearing** (STT) service in settings (Section 7.2).
2. Click **Open hearing control** on the main window (desktop) or enable voice input (web).
3. Speak. Your words are transcribed and sent to AIRI.

### 8.3 Give AIRI a voice

1. Configure a **Vocalization** (TTS) service and pick a voice (Section 7.2).
2. Use **Test voice** to confirm it sounds right.
3. Optionally open the **caption** overlay (tray menu) to see subtitles while AIRI speaks.

### 8.4 Let AIRI see your screen (desktop)

1. Enable **System → Developer → vision capture** and grant your OS's screen-recording permission.
2. Configure a **Vision** service (a vision-capable model) in settings.
3. AIRI will periodically capture and react to what's on screen (tune **Capture interval**).

### 8.5 Change how AIRI looks

Switch or import a Live2D / VRM model in **Character Model** (Section 7.4), adjust its position and scale, change the **Scene** background, and recolor the UI under **System → Color Scheme**.

### 8.6 Back up or move your data

Use **Settings → Data** to **export chat history** before resetting or moving machines. On desktop, **Open app data folder** reveals where AIRI stores its files.

---

## 9. Connecting AIRI to Other Apps

AIRI can reach into other applications through optional **services** (bots) and **plugins**. Most of these are not in the installer — you run them from the source code (see the [Admin Guide](/moeru-ai/airi/admin-guide/) for full developer setup). This section shows what each integration does and the shape of its setup.

> [!NOTE]
> The bot services live under `services/` in the project and are configured with a `.env.local` file you copy from the provided `.env` template, then run with a `pnpm` command. They generally connect back to a running AIRI instance.

### 9.1 Discord

Lets AIRI join a Discord server, chat, and listen in voice channels.

```shell
cd services/discord-bot
cp .env .env.local      # then edit credentials (your Discord bot token, etc.)
pnpm -F @proj-airi/discord-bot start
```

### 9.2 Telegram

Lets AIRI chat on Telegram. **Requires a Postgres database.**

```shell
cd services/telegram-bot
docker compose up -d                          # starts Postgres
cp .env .env.local                            # then edit credentials
pnpm -F @proj-airi/telegram-bot db:generate
pnpm -F @proj-airi/telegram-bot db:push       # run migrations
pnpm -F @proj-airi/telegram-bot start
```

### 9.3 Minecraft

Lets AIRI join and play on a Minecraft world (via Mineflayer).

```shell
cd services/minecraft
cp .env .env.local      # set your world's port and credentials
pnpm -F @proj-airi/minecraft-bot start
```

### 9.4 Twitter / X, Satori, and the computer-use service

- **Twitter/X** (`services/twitter-services`) drives a browser to read and post tweets; configured entirely through environment variables (Twitter API keys, browser settings).
- **Satori** (`services/satori-bot`) connects AIRI to chat platforms via the [Satori protocol](https://satori.js.org/).
- **Computer-use (`services/computer-use-mcp`)** is a desktop-grounding layer that lets AIRI observe and control your computer using real OS-level input. It includes a **read-only** Chrome extension that reports interactive page elements but never clicks, types, or makes network requests on its own.

### 9.5 Link mobile to the desktop "server channel"

You can run the desktop app as a WebSocket server so the mobile (Pocket) app drives the same brain:

1. Start the desktop app (on macOS/Linux, the secure-WebSocket case may require running it with elevated privileges).
2. In the desktop app, enable secure WebSocket under **Settings → Connection**.
3. In the mobile app, set the **WebSocket server address** under **Settings → Connection** to your desktop's address.

### 9.6 VS Code

The official **AIRI VS Code extension** streams your current coding context (the lines around your cursor) back to AIRI so it can comment on what you're working on.

| Setting | Default | Meaning |
|---|---|---|
| `airi-vscode.enabled` | `true` | Enable or disable the extension. |
| `airi-vscode.contextLines` | `5` | Lines of context to send before and after the current line. |
| `airi-vscode.sendInterval` | `3000` | Milliseconds between updates (`0` = real-time). |

Commands: **AIRI: Enable**, **AIRI: Disable**, **AIRI: Show Status**.

### 9.7 Plugins

AIRI has a plugin system that extends what your companion can do. Bundled/official plugins include integrations for **Claude Code**, **Home Assistant** (smart home), **Bilibili**, a **browser web extension**, and a **chess game**. Plugins are loaded by the desktop app's plugin host; you can inspect them in **Settings → System → Developer → Plugin Host Debug**.

---

## 10. Supported AI Service Providers

AIRI talks to LLM providers through [`xsai`](https://github.com/moeru-ai/xsai), a lightweight multi-provider client. You bring your own key (or run a local model). The following chat providers are supported:

| Cloud (commercial) | Cloud (aggregators) | Local / self-hosted |
|---|---|---|
| OpenAI, Azure OpenAI | OpenRouter | Ollama |
| Anthropic (Claude) | AIHubMix *(recommended)* | vLLM |
| Google Gemini | 302.AI | SGLang |
| xAI (Grok) | Novita | LM Studio *(OpenAI-compatible)* |
| DeepSeek | Together.ai | any OpenAI-compatible endpoint |
| Qwen (Alibaba) | Fireworks.ai | |
| Groq | SiliconFlow | |
| Mistral | ModelScope | |
| Moonshot AI (Kimi) | Player2 | |
| Zhipu, Stepfun, Baichuan, Minimax | Cloudflare Workers AI | |
| Tencent Cloud, Xiaomi Mimo | | |

> [!NOTE]
> AWS Bedrock (Claude), iFlytek Spark, and Volcano Engine are marked "PR welcome" — not yet supported in this release. If a provider you want isn't listed, use **OpenAI Compatible API**.

**Voice (TTS)** providers include ElevenLabs, Microsoft/Azure Speech, OpenAI-compatible TTS, Alibaba Cloud Model Studio, and local **Kokoro** TTS. **Speech recognition (STT)** runs client-side in the browser/app, with provider options for higher-quality transcription.

---

## 11. Working With Character Models

AIRI supports two model formats. Choose based on the look you want.

| Format | Dimension | Notes |
|---|---|---|
| **Live2D** | 2D | Layered 2D art with rigging. Must be `*.moc3` format; package the model folder as a `*.zip` to import. |
| **VRM** | 3D | Standard 3D humanoid avatar format (same family as VRChat / Grok Companion-style avatars). |

Both formats get automatic **blinking**, **idle eye movement**, and **look-at** behavior, plus optional idle animations (include animation files in the model package).

> [!TIP]
> Importing a model exported from **VTuber Studio**? Before zipping the Live2D model, **delete `items_pinned_to_model.json`** — AIRI's Live2D loader can fail on files VTuber Studio adds that the Live2D engine doesn't recognize.

> [!WARNING]
> In the current release, reloading a model's scene does not always work as intended. After importing or switching a model, **restart AIRI** if the scene looks wrong.

---

## 12. How AIRI Works (Concepts)

You do not need this section to use AIRI, but it helps to understand the moving parts.

- **You bring the intelligence.** AIRI itself is not an AI model. It orchestrates *your* chosen LLM, TTS, STT, and vision providers. Your API keys and most settings are stored **locally** (in your browser or desktop app), not on a central server.
- **Web-first, but not web-limited.** AIRI is built on web technologies (WebGPU, WebAudio, Web Workers, WebAssembly, WebSocket) so it runs anywhere a browser does. The desktop version adds native power: local GPU inference and raw network/OS access.
- **One brain, many surfaces.** The web, desktop, and mobile apps share the same core logic. The desktop app can act as a server that other surfaces connect to.
- **Modules are capabilities.** Each thing AIRI can do (hearing, voice, vision, Discord, Minecraft…) is a module you enable independently.
- **Characters are data.** A "character card" bundles a personality, behavior, and module preferences. You can create, import, switch, and activate cards.
- **Memory is local.** Conversation memory uses an in-browser database (DuckDB WASM / `pglite`), keeping your data on your device.

For the full architecture, deployment model, and internals, see the [Admin Guide](/moeru-ai/airi/admin-guide/).

---

## 13. Troubleshooting

Each entry lists the symptom, the cause, the fix, and how to prevent it.

### Issue: The control panel auto-closes when you expand it (startup glitch)

- **Cause:** A first-launch rendering glitch where the main-window border flickers and the expanded menu retracts immediately. (Tracked as [issue #1939](https://github.com/moeru-ai/airi/issues/1939); an early startup variant was later fixed.)
- **Solution:** Click **Expand** at the exact moment the flickering border goes dark, then quickly click **Refresh** (first option, second row). This stabilizes the window.
- **Prevention:** Keep AIRI updated; this class of glitch has been addressed in newer builds.

### Issue: A Live2D model fails to load

- **Cause:** The ZIP archive contains files the Live2D loader doesn't expect (common with VTuber Studio exports), or optional settings references are `null` ([issue #1933](https://github.com/moeru-ai/airi/issues/1933)). Internally the loader reports errors such as `Textures not found`, `Cannot find file`, or `Expected exactly one moc file`.
- **Solution:** Re-zip the model folder excluding `items_pinned_to_model.json`; ensure exactly one `.moc3` file and the textures are present; confirm the model is modern `.moc3` format.
- **Prevention:** Always package Live2D models as a clean `*.zip` of the model folder with only Live2D-recognized files.

### Issue: Kokoro TTS mispronounces or errors on Chinese text

- **Cause:** A known limitation of the local Kokoro TTS engine with Chinese characters ([issue #1184](https://github.com/moeru-ai/airi/issues/1184)).
- **Solution:** Use a cloud TTS provider (Azure Speech, Alibaba Cloud, ElevenLabs, or an OpenAI-compatible TTS) for Chinese voice output.
- **Prevention:** Match the TTS provider to the language you speak most.

### Issue: Vision crashes with a `structuredClone` error

- **Cause:** A bug where a non-cloneable `Window` object is passed during vision image input ([issue #1909](https://github.com/moeru-ai/airi/issues/1909)).
- **Solution:** Update to the latest build; if it persists, disable Vision and report the issue.
- **Prevention:** Keep AIRI updated.

### Issue: `tokenization failed` with Moonshot/Kimi

- **Cause:** A provider-side tokenization error reported with the Kimi (Moonshot) API ([issue #1768](https://github.com/moeru-ai/airi/issues/1768), since closed).
- **Solution:** Update AIRI; if it recurs, switch to the **OpenAI Compatible API** option for that provider or pick another model.
- **Prevention:** Keep AIRI and provider configurations current.

### Issue: Your character model "disappeared" after updating

- **Cause:** Upgrading (for example to `v0.10.2`) can leave a previously customized model scale/position off-screen.
- **Solution:** Open **Settings → Character Model** and **reset the model's scale and position**.
- **Prevention:** Note your custom scale/position values before major upgrades.

### Issue: A provider's settings screen doesn't work

- **Cause:** Some provider integrations lag behind provider API changes and are not always maintained in lockstep.
- **Solution:** Configure the service through the **OpenAI Compatible API** option instead, and consider filing a GitHub issue.
- **Prevention:** Prefer providers that expose a stable OpenAI-compatible endpoint.

### Issue: "Open app data folder" opens the folder multiple times

- **Cause:** A known minor bug in the Data settings.
- **Solution:** Close the extra windows; the folder still opens correctly.
- **Prevention:** Click the button once and wait.

### Issue: You can't click a service source tab — there are too many

- **Cause:** The provider tab strip overflows.
- **Solution:** Hover over a tab, hold the **middle mouse button**, and drag left or right to scroll the tabs.
- **Prevention:** Remove providers you no longer use under **Service Sources**.

### Issue: AIRI won't run on Linux (missing libraries)

- **Cause:** Electron needs system libraries (WebKitGTK, GTK, etc.) that may be missing, especially on NixOS.
- **Solution:** Install the required packages (`libwebkit2gtk-4.1`, `libgtk-3`, `libglib2.0`, `libssl`, `libjavascriptcoregtk-4.1`). On NixOS, use the project's FHS shell. See the [Admin Guide](/moeru-ai/airi/admin-guide/).
- **Prevention:** Use a packaged release for your distribution where available.

---

## 14. Frequently Asked Questions

**Q: Is AIRI free?**
Yes. AIRI is open source. You may pay your chosen AI provider for API usage, but AIRI itself costs nothing.

**Q: Do I need to know how to code?**
No, for the web and desktop apps. You only need an API key. Coding is required for the optional bot services (Discord, Telegram, Minecraft, etc.) that aren't in the installer.

**Q: Does AIRI send my data to its developers?**
Your API keys and settings are stored locally on your device. Optional, opt-in anonymous usage and crash reporting can be toggled under **System → General**.

**Q: Can I run AIRI fully offline / locally?**
Largely, on desktop. Use a local LLM (Ollama, vLLM, LM Studio), local Kokoro TTS, client-side STT, and the in-browser database. Some features still benefit from cloud providers.

**Q: Which version should I use?**
Start with **web** ([airi.moeru.ai](https://airi.moeru.ai)) to try it. Move to **desktop** for a floating companion, local models, screen vision, and streaming. Use **mobile** (PWA) to carry it around.

**Q: What's the difference between Live2D and VRM?**
Live2D is 2D rigged art; VRM is a 3D humanoid avatar. Both work; it's an aesthetic choice.

**Q: Does AIRI have a cryptocurrency or token?**
**No.** The project explicitly has no official cryptocurrency or token. Treat any such claim as a scam.

**Q: Can AIRI really play games?**
It can play Minecraft today and has a working Factorio proof-of-concept. Game-playing is among the project's headline goals and is actively expanding.

**Q: How do I update?**
Desktop has a built-in updater (check from **About**). Web/PWA updates automatically. Package-manager installs update via `winget upgrade`, `scoop update`, or `brew upgrade`.

**Q: Where are my chats stored, and how do I move them?**
Locally, in an in-browser/desktop database. Use **Settings → Data → export chat history** to back up or transfer.

**Q: Can my phone use the AI running on my PC?**
Yes — run the desktop app as a WebSocket server and point the mobile app's **Connection** setting at it (Section 9.5).

**Q: Can I make my own character?**
Yes. Create a **Character Card** in settings (Section 7.1), define identity and behavior, then activate it.

**Q: A setting in the manual says "details omitted" — why?**
Parts of AIRI's community manual are still being written. Features marked "not yet released" are planned; everything else can be explored hands-on.

---

## 15. Reference

### 15.1 Versions at a glance

| Product | Internal name | Where it runs |
|---|---|---|
| Web | `@proj-airi/stage-web` | Browser ([airi.moeru.ai](https://airi.moeru.ai)) |
| Desktop | `@proj-airi/stage-tamagotchi` | Windows / macOS / Linux (Electron) |
| Mobile | `@proj-airi/stage-pocket` | iOS / Android (Capacitor / PWA) |

### 15.2 Install commands

| Platform | Command |
|---|---|
| Windows (winget) | `winget install MoeruAI.AIRI` |
| Windows (Scoop) | `scoop bucket add airi https://github.com/moeru-ai/airi` then `scoop install airi/airi` |
| macOS (Homebrew) | `brew install --cask airi` |
| Nix | `nix run github:moeru-ai/airi` |
| Web | Open [airi.moeru.ai](https://airi.moeru.ai) |

### 15.3 Settings sections

AIRI Character Card · Body Modules · Scene · Character Model · Memory Bank · Service Sources · Data · Connection · System (General / Color Scheme / Window Shortcuts / Developer)

### 15.4 Body modules

Consciousness · Vocalization · Hearing · Vision · Artistry · Short-term Memory *(WIP)* · Long-term Memory *(WIP)* · Discord · X/Twitter · Minecraft · Factorio · MCP Server · Rhythm Game

### 15.5 Useful links

- Project home: <https://github.com/moeru-ai/airi>
- Try it (web): <https://airi.moeru.ai>
- Documentation site: <https://airi.moeru.ai/docs/en/>
- Discord community: <https://discord.gg/TgQ3Cu2F7A>
- Sub-projects organization: <https://github.com/proj-airi>

---

_Generated June 2026 from moeru-ai/airi at 19e5020. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._