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.

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

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

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

macOS

1. Download AIRI-{version}-darwin-{arch}.dmg from GitHub 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

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”

Linux

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

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

Windows

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

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

macOS

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

Linux

# 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

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.

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

Metal is automatically used on Apple Silicon Macs.

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

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:

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

Use Chrome DevTools (automatically opens):

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

Main Process

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

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

# 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

Web Platform

Browser-based version with WebGPU

Mobile Platform

iOS and Android support