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

> Learn how to run moeru-ai/airi locally with our complete setup guide. Install dependencies and launch the web, desktop, or mobile interface easily.

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

---

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

```bash

# 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:

```bash
pnpm dev

```

This starts the development server at `http://localhost:5173`. The Vite configuration lives in [`apps/stage-web/vite.config.ts`](https://github.com/moeru-ai/airi/blob/main/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:

```bash
pnpm dev:tamagotchi

```

The Electron-Vite configuration is located at [`apps/stage-tamagotchi/electron.vite.config.ts`](https://github.com/moeru-ai/airi/blob/main/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):

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

```bash
nix run github:moeru-ai/airi

```

This executes the build defined in [`flake.json`](https://github.com/moeru-ai/airi/blob/main/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`](https://github.com/moeru-ai/airi/blob/main/.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`](https://github.com/moeru-ai/airi/blob/main/.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.