> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/moeru-ai/airi/llms.txt
> Use this file to discover all available pages before exploring further.

# Desktop Platform

> Native Electron app for Windows, macOS, and Linux

## Overview

Stage Tamagotchi is the native desktop application for AIRI, built with Electron. It provides the best performance and full access to native system capabilities including CUDA/Metal acceleration, screen capture, and system integrations.

<Info>
  Download the latest release from [GitHub Releases](https://github.com/moeru-ai/airi/releases)
</Info>

## System Requirements

### Minimum Requirements

* **Windows**: Windows 10 64-bit or later
* **macOS**: macOS 11.0 (Big Sur) or later
* **Linux**: Ubuntu 20.04+ or equivalent
* **RAM**: 4GB minimum, 8GB recommended
* **Storage**: 2GB free space
* **GPU**: Recommended for optimal performance

### Recommended Specifications

* **NVIDIA GPU**: For CUDA acceleration (Windows/Linux)
* **Apple Silicon**: For Metal acceleration (macOS)
* **Intel/AMD GPU**: For general acceleration
* **RAM**: 16GB for large models
* **SSD**: For faster model loading

## Installation

### Download Pre-built Binaries

<Tabs>
  <Tab title="Windows">
    1. Download `AIRI-{version}-windows-x64-setup.exe` from [GitHub Releases](https://github.com/moeru-ai/airi/releases)
    2. Run the installer
    3. Follow the setup wizard
    4. Launch AIRI from Start Menu or Desktop shortcut

    <Note>
      Windows may show a SmartScreen warning. Click "More info" → "Run anyway" if you trust the source.
    </Note>
  </Tab>

  <Tab title="macOS">
    1. Download `AIRI-{version}-darwin-{arch}.dmg` from [GitHub Releases](https://github.com/moeru-ai/airi/releases)
       * `arm64` for Apple Silicon (M1/M2/M3)
       * `x64` for Intel Macs
    2. Open the DMG file
    3. Drag AIRI to Applications folder
    4. Launch AIRI from Applications

    <Warning>
      First launch may show "AIRI can't be opened because Apple cannot check it for malicious software." Go to System Settings → Privacy & Security → Click "Open Anyway"
    </Warning>
  </Tab>

  <Tab title="Linux">
    ### Debian/Ubuntu (DEB)

    ```bash theme={null}
    wget https://github.com/moeru-ai/airi/releases/download/v{version}/AIRI-{version}-linux-amd64.deb
    sudo dpkg -i AIRI-{version}-linux-amd64.deb
    ```

    ### Fedora/RHEL (RPM)

    ```bash theme={null}
    wget https://github.com/moeru-ai/airi/releases/download/v{version}/AIRI-{version}-linux-x86_64.rpm
    sudo rpm -i AIRI-{version}-linux-x86_64.rpm
    ```

    ### AppImage (Universal)

    ```bash theme={null}
    wget https://github.com/moeru-ai/airi/releases/download/v{version}/AIRI-{version}-linux-x86_64.AppImage
    chmod +x AIRI-{version}-linux-x86_64.AppImage
    ./AIRI-{version}-linux-x86_64.AppImage
    ```
  </Tab>
</Tabs>

### Nix Package

For NixOS or Nix package manager users:

```bash theme={null}
nix run github:moeru-ai/airi
```

Or add to your `flake.nix`:

```nix theme={null}
{
  inputs.airi.url = "github:moeru-ai/airi";
}
```

## Building from Source

### Prerequisites

* Node.js 20+
* pnpm 10+
* Git
* Platform-specific build tools:
  * **Windows**: Visual Studio 2019+ with C++ tools
  * **macOS**: Xcode 26+ (or Xcode 14+ for legacy icon format)
  * **Linux**: `build-essential`, `libgtk-3-dev`

### Clone and Install

```bash theme={null}
git clone https://github.com/moeru-ai/airi.git
cd airi
pnpm install
```

### Development Mode

Start the development server:

```bash theme={null}
pnpm dev:tamagotchi
```

This launches the Electron app with hot reload enabled.

### Production Build

<Tabs>
  <Tab title="All Platforms">
    ```bash theme={null}
    # Build the app (no packaging)
    pnpm -F @proj-airi/stage-tamagotchi build
    ```
  </Tab>

  <Tab title="Windows">
    ```bash theme={null}
    # Build and package for Windows
    pnpm -F @proj-airi/stage-tamagotchi build:win
    ```

    Output: `apps/stage-tamagotchi/dist/AIRI-{version}-windows-x64-setup.exe`
  </Tab>

  <Tab title="macOS">
    ```bash theme={null}
    # Build and package for macOS
    pnpm -F @proj-airi/stage-tamagotchi build:mac
    ```

    Output: `apps/stage-tamagotchi/dist/AIRI-{version}-darwin-{arch}.dmg`

    <Note>
      Code signing and notarization require Apple Developer account. See [electron-builder.config.ts](https://github.com/moeru-ai/airi/blob/main/apps/stage-tamagotchi/electron-builder.config.ts) for configuration.
    </Note>
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    # Build and package for Linux
    pnpm -F @proj-airi/stage-tamagotchi build:linux
    ```

    Output:

    * `apps/stage-tamagotchi/dist/AIRI-{version}-linux-amd64.deb`
    * `apps/stage-tamagotchi/dist/AIRI-{version}-linux-x86_64.rpm`
    * `apps/stage-tamagotchi/dist/AIRI-{version}-linux-x86_64.AppImage`
  </Tab>
</Tabs>

## Architecture

### Electron App Structure

```
apps/stage-tamagotchi/
├── src/
│   ├── main/              # Main process
│   │   ├── index.ts       # Entry point
│   │   ├── services/      # Backend services
│   │   │   └── electron/  # Electron IPC services
│   │   └── modules/       # Native modules
│   ├── preload/           # Preload scripts
│   │   ├── index.ts       # Main preload
│   │   └── beat-sync.ts   # Beat sync preload
│   ├── renderer/          # Renderer process
│   │   ├── pages/         # Vue pages
│   │   ├── layouts/       # Vue layouts
│   │   ├── stores/        # Pinia stores
│   │   └── index.html     # HTML entry
│   └── shared/            # Shared types/contracts
├── build/                 # Build resources
│   ├── icons/             # App icons
│   └── entitlements.mac.plist
├── electron.vite.config.ts
├── electron-builder.config.ts
└── package.json
```

### IPC Communication

AIRI uses `@moeru/eventa` for type-safe IPC/RPC:

```typescript theme={null}
// Define contract in src/shared/
import { defineContract } from '@moeru/eventa'

export const myContract = defineContract({
  name: 'my-service',
  methods: {
    doSomething: {
      input: z.object({ id: z.string() }),
      output: z.object({ result: z.boolean() })
    }
  }
})

// Use in renderer
import { useEventa } from '@proj-airi/electron-eventa'

const eventa = useEventa()
const result = await eventa.call('my-service', 'doSomething', { id: '123' })
```

## Native Features

### GPU Acceleration

<Tabs>
  <Tab title="NVIDIA CUDA">
    Automatic CUDA support on Windows/Linux with NVIDIA GPUs:

    * Accelerated model inference via `candle`
    * Real-time speech recognition
    * Faster model loading
    * Reduced CPU usage

    <Info>
      CUDA support is automatically detected. No manual configuration needed.
    </Info>
  </Tab>

  <Tab title="Apple Metal">
    Native Metal acceleration on Apple Silicon:

    * Optimized for M1/M2/M3 chips
    * Up to 10x faster than CPU
    * Lower power consumption
    * Better thermal management

    <Info>
      Metal is automatically used on Apple Silicon Macs.
    </Info>
  </Tab>
</Tabs>

### Screen Capture

```typescript theme={null}
import { useScreenCapture } from '@proj-airi/electron-screen-capture'

const { capture, sources } = useScreenCapture()

// Get available sources
const screens = await sources()

// Capture screen
const imageData = await capture(screens[0].id)
```

### Native Integrations

* **System Tray**: Minimize to tray
* **Notifications**: Native system notifications
* **File System**: Full file system access
* **Auto-Start**: Launch on system startup
* **Deep Links**: Custom URL protocol (`airi://`)
* **Keyboard Shortcuts**: Global hotkeys

## Auto-Updater

AIRI includes automatic update checking via `electron-updater`:

### How It Works

1. App checks for updates on startup
2. Downloads updates in background
3. Prompts user to restart when ready
4. Installs update on restart

### Configuration

Updates are published to GitHub Releases. Configuration in `package.json`:

```json theme={null}
{
  "build": {
    "publish": {
      "provider": "github",
      "owner": "moeru-ai",
      "repo": "airi"
    }
  }
}
```

### Manual Update Check

Settings → System → General → Check for Updates

## Development Workflow

### Hot Reload

Both main and renderer processes support hot reload:

```bash theme={null}
pnpm dev:tamagotchi
```

### Debugging

<Tabs>
  <Tab title="Renderer Process">
    Use Chrome DevTools (automatically opens):

    * Cmd/Ctrl + Shift + I: Toggle DevTools
    * Cmd/Ctrl + R: Reload
    * Vue DevTools available at `__devtools__/`
  </Tab>

  <Tab title="Main Process">
    VS Code launch configuration:

    ```json theme={null}
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to Main Process",
      "port": 9229
    }
    ```

    Start with:

    ```bash theme={null}
    pnpm dev:tamagotchi --inspect-brk
    ```
  </Tab>
</Tabs>

### Testing

```bash theme={null}
# Run tests
pnpm -F @proj-airi/stage-tamagotchi exec vitest run

# Run specific test file
pnpm exec vitest run apps/stage-tamagotchi/src/renderer/stores/tools/builtin/widgets.test.ts
```

## Limitations

Compared to the web version, the desktop app:

<Check>
  **Advantages**
</Check>

* Native CUDA/Metal GPU acceleration
* Full file system access
* System integrations (tray, notifications, etc.)
* Better performance
* Offline support without PWA limitations
* Can run background services

<Warning>
  **Considerations**
</Warning>

* Larger download size (\~200MB vs \~50MB web)
* Requires installation
* Platform-specific builds needed
* Updates require restart

## Troubleshooting

### App Won't Start

1. Check system requirements
2. Try deleting config: `~/.config/airi` (Linux/macOS) or `%APPDATA%/airi` (Windows)
3. Check logs: Help → Show Logs
4. Run from terminal to see error messages

### GPU Not Detected

```bash theme={null}
# Check GPU detection
Settings → System → General → GPU Information
```

If GPU is not detected:

* Update GPU drivers
* Check CUDA/Metal is installed
* Verify GPU meets minimum requirements

### IPC Errors

If you see IPC-related errors:

1. Clear cache and restart
2. Check main process logs
3. Verify preload script is loading
4. Check Eventa contract definitions

## Technology Stack

* **Framework**: Electron 33+
* **Renderer**: Vue 3 + Vite
* **Build**: electron-vite + electron-builder
* **IPC**: @moeru/eventa
* **DI**: injeca
* **State**: Pinia
* **GPU**: CUDA (NVIDIA) / Metal (Apple) / Vulkan (fallback)
* **Database**: DuckDB (native)
* **Audio**: Native audio APIs

## Related Resources

<CardGroup cols={2}>
  <Card title="Web Platform" icon="globe" href="/platforms/web">
    Browser-based version with WebGPU
  </Card>

  <Card title="Mobile Platform" icon="mobile" href="/platforms/mobile">
    iOS and Android support
  </Card>
</CardGroup>