InitRunner

Website · Docs · InitHub · Discord · Issues

AI agents that work. A docs assistant that answers from your knowledge base. A research team that searches the web and writes cited reports. A code review team that catches bugs before your human reviewers do. Each one is a single command:

initrunner run helpdesk -i                                    # docs Q&A with RAG + memory
initrunner run deep-researcher -p "Compare vector databases"  # 3-agent research team
initrunner run code-review-team -p "Review the latest commit" # multi-perspective code review

14 starters included, or define your own in one YAML file. Built-in RAG, persistent memory, 25+ tools, any model.

v2026.3.7 -- New branding: InitRunner logo replaces mascot across README, PyPI, and dashboard. See the Changelog.

Quickstart
Define an Agent in YAML
Why InitRunner
Features
Intelligence
User Interfaces
Security & Authorization
Distribution & Deployment
Documentation
Community

Quickstart

Install and configure:

curl -fsSL https://initrunner.ai/install.sh | sh
initrunner setup        # wizard: pick provider, model, API key

Or install with a package manager: uv pip install "initrunner[recommended]" / pipx install "initrunner[recommended]". See Installation and Setup.

Upgrade: re-run the install command, or: uv tool upgrade initrunner / pipx upgrade initrunner.

Try a starter agent

Run initrunner run --list to see all available starters. The model is auto-detected from your API key.

Starter	What it does	Kind
`helpdesk`	Drop your docs in, get an AI helpdesk with citations and memory	Agent (RAG)
`code-review-team`	Multi-perspective review: architect, security, maintainer	Team
`deep-researcher`	3-agent pipeline: planner, web researcher, synthesizer with shared memory	Team
`codebase-analyst`	Index your repo, chat about architecture, learns patterns across sessions	Agent (RAG)
`web-researcher`	Search the web and produce structured briefings with citations	Agent
`content-pipeline`	Topic researcher, writer, editor/fact-checker via webhook or cron	Compose
`project-monitor`	Heartbeat-driven health checks, learns baselines over time	Agent (Daemon)
`telegram-assistant`	Telegram bot with memory and web search	Agent (Daemon)
`discord-assistant`	Discord bot with memory and web search	Agent (Daemon)
`rag-agent`	Document Q&A agent with ingestion and citations	Agent (RAG)
`memory-assistant`	Personal assistant that learns and remembers across sessions	Agent
`email-agent`	Monitors inbox, triages messages, drafts replies, alerts Slack on urgent mail	Agent (Daemon)
`ci-pipeline`	Webhook receiver, build analyzer, Slack notifier for CI events	Compose
`support-desk`	Sense-routed intake, researcher, responder, and escalator	Compose

RAG starters auto-ingest on first run -- just cd into your project and go:

cd ~/myproject
initrunner run codebase-analyst -i   # indexes your code, then starts Q&A

Want to customize? Copy locally and edit:

initrunner run helpdesk --save ./my-helpdesk/
# add your docs to ./my-helpdesk/knowledge-base/, then:
initrunner run ./my-helpdesk/ -i

Use a premade agent from InitHub

Browse hub.initrunner.ai or search from the terminal:

initrunner search "code review"                                    # find agents
initrunner install alice/code-reviewer                             # install one
initrunner run alice/code-reviewer -p "Review the latest commit"   # run it

See Registry docs for version pinning, updates, and OCI sources.

Or build your own

initrunner new "a research assistant that summarizes papers"  # AI-generates a role.yaml
initrunner run --ingest ./docs/    # or skip YAML entirely -- chat with your docs, memory on by default

Fork a hub agent as a starting point: initrunner new --from hub:alice/code-reviewer. See Tutorial.

Or run with Docker, no install needed:

# Dashboard (default) -- http://localhost:8100
docker run -d -e OPENAI_API_KEY -p 8100:8100 \
    -v initrunner-data:/data ghcr.io/vladkesler/initrunner:latest

# Interactive chat
docker run --rm -it -e OPENAI_API_KEY \
    -v initrunner-data:/data ghcr.io/vladkesler/initrunner:latest run -i

See the Docker guide for RAG, Telegram, API server, and compose examples.

Define Agent Roles in YAML

When you need more control, define an agent as a YAML file:

apiVersion: initrunner/v1
kind: Agent
metadata:
  name: code-reviewer
  description: Reviews code for bugs and style issues
spec:
  role: |
    You are a senior engineer. Review code for correctness and readability.
    Use git tools to examine changes and read files for context.
  model: { provider: openai, name: gpt-5-mini }
  tools:
    - type: git
      repo_path: .
    - type: filesystem
      root_path: .
      read_only: true

initrunner run reviewer.yaml -p "Review the latest commit"

That's it. No Python, no boilerplate. The model: section is optional -- omit it and InitRunner auto-detects from your API key. Or pin a specific model: model: { provider: anthropic, name: claude-sonnet-4-5-20250929 }.

Why InitRunner

Zero config to start. initrunner run gives you an AI assistant with persistent memory and document search out of the box. No YAML, no setup beyond an API key.

Config, not code. Define your agent's tools, knowledge base, and memory in one YAML file. No framework boilerplate, no wiring classes together. 25+ built-in tools (filesystem, git, HTTP, Python, shell, SQL, search, email, MCP, think, script, and more) work out of the box. Need a custom tool? One file, one decorator.

Version-control your agents. Agent configs are plain text. Diff them, review them in PRs, validate in CI, reproduce anywhere. Your agent definition lives next to your code.

Prototype to production. Same YAML runs as an interactive chat, a one-shot CLI command, a trigger-driven daemon, or an OpenAI-compatible API. No rewrite when you're ready to deploy.

How It Compares

	InitRunner	Build from scratch	LangChain
Setup	`curl -fsSL https://initrunner.ai/install.sh \| sh` + API key	Install 5-10 packages, write glue code	`pip install langchain` + adapters
Agent config	One YAML file	Python classes + wiring	Python chains + config objects
RAG	`--ingest ./docs/` (one flag)	Embed, store, retrieve, prompt - DIY	Loaders > splitters > vectorstore chain
Bot deployment	`--telegram` / `--discord` flag	Build bot framework integration	Separate bot framework + adapter
Model switching	`--model` flag, aliases, or change YAML	Rewrite client code	Swap LLM class + adjust prompts
Multi-agent	`compose.yaml` with delegation + auto-routing	Custom orchestration layer	Agent executor + custom routing

What Can You Build?

A Telegram bot that answers questions about your codebase - point it at your repo, deploy with one flag
A cron job that monitors competitors and sends daily digests - cron trigger + web scraper + Slack sink
A document Q&A agent for your team's knowledge base - ingest PDFs and Markdown, serve as an API
A code review bot triggered by new commits - file-watch trigger + git tools + structured output
A multi-agent pipeline with auto-routing: intake > researcher / responder / escalator - sense routing picks the right target per message (initrunner examples copy support-desk)
A personal assistant that remembers everything - persistent memory across sessions, no setup

Features

Start with the code-reviewer above. Each step adds one capability - no rewrites, just add a section to your YAML.

Knowledge & memory

Point at your docs for RAG - a search_documents tool is auto-registered. Set auto: true and it indexes on first run, no extra step:

spec:
  ingest:
    auto: true
    sources: ["./docs/**/*.md", "./docs/**/*.pdf"]
  memory:
    semantic:
      max_memories: 1000

initrunner run role.yaml -i   # auto-ingests on first run, then search_documents + memory ready

Common junk directories (node_modules, .venv, __pycache__, .git) are auto-excluded from glob patterns. Or ingest manually: initrunner ingest role.yaml.

See Ingestion · Memory · RAG Quickstart.

Capabilities

Use native PydanticAI capabilities directly in YAML -- no tool wiring needed:

spec:
  capabilities:
    - Thinking
    - WebSearch
    - WebFetch: { max_size: 1048576 }
  model: { provider: anthropic, name: claude-sonnet-4-5-20250929 }

Capabilities like Thinking, WebSearch, WebFetch, ImageGeneration, and MCP are resolved at build time. InputGuardCapability enforces content policy from security.content_policy. See Capabilities.

Clarify tool

Let agents ask follow-up questions mid-run instead of guessing:

spec:
  tools:
    - type: clarify

The agent calls clarify("Which branch should I deploy?") and blocks until the user responds. Works in REPL, Telegram/Discord bots, daemon mode, and autonomous runs. See Tools.

Context budget guard

Long autonomous runs accumulate history that can exceed the context window. The built-in history processor estimates token usage and drops oldest message pairs when the budget is exceeded:

spec:
  model:
    provider: anthropic
    name: claude-sonnet-4-5-20250929
    context_window: 200000   # optional -- auto-detected per provider
  autonomy:
    max_iterations: 50

No extra config needed -- the guard activates automatically for autonomous and daemon runs. See Autonomy.

Triggers

Turn it into a daemon that reacts to events - cron, file watch, webhook, heartbeat, Telegram, or Discord:

spec:
  triggers:
    - type: cron
      schedule: "0 9 * * 1"
      prompt: "Generate the weekly status report."
    - type: file_watch
      paths: [./src]
      prompt_template: "File changed: {path}. Review it."

initrunner run role.yaml --daemon   # runs until stopped

See Triggers · Telegram · Discord.

Compose agents

Orchestrate multiple agents into a chain - one agent's output feeds into the next. Use strategy: sense to auto-route messages to the right target:

apiVersion: initrunner/v1
kind: Compose
metadata: { name: email-chain }
spec:
  services:
    inbox-watcher:
      role: roles/inbox-watcher.yaml
      sink: { type: delegate, target: triager }
    triager:
      role: roles/triager.yaml
      sink: { type: delegate, strategy: sense, target: [researcher, responder] }
    researcher: { role: roles/researcher.yaml }
    responder: { role: roles/responder.yaml }

Run with initrunner compose up compose.yaml. See Orchestration Patterns for all five patterns side-by-side, or dive into Compose · Delegation.

Intelligence

Reasoning patterns

Control how your agent thinks, not just what it does:

spec:
  reasoning:
    pattern: plan_execute    # plan upfront, then execute each step
    auto_plan: true
  tools:
    - type: think            # internal scratchpad -- agent reasons before acting
      critique: true         # self-evaluates each thought
    - type: todo             # structured task list for multi-step work

Four patterns: react (simple tool loop), todo_driven (works through a task list), plan_execute (plans then acts), and reflexion (self-critiques and retries). The dashboard Cognition panel lets you switch patterns, toggle think/todo tools, and tune autonomy settings visually -- no YAML editing required.

See Reasoning · Autonomy.

Sense routing

When a compose pipeline has multiple targets, sense routing picks the right one automatically:

triager:
  role: roles/triager.yaml
  sink:
    type: delegate
    strategy: sense
    target: [researcher, responder, escalator]

Two-pass scoring: first, keyword matching against each target's tags, name, and description (zero API calls). If scores are close, a single LLM call breaks the tie. In practice, keyword scoring resolves 90%+ of routing decisions -- the LLM tiebreaker fires only on genuinely ambiguous messages.

Scoring weights and strategy comparison

Signal	Weight	Example
Tags	3x	`tags: [research, analysis, investigation]`
Name	2x	`name: researcher`
Description	1.5x	`description: Investigates technical issues`

Strategy	Behavior	Cost
`all`	Fan-out to every target (default)	None
`keyword`	Keyword scoring only	None
`sense`	Keyword + LLM tiebreaker	0-1 LLM call per message

The dashboard compose builder exposes all three strategies as inline controls when you create a Route composition, with quality indicators showing how well each target's metadata is optimized for routing.

See Intent Sensing · Compose Routing.

Tool search

Agents with many tools waste context and pick worse. Tool search hides tools behind on-demand keyword discovery:

spec:
  tools:
    - type: datetime
    - type: web_reader
    - type: search
    - type: python
    - type: slack
    - type: filesystem
    - type: git
    - type: shell
    # ... 10+ tools
  tool_search:
    enabled: true
    always_available: [current_time, fetch_page]

The agent sees only search_tools and the pinned tools. When it needs something else, it calls search_tools("send slack message"), discovers send_slack_message, and calls it -- all in one turn. BM25 keyword search, no API calls, no embeddings. Typically saves 60-80% context on tool-heavy agents.

The dashboard Cognition panel lets you toggle tool search and pick always-visible tools from a checklist when creating or editing an agent.

See Tool Search.

User Interfaces

InitRunner Dashboard
Dashboard Launchpad - agents, activity, compositions, and teams at a glance

Manage agents, run prompts, build compositions, and browse audit trails from a visual interface. Two modes are available: a web dashboard that opens in your browser, and a native desktop app.

Dashboard (web)

pip install "initrunner[dashboard]"   # included in initrunner[all]
initrunner dashboard                  # opens http://localhost:8100

The browser opens automatically. Flags:

Flag	Description
`--port`	Listen on a different port (default: `8100`)
`--no-open`	Don't open the browser automatically
`--expose`	Bind to `0.0.0.0` instead of localhost
`--api-key`	Protect access with a login page and cookie-based session (also reads `INITRUNNER_DASHBOARD_API_KEY` env var)
`--roles-dir`	Extra directories to scan for role YAML files (repeatable)

Desktop (native window)

pip install "initrunner[desktop]"     # adds pywebview
initrunner desktop                    # opens a native OS window

No browser needed. The desktop app embeds the dashboard in a native window using the platform's WebView (WKWebView on macOS, WebView2 on Windows). On Linux, GTK and WebKit packages are required -- the command detects missing packages and prints the install command for your distro.

If a dashboard is already running on the port, the desktop window connects to it instead of starting a second backend.

What's in the UI

Agent management -- browse, create, delete, and inspect agents in a flow canvas or list view
Cognition panel -- configure reasoning patterns, autonomy, think/todo tools, and tool search visually
Run panel -- send prompts and stream responses in real time
Compose and Team builders -- visual editors with routing strategy selection and quality indicators
Audit log -- filterable run history with token usage and durations
System health -- detected providers, doctor checks, and tool registry

See the full Dashboard docs and Design System.

Security & Authorization

Built-in security with an embedded initguard agent-as-principal policy engine. Agents get identity from role.metadata (name, team, tags, author), with tool-level authorization and delegation policy enforced across CLI, compose, daemon, and API:

export INITRUNNER_POLICY_DIR=./policies   # point to your policy YAML directory
initrunner run role.yaml                  # tool calls + delegation checked against policies

Also includes content filtering, PEP 578 sandboxing, Docker isolation, token budgets, and rate limiting out of the box. See Agent Policy · Security · Guardrails.

More capabilities

Feature	Command / config	Docs
Skills - reusable tool + prompt bundles, auto-discovered	`spec: { skills: [../skills/web-researcher] }`	Skills
Team mode - multi-persona on one task	`kind: Team` + `spec: { personas: {…} }`	Team Mode
API server - OpenAI-compatible endpoint	`initrunner run agent.yaml --serve --port 3000`	Server
Multimodal - images, audio, video, docs	`initrunner run role.yaml -p "Describe" -A photo.png`	Multimodal
Structured output - validated JSON schemas	`spec: { output: { schema: {…} } }`	Structured Output
Evals - test agent output quality	`initrunner test role.yaml -s eval.yaml`	Evals
MCP gateway - expose agents as MCP tools	`initrunner mcp serve agent.yaml`	MCP Gateway
MCP toolkit - tools without an agent	`initrunner mcp toolkit`	MCP Gateway
Configure - switch provider/model on any role	`initrunner configure role.yaml --provider groq`	Providers

See Tutorial for a guided walkthrough.

Distribution & Deployment

InitHub

initrunner search "code review"                          # browse InitHub
initrunner install alice/code-reviewer                   # install from InitHub
initrunner install alice/[email protected]             # pin a version

See Registry.

initrunner login                        # browser-based device code auth
initrunner login --token <TOKEN>        # CI/headless
initrunner publish                      # publish from current agent directory

See Publishing Guide.

OCI registry

Publish and install complete role bundles to any OCI-compliant container registry:

initrunner publish oci://ghcr.io/org/my-agent --tag 1.0.0       # from current dir
initrunner publish ./my-agent/ oci://ghcr.io/org/my-agent --tag 1.0.0  # or pass a path
initrunner install oci://ghcr.io/org/my-agent:1.0.0

See OCI Distribution.

Cloud deploy

Fly.io: See the deploy/fly.toml configuration in the repository.

Documentation

Area	Key docs
Getting started	Installation · Setup · RAG Quickstart · Tutorial · CLI Reference · Docker · Discord Bot · Telegram Bot
Agents & tools	Tools · Tool Creation · Tool Search · Skills · Structured Output · Providers
Intelligence	Reasoning · Intent Sensing · Tool Search · Autonomy
Knowledge & memory	Ingestion · Memory · Multimodal Input
Orchestration	Patterns Guide · Compose · Delegation · Team Mode · Autonomy · Triggers · Intent Sensing
Interfaces	Dashboard · API Server · MCP Gateway
Distribution	OCI Distribution · Shareable Templates
Operations	Security · Agent Policy · Guardrails · Audit · Reports · Evals · Doctor · Deprecations · Observability · CI/CD

See docs/ for the full index.

Examples

initrunner examples list               # see all available examples
initrunner examples copy code-reviewer # copy to current directory

The examples/ directory includes 20+ ready-to-run agents, skills, and compose projects.

Upgrading & Deprecations

Role YAML files now include metadata.spec_version to track schema compatibility. When InitRunner removes or renames a config field, the deprecation system gives a clear error message pointing to the fix instead of a cryptic validation failure.

Run initrunner doctor --role role.yaml to check any role file for deprecated fields, schema errors, and spec version status. Add --fix to auto-install missing SDKs, install required extras for your role's tools/triggers, and bump spec_version -- or --fix --yes for non-interactive CI. See the Deprecations guide for the full list of removed fields and migration instructions.

Community & Contributing

Discord - InitRunner Hub - Chat, ask questions, share roles
GitHub Issues - Bug reports and feature requests
Changelog - Release notes and version history

Contributions welcome! See CONTRIBUTING.md for dev setup and PR guidelines. For security vulnerabilities, see SECURITY.md.

License

Licensed under MIT or Apache-2.0, at your option.

_v2026.3.7

initrunner