AI Runner: a self-hosted companion and art canvas from Capsize-Games

What AI Runner is for, and who it is actually aimed at

AI Runner is an offline inference engine packaged as a desktop application. The README frames it as two interlocking experiences: a companion you name, give a personality and a voice, and let accumulate memory across sessions, and a layered canvas where you sketch, generate, filter and composite images. Both run on your hardware. The README states that neither experience requires an internet connection, an API key, or a subscription, and that conversations, memories and personality stay on the machine.

The target user is not a backend engineer wiring an inference endpoint into a service. It is someone who wants Stable Diffusion and a local LLM in one window, with a drawing surface attached. The topics list confirms the shape: desktop-app, pygame, pyside6, self-hosted, privacy. The system requirements table points the same way. Minimum is an NVIDIA RTX 3060 with 16 GB of RAM; recommended is an RTX 5080 with 32 GB. Storage is listed as 22 GB to 100 GB or more, SSD recommended. That is a workstation-class footprint, not a laptop you happen to have.

The daemon, the GUI, and the native sidecars

The repository is split into four Python packages, and the README's flowchart shows how they connect. A native launcher sits at the top and starts both the GUI in src/ and the headless daemon in services/. The daemon exposes a FastAPI server and a runtime registry, and it owns orchestration, downloads and persistence. Both the GUI and the daemon talk to the same data directory, referenced as AIRUNNER_BASE_PATH.

The interesting part is the sidecars. The flowchart labels them llama.cpp and whisper.cpp sidecars, and the install script builds them under build/runtime-sidecars/linux/. So the LLM and speech-to-text paths are not Python libraries called in-process. They are compiled native binaries that the daemon and GUI reach out to. That choice explains the CUDA flag in the installer and the Dockerfile's AIRUNNER_INSTALL_PROFILES argument, which lists profiles such as llm-native, stt-native, art-python and tts-python. Image generation and text-to-speech stay in Python; LLM and STT go native.

This is a heavier architecture than a single-process Gradio app, and it buys the split-machine deployment described in the README, where the daemon and the GUI client install separately. It also means the daemon can serve a headless HTTP API on port 8080, which the docker-compose file documents as requiring --service-ports.

Installing AI Runner and generating a first image

The README gives two install paths. The dev path is for contributors working from a repository checkout. It reuses ./venv by default, installs the Python packages in editable mode, and builds the pinned llama.cpp and whisper.cpp sidecars. Run it from the repository root:

./scripts/install.sh

The README notes that rerunning the command reuses the existing environment instead of recreating it, and refreshes the local editable installs without re-solving the full dependency graph. Two flags are documented: --refresh-deps for a full dependency refresh, and --sidecars-cuda for CUDA-enabled native sidecars. If you have an NVIDIA card, you want the second one.

The distributed path is for operators who want the daemon and the GUI client installed separately, including split-machine setups:

./deployment/install_distributed.sh --role daemon
./deployment/install_distributed.sh --role gui-client

There is also a Docker route. The compose file documents two modes, and the headless one needs --service-ports so port 8080 is reachable:

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

The compose file mounts ~/.local/share/airunner and ~/.cache/huggingface from your home directory, so models and the database survive container restarts. It runs the container as your host UID and GID, and the README of that file says to copy .env.example to .env and set UID, GID, XDG_RUNTIME_DIR and XAUTHORITY if your UID is not 1000. For X11 permission errors it gives one command: xhost +SI:localuser:$USER.

After install, the first real use is the art canvas. The README lists SDXL and Z-Image Turbo as the image models, with LoRA, embeddings, image-to-image, inpainting, post-process filters and background removal. The built-in HuggingFace and Civitai downloaders are how models arrive, since nothing ships with weights. Expect the download and the sidecar build to dominate the first hour, not the pip install.

Where AI Runner gets in your way

The platform support is the first constraint. The README's requirement table marks Windows with an asterisk and the note below it says Windows support is experimental and community-maintained, while Linux is the primary supported platform. If your team is on Windows, you are on the unmaintained edge of this project.

Language coverage is uneven in a way that matters. The README's language table shows English with TTS, LLM, STT and GUI all supported. Japanese has TTS, LLM and GUI but no STT. Spanish, French, Chinese and Korean have TTS and LLM only, with no STT and no GUI. So a Spanish-speaking user can hear the companion but cannot speak to it, and the interface will not be in Spanish.

The dependency constraints are unusually tight. The pyproject.toml build-system section pins setuptools to >=80.9.0,<82 with a comment explaining that the torch==2.13.0+cu129 wheel's runtime metadata requires setuptools below 82, and that bumping past it breaks pip check. The GUI requirements in setup.py pin PySide6 to exactly 6.9.0 across three packages. If you are trying to fold AI Runner into an existing environment with a different PySide6 or a newer setuptools, you will be fighting the resolver.

Finally, the mypy configuration in pyproject.toml is explicitly a non-strict baseline. It sets follow_imports to skip, disallow_untyped_defs to false, and lists a graduation target of stricter flags as annotation coverage improves. That is a candid description of a codebase that is not fully typed, and it tells you something about how much static checking you can expect on the Python side.

AI Runner against a plain Stable Diffusion WebUI setup

The obvious comparison is Automatic1111's Stable Diffusion WebUI or ComfyUI. Those are browser-fronted image generators. You open a tab, type a prompt, get a picture. They do not ship a companion with persistent memory, they do not do text-to-speech, and they do not run a daemon that a separate client connects to.

AI Runner's difference is the companion layer and the memory model. The README describes long-term memory built from your conversations with RAG-powered recall, plus awareness of time, date and local weather. That is a stateful application, not a generation endpoint. The layered canvas is a second difference: it is a drawing surface where you sketch and then convert the sketch to an image, rather than a prompt box that happens to have an img2img tab.

The trade-off runs the other way too. ComfyUI's node graph is more expressive for complex pipelines than a fixed canvas with filters. A WebUI install is typically a single Python environment without compiled sidecars. AI Runner asks for more disk, more build time, and a specific GPU vendor. If you only want text-to-image, the extra machinery is overhead you will notice on every install.

Maintenance, releases, and what the licence situation looks like

The repository is not archived, and the last push was on 2026-09-06, the same day as the v6.0.5 release. The release cadence visible in the repository is tight: v6.0.3 and v6.0.4 both landed on 2026-08-29, and v6.0.5 followed on 2026-09-06. That is three releases in roughly a week, which suggests active work but also a fast-moving surface where a pinned dependency can shift under you.

Upgrade cost is real here. The sidecars are compiled from pinned llama.cpp and whisper.cpp sources, so a version bump can mean a rebuild, not just a pip install. The install script's --refresh-deps flag exists precisely because the default rerun deliberately avoids re-solving the full dependency graph. The setuptools ceiling tied to the torch wheel is the kind of constraint that will bite when you try to move any other package forward.

On licensing, the signals conflict and the repository does not resolve them. The repository metadata reports the licence as NOASSERTION, while the README badge and the badge link point to GPL v3. There is a LICENSE file at the repository root and a THIRD_PARTY_NOTICES.md, but their contents are not shown in the README. If you plan to redistribute AI Runner or ship it inside a product, read LICENSE and THIRD_PARTY_NOTICES.md yourself before you build anything on top of it. This is not legal advice, and the discrepancy is exactly the kind of thing a lawyer should see rather than an engineer guessing.

Editorial conclusion

Adopt AI Runner if you want a companion with persistent memory and a layered art canvas on local hardware, you are comfortable on Ubuntu 22.04, and you have an NVIDIA GPU with 16 GB of RAM or more. Do not adopt it if you need Windows as a first-class target (the README calls Windows support experimental and community-maintained), if you rely on STT for Japanese, Spanish, French, Chinese or Korean, or if you want a headless API without the PySide6 GUI stack. Before committing, check the LICENSE file yourself, since the repository metadata reports NOASSERTION while the README badge says GPLv3, and run ./scripts/install.sh on a machine with the recommended storage headroom, because the sidecar build and model downloads are the slow part.

Frequently asked questions

Official sources

1. Capsize-Games/airunner on GitHub
2. Issues
3. Project website
4. README
5. Releases