InitRunner

InitRunner is an open-source CLI tool (GitHub) 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

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/