GitHub - vladkesler/initrunner: Define AI agent roles in YAML and run them anywhere: CLI, API server, or autonomous daemon

Website · Docs · InitHub · Discord

English · 简体中文 · 日本語

YAML-first AI agent platform. Define an agent's role, tools, knowledge base, and memory in one file. Run it as an interactive chat, a one-shot command, an autonomous daemon with cron/webhook/file-watch triggers, a Telegram/Discord bot, or an OpenAI-compatible API. RAG and persistent memory work out of the box. Manage everything from a web dashboard or native desktop app. Install with curl or pip, no containers required.

initrunner run helpdesk -i                                    # docs Q&A with RAG + memory
initrunner run deep-researcher -p "Compare vector databases"  # 3-agent research team
initrunner run code-review-team -p "Review the latest commit" # multi-perspective code review

15 curated starters, 60+ examples, or define your own.

v2026.4.10: pre-flight YAML validation, auto-ingest of stale RAG sources on every run, initrunner new --run to go from prompt to output in one command, and an inline API-key prompt on first run. See the Changelog.

Quickstart

curl -fsSL https://initrunner.ai/install.sh | sh
initrunner setup        # wizard: pick provider, model, API key

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

Try a starter

Run initrunner run --list for the full catalog. The model is auto-detected from your API key.

RAG starters auto-index on every run; initrunner run picks up new and edited files automatically. Just cd into your project:

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

Build your own

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

initrunner new "a regex explainer" --run "what does ^[a-z]+$ match?"
# one-liner: generate and execute in a single command

initrunner run --ingest ./docs/    # or skip YAML entirely, just chat with your docs

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

Docker, no install needed:

docker run -d -e OPENAI_API_KEY -p 8100:8100 \
    -v initrunner-data:/data ghcr.io/vladkesler/initrunner:latest        # dashboard
docker run --rm -it -e OPENAI_API_KEY \
    -v initrunner-data:/data ghcr.io/vladkesler/initrunner:latest run -i # chat

See the Docker guide for more.

Define an agent in YAML

apiVersion: initrunner/v1
kind: Agent
metadata:
  name: code-reviewer
  description: Reviews code for bugs and style issues
spec:
  role: |
    You are a senior engineer. Review code for correctness and readability.
    Use git tools to examine changes and read files for context.
  model: { provider: openai, name: gpt-5-mini }
  tools:
    - type: git
      repo_path: .
    - type: filesystem
      root_path: .
      read_only: true

initrunner run reviewer.yaml -p "Review the latest commit"

The model: section 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. 28 built-in tools (filesystem, git, HTTP, Python, shell, SQL, search, email, Slack, MCP, audio, PDF extraction, CSV analysis, image generation) and you can add your own in a single file.

From chat to autopilot

The same YAML file works across four escalating modes. You start by chatting with it. When it works, you let it run on its own. When you trust it, you deploy it as a daemon. No rewrite between stages.

Interactive and one-shot:

initrunner run role.yaml -i              # REPL: chat back and forth
initrunner run role.yaml -p "Scan for security issues"  # one prompt, one response

Autonomous: Add -a and the agent keeps going. It builds a task list, works through each item, reflects on progress, and finishes when everything is done. You set the budget so it can't run away.

initrunner run role.yaml -a -p "Scan this repo for security issues and file a report"

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

Four reasoning strategies control how the agent thinks through multi-step work: react (default), todo_driven, plan_execute, and reflexion. Budget enforcement, iteration limits, timeout, and spin guards (consecutive turns with no tool calls) keep autonomous runs bounded. See Autonomy · Guardrails.

Daemon: Add triggers and switch to --daemon. The agent runs continuously, reacting to cron schedules, file changes, webhooks, Telegram messages, or Discord mentions. Each event fires a single prompt-response cycle.

spec:
  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]

initrunner run role.yaml --daemon   # runs until Ctrl+C

Six trigger types: cron, webhook, file_watch, heartbeat, telegram, and discord. The daemon hot-reloads role changes without restarting, enforces daily and lifetime token budgets, and runs up to 4 triggers concurrently. See Triggers · Telegram · Discord.

Autopilot: A daemon responds. An autopilot thinks, then responds. Someone messages your Telegram bot "find me flights from NYC to London next week" -- in daemon mode, you get one shot at an answer. In autopilot, the agent searches the web, compares options, checks dates, and sends back something worth reading.

initrunner run role.yaml --autopilot   # every trigger gets the full autonomous loop

--autopilot is --daemon where every trigger runs multi-step autonomous execution instead of single-shot. Same guardrails as -a: iteration limits, token budgets, spin guards, finish_task. The agent plans, uses tools, reflects, and replies when it's done.

You can also be selective. Set autonomous: true on individual triggers and leave the rest as quick single-shot responses.

spec:
  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."
      # autonomous: false (default) -- quick single response

Agents can self-schedule follow-up tasks within a run. See Autonomy · Guardrails.

Memory carries across everything. Episodic, semantic, and procedural memory persist across interactive sessions, autonomous runs, and daemon triggers. After each session, consolidation extracts durable facts from episode history using an LLM. The agent doesn't just run. It learns. See Memory.

Security

InitRunner ships 12 security layers. They're opt-in via the security: config key, not on by magic, but they're integrated and ready to use. Roles without a security: section get safe defaults. The point is that these capabilities exist in the box rather than being something you bolt on from a third-party library six months into production.

Input: Server middleware (Bearer auth with timing-safe comparison, rate limiting, body size limits, HTTPS enforcement, security headers, CORS). Content policy engine (profanity filter, blocked-pattern matching, prompt length limits, optional LLM topic classifier). Input guard capability (PydanticAI before_run hook that validates prompts before the agent starts).

Authorization: InitGuard ABAC policy engine (agents get identity from role metadata, every tool call and delegation checked against CEL policies). Argument-level permission rules (per-tool allow/deny glob patterns, deny-wins precedence). SQL authorization callbacks (blocks dangerous operations at the engine level).

Execution: PEP 578 audit hook sandbox (per-thread enforcement of filesystem write restrictions, subprocess blocking, private-IP network blocking, dangerous-module import blocking, eval/exec blocking). Docker container sandboxing (read-only rootfs, memory/CPU limits, network isolation, pid limits). Environment variable scrubbing (prefix and suffix matching strips sensitive keys from every subprocess environment).

Budget: Token-bucket rate limiting for API requests. Token budgets at five granularities: per-run, per-session, per-autonomous-run, per-daemon-daily, and per-daemon-lifetime.

Audit: Append-only SQLite trail with automatic secret scrubbing (16 regex patterns covering GitHub tokens, AWS keys, Stripe keys, Slack tokens, and more). Every tool call, delegation event, and security violation is logged.

export INITRUNNER_POLICY_DIR=./policies
initrunner run role.yaml                  # tool calls + delegation checked against policies

See Agent Policy · Security · Guardrails.

Why InitRunner

A YAML file is the agent. One file. Readable, diffable, PR-reviewable. You open it and know what the agent does: which model, which tools, what knowledge sources, what guardrails. No Python class hierarchy to learn before you can configure a tool. New team members read the YAML and understand. You review agent changes in pull requests like any other config.

Same file, different flag. The agent you prototyped interactively with -i is the exact same one you deploy as a daemon with --daemon. No rewrite, no deployment adapter, no "production mode" that works differently from development. You pick the execution mode at runtime with a flag, not at design time with an architecture decision.

Security is in the box, not bolted on. Most agent frameworks treat security as "add auth middleware when you get to production." InitRunner ships with a policy engine, PII redaction, sandboxing, tool authorization, and audit logging already integrated. You turn them on with config, not with a weekend of plumbing.

Autonomy with brakes. The agent runs unsupervised, but it can't run away. Token budgets, iteration limits, wall-clock timeouts, and spin guards are all declarative YAML config. You decide how much rope to give it before a single autonomous run starts.

Knowledge and memory

Point your agent at a directory. It extracts, chunks, embeds, and indexes your documents. During conversation, the agent searches the index automatically and cites what it finds. Memory persists across sessions.

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

initrunner run role.yaml -i   # auto-indexes new/changed files, memory + search ready

See Ingestion · Memory · RAG Quickstart.

Multi-agent orchestration

Chain agents together. One agent's output feeds into the next. Sense routing auto-picks the right target per message (keyword matching first, single LLM call to break ties):

apiVersion: initrunner/v1
kind: Flow
metadata: { name: email-chain }
spec:
  agents:
    inbox-watcher:
      role: roles/inbox-watcher.yaml
      sink: { type: delegate, target: triager }
    triager:
      role: roles/triager.yaml
      sink: { type: delegate, strategy: sense, target: [researcher, responder] }
    researcher: { role: roles/researcher.yaml }
    responder: { role: roles/responder.yaml }

Run with initrunner flow up flow.yaml. See Patterns Guide · Flow.

MCP -- plug into any tool ecosystem

Agents can use any MCP server as a tool source. Point at a server, and every tool it exposes becomes available to the agent:

spec:
  tools:
    - type: mcp
      transport: stdio
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "./data"]
    - type: mcp
      transport: sse
      url: https://my-mcp-server.example.com/sse

Agents can consume multiple MCP servers alongside built-in tools. Three transports: stdio (local processes), sse (Server-Sent Events), and streamable-http. Tool filtering (tool_filter / tool_exclude) and namespacing (tool_prefix) keep things clean when servers expose many tools.

Going the other direction, expose your agents as MCP tools so Claude Code, Cursor, Windsurf, and other MCP clients 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

The dashboard's MCP Hub shows every configured server across all agents, lets you test any tool in isolation via the Playground, and visualizes the server-agent topology on a drag-and-drop canvas.

See MCP Gateway · Dashboard.

User interfaces

Dashboard: agents, activity, compositions, and teams at a glance

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

Run agents, build flows visually, and dig through audit trails. Also available as a native desktop window (initrunner desktop). See Dashboard docs.

Everything else

Architecture

initrunner/
  agent/        Role schema, loader, executor, 28 self-registering tools
  authz.py      InitGuard ABAC policy engine integration
  runner/       Single-shot, REPL, autonomous, daemon execution modes
  flow/         Multi-agent orchestration via flow.yaml
  triggers/     Cron, file watcher, webhook, heartbeat, Telegram, Discord
  stores/       Document + memory stores (LanceDB, zvec)
  ingestion/    Extract -> chunk -> embed -> store pipeline
  mcp/          MCP server integration and gateway
  audit/        Append-only SQLite audit trail with secret scrubbing
  middleware.py Server security middleware (auth, rate limit, CORS, headers)
  services/     Shared business logic layer
  cli/          Typer + Rich CLI entry point

Built on PydanticAI for the agent framework, Pydantic for config validation, LanceDB for vector search. See CONTRIBUTING.md for dev setup.

Distribution

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

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.

Cloud deploy:

Documentation

Examples

initrunner examples list               # 60+ agents, teams, and flow projects
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, or --fix --yes for CI. See Deprecations.

Community & contributing

• Discord: chat, ask questions, share roles
• GitHub Issues: bug reports and feature requests
• Changelog: release notes

Contributions welcome! See CONTRIBUTING.md for dev setup and PR guidelines.

License

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

_v2026.4.10