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: { ... }
  guardrails: { ... }

Section	Purpose
`metadata`	Identity — name, description, tags
`spec.role`	System prompt — the agent's personality and instructions
`spec.model`	Which LLM provider and model to use
`spec.tools`	Capabilities the agent can invoke
`spec.memory`	Short-term and long-term memory configuration
`spec.ingest`	Document ingestion and RAG settings
`spec.triggers`	Events that start agent runs (cron, file watch, webhook)
`spec.sinks`	Where output goes (Slack, email, file, delegate)
`spec.autonomy`	Plan-execute-adapt loop settings
`spec.guardrails`	Safety limits (tokens, tools, timeouts)

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).

Runtime — The parser validates the YAML and hands it to the provider, which creates an agent bound to a specific LLM. The agent 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 14 tool types:

Category	Types
Data	`filesystem`, `sql`, `api`, `http`
Execution	`shell`, `python`, `mcp`
Communication	`slack`, `email`
Knowledge	`search_documents` (auto-registered via ingestion)
Time	`datetime`
System	`delegate`, `memory_read`, `memory_write`

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 supports two types of memory:

Short-term — Session-based persistence. The agent remembers context within a single conversation or daemon lifetime.
Long-term — Semantic memory stored in SQLite with vector embeddings. The agent can recall relevant facts across sessions.

See Memory.

Ingestion & RAG

The ingestion pipeline converts documents into searchable vector embeddings:

Glob source files
Extract text (Markdown, PDF, DOCX, CSV, HTML, JSON)
Chunk into overlapping segments
Embed with a provider model
Store in SQLite (sqlite-vec)

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

Execution Lifecycle

The user invokes the CLI with a role file and a prompt.
The runtime parses the YAML, resolves the provider, and sends the system prompt + user message to the LLM.
The LLM responds — possibly requesting tool calls.
The runtime executes each tool, logs the action to the audit database, updates memory, and feeds the result back to the LLM.
This loop continues until the LLM produces a final response (or a guardrail limit is hit).
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:

Mode	Command	Description
Single-shot	`initrunner run role.yaml -p "..."`	One prompt in, one response out
REPL	`initrunner run role.yaml -i`	Interactive conversation loop
Autonomous	`initrunner run role.yaml -a -p "..."`	Plan-execute-adapt loop without human input (Autonomy)
Daemon	`initrunner daemon role.yaml`	Long-running process that listens for triggers (Triggers)
Compose	`initrunner compose up compose.yaml`	Multi-agent orchestration (Compose)
Server	`initrunner serve role.yaml`	OpenAI-compatible HTTP API (Server)

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.

On this page