Role Creation

A role file (role.yaml) defines your agent — its model, system prompt, tools, guardrails, and everything else. InitRunner gives you multiple ways to create one depending on how much control you want.

Quick Comparison

AI Generation

Generate a complete role from a natural language description:

initrunner create "A code review assistant that reads git diffs and suggests improvements"

This creates a role.yaml in the current directory. Review it, tweak if needed, and run it.

Flags

How It Works

1. Builds a dynamic schema reference by introspecting Pydantic models. This includes all tool types from the registry, trigger types, sink types, and every configurable field with defaults.
2. Sends the description plus schema reference to the configured LLM.
3. Validates the returned YAML against RoleDefinition.
4. If validation fails, retries once by sending the error back to the LLM for correction.

Provider Auto-Detection

When --provider is omitted, InitRunner checks for available API keys in the environment (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.) and uses the first provider found. Falls back to openai.

Example

initrunner create "A Python tutor that executes code examples and explains errors" \
  --provider anthropic \
  --name python-tutor \
  --output tutor-role.yaml

Interactive Wizard

Launch the guided wizard:

initrunner init -i

The wizard walks through each section of a role definition, building a complete role.yaml step by step.

Wizard Flow

1. Agent name — lowercase with hyphens (e.g. my-agent)
2. Description — optional free-text
3. Provider — choose from openai, anthropic, google, groq, mistral, cohere, ollama
4. Model — choose from a curated list for the selected provider, or type a custom model name
5. Base template — pre-populates system prompt, tools, and features (see table below)
6. Tool selection — pick tools by number or name, then configure each one
7. Memory — enable/disable long-term memory
8. Ingestion — enable/disable RAG with source glob and chunking config
9. Output file — path to write (default: role.yaml)

Templates

Available Tools

Each selected tool prompts for its key configuration fields. For details on all tools, see Tools.

Anthropic Embedding Warning

When the wizard detects that anthropic is selected as the provider and memory or ingestion is enabled, it displays a warning:

Warning: Anthropic does not provide an embeddings API. RAG and memory features require OPENAI_API_KEY for embeddings.

The embedding provider can be overridden via spec.ingest.embeddings or spec.memory.embeddings in the generated role file.

Templates

Scaffold from a built-in template without interactive prompts:

initrunner init --name my-agent --template basic

Available templates: basic, rag, daemon, memory, ollama, tool, api, skill.

# RAG agent with document search
initrunner init --name doc-search --template rag

# Background daemon that runs on a schedule
initrunner init --name watcher --template daemon

# Agent with long-term memory
initrunner init --name assistant --template memory

Copy an Example

Browse and copy community examples:

initrunner examples list                  # browse available examples
initrunner examples show file-reader      # preview the YAML
initrunner examples copy file-reader      # copy files to current directory

See Examples for the full catalog.

Dashboard — Create Role

The web dashboard at /roles/new offers two tabs for role creation.

Form Builder Tab

A structured form with fields for:

• Name, description
• Provider, model (dropdown with curated per-provider options and custom input)
• System prompt
• Tool checkboxes
• Memory and ingestion toggles
• Live YAML preview that updates as you fill in the form

Submitting the form calls POST /api/roles with the generated YAML.

AI Generate Tab

1. Enter a natural language description
2. Click Generate to produce a role.yaml via AI
3. Review and edit the generated YAML
4. Click Save to persist

This calls POST /api/roles/generate to get the YAML, then POST /api/roles to save.

API Endpoints

POST /api/roles returns 409 if a role file with the same name already exists.

Manual YAML

For full control, create a role.yaml by hand. Every role file has four top-level keys: apiVersion, kind, metadata, and spec. See Configuration for the full schema reference.

Minimum Viable Role

The smallest valid role needs metadata, a system prompt, and a model:

apiVersion: initrunner/v1
kind: Agent
metadata:
  name: my-agent
  description: A helpful assistant
spec:
  role: |
    You are a helpful assistant.
  model:
    provider: openai
    name: gpt-4o-mini

Adding Tools

Add a tools list under spec:

spec:
  tools:
    - type: filesystem
      root_path: .
      read_only: true
    - type: shell
      require_confirmation: true
      timeout_seconds: 30

Adding Memory

Add a memory section so the agent remembers across sessions:

spec:
  memory:
    max_sessions: 10
    max_resume_messages: 20
    semantic:
      max_memories: 500

Run with --resume to pick up where you left off. See Memory for details.

Adding Ingestion / RAG

Add an ingest section to let the agent search your documents:

spec:
  ingest:
    sources:
      - "./**/*.md"
    chunking:
      strategy: paragraph
      chunk_size: 512
      chunk_overlap: 50

Run initrunner ingest role.yaml to index, then ask questions about your docs. See Ingestion for details.

Adding Triggers and Sinks

Triggers automate when the agent runs. Sinks control where output goes:

spec:
  triggers:
    - type: cron
      schedule: "*/30 * * * *"
    - type: watch
      paths: ["./src/**/*.py"]
  sinks:
    - type: file
      path: ./reports/output.md
    - type: slack
      channel: "#alerts"

See Triggers and Sinks for all options.

Adding Guardrails

Set resource limits to keep the agent safe:

spec:
  guardrails:
    max_tokens_per_run: 10000
    max_tool_calls: 10
    timeout_seconds: 60
    max_request_limit: 10

See Guardrails for the full reference.

Editing Existing Roles

Dashboard YAML Editor

The role detail page (/roles/{role_id}) includes an editable YAML tab with Save and Reset buttons.

• Save calls PUT /api/roles/{role_id} with the updated YAML content
• Creates a .bak backup of the existing file before overwriting
• Validates the YAML against RoleDefinition before writing

CLI Editing

Open the role file in your editor, make changes, then validate:

$EDITOR role.yaml
initrunner validate role.yaml

Validation

Check your YAML before running:

initrunner validate role.yaml

This parses the file and validates it against the RoleDefinition schema. Errors are printed with field paths so you can fix them quickly.

Security Notes

• Name validation: metadata.name must match ^[a-z0-9][a-z0-9-]*[a-z0-9]$
• Directory restrictions: API writes are restricted to configured role directories; path traversal (..) is rejected
• Overwrite protection: POST /api/roles returns 409 if the file exists; updates via PUT create a .bak backup before overwriting
• Validation before write: YAML is parsed and validated against RoleDefinition before being written to disk

Next Steps

• Configuration — Full YAML schema reference
• Tools — All available tools and their configuration
• Examples — Complete, runnable agents for common use cases
• Quickstart — Get your first agent running in under five minutes