{"id":44799839,"url":"https://github.com/vladkesler/initrunner","last_synced_at":"2026-04-12T17:20:26.254Z","repository":{"id":338676884,"uuid":"1154022019","full_name":"vladkesler/initrunner","owner":"vladkesler","description":"Define AI agent roles in YAML and run them anywhere: CLI, API server, or autonomous daemon","archived":false,"fork":false,"pushed_at":"2026-04-01T23:31:38.000Z","size":7478,"stargazers_count":27,"open_issues_count":2,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-02T02:40:37.785Z","etag":null,"topics":["agent-framework","ai-agents","ai-automation","ai-tools","autonomous-agents","cli","llm","llm-agents","mcp","multi-agent","no-code","openai-compatible","pydantic-ai","python","rag","yaml","yaml-configuration"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vladkesler.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"support-agent/knowledge-base/account-management.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-09T23:41:05.000Z","updated_at":"2026-04-01T14:13:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vladkesler/initrunner","commit_stats":null,"previous_names":["vladkesler/initrunner"],"tags_count":81,"template":false,"template_full_name":null,"purl":"pkg:github/vladkesler/initrunner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladkesler%2Finitrunner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladkesler%2Finitrunner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladkesler%2Finitrunner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladkesler%2Finitrunner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vladkesler","download_url":"https://codeload.github.com/vladkesler/initrunner/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladkesler%2Finitrunner/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31441057,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T15:22:31.103Z","status":"ssl_error","status_checked_at":"2026-04-05T15:22:00.205Z","response_time":75,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-framework","ai-agents","ai-automation","ai-tools","autonomous-agents","cli","llm","llm-agents","mcp","multi-agent","no-code","openai-compatible","pydantic-ai","python","rag","yaml","yaml-configuration"],"created_at":"2026-02-16T13:11:04.137Z","updated_at":"2026-04-05T16:01:29.459Z","avatar_url":"https://github.com/vladkesler.png","language":"Python","readme":"# InitRunner\n\n\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/logo-dark.svg\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"assets/logo-light.svg\"\u003e\n    \u003cimg src=\"assets/logo-light.svg\" alt=\"InitRunner\" width=\"500\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/initrunner/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/initrunner?color=%2334D058\u0026v=1\" alt=\"PyPI version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/initrunner/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/dm/initrunner?color=%2334D058\" alt=\"PyPI downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://hub.docker.com/r/vladkesler/initrunner\"\u003e\u003cimg src=\"https://img.shields.io/docker/pulls/vladkesler/initrunner?color=%2334D058\" alt=\"Docker pulls\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE-MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-%2334D058\" alt=\"MIT OR Apache-2.0\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://ai.pydantic.dev/\"\u003e\u003cimg src=\"https://img.shields.io/badge/PydanticAI-6e56cf?logo=pydantic\u0026logoColor=white\" alt=\"PydanticAI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://discord.gg/GRTZmVcW\"\u003e\u003cimg src=\"https://img.shields.io/badge/Discord-InitRunner%20Hub-5865F2?logo=discord\u0026logoColor=white\" alt=\"Discord\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://initrunner.ai/\"\u003eWebsite\u003c/a\u003e · \u003ca href=\"https://initrunner.ai/docs\"\u003eDocs\u003c/a\u003e · \u003ca href=\"https://hub.initrunner.ai/\"\u003eInitHub\u003c/a\u003e · \u003ca href=\"https://discord.gg/GRTZmVcW\"\u003eDiscord\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  English · \u003ca href=\"README.zh-CN.md\"\u003e简体中文\u003c/a\u003e · \u003ca href=\"README.ja.md\"\u003e日本語\u003c/a\u003e\n\u003c/p\u003e\n\nYAML-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.\n\n```bash\ninitrunner run helpdesk -i                                    # docs Q\u0026A with RAG + memory\ninitrunner run deep-researcher -p \"Compare vector databases\"  # 3-agent research team\ninitrunner run code-review-team -p \"Review the latest commit\" # multi-perspective code review\n```\n\n15 curated starters, 60+ examples, or define your own.\n\n\u003e **v2026.4.6**: Deferred MCP tool loading with schema cache. Unified async bridge. 4 edge-case bug fixes. See the [Changelog](CHANGELOG.md).\n\n## Quickstart\n\n```bash\ncurl -fsSL https://initrunner.ai/install.sh | sh\ninitrunner setup        # wizard: pick provider, model, API key\n```\n\nOr: `uv pip install \"initrunner[recommended]\"` / `pipx install \"initrunner[recommended]\"`. See [Installation](docs/getting-started/installation.md).\n\n### Try a starter\n\nRun `initrunner run --list` for the full catalog. The model is auto-detected from your API key.\n\n| Starter | What it does | Kind |\n|---------|-------------|------|\n| `helpdesk` | Drop your docs in, get a Q\u0026A agent with citations and memory | Agent (RAG) |\n| `code-review-team` | Multi-perspective review: architect, security, maintainer | Team |\n| `deep-researcher` | 3-agent pipeline: planner, web researcher, synthesizer with shared memory | Team |\n| `codebase-analyst` | Index your repo, chat about architecture, learns patterns across sessions | Agent (RAG) |\n| `web-researcher` | Search the web and produce structured briefings with citations | Agent |\n| `content-pipeline` | Topic researcher, writer, editor/fact-checker via webhook or cron | Flow |\n| `telegram-assistant` | Telegram bot with memory and web search | Agent (Daemon) |\n| `email-agent` | Monitors inbox, triages messages, drafts replies, alerts Slack on urgent mail | Agent (Daemon) |\n| `support-desk` | Sense-routed intake: auto-routes to researcher, responder, or escalator | Flow |\n| `memory-assistant` | Personal assistant that remembers across sessions | Agent |\n\nRAG starters auto-ingest on first run. Just `cd` into your project:\n\n```bash\ncd ~/myproject\ninitrunner run codebase-analyst -i   # indexes your code, then starts Q\u0026A\n```\n\n### Build your own\n\n```bash\ninitrunner new \"a research assistant that summarizes papers\"  # generates a role.yaml\ninitrunner run --ingest ./docs/    # or skip YAML entirely, just chat with your docs\n```\n\nBrowse and install community agents from [InitHub](https://hub.initrunner.ai/): `initrunner search \"code review\"` / `initrunner install alice/code-reviewer`.\n\n**Docker**, no install needed:\n\n```bash\ndocker run -d -e OPENAI_API_KEY -p 8100:8100 \\\n    -v initrunner-data:/data ghcr.io/vladkesler/initrunner:latest        # dashboard\ndocker run --rm -it -e OPENAI_API_KEY \\\n    -v initrunner-data:/data ghcr.io/vladkesler/initrunner:latest run -i # chat\n```\n\nSee the [Docker guide](docs/getting-started/docker.md) for more.\n\n## Define an agent in YAML\n\n```yaml\napiVersion: initrunner/v1\nkind: Agent\nmetadata:\n  name: code-reviewer\n  description: Reviews code for bugs and style issues\nspec:\n  role: |\n    You are a senior engineer. Review code for correctness and readability.\n    Use git tools to examine changes and read files for context.\n  model: { provider: openai, name: gpt-5-mini }\n  tools:\n    - type: git\n      repo_path: .\n    - type: filesystem\n      root_path: .\n      read_only: true\n```\n\n```bash\ninitrunner run reviewer.yaml -p \"Review the latest commit\"\n```\n\nThe `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](docs/agents/tool_creation.md) in a single file.\n\n## From chat to autopilot\n\nThe 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.\n\n**Interactive and one-shot:**\n\n```bash\ninitrunner run role.yaml -i              # REPL: chat back and forth\ninitrunner run role.yaml -p \"Scan for security issues\"  # one prompt, one response\n```\n\n**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.\n\n```bash\ninitrunner run role.yaml -a -p \"Scan this repo for security issues and file a report\"\n```\n\n```yaml\nspec:\n  autonomy:\n    compaction: { enabled: true, threshold: 30 }\n  guardrails:\n    max_iterations: 15\n    autonomous_token_budget: 100000\n    autonomous_timeout_seconds: 600\n```\n\nFour 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](docs/orchestration/autonomy.md) · [Guardrails](docs/configuration/guardrails.md).\n\n**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.\n\n```yaml\nspec:\n  triggers:\n    - type: cron\n      schedule: \"0 9 * * 1\"\n      prompt: \"Generate the weekly status report.\"\n    - type: file_watch\n      paths: [./src]\n      prompt_template: \"File changed: {path}. Review it.\"\n    - type: telegram\n      allowed_user_ids: [123456789]\n```\n\n```bash\ninitrunner run role.yaml --daemon   # runs until Ctrl+C\n```\n\nSix 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](docs/core/triggers.md) · [Telegram](docs/getting-started/telegram.md) · [Discord](docs/getting-started/discord.md).\n\n**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.\n\n```bash\ninitrunner run role.yaml --autopilot   # every trigger gets the full autonomous loop\n```\n\n`--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.\n\nYou can also be selective. Set `autonomous: true` on individual triggers and leave the rest as quick single-shot responses.\n\n```yaml\nspec:\n  triggers:\n    - type: telegram\n      autonomous: true          # think, research, then reply\n    - type: cron\n      schedule: \"0 9 * * 1\"\n      prompt: \"Generate the weekly status report.\"\n      autonomous: true          # plan, gather data, write, review\n    - type: file_watch\n      paths: [./src]\n      prompt_template: \"File changed: {path}. Review it.\"\n      # autonomous: false (default) -- quick single response\n```\n\nAgents can self-schedule follow-up tasks within a run. See [Autonomy](docs/orchestration/autonomy.md) · [Guardrails](docs/configuration/guardrails.md).\n\n**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](docs/core/memory.md).\n\n## Security\n\nInitRunner 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.\n\n**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).\n\n**Authorization:** [InitGuard](https://github.com/initrunner/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).\n\n**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).\n\n**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.\n\n**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.\n\n```bash\nexport INITRUNNER_POLICY_DIR=./policies\ninitrunner run role.yaml                  # tool calls + delegation checked against policies\n```\n\nSee [Agent Policy](docs/security/agent-policy.md) · [Security](docs/security/security.md) · [Guardrails](docs/configuration/guardrails.md).\n\n## Why InitRunner\n\n**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.\n\n**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.\n\n**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.\n\n**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.\n\n## Knowledge and memory\n\nPoint 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.\n\n```yaml\nspec:\n  ingest:\n    auto: true\n    sources: [\"./docs/**/*.md\", \"./docs/**/*.pdf\"]\n  memory:\n    semantic:\n      max_memories: 1000\n```\n\n```bash\ninitrunner run role.yaml -i   # auto-ingests on first run, memory + search ready\n```\n\nSee [Ingestion](docs/core/ingestion.md) · [Memory](docs/core/memory.md) · [RAG Quickstart](docs/getting-started/rag-quickstart.md).\n\n## Multi-agent orchestration\n\nChain 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):\n\n```yaml\napiVersion: initrunner/v1\nkind: Flow\nmetadata: { name: email-chain }\nspec:\n  agents:\n    inbox-watcher:\n      role: roles/inbox-watcher.yaml\n      sink: { type: delegate, target: triager }\n    triager:\n      role: roles/triager.yaml\n      sink: { type: delegate, strategy: sense, target: [researcher, responder] }\n    researcher: { role: roles/researcher.yaml }\n    responder: { role: roles/responder.yaml }\n```\n\nRun with `initrunner flow up flow.yaml`. See [Patterns Guide](docs/orchestration/patterns-guide.md) · [Flow](docs/orchestration/flow.md).\n\n## MCP -- plug into any tool ecosystem\n\nAgents can use any [MCP](https://modelcontextprotocol.io/) server as a tool source. Point at a server, and every tool it exposes becomes available to the agent:\n\n```yaml\nspec:\n  tools:\n    - type: mcp\n      transport: stdio\n      command: npx\n      args: [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"./data\"]\n    - type: mcp\n      transport: sse\n      url: https://my-mcp-server.example.com/sse\n```\n\nAgents 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.\n\nGoing the other direction, expose your agents *as* MCP tools so Claude Code, Cursor, Windsurf, and other MCP clients can call them:\n\n```bash\ninitrunner mcp serve agent.yaml          # agent becomes an MCP tool\ninitrunner mcp toolkit --tools search,sql  # expose raw tools, no LLM needed\n```\n\nThe dashboard's [MCP Hub](/mcp) 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.\n\nSee [MCP Gateway](docs/interfaces/mcp-gateway.md) · [Dashboard](docs/interfaces/dashboard.md#mcp-hub-mcp).\n\n## User interfaces\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/screenshot-dashboard.png\" alt=\"InitRunner Dashboard\" width=\"800\"\u003e\u003cbr\u003e\n  \u003cem\u003eDashboard: agents, activity, compositions, and teams at a glance\u003c/em\u003e\n\u003c/p\u003e\n\n```bash\npip install \"initrunner[dashboard]\"\ninitrunner dashboard                  # opens http://localhost:8100\n```\n\nRun agents, build flows visually, and dig through audit trails. Also available as a native desktop window (`initrunner desktop`). See [Dashboard docs](docs/interfaces/dashboard.md).\n\n## Everything else\n\n| Feature | Command / config | Docs |\n|---------|-----------------|------|\n| **Skills** (reusable tool + prompt bundles) | `spec: { skills: [../skills/web-researcher] }` | [Skills](docs/agents/skills_feature.md) |\n| **Team mode** (multi-persona on one task) | `kind: Team` + `spec: { personas: {…} }` | [Team Mode](docs/orchestration/team_mode.md) |\n| **API server** (OpenAI-compatible endpoint) | `initrunner run agent.yaml --serve --port 3000` | [Server](docs/interfaces/server.md) |\n| **Multimodal** (images, audio, video, docs) | `initrunner run role.yaml -p \"Describe\" -A photo.png` | [Multimodal](docs/core/multimodal.md) |\n| **Structured output** (validated JSON schemas) | `spec: { output: { schema: {…} } }` | [Structured Output](docs/core/structured-output.md) |\n| **Evals** (test agent output quality) | `initrunner test role.yaml -s eval.yaml` | [Evals](docs/core/evals.md) |\n| **MCP gateway** (expose agents as MCP tools) | `initrunner mcp serve agent.yaml` | [MCP Gateway](docs/interfaces/mcp-gateway.md) |\n| **MCP toolkit** (tools without an agent) | `initrunner mcp toolkit` | [MCP Gateway](docs/interfaces/mcp-gateway.md) |\n| **Capabilities** (native PydanticAI features) | `spec: { capabilities: [Thinking, WebSearch] }` | [Capabilities](docs/core/capabilities.md) |\n| **Observability** (OpenTelemetry integration) | `spec: { observability: { enabled: true } }` | [Observability](docs/core/observability.md) |\n| **Configure** (switch provider/model on any role) | `initrunner configure role.yaml --provider groq` | [Providers](docs/configuration/providers.md) |\n| **Reasoning** (structured thinking patterns) | `spec: { reasoning: { pattern: plan_execute } }` | [Reasoning](docs/core/reasoning.md) |\n| **Tool search** (on-demand tool discovery) | `spec: { tool_search: { enabled: true } }` | [Tool Search](docs/core/tool-search.md) |\n\n## Architecture\n\n```\ninitrunner/\n  agent/        Role schema, loader, executor, 28 self-registering tools\n  authz.py      InitGuard ABAC policy engine integration\n  runner/       Single-shot, REPL, autonomous, daemon execution modes\n  flow/         Multi-agent orchestration via flow.yaml\n  triggers/     Cron, file watcher, webhook, heartbeat, Telegram, Discord\n  stores/       Document + memory stores (LanceDB, zvec)\n  ingestion/    Extract -\u003e chunk -\u003e embed -\u003e store pipeline\n  mcp/          MCP server integration and gateway\n  audit/        Append-only SQLite audit trail with secret scrubbing\n  middleware.py Server security middleware (auth, rate limit, CORS, headers)\n  services/     Shared business logic layer\n  cli/          Typer + Rich CLI entry point\n```\n\nBuilt on [PydanticAI](https://ai.pydantic.dev/) for the agent framework, Pydantic for config validation, LanceDB for vector search. See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup.\n\n## Distribution\n\n**InitHub:** Browse and install community agents at [hub.initrunner.ai](https://hub.initrunner.ai/). Publish your own with `initrunner publish`. See [Registry](docs/agents/registry.md).\n\n**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](docs/core/oci-distribution.md).\n\n**Cloud deploy:**\n\n[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/template/FROM_REPO?referralCode=...)\n[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/vladkesler/initrunner)\n\n## Documentation\n\n| Area | Key docs |\n|------|----------|\n| Getting started | [Installation](docs/getting-started/installation.md) · [Setup](docs/getting-started/setup.md) · [Tutorial](docs/getting-started/tutorial.md) · [CLI Reference](docs/getting-started/cli.md) |\n| Quickstarts | [RAG](docs/getting-started/rag-quickstart.md) · [Docker](docs/getting-started/docker.md) · [Discord Bot](docs/getting-started/discord.md) · [Telegram Bot](docs/getting-started/telegram.md) |\n| Agents \u0026 tools | [Tools](docs/agents/tools.md) · [Tool Creation](docs/agents/tool_creation.md) · [Tool Search](docs/core/tool-search.md) · [Skills](docs/agents/skills_feature.md) · [Providers](docs/configuration/providers.md) |\n| Intelligence | [Reasoning](docs/core/reasoning.md) · [Intent Sensing](docs/core/intent_sensing.md) · [Autonomy](docs/orchestration/autonomy.md) · [Structured Output](docs/core/structured-output.md) |\n| Knowledge \u0026 memory | [Ingestion](docs/core/ingestion.md) · [Memory](docs/core/memory.md) · [Multimodal Input](docs/core/multimodal.md) |\n| Orchestration | [Patterns Guide](docs/orchestration/patterns-guide.md) · [Flow](docs/orchestration/flow.md) · [Delegation](docs/orchestration/delegation.md) · [Team Mode](docs/orchestration/team_mode.md) · [Triggers](docs/core/triggers.md) |\n| Interfaces | [Dashboard](docs/interfaces/dashboard.md) · [API Server](docs/interfaces/server.md) · [MCP Gateway](docs/interfaces/mcp-gateway.md) |\n| Distribution | [OCI Distribution](docs/core/oci-distribution.md) · [Shareable Templates](docs/getting-started/shareable-templates.md) |\n| Security | [Security Model](docs/security/security.md) · [Agent Policy](docs/security/agent-policy.md) · [Guardrails](docs/configuration/guardrails.md) |\n| Operations | [Audit](docs/core/audit.md) · [Reports](docs/core/reports.md) · [Evals](docs/core/evals.md) · [Doctor](docs/operations/doctor.md) · [Observability](docs/core/observability.md) · [CI/CD](docs/operations/cicd.md) |\n\n## Examples\n\n```bash\ninitrunner examples list               # 60+ agents, teams, and flow projects\ninitrunner examples copy code-reviewer # copy to current directory\n```\n\n## Upgrading\n\nRun `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](docs/operations/deprecations.md).\n\n## Community \u0026 contributing\n\n- [Discord](https://discord.gg/GRTZmVcW): chat, ask questions, share roles\n- [GitHub Issues](https://github.com/vladkesler/initrunner/issues): bug reports and feature requests\n- [Changelog](CHANGELOG.md): release notes\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup and PR guidelines.\n\n## License\n\nLicensed under [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE), at your option.\n\n---\n\n\u003cp align=\"center\"\u003e\u003csub\u003ev2026.4.6\u003c/sub\u003e\u003c/p\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvladkesler%2Finitrunner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvladkesler%2Finitrunner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvladkesler%2Finitrunner/lists"}