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 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 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.

Table of Contents

1. What You Can Do With AIRI
2. Choosing a Version: Web, Desktop, or Mobile
3. Quick Start
4. Installation
5. First-Time Setup
6. The Desktop Companion Interface
7. Settings Reference
8. Everyday Tasks
9. Connecting AIRI to Other Apps
10. Supported AI Service Providers
11. Working With Character Models
12. How AIRI Works (Concepts)
13. Troubleshooting
14. Frequently Asked Questions
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.

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.

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.

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 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.

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.

4. Installation

4.1 Web (no installation)

Open 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)

winget install MoeruAI.AIRI

Windows (Scoop)

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

macOS (Homebrew Cask)

brew install --cask airi

Manual download (all platforms)

1. Go to the releases page.
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

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 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 for building from source.

4.4 System requirements

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:

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.

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.

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 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.

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.

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).

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.
• 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.

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, a lightweight multi-provider client. You bring your own key (or run a local model). The following chat providers are supported:

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.

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.

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; 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). 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).
• 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).
• 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, 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.
• 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) 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

15.2 Install commands

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