Desktop Platform

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.

Download the latest release from GitHub Releases

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

Windows
macOS
Linux

Download AIRI-{version}-windows-x64-setup.exe from GitHub Releases
Run the installer
Follow the setup wizard
Launch AIRI from Start Menu or Desktop shortcut

Windows may show a SmartScreen warning. Click “More info” → “Run anyway” if you trust the source.

Download AIRI-{version}-darwin-{arch}.dmg from GitHub Releases
- arm64 for Apple Silicon (M1/M2/M3)
- x64 for Intel Macs
Open the DMG file
Drag AIRI to Applications folder
Launch AIRI from Applications

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”

Debian/Ubuntu (DEB)

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)

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)

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

Nix Package

For NixOS or Nix package manager users:

nix run github:moeru-ai/airi

Or add to your flake.nix:

{
  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

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

Development Mode

Start the development server:

pnpm dev:tamagotchi

This launches the Electron app with hot reload enabled.

Production Build

All Platforms
Windows
macOS
Linux

# Build the app (no packaging)
pnpm -F @proj-airi/stage-tamagotchi build

# Build and package for Windows
pnpm -F @proj-airi/stage-tamagotchi build:win

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

# Build and package for macOS
pnpm -F @proj-airi/stage-tamagotchi build:mac

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

Code signing and notarization require Apple Developer account. See electron-builder.config.ts for configuration.

# 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

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:

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

NVIDIA CUDA
Apple Metal

Automatic CUDA support on Windows/Linux with NVIDIA GPUs:

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

CUDA support is automatically detected. No manual configuration needed.

Screen Capture

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

App checks for updates on startup
Downloads updates in background
Prompts user to restart when ready
Installs update on restart

Configuration

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

{
  "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:

pnpm dev:tamagotchi

Debugging

Renderer Process
Main Process

Use Chrome DevTools (automatically opens):

Cmd/Ctrl + Shift + I: Toggle DevTools
Cmd/Ctrl + R: Reload
Vue DevTools available at __devtools__/

VS Code launch configuration:

{
  "type": "node",
  "request": "attach",
  "name": "Attach to Main Process",
  "port": 9229
}

Start with:

pnpm dev:tamagotchi --inspect-brk

Testing

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

Advantages

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

Considerations

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

Troubleshooting

App Won’t Start

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

GPU Not Detected

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

Clear cache and restart
Check main process logs
Verify preload script is loading
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

Web Platform

Browser-based version with WebGPU

Mobile Platform

iOS and Android support

Get Started

Core Features

Platforms

Integrations

Configuration

Development

​Overview

​System Requirements

​Minimum Requirements

​Recommended Specifications

​Installation

​Download Pre-built Binaries

​Debian/Ubuntu (DEB)

​Fedora/RHEL (RPM)

​AppImage (Universal)

​Nix Package

​Building from Source

​Prerequisites

​Clone and Install

​Development Mode

​Production Build

​Architecture

​Electron App Structure

​IPC Communication

​Native Features

​GPU Acceleration

​Screen Capture

​Native Integrations

​Auto-Updater

​How It Works

​Configuration

​Manual Update Check

​Development Workflow

​Hot Reload

​Debugging

​Testing

​Limitations

​Troubleshooting

​App Won’t Start

​GPU Not Detected

​IPC Errors

​Technology Stack

​Related Resources

Web Platform

Mobile Platform

Build docs developers (and LLMs) love

Overview

System Requirements

Minimum Requirements

Recommended Specifications

Installation

Download Pre-built Binaries

Debian/Ubuntu (DEB)

Fedora/RHEL (RPM)

AppImage (Universal)

Nix Package

Building from Source

Prerequisites

Clone and Install

Development Mode

Production Build

Architecture

Electron App Structure

IPC Communication

Native Features

GPU Acceleration

Screen Capture

Native Integrations

Auto-Updater

How It Works

Configuration

Manual Update Check

Development Workflow

Hot Reload

Debugging

Testing

Limitations

Troubleshooting

App Won’t Start

GPU Not Detected

IPC Errors

Technology Stack

Related Resources