InitRunner

Website · Docs · InitHub · Discord

English · 简体中文 · 日本語

Define an agent in one YAML file. Chat with it. When it works, let it run autonomously. When you trust it, deploy it as a daemon that reacts to cron schedules, file changes, webhooks, and Telegram messages. Same file the whole way. No rewrite between prototyping and production. Prefer a curated outcome without YAML? Use always-on services.

Agent files are simpler now

You used to wrap every agent in apiVersion, kind, metadata, and spec. The file is the agent now: a name, a prompt, the tools.

Nothing you already have breaks. Convert a file or folder when you want:

initrunner doctor --fix PATH --yes

That keeps a .bak copy. How the rewrite works.

Quickstart

curl -fsSL https://initrunner.ai/install.sh | sh
initrunner setup        # wizard: pick provider, model, API key
initrunner run -i       # chat (or press Enter on the post-setup menu)
initrunner run memory -i

Or: uv pip install "initrunner[recommended]" / pipx install "initrunner[recommended]". See Installation.

New to InitRunner? Start with the five commands you'll actually use.

Starters

Browse the catalog with initrunner run --list. The model is auto-detected from your API key. Start with memory (API key only). helpdesk expects docs in ./knowledge-base/. scout needs initrunner[search].

Build your own

initrunner new "a research assistant that summarizes papers"
# generates agent.yaml, then asks: "Run it now? [Y/n]"

initrunner new --offline           # build via a structured form, no LLM call
initrunner run --ingest ./docs/    # skip YAML entirely, just chat with your docs

--run generates and executes in one command. A real session:

$ initrunner new "a regex explainer" --run 'what does ^[a-z]+$ match?'
╭────────── regex-explainer -- VALID ──────────╮
│ name: regex-explainer                        │
│ model: openai:gpt-5-mini                     │
│ prompt: You explain regular expressions.     │
│ ...                                          │
╰──────────────────────────────────────────────╯
Created agent.yaml

1) Brief summary
- Matches a non-empty string made only of ASCII lowercase letters a–z,
  from start to end (no digits, spaces, punctuation, or uppercase letters).
...
3) Example matches (6–10)
- "a"
- "abc"
- "lowercase"
...

Browse community agents at InitHub: initrunner search "code review" / initrunner install alice/code-reviewer.

Docker:

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

One file, four modes

Here's an agent file:

name: code-reviewer
description: Reviews code for bugs and style issues
model: openai:gpt-5-mini
prompt: |
  You are a senior engineer. Review code for correctness and readability.
  Use git tools to examine changes and read files for context.
tools:
  - git:
      repo_path: .
  - filesystem:
      root_path: .
      read_only: true

That file works four ways:

initrunner run reviewer.yaml -i                          # interactive REPL
initrunner run reviewer.yaml -p "Review PR #42"          # one prompt, one response
initrunner run reviewer.yaml -a -p "Audit the whole repo"  # autonomous loop
initrunner run reviewer.yaml --daemon                    # runs on triggers

The model: block is optional. Omit it and InitRunner auto-detects from your API key. Works with Anthropic, OpenAI, Google, Groq, Mistral, Cohere, xAI, OpenRouter, Ollama, and any OpenAI-compatible endpoint.

Fallback and caching

A daemon that dies when its provider throws a 500 isn't much of a daemon. List fallback models and the run retries each in order on API errors:

model:
  provider: anthropic
  name: claude-sonnet-4-5-20250929
  prompt_cache: true    # provider-native prompt caching (Anthropic, Bedrock)
  fallback: [openai:gpt-5-mini, mistral:mistral-large-latest]
  concurrency: { max_running: 4 }

concurrency caps in-flight model requests, so ten agents in one flow sharing an API key stay under the provider's rate limit. See Providers.

Autonomous

Add -a and the agent builds a task list, works each item, reflects on progress, and stops when everything's done. Four reasoning strategies control how: react (default), todo_driven, plan_execute, reflexion.

autonomy:
  compaction: { enabled: true, threshold: 30 }
guardrails:
  max_iterations: 15
  autonomous_token_budget: 100000
  autonomous_timeout_seconds: 600

Spin guards catch loops without progress. History compaction summarizes old context so long runs don't exhaust the token window. Iteration, token, and wall-clock caps bound every run. See Autonomy · Guardrails.

Daemon

Add triggers and switch to --daemon. The agent runs continuously. Each event fires one prompt-response cycle.

triggers:
  - type: cron
    schedule: "0 9 * * 1"
    prompt: "Generate the weekly status report."
  - type: file_watch
    paths: [./src]
    prompt_template: "File changed: {path}. Review it."
  - type: telegram
    allowed_user_ids: [123456789]

Seven trigger types: cron, webhook, file_watch, heartbeat, telegram, discord, slack. The daemon hot-reloads role changes without restarting and runs up to four triggers concurrently. See Triggers.

Always-on services

When you want a productized always-on outcome without authoring YAML, use services instead of hand-rolling a daemon role. Start once, check status, force a tick, pause cleanly:

initrunner service list
initrunner service start collector acme.com    # Linux; needs initrunner[search]
initrunner service status collector
initrunner service run collector               # one tick now (no waiting on cron)
initrunner service stop collector              # --purge deletes local instance data

Shipped first: collector (scheduled monitoring for a company, domain, or topic). Instance state lives under ~/.initrunner/services/. See Always-on Services.

Autopilot

--autopilot is --daemon plus the autonomous loop on every trigger. A Telegram message like "find me flights from NYC to London next week" in daemon mode gets one LLM turn. In autopilot, the agent searches flights, compares options, checks dates, and replies with a shortlist.

initrunner run role.yaml --autopilot

Or go selective: set autonomous: true on individual triggers, leave the rest single-shot.

triggers:
  - type: telegram
    autonomous: true          # think, research, then reply
  - type: cron
    schedule: "0 9 * * 1"
    prompt: "Generate the weekly status report."
    autonomous: true          # plan, gather data, write, review
  - type: file_watch
    paths: [./src]
    prompt_template: "File changed: {path}. Review it."
    # default: single response

Memory across modes

Semantic memory (facts the agent learns), episodic memory (what happened in past sessions), and procedural memory (how the agent prefers to solve things) persist across interactive sessions, autonomous runs, and daemon triggers. After each session, an LLM consolidates durable facts into the store. Knowledge accumulates over time, not just within a single run.

Agents that learn

Point your agent at a directory. It extracts, chunks, embeds, and indexes your documents automatically. During conversation, the agent searches the index and cites what it finds. New and changed files re-index on every run.

ingest:
  auto: true
  sources: ["./docs/**/*.md", "./docs/**/*.pdf"]
memory:
  semantic:
    max_memories: 1000

cd ~/myproject
initrunner run reader -i   # indexes your code, then starts Q&A

Consolidation is the interesting part. After each session, an LLM reads the conversation and distills it into the semantic store. Facts the agent learns during a Tuesday debugging session show up when it's reviewing code on Thursday. Shared memory across flows lets teams of agents build knowledge together. See Memory · Ingestion · RAG Quickstart.

Security

Five controls ship with the framework and turn on via config keys. Roles without a security: section get safe defaults.

Input validation. A content policy engine (blocked patterns, prompt length limits, optional LLM topic classifier) plus an input guard capability validate prompts before the agent starts.

Tool authorization. InitGuard ABAC policy engine checks every tool call and delegation against CEL policies. Per-tool allow/deny glob patterns enforce argument-level permissions.

Sandboxed code execution. Audit hooks stop python tools from writing outside allowed paths, spawning subprocesses, reaching private IPs, loading native libraries, or starting new threads. For stronger isolation, Bubblewrap on Linux or Docker anywhere runs shell and python tools with no network, a read-only filesystem, and memory and CPU caps.

Tamper-evident audit trail. Every run writes to an append-only SQLite audit log, HMAC-SHA256 signed over the previous record's hash. initrunner audit verify-chain detects any middle-row mutation, reorder, or deletion. Secrets are scrubbed on write.

Encrypted credential vault. initrunner vault init creates ~/.initrunner/vault.enc, encrypted with Fernet + scrypt from your passphrase. API keys resolve from env vars first, then the vault, so existing api_key_env: and ${VAR} placeholders keep working.

security:
  tools:
    audit_hooks_enabled: true
    block_private_ips: true
  content:
    max_prompt_length: 10000
    blocked_input_patterns: ["(?i)rm -rf /"]

See Security · Bubblewrap · Docker sandbox · Agent Policy · Credential Vault · Audit Chain · Guardrails.

Telemetry. InitRunner can send anonymous usage data (which command ran, version, OS, error type, tied to a random id) to guide what to build next. It is opt-in: the CLI asks once on the first interactive run and sends nothing until you agree. No prompts, files, paths, or keys are sent. Manage it with initrunner telemetry enable/disable (or DO_NOT_TRACK=1). See Telemetry.

Cost control

USD budgets cap daemon spend. Hit the cap and triggers stop firing until the window resets.

guardrails:
  daemon_daily_cost_budget: 5.00    # USD per day
  daemon_weekly_cost_budget: 25.00  # USD per week

Cost estimation uses genai-prices to compute spend per model and provider. Every run logs its cost to the audit trail. The dashboard plots cost across agents and time ranges. See Cost Tracking.

Memory footprint

A plain agent process runs at 150 to 220 MB of RSS. Nearly all of that is the Python AI stack (provider SDK, PydanticAI, Pydantic); InitRunner's own code adds about 7 MB, and LanceDB only loads if the role uses RAG or vector memory.

That cost is per process, not per agent. Adding an agent to a running process costs about 1 MB, because the stack is already loaded: a group of five agents served together measures about 145 MB, against about 142 MB for one. Ten agents is one ~150 MB process, not 2 GB. flow up runs a whole flow in one process, a group runs unrelated agents in one process, and --serve / --daemon keep that process warm instead of paying startup cost per task. See Memory Footprint for the measured breakdown and container sizing tips.

Multi-agent orchestration

Chain agents into flows. One agent's output feeds the next.

name: email-chain
agents:
  inbox-watcher:
    use: roles/inbox-watcher.yaml
    then: { to: triager }
  triager:
    use: roles/triager.yaml
    then: { to: [researcher, responder], strategy: sense }
  researcher: { use: roles/researcher.yaml }
  responder: { use: roles/responder.yaml }

initrunner flow up flow.yaml

Sense routing picks the right target per message using keyword scoring first (zero API calls); only ambiguous cases fall back to an LLM tiebreak.

Team mode gives multiple perspectives on one task without a full flow. Define the agents in one file and pick a run: preset: sequential (linear handoff), parallel (independent and concurrent), debate (multi-round argumentation with synthesis), or ensemble (all answer the same task, then a majority vote, a weighted pick, or an LLM judge selects the winner). See Patterns Guide · Team Mode · Flow.

Agents that ship together but don't work together

Not every set of agents is a pipeline. Sometimes you just have three agents and one place to put them. List them and you get a group: no handoffs, no coordinator, no run order.

name: desk
agents:
  intake:     { use: roles/intake.yaml }
  researcher: { use: roles/researcher.yaml }
  writer:     { use: roles/writer.yaml }

initrunner run desk.yaml --agent intake -p "order #4412 never arrived"
initrunner run desk.yaml --sense -p "write the customer reply"   # picks a member
initrunner run desk.yaml --serve                                 # all three, one process

A member picked with --agent runs exactly as its own file does, so REPL, autonomous mode, attachments, and reports all work unchanged. --serve gives each member an OpenAI model ID, so any OpenAI client picks the agent the way it picks a model:

$ curl -s localhost:8000/v1/models | jq -c '.data[].id'
"intake"
"researcher"
"writer"

--daemon runs every member's triggers in one process, and initrunner mcp serve desk.yaml turns each into an MCP tool. For Kubernetes or Argo CD, mount the group next to its role files and point the container at it: adding an agent is one new file plus one line.

You are not paying for a runtime per agent. The Python AI stack loads once and every member shares it, so each extra agent costs about 1 MB: measured, one agent served alone is about 142 MB and five together about 145 MB. Ten agents is one ~150 MB container, not ten. See Grouped Agents and Memory Footprint.

MCP and interfaces

Agents consume any MCP server as a tool source (stdio, SSE, streamable-http). Going the other direction, expose your agents as MCP tools so Claude Code, Cursor, and Windsurf can call them:

initrunner mcp serve agent.yaml          # agent becomes an MCP tool
initrunner mcp toolkit --tools search,sql  # expose raw tools, no LLM needed

See MCP Gateway.

Dashboard: run agents, build flows, dig through audit trails

pip install "initrunner[dashboard]"
initrunner dashboard                  # opens http://localhost:8100

Also available as a native desktop window (initrunner desktop). See Dashboard.

Everything else

Architecture

initrunner/
  agent/             Role schema, loader, executor, self-registering tools
  runner/            Single-shot, REPL, autonomous, daemon execution modes
  service_catalog/   Shipped always-on service templates (collector, …)
  flow/              Multi-agent orchestration via flow.yaml
  triggers/          Cron, file watcher, webhook, heartbeat, Telegram, Discord, Slack
  stores/            Document + memory stores (LanceDB)
  ingestion/         Extract, chunk, embed, store pipeline
  mcp/               MCP server integration and gateway
  audit/             Append-only SQLite audit trail with secret scrubbing
  services/          Shared business logic (incl. always-on lifecycle)
  cli/               Typer + Rich CLI entry point

Built on PydanticAI. See CONTRIBUTING.md for dev setup.

Distribution

InitHub: Browse and install community agents at hub.initrunner.ai. Publish your own with initrunner publish.

OCI registries: Push role bundles to any OCI-compliant registry: initrunner publish oci://ghcr.io/org/my-agent --tag 1.0.0. See OCI Distribution.

Documentation

Examples

initrunner examples list               # browse all agents, teams, and flows
initrunner examples copy code-reviewer # copy to current directory

Upgrading

Run initrunner doctor --role role.yaml to check any role file for deprecated fields, schema errors, and spec version issues. Add --fix to auto-repair. Use --flow flow.yaml to validate an entire flow and its referenced roles. See Deprecations.

Community

• Discord: chat, ask questions, share roles
• GitHub Issues: bug reports and feature requests
• Changelog: release notes
• CONTRIBUTING.md: dev setup and PR guidelines

License

Licensed under MIT or Apache-2.0, at your option.

_v2026.8.8