Installation

Quick Install

The install script auto-detects uv, pipx, or pip (and installs uv if none are found):

curl -fsSL https://initrunner.ai/install.sh | sh

This installs initrunner[recommended] (search + ingest + dashboard) by default.

Install with specific extras

curl -fsSL https://initrunner.ai/install.sh | sh -s -- --extras ingest

Pin a specific version

curl -fsSL https://initrunner.ai/install.sh | sh -s -- --version 1.0.0

Package Managers

uv tool install initrunner
pipx install initrunner
pip install initrunner

Note: On modern Linux (Python 3.11+), bare pip install outside a virtual environment will fail due to PEP 668. Use uv, pipx, or create a venv first.

Docker

Note: The Docker image ships with all extras pre-installed — no need to specify extras when using Docker.

Pull and run in one command:

docker run --rm -e OPENAI_API_KEY vladkesler/initrunner:latest --version

Or use Docker Compose for the full dashboard:

curl -O https://raw.githubusercontent.com/vladkesler/initrunner/main/docker-compose.yml
docker compose up -d

Build locally with custom extras:

docker build -t initrunner .
docker build --build-arg EXTRAS="dashboard,anthropic" -t initrunner-custom .

If using Ollama on the host from inside a container, set base_url: http://host.docker.internal:11434/v1 in your role YAML.

See Docker for full Docker documentation.

Cloud Deploy

Deploy the dashboard to a cloud platform with one click — no local Docker required:

• Railway — Deploy button, auto-builds from railway.json
• Render — Deploy button, Blueprint provisions a 1 GB persistent disk
• Fly.io — CLI-based deploy with fly launch and fly deploy

All platforms seed example roles on first boot and expose the dashboard. See Cloud Deploy for full instructions.

Extras

Tip: Not sure which extras you need? Install [recommended] — it includes search, ingestion, and the dashboard so the most common workflows just work out of the box. Use [all] if you want every provider and feature.

Install recommended extras (default)

# pip
pip install "initrunner[recommended]"

# uv
uv tool install "initrunner[recommended]"
# or in a venv:
uv pip install "initrunner[recommended]"

# pipx
pipx install "initrunner[recommended]"

# shell installer (defaults to [recommended])
curl -fsSL https://initrunner.ai/install.sh | sh

Install all extras

pip install "initrunner[all]"
uv tool install "initrunner[all]"
curl -fsSL https://initrunner.ai/install.sh | sh -s -- --extras all

Pick and choose

You can combine specific extras with commas:

# pip
pip install "initrunner[ingest,search,dashboard]"

# uv
uv tool install "initrunner[ingest,search,dashboard]"

# pipx
pipx install "initrunner[ingest,search,dashboard]"

# shell installer (comma-separated)
curl -fsSL https://initrunner.ai/install.sh | sh -s -- --extras ingest,search,dashboard

Available extras

Bundles

LLM Providers

Features

Messaging Triggers

Interfaces

Note: local-embeddings (fastembed) is defined but not yet implemented. Use the ollama provider instead for local embeddings — see Providers.

Development Setup

git clone https://github.com/vladkesler/initrunner.git
cd initrunner
uv sync
uv run pytest tests/ -v
uv run ruff check .
uv run initrunner --version

Environment Variables

By default, InitRunner stores data in ~/.initrunner/. Override with INITRUNNER_HOME:

export INITRUNNER_HOME=/data/initrunner
initrunner run role.yaml -p "hello"

Or, to persist across sessions, add it to ~/.initrunner/.env:

INITRUNNER_HOME=/data/initrunner

Resolution order: INITRUNNER_HOME > XDG_DATA_HOME/initrunner > ~/.initrunner.

Platform Notes

• Python 3.11+ is required (3.11, 3.12, and 3.13 are tested).
• Linux / macOS / WSL are fully supported.
• Windows works but systemd-related flow features (flow install/start/stop) are unavailable.
• Docker: if using Ollama on the host from inside a container, set base_url: http://host.docker.internal:11434/v1 in your role YAML.