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

> Easily install moeru-ai/airi with our complete setup guide. Clone the repo, install dependencies, and launch the AI VTuber platform in minutes for a seamless virtual experience.

- Repository: [Moeru AI/airi](https://github.com/moeru-ai/airi)
- Tags: getting-started
- Published: 2026-03-08

---

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

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

2. **Install all workspace dependencies**

   ```bash
   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`](https://github.com/moeru-ai/airi/blob/main/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`](https://github.com/moeru-ai/airi/blob/main/apps/stage-web/vite.config.ts):

```bash
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`](https://github.com/moeru-ai/airi/blob/main/apps/stage-tamagotchi/electron.vite.config.ts):

```bash
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`](https://github.com/moeru-ai/airi/blob/main/apps/stage-pocket/vite.config.ts):

```bash
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:

```bash
pnpm dev:server

```

This initializes the RPC channel defined in [`packages/server-runtime/src/core.ts`](https://github.com/moeru-ai/airi/blob/main/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:

```bash
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`](https://github.com/moeru-ai/airi/blob/main/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

```bash
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:

```bash
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:

```typescript
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`](https://github.com/moeru-ai/airi/blob/main/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.