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

# Mobile Platform

> iOS and Android support via Capacitor

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

<Warning>
  Stage Pocket is currently in early development. Some features may be limited or unavailable.
</Warning>

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

```typescript theme={null}
// 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

<Tabs>
  <Tab title="iOS 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`
  </Tab>

  <Tab title="Android Development">
    * macOS, Windows, or Linux
    * Android Studio
    * Android SDK 24+
    * Java Development Kit (JDK) 17+
    * Android device or emulator
  </Tab>
</Tabs>

### Installation

Clone the repository and install dependencies:

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

### Development Workflow

<Steps>
  <Step title="Start Web Development Server">
    ```bash theme={null}
    pnpm dev:pocket
    ```

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

    ```bash theme={null}
    ➜  Local:   https://localhost:5273/
    ➜  Network: https://192.168.1.100:5273/
    ```
  </Step>

  <Step title="Open Native IDE">
    <Tabs>
      <Tab title="iOS">
        ```bash theme={null}
        # Set your development server URL
        export CAPACITOR_DEV_SERVER_URL=https://192.168.1.100:5273
        pnpm open:ios
        ```

        This will:

        1. Build the web app
        2. Sync assets to iOS project
        3. Open Xcode
      </Tab>

      <Tab title="Android">
        ```bash theme={null}
        # Build and sync
        pnpm -F @proj-airi/stage-pocket build
        npx cap sync android
        npx cap open android
        ```

        Android Studio will open the project.
      </Tab>
    </Tabs>
  </Step>

  <Step title="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.
  </Step>
</Steps>

### Hot Reload

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

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

## Building for Production

### iOS Build

<Steps>
  <Step title="Build Web Assets">
    ```bash theme={null}
    pnpm -F @proj-airi/stage-pocket build
    ```
  </Step>

  <Step title="Sync to iOS">
    ```bash theme={null}
    npx cap sync ios
    npx cap open ios
    ```
  </Step>

  <Step title="Configure Signing">
    In Xcode:

    1. Select project in navigator
    2. Select "AIRI" target
    3. Go to "Signing & Capabilities"
    4. Select your team and provisioning profile
  </Step>

  <Step title="Archive and Upload">
    1. Product → Archive
    2. Wait for archive to complete
    3. Click "Distribute App"
    4. Follow App Store Connect wizard
  </Step>
</Steps>

### Android Build

<Steps>
  <Step title="Build Web Assets">
    ```bash theme={null}
    pnpm -F @proj-airi/stage-pocket build
    ```
  </Step>

  <Step title="Sync to Android">
    ```bash theme={null}
    npx cap sync android
    npx cap open android
    ```
  </Step>

  <Step title="Generate Signed APK/AAB">
    In Android Studio:

    1. Build → Generate Signed Bundle / APK
    2. Select Android App Bundle (recommended) or APK
    3. Select/create keystore
    4. Build release variant
  </Step>

  <Step title="Upload to Play Console">
    1. Open [Google Play Console](https://play.google.com/console)
    2. Select your app
    3. Go to Release → Production
    4. Upload AAB file
  </Step>
</Steps>

## Running on Physical Devices

### iOS Device

<Steps>
  <Step title="Enable Developer Mode">
    On iOS 16+:

    1. Settings → Privacy & Security → Developer Mode
    2. Toggle on and restart device
  </Step>

  <Step title="Trust Developer Certificate">
    On first run:

    1. Settings → General → VPN & Device Management
    2. Select your developer certificate
    3. Tap "Trust"
  </Step>

  <Step title="Run from Xcode">
    1. Connect device via USB
    2. Select device from target menu
    3. Click Run (Cmd + R)
  </Step>
</Steps>

### Android Device

<Steps>
  <Step title="Enable Developer Options">
    1. Settings → About Phone
    2. Tap "Build Number" 7 times
    3. Go back to Settings → System → Developer Options
  </Step>

  <Step title="Enable USB Debugging">
    1. Developer Options → USB Debugging (ON)
    2. Connect device via USB
    3. Accept debugging prompt on device
  </Step>

  <Step title="Run from Android Studio">
    1. Select device from target menu
    2. Click Run (Shift + F10)
  </Step>
</Steps>

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

```typescript theme={null}
// 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

```typescript theme={null}
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:

<Warning>
  **Technical Limitations**
</Warning>

* 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

<Warning>
  **Feature Limitations**
</Warning>

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

<Steps>
  <Step title="Start Tamagotchi as Root (macOS/Linux)">
    ```bash theme={null}
    sudo pnpm dev:tamagotchi
    ```

    <Note>
      Root access is required for secure WebSocket connections.
    </Note>
  </Step>

  <Step title="Enable Secure WebSocket in Tamagotchi">
    1. Open Tamagotchi Settings
    2. Navigate to System → General
    3. Enable "Secure WebSocket"
    4. Note the server address displayed
  </Step>

  <Step title="Connect from Pocket">
    1. Open Stage Pocket on your mobile device
    2. Go to Settings → Server Channel
    3. Enter the server address from Tamagotchi
    4. Tap "Connect"
  </Step>
</Steps>

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

<Tabs>
  <Tab title="iOS">
    ```bash theme={null}
    # Clean Xcode build
    cd ios/App
    rm -rf DerivedData
    xcodebuild clean

    # Reinstall pods
    pod deintegrate
    pod install
    ```
  </Tab>

  <Tab title="Android">
    ```bash theme={null}
    # Clean Gradle build
    cd android
    ./gradlew clean

    # Invalidate caches in Android Studio
    File → Invalidate Caches → Invalidate and Restart
    ```
  </Tab>
</Tabs>

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

1. Check device logs:
   * **iOS**: Xcode → Window → Devices and Simulators → View Device Logs
   * **Android**: Android Studio → Logcat
2. Verify WebView version is up to date
3. Check for JavaScript errors in web console
4. 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

<Check>Prepare assets:</Check>

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

<Check>Configure metadata:</Check>

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

<Check>Review guidelines compliance:</Check>

* [App Store Review Guidelines](https://developer.apple.com/app-store/review/guidelines/)
* [Google Play Policy Center](https://play.google.com/about/developer-content-policy/)

### Submission Process

<Tabs>
  <Tab title="iOS App Store">
    1. Archive app in Xcode
    2. Upload to App Store Connect
    3. Fill out app information
    4. Submit for review
    5. Wait 1-3 days for approval
  </Tab>

  <Tab title="Google Play Store">
    1. Generate signed AAB
    2. Upload to Play Console
    3. Complete store listing
    4. Submit for review
    5. Wait few hours to 1 day for approval
  </Tab>
</Tabs>

## Related Resources

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

  <Card title="Desktop Platform" icon="desktop" href="/platforms/desktop">
    Native Electron app with full features
  </Card>
</CardGroup>