Skip to content
INITRUNNER(1)v2026.6.9 · MIT

An init system for AI agents.

Define an agent as a YAML role file. Run it with one command. Your first agent is up in five minutes. Generate the file with initrunner new, pull one from InitHub, or import from PydanticAI or LangChain.

5,000+ tests · 28 tool types · 12+ providers · MIT licensed

Read the quickstartView source on GitHub
curl -fsSL https://initrunner.ai/install.sh | sh
boot loginitrunner v2026.6.9
$ initrunner run agent.yaml [  OK  ] Parsed role file agent.yaml[  OK  ] Resolved provider anthropic[  OK  ] Mounted tools: git, http, shell[  OK  ] Restored memory (3 stores)[  OK  ] Indexed ./docs for retrieval[  OK  ] Opened append-only audit log[  OK  ] Armed triggers: cron, webhook[  OK  ] Reached target Agent Ready agent >
Fig. 1 Cold start to Agent Ready in one command.

01 · INSTALL

Three commands to a running agent.

The installer brings everything, including Python. Works on Linux, macOS, and WSL.

01.1

Install

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

One command. Works on Linux, macOS, and WSL.

01.2

Setup

initrunner setup

Pick a provider, save your API key. Run this once.

01.3

Run

initrunner run

Start a conversation. No config files needed.

Options

Full flag reference in the CLI docs.

02 · ROLE FILES

The role file is the agent.

One YAML file declares the model, the prompt, the tools, and the limits. Check it into git. Review it like code.

agent.yamlyaml
apiVersion: initrunner/v1
kind: Agent
metadata:
  name: code-reviewer
spec:
  role: >
    You review pull requests for bugs,
    style issues, and security flaws.
  model:
    provider: anthropic
    name: claude-sonnet-4-6
  tools:
    - type: git
      permissions: [read]
    - type: filesystem
      root_path: ./repo
  guardrails:
    max_tokens_per_run: 10000
Fig. 2 A complete role file. Validate it with initrunner validate.
terminalrun
$ initrunner run agent.yaml

[  OK  ] Parsed role file agent.yaml
[  OK  ] Resolved provider anthropic
[  OK  ] Mounted tools: git, filesystem
[  OK  ] Reached target Agent Ready

> Review PR #42 for security issues

[tool] git → diff main...pr-42
[tool] filesystem → read src/auth.ts
[done] Review complete. 2 issues found.
Fig. 3 The same file, running.

Read the role file reference →

03 · DASHBOARD

Watch your agents work.

A built-in dashboard for managing agents, building flow pipelines visually, and monitoring runs. Browser or native window.

initrunner dashboard
InitRunner Dashboard, Launchpad. The agent library and one-click runs.
Fig. 4 Launchpad. The agent library and one-click runs.

04 · AUTONOMOUS MODE

Give it the job. Read the report.

Autonomous runs plan the work, execute each step, and adapt on failure. Budgets cap tokens, iterations, and wall-clock time. Add --autopilot and every trigger runs the full loop, including Telegram and Discord.

terminalplan_execute
$ initrunner run researcher.yaml -a \
    -p "Compare top 3 vector databases for production RAG"

[init] Agent: researcher
[init] Strategy: plan_execute
[init] Budget: 10 iterations, 50k tokens

[plan] PHASE 1: creating plan...
[todo] + Compare feature sets         [pending]
[todo] + Benchmark performance        [pending]
[todo] + Evaluate pricing           [pending]
[todo] + Write summary report       [pending]
[plan] finalize_plan(): 4 items locked

[exec] PHASE 2: working...
[todo] ✓ Compare feature sets         [completed]
[todo] ✓ Benchmark performance        [completed]
[budget] 5/10 iter · 21,400/50,000 tokens
[todo] ✓ Evaluate pricing           [completed]
[todo] ✓ Write summary report       [completed]

[done] finish_task(completed)
[done] Report saved to ./output/comparison.md
Fig. 5 A plan_execute run under a budget of 10 iterations and 50k tokens.
terminalautopilot
$ initrunner run assistant.yaml --autopilot

[daemon] Autopilot: agent assistant
[daemon] Triggers: telegram, cron (all autonomous)

[telegram] @alice: "Research quantum error correction breakthroughs"
[init] Strategy: plan_execute
[exec] Working... 4 steps
[done] finish_task(completed)
[done] Reply sent to @alice
Fig. 6 Autopilot. Triggers run the loop unattended.
04.1

Plan, execute, adapt

Four reasoning strategies orchestrate how your agent thinks. It breaks tasks into steps, works through each one, and self-corrects when something fails.

04.2

Budgets, enforced

Agents see their remaining tokens, iterations, and wall-clock time at every turn. They finish the job before hitting a limit.

04.3

Autopilot

Run with --autopilot and every trigger fires the full autonomous loop. Telegram messages, Discord pings, cron jobs, webhooks. Your agent thinks before it replies.

Read the autonomy guide →

05 · SPECIFICATION

Standard equipment.

Everything below ships in the box. MIT licensed, no paid tier.

05.1
Agents are config, not code
Run initrunner new with a description and it writes the config for you. Start from a template, import existing agents, or write every field by hand. No framework to learn, just a file you can check into git.
05.2
An audit log you cannot edit
Every input, tool call, and output is written to an immutable SQLite log. Plug in OpenTelemetry for distributed tracing in production. Full auditability, no setup required.
05.3
Providers swap in one line
Run on Anthropic today, switch to OpenAI tomorrow. Run initrunner configure or change one line in your YAML. No vendor lock-in.
05.4
Triggers and schedules
Wire up cron schedules, file watchers, webhooks, or Telegram and Discord bots. Your agents run unattended: on a timer, on file changes, or in a chat.
05.5
28 tool types, plus yours
28 built-in tool types: filesystem, HTTP, MCP, shell, git, search, and more. Or write a Python function and plug it in. Cherry-pick with --tools or enable everything with --tool-profile all.
05.6
Images, audio, video, documents
Attach images, audio, video, or documents to any prompt. Vision, transcription, and document parsing work across CLI, API, and dashboard. Use --attach or add attachments in YAML.

06 · CAPABILITIES

Built in, not bolted on.

RAG, memory, 28 tool types, an OpenAI-compatible API server, and a live dashboard. Configure in YAML, or try the CLI flags for a quick start.

06.1SERVE

Serve it as an API.

Run ⁨initrunner run --serve⁩ and your agent becomes an OpenAI-compatible API. /v1/chat/completions with streaming, auth, and multi-turn conversations. Plug it into any OpenAI SDK, chat UI, or internal tool.

One command. OpenAI-compatible. Zero config.

terminal
$ initrunner run agent.yaml --serve --port 8000

[serve] Agent: research-assistant
[serve] Endpoint: /v1/chat/completions
[serve] Auth: Bearer token ✓
[serve] Streaming: enabled ✓
[serve] Listening on http://0.0.0.0:8000
Fig. 7 An agent served at /v1/chat/completions.

06.2GUARDRAILS

Budgets are enforced, not suggested.

A ⁨guardrails:⁩ block sets per-run token caps, session budgets, and daily or lifetime daemon budgets in YAML. Agents warn at 80 % of a limit and stop at 100 %. No surprise bills from runaway loops. Add content policies for PII redaction, or initguard for CEL-based access control.

Per-run caps. Daily budgets. Automatic enforcement.

agent.yaml
guardrails:
  max_tokens_per_run: 10000
  max_tool_calls: 15
  session_token_budget: 100000
  daemon_token_budget: 500000
  daemon_daily_token_budget: 100000

# Agents stop at the limit. Warn at 80%.
# No surprise bills from runaway loops.
Fig. 8 Guardrails in the role file.

06.3RETRIEVAL

Retrieval over your own files.

Point at a folder of markdown, PDFs, or CSVs. InitRunner chunks, embeds, and indexes them automatically. Your agent gets search_documents() as a tool: semantic search over your own knowledge base, with source citations. No vector database to manage. No embedding pipeline to wire up. For a quick start, initrunner run --ingest ./docs/ gives you the same RAG pipeline from a single CLI flag.

One CLI flag or three lines of YAML. Semantic search over your own docs.

terminal / agent.yaml
# CLI: zero-config RAG
$ initrunner run --ingest ./docs/

# YAML: full control
ingest:
  sources:
    - "./docs/**/*.md"
    - "./reports/*.pdf"
  chunking:
    strategy: paragraph
    chunk_size: 512
Fig. 9 RAG from a flag or from YAML.

06.4MEMORY

Memory that survives the session.

Session persistence picks up where you left off. Three memory types (semantic, episodic, and procedural) let agents remember() facts, record_episode() outcomes, and learn_procedure() policies. A consolidation pass rolls up episodic records into durable knowledge. Your support agent remembers the customer’s last issue. Your research agent builds on yesterday’s findings. In ephemeral mode, memory is on by default. Use --resume to pick up where you left off.

Three memory types. Auto-consolidation. On by default in ephemeral mode.

terminal / agent.yaml
# CLI: memory on by default
$ initrunner run
$ initrunner run --resume
$ initrunner run --no-memory

# YAML: full control
memory:
  semantic:
    max_memories: 1000
  episodic:
    max_episodes: 500
  procedural:
    max_procedures: 100
  consolidation:
    enabled: true
    interval: after_session
Fig. 10 Three memory types, consolidated.

06.5SKILLS

Skills are files too.

Bundle tools and prompt instructions into a single SKILL.md file. YAML frontmatter for tools and requirements, Markdown body for the prompt. Drop it in a well-known directory and agents auto-discover it, or reference it explicitly. Prompts stay lean: agents load a skill with activate_skill only when they need it.

One SKILL.md. Auto-discovered or explicit. Every agent gets it.

SKILL.md
---
name: web-research
tools:
  - type: web_reader
  - type: filesystem
    root_path: ./output
requires:
  env: [SEARCH_API_KEY]
---

You are a web research specialist.
Search the web, extract key findings,
and save structured summaries to ./output.
Always cite your sources.
Fig. 11 A complete skill in one file.

06.6SENSE

The right agent finds itself.

Describe your task. InitRunner finds the right agent from your library and runs it. That's --sense. In flow pipelines, set strategy: sense on a delegate sink and each message routes to the best-matching agent.

CLI or flow. The right agent finds itself.

terminal
$ initrunner run --sense -p "analyze this CSV and find trends"

[sense] Scanning ./roles/, ~/.initrunner/roles/
[sense] Scored 4 candidates
[sense] Selected: csv-analyst  (score 0.87, gap +0.41)

Agent: csv-analyst
Running...

# Same scoring in flow pipelines:
# sink:
#   type: delegate
#   strategy: sense
#   target: [researcher, responder, escalator]
Fig. 12 Routing by score with --sense.

07 · PROVIDERS

Twelve providers. One line of YAML.

Set provider: in the role file or let it auto-detect from environment variables. Switch with a one-line change. No SDK migration.

Providerprovider:
Anthropicanthropic
OpenAIopenai
Google Geminigoogle
Groqgroq
Mistralmistral
Coherecohere
AWS Bedrockbedrock
xAIxai
Ollama (local)ollama
OpenRouteropenai + base_url
DeepSeekopenai + base_url
Azure OpenAIopenai + base_url
Any OpenAI-compatible endpoint: base_url points at vLLM, LiteLLM, or your own server.

Table 1 Supported providers. Full matrix in the provider docs.