Concepts & Architecture

This page gives you a mental model of how InitRunner works before you dive into specific features.

The Role File

Every InitRunner agent starts with a role file — a single YAML document that describes what the agent is, what it can do, and how it should behave. The format follows a Kubernetes-style structure:

apiVersion: initrunner/v1
kind: Agent
metadata:
  name: my-agent
  description: What this agent does
  tags: [category, purpose]
spec:
  role: |
    System prompt goes here.
  model:
    provider: openai
    name: gpt-4o-mini
  tools: [...]
  memory: { ... }
  ingest: { ... }
  triggers: [...]
  sinks: [...]
  autonomy: { ... }
  reasoning: { ... }
  guardrails: { ... }

Everything except metadata and spec.role is optional — a minimal agent only needs a name and a system prompt.

Architecture Overview

Input — An agent run is initiated by one of three paths: loading a role file directly, interactive CLI input, or an event trigger (cron, file watch, webhook, Telegram, Discord). Prompts can include multimodal attachments (images, audio, video, documents) — see Multimodal Input.

Runtime — The parser validates the YAML and hands it to the LLM Adapter — the internal client object that wraps a specific provider SDK (OpenAI, Anthropic, Google, etc.). This is distinct from the spec.model.provider string in your role file, which is just the name used to select the adapter. The adapter creates an agent that orchestrates tool calls, memory reads/writes, and document searches during execution.

Output — Results flow to configured sinks (Slack, email, file, delegate to another agent), the audit log (SQLite), and back to the caller as a response.

Core Building Blocks

Tools

Tools give agents the ability to act. InitRunner supports 27 configurable tool types plus auto-registered tools:

Each tool is sandboxed by the guardrails system. See Tools for the full reference.

Skills

Skills are reusable prompt-and-tool bundles that can be attached to any agent. They let you share common capabilities (e.g., "summarize a webpage", "query a database") across multiple agents without duplicating configuration. See Skills.

Memory

InitRunner's memory system has two distinct parts:

Session persistence (short-term) — Conversation history is saved to SQLite during REPL and daemon runs. Use --resume to reload the most recent session. This is not a "memory type" — it's automatic when spec.memory is configured and is always available.

Long-term memory types — Three typed stores backed by vector embeddings:

• Semantic — Facts and knowledge. The agent stores and retrieves these explicitly via remember() and recall().
• Episodic — Records of what happened during tasks — outcomes, decisions, errors. Auto-captured in autonomous and daemon modes, or written explicitly via record_episode().
• Procedural — Learned policies and patterns, stored via learn_procedure() and auto-injected into the system prompt on every run.

Automatic consolidation extracts durable semantic facts from episodic records using an LLM. See Memory.

Ingestion & RAG

The ingestion pipeline converts documents into searchable vector embeddings:

1. Glob source files
2. Extract text (Markdown, PDF, DOCX, CSV, HTML, JSON)
3. Chunk into overlapping segments
4. Embed with a provider model
5. Store in LanceDB

At runtime, the auto-registered search_documents tool performs similarity search against the stored vectors. See Ingestion.

Execution Lifecycle

1. The user invokes the CLI with a role file and a prompt.
2. The runtime parses the YAML, resolves the provider, and sends the system prompt + user message to the LLM. If the prompt includes attachments, they are resolved (local files are read, URLs are fetched) and sent as multimodal content parts.
3. The LLM responds — possibly requesting tool calls.
4. The runtime executes each tool, logs the action to the audit database, updates memory, and feeds the result back to the LLM.
5. This loop continues until the LLM produces a final response (or a guardrail limit is hit).
6. The final response is returned to the user and sent to any configured sinks.

Execution Modes

InitRunner supports several execution modes for different use cases:

Safety Layers

InitRunner enforces safety at multiple levels:

• Guardrails — Token budgets, tool call limits, iteration caps, and timeouts. Prevents runaway agents.
• Security — Shell command allowlists, filesystem sandboxing, confirmation prompts for destructive actions, HMAC webhook verification.
• Audit — Every tool call, LLM interaction, and agent run is logged to a SQLite database for inspection and compliance.

These layers work together so you can give agents powerful tools while keeping them within safe boundaries.