Mobile Platform

Overview

Stage Pocket is the mobile version of AIRI, built with Capacitor to bring the full AIRI experience to iOS and Android devices. It shares the same Vue 3 codebase as Stage Web, wrapped in native mobile containers.

Stage Pocket is currently in early development. Some features may be limited or unavailable.

Platform Support

iOS

Minimum: iOS 13.0+
Recommended: iOS 15.0+
Devices: iPhone 8 and newer
Simulator: Xcode 14+ required for development

Android

Minimum: Android 7.0 (API 24)+
Recommended: Android 10.0 (API 29)+
Devices: Any device with WebView support
Emulator: Android Studio required for development

Capacitor Setup

Stage Pocket uses Capacitor to bridge web code to native mobile platforms.

Key Configuration

// capacitor.config.ts
import type { CapacitorConfig } from '@capacitor/cli'

const config: CapacitorConfig = {
  appId: 'ai.moeru.airi',
  appName: 'AIRI',
  webDir: 'dist',
  server: {
    url: process.env.CAPACITOR_DEV_SERVER_URL,
    cleartext: false
  }
}

Installed Plugins

@capacitor/core: Core Capacitor runtime
@capacitor/ios: iOS platform support
@capacitor/local-notifications: Push notifications
Custom plugins for AIRI-specific features

Development Setup

Prerequisites

iOS Development
Android Development

macOS (required for iOS development)
Xcode 14+ (26+ recommended for new icon format)
iOS 13+ device or simulator
Apple Developer account (for device testing)
CocoaPods: sudo gem install cocoapods

Installation

Clone the repository and install dependencies:

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

Development Workflow

Start Web Development Server

pnpm dev:pocket

This starts Vite development server. Note your IP address from the output:

➜  Local:   https://localhost:5273/
➜  Network: https://192.168.1.100:5273/

Open Native IDE

iOS
Android

# Set your development server URL
export CAPACITOR_DEV_SERVER_URL=https://192.168.1.100:5273
pnpm open:ios

This will:

Build the web app
Sync assets to iOS project
Open Xcode

# Build and sync
pnpm -F @proj-airi/stage-pocket build
npx cap sync android
npx cap open android

Android Studio will open the project.

Run on Device/Simulator

Xcode: Click the “Run” button (Cmd + R)
Android Studio: Click “Run ‘app’” (Shift + F10)

The app will launch with live reload from your development server.

Hot Reload

Changes to your web code will automatically reload in the mobile app when connected to the development server.

Both your development machine and mobile device must be on the same network for hot reload to work.

Building for Production

iOS Build

Build Web Assets

pnpm -F @proj-airi/stage-pocket build

Sync to iOS

npx cap sync ios
npx cap open ios

Configure Signing

In Xcode:

Select project in navigator
Select “AIRI” target
Go to “Signing & Capabilities”
Select your team and provisioning profile

Archive and Upload

Product → Archive
Wait for archive to complete
Click “Distribute App”
Follow App Store Connect wizard

Android Build

Build Web Assets

pnpm -F @proj-airi/stage-pocket build

Sync to Android

npx cap sync android
npx cap open android

Generate Signed APK/AAB

In Android Studio:

Build → Generate Signed Bundle / APK
Select Android App Bundle (recommended) or APK
Select/create keystore
Build release variant

Upload to Play Console

Open Google Play Console
Select your app
Go to Release → Production
Upload AAB file

Running on Physical Devices

iOS Device

Enable Developer Mode

On iOS 16+:

Settings → Privacy & Security → Developer Mode
Toggle on and restart device

Trust Developer Certificate

On first run:

Settings → General → VPN & Device Management
Select your developer certificate
Tap “Trust”

Run from Xcode

Connect device via USB
Select device from target menu
Click Run (Cmd + R)

Android Device

Enable Developer Options

Settings → About Phone
Tap “Build Number” 7 times
Go back to Settings → System → Developer Options

Enable USB Debugging

Developer Options → USB Debugging (ON)
Connect device via USB
Accept debugging prompt on device

Run from Android Studio

Select device from target menu
Click Run (Shift + F10)

Mobile-Specific Features

Native Capabilities

Local Notifications: Background reminders and alerts
Haptic Feedback: Tactile responses to interactions
Native Navigation: iOS/Android navigation patterns
Biometric Auth: Face ID, Touch ID, fingerprint (planned)
Native Sharing: Share to other apps
Background Audio: Continue audio playback when app is backgrounded (planned)

Mobile-Optimized UI

Touch-optimized controls
Responsive layouts for various screen sizes
Bottom navigation for easy thumb access
Gesture support (swipe, pinch-to-zoom)
Native keyboard handling

Storage

// Using Capacitor Storage
import { Preferences } from '@capacitor/preferences'

// Save data
await Preferences.set({ key: 'user_id', value: '123' })

// Retrieve data
const { value } = await Preferences.get({ key: 'user_id' })

Notifications

import { LocalNotifications } from '@capacitor/local-notifications'

// Request permission
await LocalNotifications.requestPermissions()

// Schedule notification
await LocalNotifications.schedule({
  notifications: [{
    id: 1,
    title: 'AIRI',
    body: 'Your AI companion is waiting!',
    schedule: { at: new Date(Date.now() + 3600000) }
  }]
})

Limitations

Compared to desktop/web versions:

Technical Limitations

Limited GPU memory on mobile devices
Smaller models required for acceptable performance
Background processing restrictions (iOS/Android)
No native CUDA/Metal support (uses WebGPU in WebView)
Reduced battery life with intensive AI tasks
Network-dependent for large model inference

Feature Limitations

No desktop game integrations (Minecraft, Factorio)
No screen capture capabilities
Limited file system access
No Discord bot features
Simplified UI due to screen size constraints
No system tray functionality

Performance Considerations

Use smaller, optimized models
Leverage server-side inference when possible
Implement aggressive caching strategies
Optimize asset loading for cellular networks
Monitor battery usage and heat generation

Wireless Server Channel

Connect Stage Pocket to Stage Tamagotchi for enhanced features:

Start Tamagotchi as Root (macOS/Linux)

sudo pnpm dev:tamagotchi

Root access is required for secure WebSocket connections.

Enable Secure WebSocket in Tamagotchi

Open Tamagotchi Settings
Navigate to System → General
Enable “Secure WebSocket”
Note the server address displayed

Connect from Pocket

Open Stage Pocket on your mobile device
Go to Settings → Server Channel
Enter the server address from Tamagotchi
Tap “Connect”

This allows mobile app to:

Offload inference to desktop GPU
Access desktop’s model library
Share chat history and settings
Use desktop plugins and integrations

Troubleshooting

Build Fails

iOS
Android

# Clean Xcode build
cd ios/App
rm -rf DerivedData
xcodebuild clean

# Reinstall pods
pod deintegrate
pod install

# Clean Gradle build
cd android
./gradlew clean

# Invalidate caches in Android Studio
File → Invalidate Caches → Invalidate and Restart

Device Not Detected

iOS: Check USB connection, trust computer prompt
Android: Enable USB debugging, install device drivers (Windows)
Try different USB cable or port

App Crashes on Launch

Check device logs:
- iOS: Xcode → Window → Devices and Simulators → View Device Logs
- Android: Android Studio → Logcat
Verify WebView version is up to date
Check for JavaScript errors in web console
Ensure native dependencies are properly linked

Technology Stack

Framework: Capacitor 7
Web Layer: Vue 3 + Vite (shared with Stage Web)
iOS: Swift + WKWebView
Android: Kotlin + WebView
State: Pinia
Graphics: WebGPU (in WebView)
Database: DuckDB WASM
Styling: UnoCSS

App Store Deployment

Pre-submission Checklist

Prepare assets:

App icon (1024x1024)
Screenshots for all device sizes
Privacy policy URL
App description and keywords
Promotional images (optional)

Configure metadata:

App name and subtitle
Category selection
Age rating
Price (free/paid)
In-app purchases (if any)

Review guidelines compliance:

Submission Process

iOS App Store
Google Play Store

Archive app in Xcode
Upload to App Store Connect
Fill out app information
Submit for review
Wait 1-3 days for approval

Web Platform

Browser-based version with WebGPU

Desktop Platform

Native Electron app with full features

Get Started

Core Features

Platforms

Integrations

Configuration

Development

​Overview

​Platform Support

​iOS

​Android

​Capacitor Setup

​Key Configuration

​Installed Plugins

​Development Setup

​Prerequisites

​Installation

​Development Workflow

​Hot Reload

​Building for Production

​iOS Build

​Android Build

​Running on Physical Devices

​iOS Device

​Android Device

​Mobile-Specific Features

​Native Capabilities

​Mobile-Optimized UI

​Storage

​Notifications

​Limitations

​Performance Considerations

​Wireless Server Channel

​Troubleshooting

​Build Fails

​Device Not Detected

​App Crashes on Launch

​Technology Stack

​App Store Deployment

​Pre-submission Checklist

​Submission Process

​Related Resources

Web Platform

Desktop Platform

Build docs developers (and LLMs) love

Overview

Platform Support

iOS

Android

Capacitor Setup

Key Configuration

Installed Plugins

Development Setup

Prerequisites

Installation

Development Workflow

Hot Reload

Building for Production

iOS Build

Android Build

Running on Physical Devices

iOS Device

Android Device

Mobile-Specific Features

Native Capabilities

Mobile-Optimized UI

Storage

Notifications

Limitations

Performance Considerations

Wireless Server Channel

Troubleshooting

Build Fails

Device Not Detected

App Crashes on Launch

Technology Stack

App Store Deployment

Pre-submission Checklist

Submission Process

Related Resources