Quickstart

Get your first AI agent running in under five minutes.

Prerequisites

• Python 3.11 or later
• An API key from a supported provider (OpenAI, Anthropic, Google, Groq, or Mistral)

Installation

pip install initrunner

Other methods:

uv tool install initrunner
pipx install initrunner
curl -fsSL https://initrunner.ai/install.sh | sh

Or run with Docker (no Python required):

docker run --rm -e OPENAI_API_KEY vladkesler/initrunner:latest --version

Guided Setup

Run the interactive setup wizard to select a provider and verify your API key:

initrunner setup

Create Your First Agent

In InitRunner, an agent's behavior is defined in a YAML file called a role (role.yaml). It declares the model, system prompt, tools, and guardrails. There are four ways to create one:

AI Generate

The fastest way to get started. Describe what you want and InitRunner generates the YAML:

initrunner create "a file reader assistant that can browse and summarize local files"

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

Template

Scaffold from a built-in template:

initrunner init --name file-reader --template basic

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

Clone Example

Browse and clone community examples:

initrunner examples list
initrunner examples clone file-reader

See Examples for the full catalog.

Manual YAML

Create a role.yaml by hand for full control:

apiVersion: initrunner/v1
kind: Agent
metadata:
  name: file-reader
  description: A helpful assistant that can read and summarize files
  tags:
    - example
    - filesystem
spec:
  role: |
    You are a helpful assistant with access to the local filesystem.
    When the user asks about a file, use read_file to read its contents
    and then provide a clear, concise answer. Use list_directory to
    explore the project structure when needed.
  model:
    provider: openai
    name: gpt-4o-mini
    temperature: 0.2
    max_tokens: 2048
  tools:
    - type: filesystem
      root_path: .
      read_only: true
  guardrails:
    max_tokens_per_run: 10000
    max_tool_calls: 10
    timeout_seconds: 60
    max_request_limit: 10

Run the Agent

Single-shot mode

Send a prompt and get a response:

initrunner run role.yaml -p "Read the README and summarize it"

Interactive REPL

Start a conversational session:

initrunner run role.yaml -i

Resume a session

Pick up where you left off (requires memory: config):

initrunner run role.yaml -i --resume

Dry run

Test without making API calls:

initrunner run role.yaml -p "Hello!" --dry-run

Validate a Role

Check your YAML before running:

initrunner validate role.yaml

Level Up

Your file-reader agent works, but InitRunner can do much more. Here's how to add memory and RAG to the same agent.

Add memory

Add a memory section so the agent remembers across sessions:

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

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

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

Next Steps

• Examples — Complete, runnable agents for common use cases
• Installation — Extras, platform notes, and development setup
• Configuration — Full YAML schema reference
• Providers — All supported providers and model options
• Tools — Add tools to your agent