Deployment

Deployment

Guide for deploying AI Runner in various configurations.

Installation Methods

pip Install (Recommended)

# Install with all features
pip install airunner[all]

# Download models
airunner-setup

# Launch
airunner

One-Line Install Script

curl -sSL https://raw.githubusercontent.com/Capsize-Games/airunner/develop/install.sh | bash

The script:

• Checks Python 3.13+ and CUDA
• Creates isolated virtual environment
• Installs PyTorch with GPU support
• Creates launcher scripts in ~/.local/bin

Docker

# Run with GPU support
docker run -it --gpus all \
    -v ~/.local/share/airunner:/data \
    -p 8188:8188 \
    capsizegames/airunner

Headless Server

Run AI Runner as a background service for API access.

Manual Start

airunner-headless --port 8188

Systemd Service (Linux)

1. Copy service file:

sudo cp deployment/systemd/airunner-headless.service /etc/systemd/system/

2. Edit configuration:

sudo nano /etc/systemd/system/airunner-headless.service

Update paths:

[Service]
User=your_username
Group=your_group
WorkingDirectory=/path/to/airunner
ExecStart=/path/to/venv/bin/python -m airunner.bin.airunner_headless --port 8188

3. Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable airunner-headless
sudo systemctl start airunner-headless

Service Management

# Check status
sudo systemctl status airunner-headless

# View logs
sudo journalctl -u airunner-headless -f

# Restart
sudo systemctl restart airunner-headless

# Stop
sudo systemctl stop airunner-headless

API Server

AI Runner includes a FastAPI server for HTTP access.

Start API Server

airunner-service --host 0.0.0.0 --port 8188

Endpoints

Endpoint	Method	Description
/llm/generate	POST	Generate text
/llm/chat	POST	Chat completion
/image/generate	POST	Generate image
/tts/speak	POST	Text to speech
/health	GET	Health check

Example Request

curl -X POST http://localhost:8188/llm/generate \
    -H "Content-Type: application/json" \
    -d '{"prompt": "Hello, how are you?"}'

Reverse Proxy (nginx)

Example nginx configuration:

server {
    listen 80;
    server_name ai.example.com;

    location / {
        proxy_pass http://localhost:8188;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Environment Variables

Variable	Description	Default
AIRUNNER_DATA_DIR	Data directory	~/.local/share/airunner
AIRUNNER_LOG_LEVEL	Log level	INFO
AIRUNNER_HOST	API host	127.0.0.1
AIRUNNER_PORT	API port	8188
PYTORCH_CUDA_ALLOC_CONF	PyTorch memory config	expandable_segments:True

Hardware Requirements

Minimum

• 8GB RAM
• 4GB VRAM (for small models)
• 20GB disk space

Recommended

• 16GB+ RAM
• 12GB+ VRAM (RTX 3060 or better)
• 100GB+ SSD storage
• CUDA-capable NVIDIA GPU

Troubleshooting

Service Won't Start

1. Check logs: journalctl -u airunner-headless -n 50
2. Verify paths in service file
3. Check Python environment activation
4. Ensure port isn't in use

GPU Not Detected

1. Verify NVIDIA drivers: nvidia-smi
2. Check CUDA installation
3. Ensure PyTorch has CUDA: python -c "import torch; print(torch.cuda.is_available())"

Out of Memory

1. Use smaller model or quantization
2. Reduce batch size
3. Enable memory efficient attention
4. Check PYTORCH_CUDA_ALLOC_CONF

See Also

• Installation - Detailed setup
• Settings - Configuration options
• Architecture - System design