initrunner 1.45.0

Define AI agent roles in YAML and run them anywhere — CLI, API server, or autonomous daemon

InitRunner

Website · Docs · InitHub · Discord · Issues

AI agents that work. A docs assistant that answers from your knowledge base with citations. A code review team that catches bugs before your human reviewers do. A Telegram bot that supports your users 24/7 with persistent memory.

Each one is a single command:

initrunner run helpdesk -i                                    # docs Q&A with RAG + memory
initrunner run code-review-team -p "Review the latest commit" # multi-perspective code review
initrunner run web-researcher -p "Compare React vs Svelte"    # web research with citations
initrunner run telegram-assistant --daemon                     # Telegram bot with memory
initrunner run discord-assistant --daemon                      # Discord bot with memory

Or define your own in one YAML file. Built-in RAG, persistent memory, 25+ tools, any model.

v1.45.0 -- Unified run command (chat merged in), built-in starter agents, [recommended] install bundle, dashboard prompt after setup. See the Changelog.

Contents

• Quickstart
• Define an Agent in YAML
• Why InitRunner
• Features
• 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 to see all available starters, or jump right in:

initrunner run helpdesk -i                                    # RAG over your docs folder
initrunner run code-review-team -p "Review the latest commit" # team of 3 reviewers
initrunner run memory-assistant                                # assistant that remembers

The model is auto-detected from your API key. Override with --model anthropic:claude-sonnet-4-5-20250929.

Want to customize a starter? Copy it 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:

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

See the Docker guide for RAG, Telegram, API server, and more 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. Using Claude? pipx install "initrunner[anthropic]" and set 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. Add memory for persistent recall across sessions:

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

initrunner ingest role.yaml   # extract | chunk | embed | store
initrunner run role.yaml -i --resume   # search_documents + memory ready

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 Compose · Delegation.

User Interfaces

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
--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
• Run panel -- send prompts and stream responses in real time
• Compose and Team builders -- visual editors for multi-agent orchestration
• 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 optional Cerbos agent-as-principal policy engine. Agents get Cerbos identity from role.metadata (name, team, tags, author), with tool-level authorization and delegation policy enforced across CLI, compose, daemon, and API:

pip install initrunner[authz]
export INITRUNNER_CERBOS_ENABLED=true
export INITRUNNER_CERBOS_AGENT_CHECKS=true  # per-agent identity checks
initrunner run role.yaml   # tool calls + delegation checked against Cerbos 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/code-reviewer@1.2.0             # 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
Knowledge & memory	Ingestion · Memory · Multimodal Input
Orchestration	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. 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.

---

_v1.45.0