Project AIRI

What it is

Project AIRI is an open-source virtual character you run yourself, made by the Moeru AI team and inspired by the AI streamer Neuro-sama. It runs as a desktop app or in a browser and shows an animated character, with Live2D, VRM, Spine, MMD and Tachie models supported. It chats through a language model you choose. Add a speech provider and a transcription provider and it talks and listens. Add a vision model and it can read an image or a window you capture. Three modules need a clone of the repository: the Minecraft agent, the Discord bot and the Telegram bot. AIRI needs a chat model before it can answer. That can be a cloud provider with your key, a local service such as Ollama, or the official AIRI provider after you sign in.

1. You pick a chat provider and a model
2. You choose a character card and a body model
3. You add speech, hearing or vision if you want them
4. You talk to it by text or voice, on desktop or web
5. Bots you run from source reach Discord and Minecraft

Who it suits

People who want a character that lives on their own computer and talks with them, and developers who want to study or extend one. The introduction page says the desktop version suits VTuber streaming, computer use and local models. Modellers, artists and translators are welcome too, since the README asks for help with Live2D and VRM models, speech recognition, speech synthesis and WebGPU.

Skip it if you want a finished product. The README says the project is in the early stage of development, and the bots need a terminal.

Where to use it

AIRI is an app, not an agent skill. You use it on a desktop, in a browser, on a phone or from source.

• Desktop app (Stage Tamagotchi): one Windows x64 setup .exe, which the manual also lists for Windows 11 ARM64. There are .dmg files for macOS on Apple silicon and Intel, and .deb, .rpm and .flatpak files for Linux x64 and ARM64
• Web (Stage Web): runs at airi.moeru.ai with no install
• Phone and tablet: an Android .apk and an iOS .ipa from the releases page, or the web version. iOS files must be signed and installed by hand
• Package managers: winget and Scoop on Windows, Homebrew Cask on macOS, and a Nix package
• From source: a clone of the repository, which the Discord, Minecraft and Telegram bots need

How to set it up

Get it saves a zip of Mindket’s setup notes in your downloads folder, with steps for each platform and module from the project’s docs. The web version needs no install. The desktop app comes from the latest release or from a package manager.

1. Install AIRI or open the web version. The installer is in the latest release, or use a package manager.
2. Start it and pick a language. Then choose Setup with your provider, or Sign in for the official provider.
3. Choose a chat provider and a model. Enter the provider’s key or address.
4. Select Save and Continue. On the desktop, click Expand in the Controls Island, then Open Chat. On the web, type in the chat box. Send a message.
5. Add speech, hearing or vision later. Set the provider up under Settings, then Providers, then select it, its model (and a voice for speech) under Settings, then Modules (Speech, Hearing or Vision).

winget install MoeruAI.AIRI

brew install --cask airi

Scoop works on Windows too, and Nix users with flakes enabled can run the desktop app straight from GitHub.

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

nix run github:moeru-ai/airi

From a clone, pnpm dev starts the browser version and pnpm dev:tamagotchi starts the desktop app.

pnpm i
pnpm dev

How to use it

On the desktop, click Expand in the Controls Island, then Open Chat. The chat has a floating style with a transparent background and a classic window. The voice message control offers voice-message and speech-to-text modes. Open Settings, then AIRI Card, to import, create or switch character cards, and Settings, then Models, to swap the body. Switch Profile in the Controls Island changes the card without opening Settings.

Example

You have an evening and no API key, so you run the model on your own computer. You install Ollama and start a model. The docs use qwen2 and say to put another model’s ID in its place.

ollama --version
ollama run qwen2

In AIRI you open Settings, Providers, Chat, then Ollama. The Base URL can stay at its default.

http://localhost:11434/v1/

Then you open Settings, Modules, Consciousness and select Ollama and the model. You send “Hello” in the chat. A reply means the provider and the model both work. The docs say Ollama already allows the desktop app’s origins, so a local setup does not usually need OLLAMA_ORIGINS.

For newcomers and experts

If you are new. A chat provider is the service that writes AIRI’s replies, and an API key is the password it gives you. A Base URL is the address AIRI sends requests to. Ollama runs a model on your own computer, so it needs no key. Live2D and VRM are file formats for 2D and 3D characters. A character card holds a name, a personality and some preferences. Neuro-sama is the AI streamer the README says AIRI is inspired by. Get chat working first, as the docs advise, and add voice after.

For experts. The repository is a monorepo. Stage Web, Stage Tamagotchi and the experimental Stage Pocket share a UI package, character and agent packages, audio pipelines and Live2D and Three.js renderers. The README says AIRI was built with web technologies such as WebGPU, WebAudio, Web Workers and WebAssembly from the first day. The desktop version can use native CUDA and Apple Metal through candle. Language models are called through xsAI, and the README lists a long run of providers.

The desktop app opens a server channel that the bots reach through the server SDK. The Discord page puts it at ws://localhost:6121/ws, with the Auth Token from Settings, Connection. Secure WebSocket is an option there. In the README’s roadmap, Memory is not yet ticked: pure in-browser database support (DuckDB WASM or pglite) is done, and Memory Alaya is work in progress. The manual says the long-term memory module may change a lot or be renamed.

The MCP module adds a server by command, arguments and environment variables, and it runs that server as a local process. Character card packs use Character Card V3 data with a field whitelist, so they are not lossless CCv3 backups. Two global shortcuts, Spotlight and Push to talk, each need a modifier key. For tests, the contributing guide says Node.js 26 has its own localStorage, so CI runs with --no-experimental-webstorage.

Good to know

Read these before you build on it.

• Early stage: the README says the project is still early, and the manual says it may be incomplete, inaccurate or out of date. Follow the app when the two differ
• No token: the README warns that there is no officially minted cryptocurrency or token, and tells you to check any claim of one
• Your model, your bill: third-party providers bill usage separately, and a local service such as Ollama needs no API key by default. Requests to the official chat, vision or speech services can use Flux, the official services’ balance
• Screen capture: visual analysis sends captured frames to the provider you select, so do not capture keys, passwords or private content
• Bots: the Minecraft agent controls a local Minecraft session, so never point it at an untrusted public server. A leaked Discord bot token should be reset in the Discord Developer Portal at once
• Network: expose AIRI only on trusted networks and keep the Auth Token private. Turning on secure WebSocket adds a local certificate to the macOS login keychain
• MCP servers: they can run commands on your machine and read the environment variables you grant, so add only ones you trust
• Usage data: a System setting, Enable usage analytics, controls anonymous analytics where a build has them. The docs Mindket read do not list what is sent
• Voice chat: the manual’s editors say they have not tested it much, and it may change
• Cloud sync: the manual says character-card and model cloud sync are currently unavailable, and local features are unaffected
• Removal: the docs give no uninstall steps. The Data settings have controls to delete stored data, and the manual says deletion cannot be undone
• License: MIT. The LICENSE file reads “Copyright (c) 2024-PRESENT Neko Ayaka”