{"id":23331073,"url":"https://github.com/capsize-games/airunner","last_synced_at":"2026-10-19T14:10:13.973Z","repository":{"id":148312035,"uuid":"617136332","full_name":"Capsize-Games/airunner","owner":"Capsize-Games","description":"Offline inference engine for art, real-time voice conversations, LLM powered chatbots and automated workflows","archived":false,"fork":false,"pushed_at":"2026-10-13T11:59:00.000Z","size":84680,"stargazers_count":1318,"open_issues_count":26,"forks_count":104,"subscribers_count":10,"default_branch":"master","last_synced_at":"2026-10-13T12:50:47.000Z","etag":null,"topics":["ai","ai-art","art","asset-generator","chatbot","deep-learning","desktop-app","image-generation","mistral","multimodal","privacy","pygame","pyside6","python","self-hosted","speech-to-text","stable-diffusion","text-to-image","text-to-speech","text-to-speech-app"],"latest_commit_sha":null,"homepage":"https://airunner.art","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Capsize-Games.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","accessibility":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"claude":null,"gemini":null,"cursor":null,"copilot":".github/copilot-instructions.md","dco":null,"cla":null,"disclosure":null},"funding":{"github":"w4ffl35"}},"created_at":"2023-03-21T19:14:03.000Z","updated_at":"2026-10-09T15:37:43.000Z","dependencies_parsed_at":"2026-10-13T12:35:57.597Z","dependency_job_id":null,"html_url":"https://github.com/Capsize-Games/airunner","commit_stats":null,"previous_names":[],"tags_count":279,"template":false,"template_full_name":null,"purl":"pkg:github/Capsize-Games/airunner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Capsize-Games%2Fairunner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Capsize-Games%2Fairunner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Capsize-Games%2Fairunner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Capsize-Games%2Fairunner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Capsize-Games","download_url":"https://codeload.github.com/Capsize-Games/airunner/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Capsize-Games%2Fairunner/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":344872684,"owners_count":38357901,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-10-03T21:59:58.778Z","status":"online","status_checked_at":"2026-10-19T02:00:06.414Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-art","art","asset-generator","chatbot","deep-learning","desktop-app","image-generation","mistral","multimodal","privacy","pygame","pyside6","python","self-hosted","speech-to-text","stable-diffusion","text-to-image","text-to-speech","text-to-speech-app"],"created_at":"2024-12-20T22:30:30.491Z","updated_at":"2026-10-19T14:10:13.965Z","avatar_url":"https://github.com/Capsize-Games.png","language":"Python","funding_links":["https://github.com/sponsors/w4ffl35"],"categories":[],"sub_categories":[],"readme":"# AI Runner\n\n## Edge AI for art and chat companions, built with privacy, flexibility, and creativity in mind.\n\nAI Runner is a private AI companion you shape — name, personality, voice, memory — and a layered canvas for AI art generation. Everything runs on your machine by default.\n\n\n\u003cimg src=\"./images/art_interface.png\" alt=\"AI Runner Logo\" /\u003e\n\n\n[![Build](https://github.com/Capsize-Games/airunner/actions/workflows/eval-tests.yml/badge.svg)](https://github.com/Capsize-Games/airunner/actions/workflows/eval-tests.yml)\n[![Native Runtime Sidecars](https://github.com/Capsize-Games/airunner-native/actions/workflows/native-runtime-sidecars.yml/badge.svg)](https://github.com/Capsize-Games/airunner-native/actions/workflows/native-runtime-sidecars.yml)\n[![Docker Release](https://github.com/Capsize-Games/airunner/actions/workflows/docker-release.yml/badge.svg)](https://github.com/Capsize-Games/airunner/actions/workflows/docker-release.yml)\n[![PyPI](https://github.com/Capsize-Games/airunner/actions/workflows/pypi-dispatch.yml/badge.svg)](https://github.com/Capsize-Games/airunner/actions/workflows/pypi-dispatch.yml)\n[![Python 3.13](https://img.shields.io/badge/Python-3.13-blue.svg)](https://www.python.org/downloads/)\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![GitHub last commit](https://img.shields.io/github/last-commit/Capsize-Games/airunner)](https://github.com/Capsize-Games/airunner/commits/master)\n[![Discord](https://img.shields.io/badge/Discord-Join%20the%20community-5865F2?logo=discord\u0026logoColor=white)](https://discord.gg/7254Hkzc4T)\n\n[🐞 Report Bug](https://github.com/Capsize-Games/airunner/issues/new?template=bug_report.md) · [✨ Request Feature](https://github.com/Capsize-Games/airunner/issues/new?template=feature_request.md) · [🛡️ Report Vulnerability](https://github.com/Capsize-Games/airunner/issues/new?template=vulnerability_report.md) · [📖 Wiki](https://github.com/Capsize-Games/airunner/wiki)\n\n### Get AI Runner\n\n| | |\n|---|---|\n| **Desktop download** | [capsizegames.itch.io/ai-runner](https://capsizegames.itch.io/ai-runner) — no Python setup required |\n| **Container** | `docker pull ghcr.io/capsize-games/airunner:linux-desktop` ([also `linux`, `linux-headless`](https://github.com/Capsize-Games/airunner/pkgs/container/airunner%2Fairunner)) |\n| **Python** | `pip install airunner` ([PyPI](https://pypi.org/project/airunner/)) |\n| **On the web** | [airunner.art](https://airunner.art) |\n\nAI Runner is free and GPL-3.0. If it is useful to you, [**sponsoring the project**](https://github.com/sponsors/w4ffl35) is what keeps it maintained — it is built and released by one engineer at [Capsize LLC](https://capsize.online).\n\n---\n\n## What AI Runner Is For\n\nAI Runner is built around two interlocking experiences.\n\n**A companion you shape.** Name it, give it a personality, assign it\na voice, and let it build memory of who you are over time. Your\ncompanion is aware of the time, date, and weather, and its mood shifts\nnaturally through conversation. Everything — the conversations, the\nmemories, the personality — stays on your machine.\n\n**A canvas for AI art.** A layered drawing and generation surface where\nyou can sketch, paint, generate, and filter. Convert sketches to images,\niterate with image-to-image, composite on layers, and apply styles and\nfilters — with your companion present alongside you while you create.\n\nNeither experience requires an internet connection, an API key, or a\nsubscription. Everything runs on your hardware.\n\n## ✨ Key Features\n\n| Feature | Description |\n|---------|-------------|\n| **🤖 AI Companion** | Shape a named, voiced companion with persistent personality, shifting mood, and long-term memory built from your conversations |\n| **🎨 Layered Canvas** | Draw, paint, generate, and filter on a multi-layer canvas — convert sketches to images, composite scenes, and iterate in place |\n| **🖼️ Image Generation** | Z-Image Turbo with embeddings, image-to-image, inpainting, and post-process filters, background removal |\n| **🗣️ Voice Conversation** | Full TTS and STT — speak to your companion and hear it respond in a voice you choose |\n| **🧠 Memory \u0026 Recall** | Companion builds long-term memory of you across sessions with RAG-powered recall |\n| **🌤️ Environmental Awareness** | Companion is aware of time, date, and local weather — grounded in the real moment |\n| **🔒 Privacy First** | Private by default — no telemetry and no data leaves your machine unless you explicitly enable an optional cloud feature |\n| **🛡️ Safety Filters** | Configurable NSFW output filtering and always-on prompt classifier for illegal content |\n| **📦 Model Management** | Built-in HuggingFace and Civitai downloaders with support for multiple local LLMs and image models |\n\n### 🌍 Language Support\n\n| Language | TTS | LLM | STT | GUI |\n|----------|-----|-----|-----|-----|\n| English | ✅ | ✅ | ✅ | ✅ |\n| Japanese | ✅ | ✅ | ❌ | ✅ |\n| Spanish/French/Chinese/Korean | ✅ | ✅ | ❌ | ❌ |\n\n## 🧱 Package Overview\n\n```mermaid\nflowchart LR\n  User[User] --\u003e Native[native/ launcher and bundle helpers]\n  Native --\u003e GUI[src/ desktop client]\n  Native --\u003e Daemon[services/ headless daemon]\n  GUI --\u003e Daemon\n  Native --\u003e Sidecars[llama.cpp and whisper.cpp sidecars]\n  Daemon --\u003e Sidecars\n  GUI --\u003e Scripts[scripts/ tooling]\n  Daemon --\u003e Scripts\n  GUI --\u003e Data[(AIRUNNER_BASE_PATH)]\n  Daemon --\u003e Data\n```\n\n| Package | Role |\n|---------|------|\n| [src](src/README.md) | Desktop GUI client, daemon client bridge, widgets, and application entry points |\n| [services](services/README.md) | Headless daemon, FastAPI server, runtime registry, orchestration, downloads, and persistence |\n| [native](native/README.md) | Python launcher entry point and runtime layout helpers. Native sidecar (llama.cpp/whisper.cpp) builds live in [airunner-native](https://github.com/Capsize-Games/airunner-native) |\n| [scripts](scripts/README.md) | Developer tooling: test runner, UI build, install helpers, and quality reports |\n\n---\n\n## ⚙️ System Requirements\n\n| | Minimum | Recommended |\n|---|---------|-------------|\n| **OS** | Ubuntu 22.04, Windows 10 * | Ubuntu 22.04 (Wayland) |\n| **CPU** | Ryzen 2700K / i7-8700K | Ryzen 5800X / i7-11700K |\n| **RAM** | 16 GB | 32 GB |\n| **GPU** | NVIDIA RTX 3060 | NVIDIA RTX 5080 |\n| **Storage** | 22 GB - 100 GB+ (actual usage varies, SSD recommended) | 100 GB+ |\n\n\u003e \\* Windows support is experimental and community-maintained; Linux is the primary supported platform.\n\n---\n\n## 💾 Installation\n\nCurrent status:\nAIRunner services install from apt (Ubuntu 26.04+) or run as a\nPython application with two install paths.\n\n### apt (services only, no Qt desktop)\n\n```bash\ncurl -fsSL https://apt.airunner.art/airunner-apt-keyring.gpg \\\n  -o /usr/share/keyrings/airunner-apt.gpg\nprintf 'Types: deb\\nURIs: https://apt.airunner.art\\nSuites: stable\\nComponents: main\\nSigned-By: /usr/share/keyrings/airunner-apt.gpg\\n' \\\n  \u003e /etc/apt/sources.list.d/airunner.sources\nsudo apt update \u0026\u0026 sudo apt install airunner\n```\n\nThen `systemctl status airunner-headless` and\n`curl http://127.0.0.1:8188/health` (default loopback daemon).\nWithout torch the daemon boots degraded (/health plus\nsidecar-backed modalities); install ML extras into a venv when a\nworkload needs local models (see `debian/README.Debian`).\n\nChoose one of the two primary install modes:\n\n| Install mode | Best for | Primary command |\n|--------------|----------|-----------------|\n| `dev` | Contributors working from a repo checkout | `./scripts/install.sh` |\n| `distributed` | Operators separating daemon and GUI-client installs | `./deployment/install_distributed.sh --role ...` |\n\n1. `dev` for contributors working from this repo checkout.\n  This reuses `./venv` by default, installs the Python packages in editable\n  mode, and downloads the pinned prebuilt `llama.cpp` and `whisper.cpp`\n  sidecar bundle (`.github/native-sidecar-version` selects the\n  [airunner-native](https://github.com/Capsize-Games/airunner-native)\n  release) into `build/runtime-sidecars-download/`, linking `llama-server`\n  and `whisper-server` into the venv.\n  ```bash\n  ./scripts/install.sh\n  ```\n  If you already have the venv, rerun the command and it will reuse the\n  existing environment instead of recreating it, and it refreshes the local\n  editable installs without re-solving the full dependency graph. Add\n  `--refresh-deps` when you want a full dependency refresh, and add\n  `--sidecars-cuda` when you want CUDA-enabled native sidecars (that flag\n  clones the pinned tag and builds from source instead of downloading).\n\n2. `distributed` for operators who want the daemon and GUI client installed\n  separately, including split-machine setups.\n  ```bash\n  ./deployment/install_distributed.sh --role daemon\n  ./deployment/install_distributed.sh --role gui-client\n  ```\n\nThe manual and Docker paths below are still useful developer/operator\ninstallation flows.\n\n### Docker (Recommended)\n\n**GUI Mode:**\n```bash\nxhost +local:docker \u0026\u0026 docker compose run --rm airunner\n```\n\n**Headless API Server:**\n```bash\ndocker compose run --rm --service-ports airunner --headless\n```\n\n\u003e **Note:** `--service-ports` is required to expose the container's published port (8080), which maps to the headless daemon's HTTP API.\n\nTo trim container dependencies for a specific deployment, rebuild with a\nprofile list such as:\n\n```bash\ndocker build \\\n  --build-arg AIRUNNER_INSTALL_PROFILES=core,llm-native,stt-native \\\n  -t airunner:headless .\n```\n\nThe container publishes the headless daemon's HTTP API on port 8080 with endpoints:\n- `GET /health` - Health check and service status\n- `POST /llm` - LLM inference\n- `POST /art` - Image generation\n\n### Advanced Python Installation (Ubuntu/Debian)\n\nUse this path when you want to assemble the environment manually instead of\nusing `./scripts/install.sh` for repo development or\n`./deployment/install_distributed.sh` for managed daemon and GUI-client\ninstalls.\n\n**Python 3.13+ required.** We recommend using `pyenv` and `venv`.\n\n1. **Install system dependencies:**\n   ```bash\n   sudo apt update \u0026\u0026 sudo apt install -y \\\n     build-essential cmake git curl wget pkg-config \\\n     nvidia-cuda-toolkit pipewire libportaudio2 libxcb-cursor0 \\\n     espeak espeak-ng-espeak qt6-qpa-plugins qt6-wayland \\\n     libsentencepiece-dev \\\n     mecab libmecab-dev mecab-ipadic-utf8 libxslt-dev mkcert\n   ```\n\n2. **Create data directory:**\n   ```bash\n   mkdir -p ~/.local/share/airunner\n   ```\n\n3. **Choose the package profiles you need:**\n\n   - `llm-native`: local llama.cpp runtime and LLM toolchain\n   - `stt-native`: local STT runtime helpers\n   - `art-python`: Python image-generation runtimes\n   - `tts-python`: Python TTS runtimes without MeCab-backed language packs\n   - `headless`: aggregate of the four runtime extras above (`llm-native`,\n     `stt-native`, `art-python`, `tts-python`)\n   - `development`: test, lint, and packaging tooling\n   - `openvoice_jp` / `openvoice_kr`: MeCab-backed Japanese and Korean voice packs\n\n   All of the runtime profiles above live on the `airunner-services` package.\n   The desktop GUI ships in the root `airunner` package, which pulls in\n   `airunner-services==6.1.3` automatically (issue #2037). The optional\n   `airunner-native[gui]` extra provides the native launcher and bundle\n   tooling.\n\n4. **Install AI Runner:**\n\n   The published packages are `airunner` (desktop GUI), `airunner-services`\n   (headless daemon, API server, and model runtimes), `airunner-native`\n   (optional native launcher), and `airunner-common` (shared metadata). The\n   `airunner` package itself only ships `analysis`, `ml`, and `development`\n   extras; all model runtimes live in the `airunner-services` extras (issues\n   #2039/#2040).\n\n   From PyPI (full GUI install):\n   ```bash\n   # torch family pinned to the CUDA 12.9 wheel line (issues #2036/#2041)\n   pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu129\n   # Desktop GUI; pulls in airunner-services==6.1.3 automatically\n   pip install \"airunner\"\n   # Model runtimes (LLM, STT, art, TTS); `headless` aggregates the four extras\n   pip install \"airunner-services[headless]\"\n   # Optional: native launcher and bundle tooling (also pulls the GUI)\n   pip install \"airunner-native[gui]\"\n   ```\n\n   For a headless-only install (no GUI), install the services package with the\n   runtimes you need:\n   ```bash\n   pip install \"airunner-services[headless]\"\n   ```\n\n   From a local clone in editable mode:\n   ```bash\n   git clone https://github.com/Capsize-Games/airunner.git\n   cd airunner\n   python -m venv venv\n   source venv/bin/activate\n   pip install --upgrade pip setuptools wheel\n   # The pinned torch line (2.13.0+cu129) requires setuptools\u003e=77.0.3 with no\n   # setuptools\u003c82 upper bound, so the latest setuptools is safe for `pip check`\n   # (issue #2057). Older torch wheels (e.g. some 2.11.x) still declare\n   # `setuptools\u003c82`; if you use one, `pip install \"setuptools\u003c82\"` first.\n   pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu129\n   # airunner-common moved to its own repository and resolves from PyPI\n   # now (issue #2197, https://github.com/Capsize-Games/airunner-common)\n   # via services/native's own declared dependency -- no local install\n   # step needed for it anymore.\n   pip install -e \"./services[headless,development]\"\n   pip install -e ./native\n   pip install -e .\n   ```\n\n  The base `tts-python` profile intentionally excludes the MeCab-backed\n  Japanese and Korean voice packs so a fresh virtual environment can install\n  without extra native build steps.\n\n  To include those language packs after installing the system packages above, use:\n  ```bash\n  pip install -e \"./services[openvoice_jp,openvoice_kr]\"\n  ```\n\n5. **Install llama-cpp-python with CUDA (Python 3.13, Linux):**\n  ```bash\n  pip install --no-cache-dir \\\n    --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu124 \\\n    \"llama-cpp-python==0.3.21\"\n  ```\n  - This is the verified runtime for `Qwen3.5-9B-Q8_0.gguf` in this repo.\n  - The `cu124` wheel enables GPU offload on Linux without rebuilding from source.\n  - If you must build from source for an RTX 5080 / compute capability 12.0, use CUDA toolkit 12.8+ and `GGML_CUDA_ARCHITECTURES=120`.\n\n6. **Run:**\n   ```bash\n   airunner\n   ```\n\n### Alembic Upgrades\n\nWhen you need to run database migrations manually from a local clone, use the\nrepo Alembic config and upgrade all heads:\n\n```bash\nsource venv/bin/activate\nalembic -c src/airunner/alembic.ini upgrade heads\n```\n\nIf you are targeting a non-default database, set `AIRUNNER_DATABASE_URL`\nbefore running the command.\n\nFor detailed instructions, see the [Installation Wiki](https://github.com/Capsize-Games/airunner/wiki/Installation-instructions).\n\n## Hybrid Runtime Migration\n\nThe hybrid-runtime rewrite is being delivered in explicit phases: runtime\nfoundation, LLM cutover, STT isolation, art/TTS isolation, then packaging,\nbundles, CI, and rollout hardening. The phase order, rollout gates, and full\nissue-tree checklist live in [HYBRID_RUNTIME_MIGRATION.md](./HYBRID_RUNTIME_MIGRATION.md).\n\nAIRunner ships as a Python application with one primary `airunner` entry\npoint.\n\n---\n\n## 🤖 Models\n\nAI Runner downloads essential TTS/STT models automatically. LLM and image models must be configured:\n\n| Category | Model | Size |\n|----------|-------|------|\n| **LLM (default)** | Qwen3.5-9B, GGUF `Q8_0` | ~12 GB VRAM |\n| **Image** | Stable Diffusion 1.5 | ~2 GB |\n| **Image** | Z-Image Turbo | ~12 GB |\n| **TTS** | OpenVoice | 654 MB |\n| **STT** | `Systran/faster-distil-whisper-large-v3` | — |\n\nLocal LLM inference runs GGUF through a llama.cpp sidecar; `airunner-hf-download`\nfetches GGUF by default and `--full` gets safetensors instead. Ten bundled models\nship a GGUF variant, and \"Custom Local Path\" points at your own file.\n\n**LLM Providers:** Local (GGUF / llama.cpp), Ollama, OpenRouter, OpenAI\n\n**Art Models:** Place your models in `~/.local/share/airunner/art/models/`\n\n---\n\n## 🛠️ CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `airunner` | Launch GUI |\n| `airunner-headless` | Start headless API server |\n| `airunner-hf-download` | Download/manage models from HuggingFace |\n| `airunner-civitai-download` | Download models from CivitAI |\n| `airunner-build-ui` (dev) | Rebuild UI from `.ui` files (`python scripts/build_ui.py`) |\n| `airunner-tests` (dev) | Run test suite (`python scripts/run_tests.py`) |\n| `airunner-generate-cert` | Generate SSL certificate |\n\n**Note:** To download models, use *Tools → Download Models* from the main\napplication menu. The GUI now opens a filtered CivitAI browser for Z-Image\nTurbo models and queues downloads through the local daemon. You\ncan also use `airunner-hf-download` / `airunner-civitai-download` from the\ncommand line.\n\n### Rebuilding Qt UI Files\n\nWhen you change any `.ui` file in a local clone, rebuild the generated\n`*_ui.py` files from the repo root with:\n\n```bash\nsource venv/bin/activate\npython scripts/build_ui.py\n```\n\nIf you installed AIRunner's dev console scripts, `airunner-build-ui` runs the\nsame rebuild; from a source checkout use `python scripts/build_ui.py`.\n\nThis rebuild also refreshes the Qt resources and generated stylesheet\nassets.\n\n---\n\n## 🖥️ Headless Server\n\nAI Runner can run as a headless HTTP API server, enabling remote access to LLM, image generation, TTS, and STT capabilities. This is useful for:\n\n- Running AI services on a remote server\n- Integration with other applications via REST API\n- VS Code integration as an Ollama/OpenAI replacement\n- Automated pipelines and scripting\n\n### Quick Start\n\n```bash\n# Start with defaults (port 8080, LLM only)\nairunner-headless\n\n# Start with a specific LLM model\nairunner-headless --model \"/path/to/Qwen2.5-7B-Instruct-4bit\"\n\n# Run as Ollama replacement for VS Code (port 11434)\nairunner-headless --ollama-mode\n\n# Don't preload models - load on first request\nairunner-headless --no-preload\n```\n\n### Command Line Options\n\n| Option | Description |\n|--------|-------------|\n| `--host HOST` | Host address to bind to (default: `127.0.0.1`) |\n| `--port PORT` | Port to listen on (default: `8080`, or `11434` in ollama-mode) |\n| `--ollama-mode` | Run as Ollama replacement on port 11434 |\n| `--insecure-no-auth` | Allow binding to non-loopback without `AIRUNNER_API_KEY` (not recommended) |\n| `--model, -m PATH` | Path to LLM model to load. Also enables the LLM service. Quote paths that contain spaces. |\n| `--art-model PATH` | Path to Stable Diffusion model to load. Also enables the art service. Quote paths that contain spaces. |\n| `--tts-model PATH` | Path to TTS model to load. Also enables the TTS service. Quote paths that contain spaces. |\n| `--stt-model PATH` | Path to STT model to load. Also enables the STT service. Quote paths that contain spaces. |\n| `--enable-llm` | Enable LLM service |\n| `--enable-art` | Enable Stable Diffusion/art service |\n| `--enable-tts` | Enable TTS service |\n| `--enable-stt` | Enable STT service |\n| `--no-preload` | Don't preload models at startup |\n\n### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `AIRUNNER_LLM_MODEL_PATH` | Path to LLM model |\n| `AIRUNNER_ART_MODEL_PATH` | Path to art model |\n| `AIRUNNER_TTS_MODEL_PATH` | Path to TTS model |\n| `AIRUNNER_STT_MODEL_PATH` | Path to STT model |\n| `AIRUNNER_API_KEY` | If set, requires auth for API requests and docs (`X-API-Key` / `Authorization: Bearer`) |\n| `AIRUNNER_INSECURE_NO_AUTH` | Set to `1` to allow unauthenticated remote access (not recommended) |\n| `AIRUNNER_ALLOWED_TENANT_KEYS` | Comma-separated allowlist for `X-Tenant-Key` when API key auth is enabled |\n| `AIRUNNER_DEBUG` | Set to `1` to include exception details in 500s for loopback requests |\n| `AIRUNNER_NO_PRELOAD` | Set to `1` to disable model preloading |\n| `AIRUNNER_LLM_ON` | Enable LLM service (`1` or `0`) |\n| `AIRUNNER_SD_ON` | Enable Stable Diffusion (`1` or `0`) |\n| `AIRUNNER_TTS_ON` | Enable TTS service (`1` or `0`) |\n| `AIRUNNER_STT_ON` | Enable STT service (`1` or `0`) |\n| `AIRUNNER_BASE_PATH` | Data directory (default: `~/.local/share/airunner`) |\n| `AIRUNNER_DATABASE_URL` | Database URL override (default: `sqlite:///\u003cbase\u003e/data/airunner.db`, or `airunner.dev.db` when `DEV_ENV=1`) |\n| `AIRUNNER_DB_NAME` | Database filename (default: `airunner.db`, or `airunner.dev.db` when `DEV_ENV=1`) |\n| `AIRUNNER_HEADLESS` | Set to `1` to run headless (daemon) mode without the GUI |\n| `AIRUNNER_DAEMON_CONFIG` | Path to a daemon YAML config file to load/override defaults |\n| `AIRUNNER_HTTP_HOST` | Host the headless daemon binds to (default: `127.0.0.1`) |\n| `AIRUNNER_HTTP_PORT` | Port the headless API listens on (`airunner-headless` default: `8080`; the daemon-config default is `8188`; the container publishes `8080` → daemon) |\n| `AIRUNNER_LNA_ENABLED` | Set to `1` to enable LNA (local network access) mode for the local server |\n| `DEV_ENV` | Set to `1` to load a local `.env` file and use development defaults (default: `0`) |\n| `AIRUNNER_LOG_LEVEL` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` (default: `INFO`) |\n| `AIRUNNER_LOG_FILE` | Log file path (default: `\u003cbase\u003e/airunner.log`) |\n| `AIRUNNER_SAVE_LOG_TO_FILE` | Set to `1` to write logs to `AIRUNNER_LOG_FILE` |\n| `AIRUNNER_DISABLE_SETUP_WIZARD` | Set to `1` to skip the first-run setup wizard |\n| `AIRUNNER_LOCAL_FILES_ONLY` | Set to `0` to allow file paths outside the data directory (default: `1`) |\n| `AIRUNNER_ART_ENABLED` | Enable the art service (default: `1`) |\n| `AIRUNNER_LLM_USE_WEATHER_PROMPT` | Enable weather prompts in LLM context (default: `1`) |\n| `AIRUNNER_LLM_OPENROUTER_MODEL` | Default OpenRouter model id (default: `mistralai/mistral-7b-instruct:free`) |\n| `AIRUNNER_DISABLE_FACEHUGGERSHIELD` | Set to `1` to disable the facehuggershield download guard |\n| `AIRUNNER_DISABLE_FLASH_ATTENTION` | Set to `1` to disable flash attention |\n| `LOCAL_SERVER_HOST` | Host for the local static content server (default: `127.0.0.1`) |\n| `LOCAL_SERVER_PORT` | Port for the local static content server (default: `5005`) |\n| `QTWEBENGINE_REMOTE_DEBUGGING` | Set to a port (e.g. `9223`) to enable QtWebEngine remote debugging |\n\n### API Endpoints\n\n#### Native AIRunner Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/health` | Health check and service status |\n| POST | `/llm` | LLM text generation (streaming) |\n| POST | `/llm/generate` | LLM text generation |\n| POST | `/art` | Image generation |\n| POST | `/tts` | Text-to-speech |\n| POST | `/stt` | Speech-to-text |\n\n#### Ollama-Compatible Endpoints (port 11434)\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/api/tags` | List available models |\n| GET | `/api/version` | Get version info |\n| GET | `/api/ps` | List running models |\n| POST | `/api/generate` | Text generation |\n| POST | `/api/chat` | Chat completion |\n| POST | `/api/show` | Show model info |\n\n#### OpenAI-Compatible Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/v1/models` | List models |\n| POST | `/v1/chat/completions` | Chat completion with tool support |\n\n### Example: LLM Request\n\n```bash\ncurl -X POST http://localhost:8080/llm \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"prompt\": \"What is the capital of France?\",\n    \"stream\": true,\n    \"temperature\": 0.7,\n    \"max_tokens\": 100\n  }'\n```\n\n### Example: Image Generation (Art)\n\n```bash\n# Requires: airunner-headless --enable-art\ncurl -X POST http://localhost:8080/art \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"prompt\": \"A beautiful sunset over mountains\",\n    \"negative_prompt\": \"blurry, low quality\",\n    \"width\": 512,\n    \"height\": 512,\n    \"steps\": 20,\n    \"seed\": 42\n  }'\n# Returns: {\"images\": [\"base64_png_data...\"], \"count\": 1, \"seed\": 42}\n```\n\n### Example: Text-to-Speech (TTS)\n\n```bash\n# Requires: airunner-headless --enable-tts\ncurl -X POST http://localhost:8080/tts \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"text\": \"Hello, world!\"}'\n# Returns: {\"status\": \"queued\", \"message\": \"Text queued for speech synthesis\"}\n# Audio plays through system speakers\n```\n\n### Example: Speech-to-Text (STT)\n\n```bash\n# Requires: airunner-headless --enable-stt\n# Audio must be base64-encoded WAV (16kHz mono recommended)\ncurl -X POST http://localhost:8080/stt \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"audio\": \"UklGRi4AAABXQVZFZm10IBAAAAABAAEA...\"}'\n# Returns: {\"transcription\": \"Hello world\", \"status\": \"success\"}\n```\n\n### Example: Ollama Mode with VS Code\n\n1. Start the headless server in Ollama mode:\n   ```bash\n  airunner-headless --ollama-mode --model \"/path/to/your/model\"\n   ```\n\nIf a model path contains spaces, quote it. For example:\n```bash\nairunner-headless --enable-art --art-model \"~/.local/share/airunner/art/models/Z-Image Turbo/txt2img/moodyRealMix_zitV3FP8.safetensors\"\n```\n\n2. Configure VS Code Continue extension to use `http://localhost:11434`\n\n3. The server will respond to Ollama API calls, allowing seamless integration.\n\n### Auto-Loading Models\n\nWhen `--no-preload` is used, models are automatically loaded on the first request to the corresponding endpoint. This is useful for:\n\n- Reducing startup time\n- Running multiple services without loading all models upfront\n- Memory-constrained environments\n\n---\n\n## 📦 Model Management\n\n### Download Models\n\n```bash\n# List available models\nairunner-hf-download\n\n# List only LLM models\nairunner-hf-download list --type llm\n\n# Download a model (GGUF by default)\nairunner-hf-download qwen3-8b\n\n# Download full safetensors version\nairunner-hf-download --full qwen3-8b\n\n# Download any HuggingFace model\nairunner-hf-download Qwen/Qwen3-8B\n\n# List downloaded models\nairunner-hf-download --downloaded\n```\n\n### Delete Models\n\n```bash\n# Delete a model (with confirmation)\nairunner-hf-download --delete Qwen3-8B\n\n# Delete without confirmation (for scripts)\nairunner-hf-download --delete Qwen3-8B --force\n```\n\n### Download from CivitAI\n\n```bash\n# Download a model from CivitAI URL\nairunner-civitai-download https://civitai.com/models/995002/70s-sci-fi-movie\n\n# Download a specific version\nairunner-civitai-download https://civitai.com/models/995002?modelVersionId=1880417\n\n# Download to a custom directory\nairunner-civitai-download \u003curl\u003e --output-dir /path/to/models\n\n# Use API key for authentication (for gated models)\nairunner-civitai-download \u003curl\u003e --api-key your_api_key\n\n# Or set CIVITAI_API_KEY environment variable\nexport CIVITAI_API_KEY=your_api_key\nairunner-civitai-download \u003curl\u003e\n```\n\n---\n\n## 🔒 HTTPS Configuration\n\nAI Runner's local server uses HTTPS by default. Certificates are auto-generated in `~/.local/share/airunner/certs/`.\n\nFor browser-trusted certificates, install [mkcert](https://github.com/FiloSottile/mkcert):\n```bash\nsudo apt install libnss3-tools\nmkcert -install\n```\n\n---\n\n## ⚖️ Colorado AI Act Notice\n\n**Effective February 1, 2026**, the [Colorado AI Act (SB 24-205)](https://leg.colorado.gov/bills/sb24-205) regulates high-risk AI systems.\n\n**Your Responsibility:** If you use AI Runner for decisions with legal or significant effects on individuals (employment screening, loan eligibility, insurance, housing), you may be classified as a **deployer of a high-risk AI system** and must:\n- Implement a risk management policy\n- Complete impact assessments\n- Provide consumer notice and appeal mechanisms\n- Report algorithmic discrimination to the Colorado Attorney General\n\n**AI Runner's Design:** AI Runner is designed with privacy as a core principle—it runs entirely locally with no external data transmission by default. However, certain optional features connect to external services:\n\n- **Model Downloads:** Connecting to HuggingFace or CivitAI to download models\n- **Web Search / Deep Research:** Search queries sent to DuckDuckGo; web pages scraped for research\n- **Weather Prompt:** Location coordinates sent to Open-Meteo API if enabled\n- **External LLM Providers:** Prompts sent to OpenRouter or OpenAI if configured\n\n**We recommend using a VPN** when using features that connect to external services. See our full [Privacy Policy](src/airunner/components/downloader/gui/windows/setup_wizard/user_agreement/privacy_policy.md) for details.\n\n---\n\n## 🛡️ Content Safety\n\nAI Runner includes a best-effort content-safety filter for prohibited content.\nIt is defense-in-depth, not a guarantee — see [SECURITY.md](SECURITY.md) for the\nfull behavior.\n\nThe policy data file\n[`services/src/airunner_services/content_safety/data/policy_terms.dat`](services/src/airunner_services/content_safety/data/policy_terms.dat)\nships **empty by design** so that no policy terms are committed to the\nrepository. With no policy data loaded, the input-side filter is inactive and\nprompts pass through.\n\n**Distributor responsibility:** anyone who packages or distributes the\napplication must generate the policy list before distributing, so the shipped\nbuild includes it. Until then, the input-side filter is inactive.\n\nTo generate the list, curate a plaintext terms list kept **outside** the\nrepository (for example under the gitignored `tmp/` directory — do not commit\nit), then run:\n\n```bash\nvenv/bin/python scripts/build_policy_terms.py --input tmp/policy_terms_source.txt\n```\n\nThis writes only the hashed data file; include only that generated file in the\ndistributed build. Operators can point at a different data file by setting the\n`AIRUNNER_CONTENT_SAFETY_DATA` environment variable.\n\n---\n\n## 🧪 Testing\n\n```bash\n# General repo validation\n./venv/bin/python scripts/run_tests.py --unit\n./venv/bin/python scripts/run_tests.py --llm-runtime-smoke\n./venv/bin/python scripts/run_tests.py --stt-runtime-smoke\n./venv/bin/python scripts/run_tests.py --art-runtime-smoke\n./venv/bin/python scripts/run_tests.py --tts-runtime-smoke\n\n# API bootstrap and runtime wiring\n./venv/bin/python -m pytest services/tests/test_service_bootstrap.py -v\n./venv/bin/python -m pytest services/tests/test_tts_runtime_load.py -v\n\n# Real daemon-backed functional tests\n./venv/bin/python -m pytest services/tests/test_tts_synthesize_functional.py -v --timeout=120\n./venv/bin/python -m pytest services/tests/test_llm_functional.py -v --timeout=900\n./venv/bin/python -m pytest services/tests/test_llm_tts_functional.py -v --timeout=1200\n./venv/bin/python -m pytest services/tests/test_stt_transcribe_functional.py -v --timeout=1200\n\n# Offscreen GUI end-to-end functional tests\n./venv/bin/python -m pytest services/tests/test_gui_llm_tts_functional.py -v --timeout=1200\n./venv/bin/python -m pytest services/tests/test_gui_stt_llm_tts_functional.py -v --timeout=1200\n\n```\n\nAgent evals moved to their own repository:\n[Capsize-Games/airunner-eval](https://github.com/Capsize-Games/airunner-eval).\n\nThe functional suites under `services/tests/` use real local runtimes and skip\ncleanly when required assets are missing. They cover API bootstrap,\ndaemon-only LLM, daemon LLM plus TTS, standalone STT, standalone TTS,\noffscreen GUI LLM plus TTS, offscreen GUI STT plus LLM plus TTS, and the\nGUI conversation-progression path.\n\nThe service-owned agent eval runbook lives in\n`docs/agent-eval-tests.md` and documents coverage, commands, tool\nsurfaces, and current model notes.\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) and the [Development Wiki](https://github.com/Capsize-Games/airunner/wiki/Development).\n\n## Documentation\n\n- [Wiki](https://github.com/Capsize-Games/airunner/wiki)\n- [Layered Product Architecture](docs/architecture/layered_product_architecture.md)\n- [Package Split Contract](docs/architecture/package_split_contract.md)\n- [API and Model Extraction Plan](docs/architecture/api_model_extraction_plan.md)\n- [Deliverable-First Workflows](docs/deliverable_workflows.md)\n- [Hybrid Runtime Target](docs/hybrid-runtime-target.md)\n- [Agent Eval Tests](docs/agent-eval-tests.md)\n- [LLM Flow](docs/llm-flow.md)\n- [Document RAG Flow](docs/document-rag-flow.md)\n- [Systemd Distributed Deployment](deployment/systemd/README.md)\n- [Architecture Complexity Audit](docs/architecture/architecture-complexity-audit.md)\n- [API Service Layer](src/airunner/components/application/api/README.md)\n- [Services Package README](services/README.md)\n- [Src Package README](src/README.md)\n- [Native Package README](native/README.md)\n- [Scripts README](scripts/README.md)\n\n---\n\n\u003ca href=\"https://airunner.art\"\u003e\n   \u003cimg src=\"./images/logo.png\" alt=\"AI Runner Logo\" width=\"100\"/\u003e\n\u003c/a\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcapsize-games%2Fairunner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcapsize-games%2Fairunner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcapsize-games%2Fairunner/lists"}