airunner

⚙️ System Requirements

	Minimum	Recommended
OS	Ubuntu 22.04, Windows 10	Ubuntu 22.04 (Wayland)
CPU	Ryzen 2700K / i7-8700K	Ryzen 5800X / i7-11700K
RAM	16 GB	32 GB
GPU	NVIDIA RTX 3060	NVIDIA RTX 5080
Storage	22 GB - 100 GB+ (actual usage varies, SSD recommended)	100 GB+

---

---

💾 Installation

Current status: The hybrid-runtime branch completed the runtime refactor, and AIRunner now has embedded-Python bundle builders and installer packagers.

Available packaging paths:

• Linux staged bundle archive: ./scripts/build_airunner_bundle.sh
• Linux AppImage wrapper: ./scripts/package_linux_appimage.sh
• Linux tarball installer: ./install.sh --bundle-archive <bundle.tar.gz>
• Windows bundle staging: python src/airunner/bin/build_end_user_bundle.py
• Windows NSIS installer: pwsh ./scripts/package_windows_nsis.ps1

The manual and Docker paths below are still useful developer/operator installation flows. The bundled end-user packaging contract is summarized in END_USER_DISTRIBUTION.md.

---

Docker (Recommended)

GUI Mode:

xhost +local:docker && docker compose run --rm airunner

Headless API Server:

docker compose run --rm --service-ports airunner --headless

Note: --service-ports is required to expose port 8080 for the API.

To trim container dependencies for a specific deployment, rebuild with a profile list such as:

docker build \
  --build-arg AIRUNNER_INSTALL_PROFILES=core,llm-native,stt-native \
  -t airunner:headless .

The headless server exposes an HTTP API on port 8080 with endpoints:

• GET /health - Health check and service status
• POST /llm - LLM inference
• POST /art - Image generation

---

Manual Installation (Ubuntu/Debian)

Python 3.13+ required. We recommend using pyenv and venv.

1. Install system dependencies:

   sudo apt update && sudo apt install -y \
     build-essential cmake git curl wget pkg-config \
     nvidia-cuda-toolkit pipewire libportaudio2 libxcb-cursor0 \
     espeak espeak-ng-espeak qt6-qpa-plugins qt6-wayland \
     libsentencepiece-dev \
     mecab libmecab-dev mecab-ipadic-utf8 libxslt-dev mkcert
   

2. Create data directory:

   mkdir -p ~/.local/share/airunner
   

3. Choose the package profiles you need:

   • core: shared API, storage, config, and runtime plumbing
   • llm-native: local llama.cpp runtime and LLM toolchain
   • stt-native: local STT runtime helpers
   • art-python: Python image-generation runtimes
   • tts-python: Python TTS runtimes without MeCab-backed language packs
   • gui: desktop UI dependencies
   • development: test, lint, and packaging tooling

4. Install AI Runner:

From PyPI:

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128
pip install \
  "airunner[core,llm-native,stt-native,art-python,tts-python,gui]"

For a headless-only install, omit the GUI profile:

pip install \
  "airunner[core,llm-native,stt-native,art-python,tts-python]"

From a local clone in editable mode:

git clone https://github.com/Capsize-Games/airunner.git
cd airunner
python -m venv venv
source venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128
pip install -e \
  ".[core,llm-native,stt-native,art-python,tts-python,gui,development]"

The base tts-python profile intentionally excludes the MeCab-backed Japanese and Korean voice packs so a fresh virtual environment can install without extra native build steps.

To include those language packs after installing the system packages above, use:

pip install -e ".[openvoice_jp,openvoice_kr]"

5. **Install llama-cpp-python with CUDA (