How to Run moeru-ai/airi Locally: Complete Setup Guide for Web, Desktop, and Mobile

Clone the moeru-ai/airi repository, enable corepack to install pnpm, run pnpm install from the root to bootstrap the workspace, then launch your preferred interface with pnpm dev (web), pnpm dev:tamagotchi (desktop), or pnpm dev:pocket:ios <DEVICE> (mobile).

The moeru-ai/airi repository is a modular monorepo that ships three runnable front-ends sharing core business logic from packages/stage-ui and packages/stage-shared. Whether you need the browser-based Stage Web, the Electron-powered Stage Tamagotchi desktop application, or the Capacitor-based Stage Pocket mobile client, local development requires bootstrapping the pnpm workspace and satisfying specific runtime dependencies.

Prerequisites for Running moeru-ai/airi Locally

Before executing any dev commands, ensure your environment meets these requirements:

• Git – for cloning the repository
• Node.js 23+ – the runtime used for all JavaScript/TypeScript code
• pnpm – the package manager (installed via corepack)
• Rust tool-chain – optional, required only if modifying native crates or desktop-specific Rust services

The repository maintains detailed environment setup instructions in .github/CONTRIBUTING.md (sections 5-9), including Windows-specific steps for Visual Studio 2022 and Windows SDK installation.

Initial Setup and Installation

Run these commands from your terminal to prepare the workspace:

# Clone the repository

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

# Enable corepack and activate pnpm

corepack enable
corepack prepare pnpm@latest --activate

# Install all workspace dependencies

pnpm install

# Optional: Fetch Rust crates (only needed for native plugins)

cargo fetch

The pnpm install command resolves dependencies across all packages including apps/stage-web, apps/stage-tamagotchi, and apps/stage-pocket, as well as shared libraries in packages/ui and packages/server-runtime.

Running the Front-end Applications

The moeru-ai/airi monorepo supports three distinct runtime targets. Each uses Vite for bundling but requires different start commands.

Stage Web (Browser)

Launch the Vue 3 + Vite browser application:

pnpm dev

This starts the development server at http://localhost:5173. The Vite configuration lives in apps/stage-web/vite.config.ts, while reusable UI components are imported from packages/stage-ui.

Stage Tamagotchi (Desktop)

Run the Electron-based desktop client with hot-reload:

pnpm dev:tamagotchi

The Electron-Vite configuration is located at apps/stage-tamagotchi/electron.vite.config.ts, with renderer source code under apps/stage-tamagotchi/src/renderer/. This front-end bundles the same packages/stage-ui components as the web version but wraps them in an Electron shell.

Stage Pocket (Mobile)

Start the Capacitor mobile build for iOS (requires Xcode):

pnpm dev:pocket:ios <DEVICE>

Replace <DEVICE> with a simulator name (e.g., "iPhone 14") or UDID. The mobile configuration resides in apps/stage-pocket/vite.config.ts. For Android development, ensure the Android SDK is installed and use the corresponding Capacitor commands.

Nix Flake (Alternative Method)

If you have Nix with flakes enabled, launch the desktop version without manual Node.js setup:

nix run github:moeru-ai/airi

This executes the build defined in flake.json at the repository root, handling all dependencies automatically.

Troubleshooting Common Issues

Symptom	Cause	Solution
pnpm dev fails with "module not found"	Workspace not bootstrapped	Re-run pnpm install from the repository root
Electron build errors on Linux	Missing native development libraries	Install libssl-dev libglib2.0-dev libgtk-3-dev libjavascriptcoregtk-4.1-dev libwebkit2gtk-4.1-dev per the Linux section of .github/CONTRIBUTING.md
Mobile dev server cannot find device	Incorrect device identifier or missing SDK	Verify available devices with pnpm exec cap run ios --list (iOS) or adb devices (Android)

Summary

• moeru-ai/airi is a pnpm workspace monorepo with three front-ends: Stage Web (apps/stage-web), Stage Tamagotchi (apps/stage-tamagotchi), and Stage Pocket (apps/stage-pocket).
• Prerequisites include Node 23+, pnpm (via corepack), and optionally Rust for native development.
• Development commands are pnpm dev (web), pnpm dev:tamagotchi (desktop), and pnpm dev:pocket:ios <DEVICE> (mobile).
• Core logic is shared across all front-ends via packages/stage-ui, ensuring consistent state management and UI components.
• Nix users can bypass manual setup entirely using nix run github:moeru-ai/airi.

Frequently Asked Questions

What if the pnpm command is not found after enabling corepack?

Ensure you ran both corepack enable and corepack prepare pnpm@latest --activate from the repository root. If issues persist, install pnpm globally via npm (npm install -g pnpm) and verify your Node.js version is 23 or higher as required by the moeru-ai/airi codebase.

Can I run moeru-ai/airi on Windows?

Yes, but Windows requires additional dependencies. Install Visual Studio 2022, the Windows SDK, and Python 3 for native module compilation. Refer to the Windows-specific instructions in .github/CONTRIBUTING.md for the exact Visual Studio workload components needed for Electron builds.

Do I need Rust to run the front-ends locally?

No, Rust is only required if you plan to modify native crates or work on Rust-based services within packages/server-runtime. For standard front-end development of Stage Web, Stage Tamagotchi, or Stage Pocket, Node.js and pnpm are sufficient.

How do I run multiple front-ends simultaneously?

Open separate terminal instances for each target. Because all three front-ends share the same Pinia stores and business logic from packages/stage-ui, state changes in one interface (e.g., the web app) will reflect in others (e.g., the Electron window) when running concurrently during development.

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