Project AIRI Deployment and Usage Guide

1. Prerequisites

Before installing AIRI, ensure you have the following:

Runtime & Tools

Node.js 18+ and npm or pnpm (TypeScript project)
Git for cloning the repository
Docker and Docker Compose (optional, for containerized deployment)
Python 3.8+ (may be required for some AI model integrations)

API Accounts & Services

AI Model Provider API Keys (required for core functionality):
- OpenAI GPT API key (for ChatGPT integration)
- Anthropic Claude API key (optional alternative)
- Local LLM setup (Ollama, LM Studio, etc.) for self-hosted options
Voice Services (optional, for voice chat):
- Speech-to-text service (Web Speech API, Aliyun, or other providers)
- Text-to-speech service
Game Integrations (optional):
- Minecraft server access
- Factorio server/game instance
Messaging Platforms (optional):
- Telegram Bot Token (for Telegram bot integration)
- Discord Bot Token (for Discord integration)

2. Installation

Clone the Repository

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

Install Dependencies

AIRI uses a monorepo structure with multiple packages. Install dependencies using:

# Using npm
npm install

# Or using pnpm (recommended)
npm install -g pnpm
pnpm install

Verify Installation

Check that all packages are properly installed:

pnpm run build:check

3. Configuration

Environment Variables

Create a .env file in the root directory with the following variables:

# Core AI Model Configuration
OPENAI_API_KEY=sk-your-openai-api-key-here
ANTHROPIC_API_KEY=your-claude-api-key-here

# Optional: Local LLM Configuration
LOCAL_LLM_URL=http://localhost:11434  # Ollama default
LOCAL_LLM_MODEL=llama3.2

# Voice Configuration
VOICE_PROVIDER=web-speech-api  # or 'aliyun', 'azure', etc.
ALIYUN_ACCESS_KEY_ID=your-aliyun-key
ALIYUN_ACCESS_KEY_SECRET=your-aliyun-secret

# Telegram Bot (optional)
TELEGRAM_BOT_TOKEN=your-telegram-bot-token
TELEGRAM_WEBHOOK_URL=https://your-domain.com/webhook

# Minecraft Integration (optional)
MINECRAFT_SERVER_HOST=localhost
MINECRAFT_SERVER_PORT=25565
MINECRAFT_BOT_USERNAME=AIRI_Bot
MINECRAFT_BOT_PASSWORD=  # Leave empty for offline mode

# Application Settings
NODE_ENV=development
PORT=3000
HOST=0.0.0.0

Plugin Configuration

AIRI uses a plugin system. Configure plugins in packages/plugin-sdk/:

Module Configuration: Each plugin module requires configuration:

{
  "id": "telegram-bot",
  "version": "1.0.0",
  "labels": {
    "env": "production",
    "app": "telegram"
  }
}

Transcription Providers: Configure in packages/stage-ui/src/stores/modules/hearing.ts:

// Configure your preferred transcription provider
const transcriptionProvider: TranscriptionProviderWithExtraOptions = {
  id: 'web-speech-api',
  name: 'Web Speech API',
  capabilities: ['streaming', 'realtime']
}

Minecraft Skill Configuration

For Minecraft integration, configure skills in services/minecraft/src/skills/:

// Example block interaction configuration
const miningConfig = {
  allowedBlocks: ['stone', 'ore', 'log'],
  forbiddenBlocks: ['bedrock', 'spawner'],
  autoLight: true,  // Automatically place torches in dark areas
  allowCheats: false  // Enable/disable cheat commands
}

4. Build & Run

Development Mode

Run AIRI in development mode with hot reload:

# Start all services in development mode
pnpm run dev

# Or start specific services
pnpm run dev:ui        # Web interface only
pnpm run dev:api       # Backend API only
pnpm run dev:telegram  # Telegram bot service
pnpm run dev:minecraft # Minecraft integration

Production Build

Build the application for production:

# Build all packages
pnpm run build

# Build specific packages
pnpm run build:ui
pnpm run build:api
pnpm run build:plugins

# Type checking
pnpm run type-check

Running Production Build

After building, run the production server:

# Start production server
pnpm start

# Or using Node directly
node dist/main.js

Docker Deployment

Build and run using Docker:

# Build Docker image
docker build -t airi:latest .

# Run with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f

5. Deployment

Platform Recommendations

Based on the TypeScript/Node.js stack:

Traditional VPS/Cloud VM (Recommended for full control):
- DigitalOcean, Linode, AWS EC2, Google Cloud Compute
- Install Node.js, set up reverse proxy (Nginx/Caddy)
- Use PM2 for process management: pm2 start ecosystem.config.js
Container Platforms:
- Docker with Docker Compose for local deployment
- Kubernetes for scalable production deployments
- Railway, Render, Fly.io for managed container hosting
Serverless/Edge (for specific components):
- Vercel, Netlify for the web interface
- Cloudflare Workers for lightweight services
- Note: Game integrations require persistent connections

Deployment Steps

Option A: Docker Compose Deployment

Create a docker-compose.yml:

version: '3.8'
services:
  airi:
    image: ghcr.io/moeru-ai/airi:latest
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
    volumes:
      - ./data:/app/data
    restart: unless-stopped

  # Optional: Minecraft server
  minecraft:
    image: itzg/minecraft-server:latest
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE"
      VERSION: "1.20.1"
    volumes:
      - ./minecraft-data:/data

Option B: PM2 Process Manager

# Install PM2 globally
npm install -g pm2

# Create ecosystem file
pm2 init

# Start AIRI with PM2
pm2 start pnpm --name "airi" -- start

# Save process list
pm2 save

# Set up startup script
pm2 startup

Option C: Kubernetes Deployment

Create Kubernetes manifests:

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: airi
spec:
  replicas: 2
  selector:
    matchLabels:
      app: airi
  template:
    metadata:
      labels:
        app: airi
    spec:
      containers:
      - name: airi
        image: ghcr.io/moeru-ai/airi:latest
        ports:
        - containerPort: 3000
        envFrom:
        - secretRef:
            name: airi-secrets
---
# service.yaml
apiVersion: v1
kind: Service
metadata:
  name: airi-service
spec:
  selector:
    app: airi
  ports:
  - port: 80
    targetPort: 3000
  type: LoadBalancer

6. Troubleshooting

Common Issues and Solutions

1. Plugin System Errors

Error: Module configuration needed

Solution: Ensure all required plugins are properly configured:

# Check plugin status
pnpm run plugins:status

# Reset plugin configuration
pnpm run plugins:reset

2. Voice Transcription Failures

Error: Web Speech API not available

Solution:

Use Chrome/Edge browsers (best Web Speech API support)
Or configure alternative provider in hearing.ts:

// Switch to Aliyun provider
const provider = await streamAliyunTranscription(options)

3. Minecraft Connection Issues

Error: Cannot connect to Minecraft server

Solution:

Verify server is running: nc -z localhost 25565
Check authentication mode (online/offline)
Ensure bot has proper permissions:

// In minecraft skills configuration
const mineflayerConfig = {
  host: 'localhost',
  port: 25565,
  username: 'AIRI_Bot',
  auth: 'offline'  // Use 'microsoft' for online mode
}

4. Telegram Bot Not Responding

Error: Bot not receiving webhooks

Solution:

Set webhook manually:

curl -X POST https://api.telegram.org/bot<YOUR_TOKEN>/setWebhook \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-domain.com/webhook"}'

Check bot token validity
Ensure HTTPS is properly configured

5. Build Failures

Error: TypeScript compilation failed

Solution:

Clear build cache: pnpm run clean
Update dependencies: pnpm update
Check TypeScript version compatibility
Run type checking separately: pnpm run type-check

6. Performance Issues

High Memory Usage:

Limit conversation history length
Use streaming responses instead of full buffering
Implement memory management in plugin configuration

Slow Response Times:

Enable response caching
Use faster LLM models (smaller parameter count)
Implement request queuing in busy periods

Getting Help

Discord Community: Join AIRI Discord for real-time support
GitHub Issues: Report bugs at github.com/moeru-ai/airi/issues
Documentation: Check airi.moeru.ai/docs for updated guides
Logs: Enable verbose logging for debugging:

DEBUG=airi:* pnpm run dev

Security Notes

Never commit .env files or API keys to version control
Use environment variables or secret management systems
Regularly update dependencies: pnpm update --latest
Implement rate limiting for public deployments
Use HTTPS in production with valid SSL certificates

How to Deploy & Use airi

Project AIRI Deployment and Usage Guide

1. Prerequisites

Runtime & Tools

API Accounts & Services

2. Installation

Clone the Repository

Install Dependencies

Verify Installation

3. Configuration

Environment Variables

Plugin Configuration

Minecraft Skill Configuration

4. Build & Run

Development Mode

Production Build

Running Production Build

Docker Deployment

5. Deployment

Platform Recommendations

Deployment Steps

Option A: Docker Compose Deployment

Option B: PM2 Process Manager

Option C: Kubernetes Deployment

6. Troubleshooting

Common Issues and Solutions

1. Plugin System Errors

2. Voice Transcription Failures

3. Minecraft Connection Issues

4. Telegram Bot Not Responding

5. Build Failures

6. Performance Issues

Getting Help

Security Notes