# InitRunner > InitRunner is an open-source CLI tool for creating and running AI agents from YAML configuration files. InitRunner lets you define AI agents as YAML role files and run them from the terminal. It supports multiple LLM providers, tools, memory, RAG, guardrails, and multi-agent orchestration. ## What is InitRunner? InitRunner is an open-source, Python-based platform for building, running, and orchestrating AI agents. It provides a CLI and a built-in web dashboard for managing agents, viewing audit trails, and monitoring runs. Agents are defined declaratively as YAML role files — no framework code required. A single `initrunner run` command starts an agent with full access to tools, memory, RAG pipelines, and audit logging. InitRunner supports multi-agent orchestration, daemon mode, structured output, and integration with 10+ LLM providers out of the box. ## Key Facts - License: MIT - Language: Python 3.11+ - Package manager: uv (recommended) or pip - Install: `pip install initrunner[recommended]` or `curl -fsSL https://initrunner.ai/install.sh | sh` - Current version: 2026.6.9 - Test suite: 5,000+ tests - Built-in tools: 28 tool types - GitHub: https://github.com/vladkesler/initrunner ## Supported AI Providers InitRunner supports the following LLM providers, auto-detected from environment variables: - Anthropic (Claude) — claude-sonnet-4-6, claude-opus-4-8 - OpenAI — gpt-5-mini, gpt-4.1, o4-mini - Google Gemini — gemini-2.5-pro, gemini-2.5-flash - Ollama — any locally hosted model (llama3, mistral, etc.) - AWS Bedrock — Claude, Titan, and other Bedrock-hosted models - Azure OpenAI — enterprise OpenAI deployments - Groq — fast inference (llama, mixtral) - Mistral — mistral-large, mistral-medium - DeepSeek — deepseek-chat, deepseek-reasoner - OpenRouter — proxy to 100+ models - xAI — Grok models - Any OpenAI-compatible endpoint via custom base URL ## Links - [Website](https://initrunner.ai) - [Documentation](https://initrunner.ai/docs) - [GitHub](https://github.com/vladkesler/initrunner) - [Discord](https://discord.gg/GRTZmVcW) - [PyPI](https://pypi.org/project/initrunner/) Every documentation page is also available as plain Markdown: append `.md` to its URL (for example https://initrunner.ai/docs/quickstart.md). The full documentation in one file: https://initrunner.ai/llms-full.txt ## Getting Started - [Introduction](https://initrunner.ai/docs): InitRunner — define AI agents as YAML, run them from the terminal. - [Quickstart](https://initrunner.ai/docs/quickstart): Get your first AI agent running in under five minutes. - [Installation](https://initrunner.ai/docs/installation): Install InitRunner via pip, uv, pipx, the quick install script, or Docker. - [Setup Wizard](https://initrunner.ai/docs/setup): Guided wizard to configure your model provider, API key, and first agent role. - [Tutorial: Build a Research Assistant](https://initrunner.ai/docs/tutorial): Build a research assistant from scratch, then give it memory, a knowledge base, autonomy, a schedule, and teammates. - [Role Creation](https://initrunner.ai/docs/role-creation): Every way to create an InitRunner agent role — initrunner new with AI generation, templates, hub bundles, interactive refinement, dashboard, and manual YAML. - [RAG in 5 Minutes](https://initrunner.ai/docs/rag-quickstart): Get a retrieval-augmented generation agent running in three commands. - [Memory in 5 Minutes](https://initrunner.ai/docs/memory-quickstart): Give any agent persistent memory — sessions that resume, facts that stick, and rules that accumulate — in minutes. - [Examples](https://initrunner.ai/docs/examples): Discover, clone, and run 60+ example agent configurations from the CLI, or browse detailed walkthroughs on this page. - [Import from LangChain](https://initrunner.ai/docs/langchain-import): Bring your existing LangChain agents into InitRunner in minutes — via the dashboard or CLI. - [Import from PydanticAI](https://initrunner.ai/docs/pydanticai-import): Bring your existing PydanticAI agents into InitRunner in minutes — via the dashboard or CLI. - [Agent Spec Import & Export](https://initrunner.ai/docs/agent-spec-import): Import and export PydanticAI Agent Specs (since v2026.4.17). ## Core Concepts - [Concepts & Architecture](https://initrunner.ai/docs/concepts): High-level mental model of InitRunner — the role file, runtime architecture, execution lifecycle, and safety layers. - [Configuration](https://initrunner.ai/docs/configuration): Full YAML schema reference for InitRunner agent roles. - [Capabilities](https://initrunner.ai/docs/capabilities): PydanticAI capabilities for extended thinking, web search, MCP servers, and more. - [Intent Sensing](https://initrunner.ai/docs/intent-sensing): Auto-select the right agent from your library using the --sense flag. - [Providers](https://initrunner.ai/docs/providers): Supported LLM providers and model configuration. - [Model Aliases](https://initrunner.ai/docs/model-aliases): Define semantic model aliases and override models at runtime without editing role YAML files. - [Ollama & Local Models](https://initrunner.ai/docs/ollama): Run agents with local LLMs using Ollama or any OpenAI-compatible endpoint — zero API keys required. ## Agent Capabilities - [Tools](https://initrunner.ai/docs/tools): Tool types and configuration reference for InitRunner agents. - [Tool Search](https://initrunner.ai/docs/tool-search): Dynamic tool discovery at runtime — BM25 keyword index lets agents find and load tools on demand, cutting context usage by 60-80%. - [Skills](https://initrunner.ai/docs/skills): Reusable capability bundles that add tools and prompt instructions to agents, with optional auto-discovery. - [Memory](https://initrunner.ai/docs/memory): Session persistence and long-term memory (semantic, episodic, procedural) with automatic consolidation for InitRunner agents. - [Ingestion](https://initrunner.ai/docs/ingestion): Document ingestion and RAG pipeline for InitRunner agents. - [RAG Patterns & Guide](https://initrunner.ai/docs/rag-guide): Practical patterns for using InitRunner's retrieval-augmented generation (RAG) capabilities. - [Multimodal Input](https://initrunner.ai/docs/multimodal): Send images, audio, video, and documents alongside text prompts across CLI, REPL, API, and dashboard. - [Autonomous Mode](https://initrunner.ai/docs/autonomy): Plan-execute-adapt loops for agents that work without human intervention. - [Reasoning Primitives](https://initrunner.ai/docs/reasoning): Structured agent cognition with think, todo, and spawn tools, native extended thinking, and react, todo_driven, plan_execute, and reflexion execution strategies. - [Structured Output](https://initrunner.ai/docs/structured-output): Return validated JSON from agents using JSON Schema definitions. - [Report Export](https://initrunner.ai/docs/reports): Export structured markdown reports from any agent run, capturing prompt, output, token usage, timing, and status. ## Automation & Orchestration - [Triggers](https://initrunner.ai/docs/triggers): Cron schedules, file watchers, webhooks, heartbeat, Telegram, and Discord triggers for autonomous agent execution. - [Sinks](https://initrunner.ai/docs/sinks): Output destinations for daemon and flow agent runs. - [Telegram Bot](https://initrunner.ai/docs/telegram): Get a Telegram bot agent running in three steps. - [Discord Bot](https://initrunner.ai/docs/discord): Get a Discord bot agent running in five steps. - [Team Mode](https://initrunner.ai/docs/team-mode): Define multiple personas in one YAML file for sequential, parallel, debate, or ensemble multi-agent collaboration, with per-persona overrides, shared memory, and shared documents. - [Flow](https://initrunner.ai/docs/flow): Multi-agent orchestration with delegate sinks and startup ordering. - [Durability](https://initrunner.ai/docs/durability): Durable, resumable flows backed by an HMAC-signed checkpoint journal in the audit store. - [Blackboard](https://initrunner.ai/docs/blackboard): Per-run shared structured state that flow agents post to, read, and claim. ## Safety & Observability - [Guardrails](https://initrunner.ai/docs/guardrails): Token budgets, tool limits, and automatic enforcement for safe agent execution. - [Security](https://initrunner.ai/docs/security): Security hardening guide for InitRunner agents. - [Approvals](https://initrunner.ai/docs/approvals): Pause tool calls for human review with approval required (since v2026.4.17). - [Agent Policy Engine (InitGuard)](https://initrunner.ai/docs/initguard): Embedded agent-as-principal policy enforcement for tool access and delegation using InitGuard. - [Runtime Sandbox](https://initrunner.ai/docs/sandbox): Run tool subprocesses under kernel-level isolation with bubblewrap or Docker, or run them remotely over SSH. Shared config and a migration guide. - [Bubblewrap Sandbox](https://initrunner.ai/docs/bubblewrap): Daemonless Linux sandbox for tool subprocesses using user namespaces — no root, no Docker, no background service. - [Docker Sandbox](https://initrunner.ai/docs/docker-sandbox): Run shell, Python, and script tools inside disposable Docker containers with pinned images, bridge networking, and kernel-level isolation. - [SSH Backend](https://initrunner.ai/docs/ssh-sandbox): Run shell, Python, and script tools on a remote host over OpenSSH (since v2026.5.1). Remote execution, not isolation. - [Sandbox Comparison](https://initrunner.ai/docs/sandbox-comparison): Compare InitRunner's sandbox backends and Docker runtimes across isolation classes (container, userspace kernel, microVM), threat models, and operational tradeoffs. - [Audit Trail](https://initrunner.ai/docs/audit): SQLite audit logging, export, redaction, and pruning for InitRunner agent runs. - [Cost Tracking](https://initrunner.ai/docs/cost-tracking): Per-run USD cost estimation, cost budgets, CLI analytics, and the dashboard cost page. - [Observability](https://initrunner.ai/docs/observability): OpenTelemetry distributed tracing for InitRunner agent runs, LLM requests, tool calls, and multi-agent pipelines. - [Usage Telemetry](https://initrunner.ai/docs/telemetry): Anonymous, opt-in usage telemetry for the InitRunner CLI and dashboard, what it sends, and how to control it. - [Testing](https://initrunner.ai/docs/testing): Test suites, dry-run mode, and validation for InitRunner agents. - [Agent Evals](https://initrunner.ai/docs/evals): Define eval suites in YAML and run them against agent roles to verify output quality, tool usage, performance, and cost. ## Deployment - [Docker](https://initrunner.ai/docs/docker): Run InitRunner in Docker without installing Python — images, compose, volumes, and build options. - [Cloud Deploy](https://initrunner.ai/docs/cloud-deploy): One-click deployment to Railway, Render, and Fly.io — get the InitRunner dashboard running in the cloud in minutes. ## Interfaces - [Dashboard & Desktop](https://initrunner.ai/docs/dashboard): SvelteKit web dashboard and native desktop app for managing InitRunner agents. - [CLI Reference](https://initrunner.ai/docs/cli): Complete command reference for the InitRunner CLI. - [API Server](https://initrunner.ai/docs/server): Serve any agent as an OpenAI-compatible HTTP API. - [MCP Gateway](https://initrunner.ai/docs/mcp-gateway): Expose InitRunner agents as MCP tools for Claude Desktop, Claude Code, Cursor, and other MCP clients. - [A2A Server](https://initrunner.ai/docs/a2a): Expose agents via Google's Agent-to-Agent protocol for cross-framework communication. ## Community - [InitHub Marketplace](https://initrunner.ai/docs/registry): Browse, install, share, and manage community agent packs from InitHub, OCI registries, and the community index. - [OCI Distribution](https://initrunner.ai/docs/oci-distribution): Publish and install InitRunner role bundles via OCI-compliant container registries. ## Help - [Doctor](https://initrunner.ai/docs/doctor): Check your InitRunner environment — API keys, provider SDKs, and service connectivity — with a single command. - [Troubleshooting & FAQ](https://initrunner.ai/docs/troubleshooting): Common issues, error messages, and frequently asked questions for InitRunner. - [Tutorial: Dev Workflow Agents](https://initrunner.ai/docs/dev-workflow-agents): Run three pre-built templates — PR reviewer, changelog for Slack, and CI failure explainer — each producing copy-paste-ready output.