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, vector store, MCP, 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[recommended]"
pipx install "initrunner[recommended]"
pip install "initrunner[recommended]"

Drop the [recommended] to get the core install instead. See What to install for the four names that cover it.

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.

Core install

Since v2026.8.9, the bare package is the agent runtime and nothing optional: OpenAI and Ollama models, every built-in tool that needs no extra dependency, triggers, flows, teams, groups, and the OpenAI-compatible --serve API.

What it leaves out is MCP and the vector store, which together are about a third of a running agent's memory. Reach for it when you are packing many agents onto one box:

pip install initrunner
uv tool install initrunner
curl -fsSL https://initrunner.ai/install.sh | sh -s -- --extras none

A role that uses type: mcp, memory:, ingest:, or the web_scraper tool still validates in a core install, so initrunner validate and every editor, dashboard, and wizard behave the same everywhere. It fails when you load the agent, and since v2026.8.11 the error offers to fix itself:

Error: 'lancedb' is required: initrunner[vector]
Install now? [Y/n]

To add them ahead of time:

uv pip install "initrunner[mcp,vector]"
uv tool install "initrunner[recommended]"   # or re-run the install script

initrunner doctor --fix --role agent.yaml installs whatever that role asks for. See Missing something? for when InitRunner installs for you and when it just prints the command.

initrunner run with no role file is the one case with no role to inspect: it turns persistent memory on by default, so it wants the vector extra. Since v2026.8.10 it stops at load and offers --no-memory as the way through without installing anything.

Docker

Note: The :latest image ships with all extras pre-installed, so there is nothing to choose when using Docker. Since v2026.8.9 there is also a :slim tag, the core runtime plus the dashboard at 308 MB against 1.07 GB. See Docker.

Pull and run in one command:

docker run --rm vladkesler/initrunner:latest initrunner --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.

What to install

Four names cover it. Everything else in pyproject.toml is there for packagers and for doctor --fix; since v2026.8.11 the docs no longer ask you to learn the full list, because nothing needs installing by hand.

# The default
pip install "initrunner[recommended]"
uv tool install "initrunner[recommended]"
pipx install "initrunner[recommended]"
curl -fsSL https://initrunner.ai/install.sh | sh

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

# One provider on top of core
uv tool install "initrunner[anthropic]"

Two things sit deliberately outside [all], because both are large and neither is worth carrying by default: the desktop app (desktop, which needs a system GUI toolkit) and local fastembed embeddings (local-embeddings, which pulls in the ONNX runtime). Both install on demand like everything else.

Since v2026.8.11, cohere, bedrock, and xai have extras of their own, so initrunner[<provider>] works for all seven providers. Earlier docs said those three were reachable only through all-models.

Missing something?

Nothing is a dead end. Since v2026.8.11, a role or command that needs something this install does not have names it and offers to fix it:

$ initrunner run scout -p "state of the RISC-V ecosystem"
Error: the scout starter needs initrunner[search]
Install now? [Y/n]

Answer yes and InitRunner runs the installer that put it there in the first place, keeps the extras you already have, and reruns your command. Starters, role files, ephemeral runs, provider SDKs, dashboard, desktop, eval, mcp, and the vault all go through the one prompt.

This replaced a printed uv pip install initrunner[search] that was wrong about as often as it was right: uv pip install without --python resolves ./.venv rather than the interpreter actually running, and the shell installer's default is uv tool install.

It also stopped a quieter bug. doctor --fix and setup used to run uv tool install --force "initrunner[anthropic]", and uv resolves a tool environment to exactly the spec it is handed, so accepting an offer to add one provider silently removed search, ingestion, the vector store, MCP, and the dashboard from a [recommended] install. The extras already present now come from the install's own records and are passed along with the new one.

Where installing automatically is not safe or not possible, InitRunner prints the exact command for your install instead of guessing. That covers pipx, containers, a uv sync checkout, uvx, Windows, and any script or CI job with no terminal. initrunner mcp serve writes all of it to stderr, since the protocol owns stdout.

To get ahead of it, initrunner doctor --fix --role agent.yaml --yes installs whatever a role asks for without prompting.

Development Setup

git clone https://github.com/vladkesler/initrunner.git
cd initrunner
# The full suite exercises every optional dependency. Plain `uv sync --dev`
# gives you the lean environment CI's test-lean job runs against.
uv sync --dev --extra dashboard --extra a2a --extra mcp --extra vector
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.