How to Install moeru-ai/airi: Complete Setup Guide for the AI VTuber Platform

Clone the repository, install dependencies with pnpm i, and run pnpm dev to launch the web interface at http://localhost:5173, or use pnpm dev:tamagotchi for the desktop Electron build.

The moeru-ai/airi repository is a modular, full-stack AI-driven VTuber platform organized as a pnpm monorepo. Whether you want to run the browser-based Stage-Web, the Electron desktop Stage-Tamagotchi, or the mobile Stage-Pocket, this guide covers how to install moeru-ai/airi and configure your local development environment.

Prerequisites

Before installing, ensure your system meets these requirements:

• Node.js ≥ 18 (LTS recommended)
• pnpm package manager installed globally (npm i -g pnpm)
• Git for cloning the repository

The project uses pnpm workspaces to manage the core engine, shared UI packages, and multiple application targets within a single dependency tree.

Installation Steps

Follow these steps to install the complete monorepo:

1. Clone the repository

   git clone https://github.com/moeru-ai/airi.git
   cd airi

2. Install all workspace dependencies

   pnpm i

   This command installs every package—including the Core engine (packages/server-runtime), UI components (packages/stage-ui, packages/ui), and all application targets—into the shared node_modules directory. The installation process respects the lockfile at pnpm-lock.yaml for reproducible builds.

3. Verify the installation

   After installation completes, the workspace is ready for development. You can confirm the structure by checking the apps/ directory containing stage-web, stage-tamagotchi, stage-pocket, and server subdirectories.

Running Development Builds

The repository provides distinct development commands for each application target. Each command builds the Core engine and mounts the appropriate UI layer.

Stage-Web (Browser Version)

To launch the web application configured in apps/stage-web/vite.config.ts:

pnpm dev

This starts a Vite development server at http://localhost:5173, running the Core engine with browser-compatible adapters for speech-to-text and audio playback.

Stage-Tamagotchi (Desktop Version)

For the Electron desktop build configured in apps/stage-tamagotchi/electron.vite.config.ts:

pnpm dev:tamagotchi

This command launches the Electron wrapper, which provides native CUDA or Metal acceleration for model inference and system-level permissions not available in browser contexts.

Stage-Pocket (Mobile Version)

To develop for iOS or Android using the Capacitor configuration in apps/stage-pocket/vite.config.ts:

pnpm dev:pocket:ios

# OR

pnpm dev:pocket:android

These commands bundle the Vue UI for mobile devices and utilize native audio capture APIs through Capacitor plugins.

Server Backend

For headless server development or agent integration:

pnpm dev:server

This initializes the RPC channel defined in packages/server-runtime/src/core.ts, hosting the backend services for memory management and external game agent integrations (Minecraft, Factorio).

Alternative Installation via Nix

If you prefer reproducible builds using Nix flakes, you can install and run the desktop application without manually managing Node.js or pnpm:

nix run github:moeru-ai/airi

This method builds the Stage-Tamagotchi Electron app in an isolated environment, handling all system dependencies automatically.

Architecture Overview

Understanding the monorepo structure helps troubleshoot installation issues:

• Core Engine: Located in packages/server-runtime/src/core.ts, the createCore factory orchestrates LLM providers via xsai, real-time audio processing, and memory layers (DuckDB WASM or PGVector).
• UI Packages: @proj-airi/stage-ui contains business-logic Vue components and stores, while @proj-airi/ui provides primitive components built on Reka UI.
• Apps: Each app in apps/ imports from the Core and UI packages, ensuring consistent behavior across web, desktop, and mobile deployments.

Code Examples

Complete Fresh Install

git clone https://github.com/moeru-ai/airi.git
cd airi
pnpm i
pnpm dev          # For web

Running Linting and Type Checks

After installation, verify code quality before contributing:

pnpm lint         # ESLint + Prettier checks

pnpm lint:fix     # Auto-fix issues

pnpm -F @proj-airi/stage-ui typecheck  # Type-check specific package

Using the Core Programmatically

Once installed, you can import the Core in custom scripts:

import { createCore } from '@proj-airi/server-runtime';
import { xsai } from '@proj-airi/xsai';

async function main() {
  const core = await createCore({
    llmProvider: xsai.openai({ apiKey: process.env.OPENAI_API_KEY }),
    memory: 'duckdb-wasm',
  });
  
  core.onMessage(console.log);
  await core.chat('Hello, AIRI!');
}
main();

Summary

• Clone the moeru-ai/airi repository and ensure you have Node.js ≥ 18 and pnpm installed.
• Run pnpm i to install all workspace packages, including Core, UI libraries, and apps.
• Use pnpm dev for browser development, pnpm dev:tamagotchi for Electron desktop, or pnpm dev:pocket:ios for mobile.
• Reference AGENTS.md in the repository root for detailed architecture decisions and CI commands.
• Consider nix run for zero-dependency desktop installation if you use Nix.

Frequently Asked Questions

What are the minimum system requirements to install moeru-ai/airi?

You need Node.js version 18 or higher and the pnpm package manager. For the desktop Stage-Tamagotchi build, native CUDA or Metal acceleration is recommended but not required for basic functionality. The mobile builds require corresponding platform SDKs (Xcode for iOS, Android Studio for Android).

How do I switch between the web and desktop versions after installing?

After running pnpm i, simply use different development commands. Use pnpm dev to start the web version at http://localhost:5173, or pnpm dev:tamagotchi to launch the Electron desktop window. Both commands use the same Core engine and UI packages but target different runtime environments defined in their respective Vite configurations.

Can I install only specific parts of the monorepo instead of everything?

While pnpm i installs the entire workspace to ensure dependency consistency, you can run commands for specific packages using pnpm filters. For example, pnpm -F @proj-airi/stage-ui build builds only the stage-ui package. However, apps like stage-web depend on the Core and UI packages, so full installation is recommended for development.

Is there a way to install moeru-ai/airi without setting up Node.js manually?

Yes, if you have Nix installed, you can run nix run github:moeru-ai/airi to build and execute the desktop version directly. This approach handles Node.js, pnpm, and all native dependencies automatically in a reproducible environment, though it currently only supports the Stage-Tamagotchi Electron target.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}