### [InitRunner](https://free.ilovefree.com/)

**Published:** 2026-06-15T01:00:00

**Author:** ilovefree

**Excerpt:** 100% Free. InitRunner is an open-source CLI tool for building and deploying AI agents using YAML configurations, supporting multi-step tasks, RAG, and persistent memory.

InitRunner is an open-source CLI tool ([GitHub](https://github.com/vladkesler/initrunner)) that lets developers define AI agents in YAML configuration files and run them from the terminal. Current version is **v1.14.0**. The tool is free, self-hosted, and requires no framework to learn — agents are portable enough to check into git.

### Core Specs at a Glance

| Dimension | Details |
| :--- | :--- |
| Install | `pip install initrunner` or \`curl -fsSL https://initrunner.ai/install.sh |
| Supported platforms | Linux, macOS, WSL |
| LLM providers | OpenAI, Anthropic, Google Gemini, Groq, Mistral, Cohere, AWS Bedrock, xAI, Ollama, OpenRouter, + any OpenAI-compatible API |
| Built-in tool types | **18** (filesystem, HTTP, MCP, shell, git, search, and more) + custom Python functions |
| Agent definition | YAML config files or zero-config `initrunner chat` |
| Cost model | **100% free, open-source** — users pay only for external LLM API usage and self-hosting infrastructure |

## Three Ways to Start

1.  **Zero-config chat.** Run `initrunner setup` to pick an LLM provider and save an API key, then `initrunner chat` to start a conversation immediately. Add `--ingest ./docs/` to enable RAG on a folder of documents, or `--tool-profile all` to enable all tools. No YAML file required.
    
2.  **YAML-defined agent.** Create a YAML file specifying the model, role, system prompt, tools, and memory settings. Run with `initrunner run agent.yaml`. The agent loads, connects to tools, and begins working. Every action is logged to a tamper-proof SQLite audit trail.
    
3.  **Scheduled automation.** Add triggers — cron schedules, file watchers, webhooks, or Telegram/Discord bot integrations. Agents run unattended on a timer, on file changes, or in response to incoming messages.
    

### Built-in Capabilities

**Retrieval-Augmented Generation (RAG).** Point at a folder of markdown files, PDFs, or CSVs. InitRunner chunks, embeds, and indexes them automatically. The agent gets a `search_documents()` tool for semantic search with source citations. No vector database or embedding pipeline to manage. Quick start: `initrunner chat --ingest ./docs/`.

**Memory system.** Three memory types — **semantic** (facts), **episodic** (outcomes), and **procedural** (policies). Agents call `remember()`, `record_episode()`, and `learn_procedure()`. Automatic consolidation distills episodic records into durable knowledge. Memory is on by default in chat mode; `--resume` picks up where a previous session left off.

**Autonomous planning.** Enable autonomy and the agent plans multi-step tasks, executes each step, and adapts when something fails. This isn’t simple prompt chaining — the agent reasons about what to do next based on results from previous steps.

**Agent sensing.** Run `--sense`, describe a task in natural language, and InitRunner picks the right agent from the library and runs it. Useful when managing multiple specialized agents.

**OpenAI-compatible API server.** Run `initrunner serve` and the agent becomes an `/v1/chat/completions` endpoint with streaming, authentication, and multi-turn conversation support. Plug it into any OpenAI SDK, chat UI, or internal tool.

**Skills system.** Bundle tools and prompt instructions into a single `SKILL.md` file — YAML frontmatter for tools and requirements, Markdown body for the prompt. Reference the skill from any agent config. No duplicating tool blocks across multiple agent files.

**Triggers and scheduling.** Wire up cron schedules, file watchers, webhooks, or Telegram and Discord bots. Agents run unattended and notify when finished.

**Observability.** A terminal UI (TUI) and web dashboard show running agents in real time, a searchable audit trail for every run, and the ability to resume past sessions. Keyboard-driven TUI or browser interface.

## Cost Guardrails

The tool itself is free. External costs come from LLM API usage. InitRunner provides several cost control mechanisms:

-   **Per-run token caps** — stop agents automatically at defined thresholds
-   **Session and daily budgets** — set spending limits per session or per day
-   **Daemon lifetime budgets** — cap total spending over a daemon’s lifetime
-   **80% warnings** — agents alert at 80% of budget before hitting the hard limit
-   **Tool call limits** — restrict the number of external service calls per execution
-   **Execution timeouts** — terminate agents that exceed time limits
-   **Audit trail** — SQLite log of all token usage, tool calls, and execution steps for post-hoc cost analysis

Provider switching (OpenAI today, Anthropic tomorrow) is a single-line YAML change, allowing cost tuning across providers.

### Where It Struggles

The YAML-first approach is less suitable for agents requiring highly dynamic control flow that can’t be expressed declaratively. Complex branching logic, conditional tool routing based on intermediate results, or code-driven decision trees are better handled in Python directly.

No Windows-native support exists — the tool runs on Linux, macOS, and WSL only. Users on native Windows need WSL.

Self-hosting requires DevOps knowledge. Users without server management experience face additional infrastructure costs and maintenance overhead. There’s no managed cloud option — all deployment is self-hosted.

The tool targets developers comfortable with CLI workflows. Non-technical users who prefer GUI-based agent builders will find the terminal-centric interface inaccessible.

**Visit [InitRunner](https://www.initrunner.ai/?ref=ilovefree&utm_source=ilovefree&utm_medium=referral)** — https://www.initrunner.ai/

{ "@context": "https://schema.org", "@type": "FAQPage", "mainEntity": \[ { "@type": "Question", "name": "Is InitRunner really free?", "acceptedAnswer": { "@type": "Answer", "text": "Yes. The software is 100% free and open-source under its license. There are no tiered plans, no usage limits from InitRunner itself, and no licensing fees. The only costs are external: LLM API usage (OpenAI, Anthropic, etc.) and any server infrastructure you use for self-hosting." } }, { "@type": "Question", "name": "What is RAG in InitRunner and how does it work?", "acceptedAnswer": { "@type": "Answer", "text": "RAG stands for Retrieval-Augmented Generation. Point InitRunner at a folder of documents (markdown, PDFs, CSVs) and it automatically chunks, embeds, and indexes them. Your agent then gets a \`search\_documents()\` tool for semantic search over your own knowledge base, with source citations." } }, { "@type": "Question", "name": "Can I deploy an InitRunner agent as an API?", "acceptedAnswer": { "@type": "Answer", "text": "Yes. Run \`initrunner serve\` and your agent becomes an OpenAI-compatible API endpoint at \`/v1/chat/completions\`. It supports streaming responses, authentication, and multi-turn conversations. You can plug it into any OpenAI SDK, custom chat UI, or internal tool that speaks the OpenAI chat format." } }, { "@type": "Question", "name": "How does the memory system work?", "acceptedAnswer": { "@type": "Answer", "text": "InitRunner provides three memory types: semantic (facts the agent remembers), episodic (outcomes from past interactions), and procedural (policies the agent has learned). Agents use \`remember()\` to store facts, \`record\_episode()\` to log outcomes, and \`learn\_procedure()\` to internalize policies." } }, { "@type": "Question", "name": "What happens when an agent hits its token budget?", "acceptedAnswer": { "@type": "Answer", "text": "InitRunner enforces token budgets at multiple levels: per-run, per-session, daily, and per-daemon lifetime. When an agent reaches 80% of its budget, it issues a warning. At the hard limit, execution stops automatically." } } \] }



---