Introduction

Open-Source AI Agent CLI

InitRunner is an open-source CLI that turns a YAML file into a complete AI agent. A name, a prompt, the tools — InitRunner handles the rest: tool execution, guardrails, memory, RAG, and multi-provider routing. No framework to learn, no boilerplate to write.

LLM-friendly docs — This documentation is also available as /llms.txt and /llms-full.txt for LLM consumption.

Key Features

Define

• YAML-first — The file is the agent: a name, a prompt, the tools. Check it into git, diff it in PRs, deploy it anywhere. Old apiVersion/kind envelopes still run; convert them with initrunner doctor --fix. See Envelope Migration.
• Multi-provider — OpenAI, Anthropic, Google, Groq, Mistral, Cohere, xAI, Bedrock, and Ollama. Swap providers by changing one line.
• 28 tool types — Filesystem, HTTP, MCP, shell, SQL, custom Python, audio, web reader, and more. Add them to your YAML and they just work.
• Multimodal input — Attach images, audio, video, and documents to prompts via CLI, REPL, API, or dashboard. See Multimodal.
• Skills — Bundled tool+prompt packages that agents load on demand. Think plugins, but defined in YAML. See Skills.
• Structured output. Type-safe responses with JSON Schema validation. Pick how the model is asked for it per role: auto, tool, native, or prompted. See Structured Output.
• Extended thinking. Set a reasoning effort level for models that support it. See Reasoning.

Chat

• Zero-config chat — Run initrunner run with no YAML file. Auto-detects your API key and starts an interactive session.
• CLI-driven RAG — Add --ingest ./docs/ to search your documents directly from the command line.
• Tool profiles — Use --tools all to enable every built-in tool, or --tools git --tools shell to cherry-pick. One flag takes both profiles and tool types.
• Memory flags — --memory (default), --no-memory, and --resume control chat memory from the CLI.

Remember

• Built-in RAG. Ingest documents, chunk, embed, and vector-search with LanceDB. No external database required. In chat mode, just add --ingest ./docs/. Hybrid retrieval combines vector and keyword search; see RAG Guide.
• Local embeddings. Run an in-process embedding model with the local: provider, no HTTP hop or API key needed. See Providers.
• Memory — Three types: semantic, episodic, and procedural. Auto-consolidation distills episodes into durable facts. On by default in chat mode.

Automate

• Triggers — Run agents on a cron schedule, file change, incoming webhook, heartbeat, or as a Telegram/Discord/Slack bot. Daemon mode included.
• Always-on services — Start curated agents with initrunner service start collector acme.com. No YAML required. See Always-on Services.
• Grouped agents — List several independent agents in one file, or just put them in a directory, then run one with --agent, serve them all from one process as OpenAI model IDs, or expose them as MCP tools. Fifty agents is one ~150 MB container, not fifty. See Grouped Agents.
• Team mode — Define multiple agents in one YAML for sequential multi-agent collaboration.
• Multi-agent flow. Orchestrate multiple agents with delegate sinks and startup ordering, ensemble voting across targets, and loop-back routing that re-runs a step until a condition holds. See Flow. Agents in a flow can share structured state through a blackboard.
• Durable flows. Flow runs checkpoint their state so a long run can resume after a restart. See Durability.
• Autonomy — Plan-execute-adapt loops that let agents work through multi-step tasks independently.

Ship

• API server — initrunner run --serve exposes any agent as an OpenAI-compatible API with streaming.
• One process, not one per agent — The Python AI stack loads once, so each extra agent costs under 1 MB. In one process, one agent measures 112 MB, five measure 115 MB, and fifty measure 151 MB. See Memory Footprint.
• Web dashboard + desktop app — Build agents, watch runs in real time, and browse audit logs from a browser or native window.
• One-click cloud deploy — Deploy to Railway, Render, or Fly.io with pre-loaded example roles and persistent storage.
• Guardrails & audit — Token budgets, tool limits, content filtering, PII redaction, and full action logging to SQLite.
• Debuggable in production — Every failed run logs one warning with its run id, agent, and error category, in every mode. Raise the level with -v or INITRUNNER_LOG_LEVEL=DEBUG to see provider HTTP traffic. See Logging.
• MCP gateway — Expose agents as MCP servers for integration with other tools. Includes an MCP Hub dashboard for server discovery, health monitoring, and tool testing. See MCP Gateway.
• OCI distribution — Package and distribute agents as OCI artifacts. See OCI Distribution.
• Evals & testing. Test agents against expected outputs and score them automatically, with an optional pydantic-evals runner for the same suites. See Evals and Testing.

Quick Install

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

Or with a package manager:

uv tool install "initrunner[recommended]"
pipx install "initrunner[recommended]"
pip install "initrunner[recommended]"

Or run with Docker:

docker run --rm -it -e OPENAI_API_KEY ghcr.io/vladkesler/initrunner:latest initrunner run -i

Next Steps

• Quickstart — Get your first agent running in minutes
• Envelope Migration — Convert old apiVersion/kind files to flat YAML
• Always-on Services — Start a curated daemon without writing YAML
• Grouped Agents — Ship several agents in one file and one process
• Concepts & Architecture — High-level mental model and execution lifecycle
• Configuration — Full YAML schema reference
• Providers — Provider setup and model configuration
• Tools — All built-in tool types
• Examples — Complete, runnable agents for common use cases
• Memory Footprint — Process RSS, lazy loads, and container sizing
• Logging — Log levels, failed-run output, and debugging a provider connection
• Troubleshooting & FAQ — Common issues and solutions

All topics are in the sidebar.