RAG in 5 Minutes

Get a document-search agent up and running in three commands.

Old envelopes still load. Convert them with initrunner doctor --fix PATH. See Envelope Migration.

Before you start: initrunner ingest needs an embedding model. The default is OpenAI text-embedding-3-small — set OPENAI_API_KEY to use it, or set embeddings.provider to switch providers (Google, Ollama, and more). No API keys? Jump to fully local setup.

You also need the vector store: uv pip install "initrunner[ingest]". The default installer bundle already has it, but a core install does not. See Installation.

The 3-Command Flow

initrunner new --template rag --no-refine --output role.yaml   # scaffold a RAG-ready role file
initrunner ingest role.yaml                                    # embed and index your documents
initrunner run role.yaml                                       # chat with your knowledge base

What each command does

initrunner new --template rag --no-refine --output role.yaml

Scaffolds a role YAML pre-configured with ingest pointing at ./docs/**/*.md and ./docs/**/*.txt, fixed chunking, and search_documents usage instructions in the system prompt. Only the role file is written, so create ./docs/ and add your own documents before ingesting. (--no-refine skips the interactive refinement conversation; without --output, the file is written to agent.yaml.)

The scaffolded role file contains this ingest config:

ingest:
  sources:
    - "./docs/**/*.md"
    - "./docs/**/*.txt"
  chunking:
    strategy: fixed
    chunk_size: 512
    chunk_overlap: 50

There is no embeddings block. With none set, the embedding provider follows the agent's model provider: an openai agent embeds with text-embedding-3-small, a google agent with text-embedding-004, an ollama agent with nomic-embed-text. Add an embeddings block to pin a different backend:

ingest:
  sources:
    - "./docs/**/*.md"
    - "./docs/**/*.txt"
  embeddings:
    provider: openai
    model: text-embedding-3-small
    # api_key_env: OPENAI_API_KEY  # optional: override which env var holds the key

Change provider and model to switch embedding backends. See Providers for all options.

After initrunner new finishes it prints the next steps:

Created role.yaml

Next steps:
  initrunner ingest role.yaml
  initrunner validate role.yaml

initrunner ingest role.yaml

Reads every file matched by ingest.sources, splits the text into chunks, generates embeddings, and stores everything in a local LanceDB vector database (~/.initrunner/stores/<agent-name>.lance). Re-running is safe — existing chunks are replaced.

initrunner run role.yaml

Starts the agent. The search_documents tool is auto-registered. Ask any question and the agent will search your indexed documents before answering, citing the source files it used.

Embedding API Key

The embedding key is read from an environment variable. The default depends on your provider:

Anthropic users: Anthropic has no embeddings API. The default fallback is OpenAI — set OPENAI_API_KEY (in your environment or ~/.initrunner/.env) if keeping that default. To avoid needing an OpenAI key, set embeddings.provider: google or embeddings.provider: ollama instead.

Override the key name — if your key is stored under a different env var name, set api_key_env in the embedding config:

ingest:
  embeddings:
    provider: openai
    model: text-embedding-3-small
    api_key_env: MY_EMBED_KEY   # read from MY_EMBED_KEY instead of OPENAI_API_KEY

Diagnose key issues with the doctor command:

initrunner doctor

The Embedding Providers section shows which keys are set and which are missing.

Fully Local — No API Keys

Swap both the LLM and the embedding model to Ollama for a completely local setup:

model:
  provider: ollama
  name: llama3.2
ingest:
  sources:
    - "./docs/**/*.md"
  embeddings:
    provider: ollama
    model: nomic-embed-text

Then run the same three commands — no API keys required.

Next Steps

• Ingestion reference — chunking strategies, embedding models, supported file formats
• RAG Patterns & Guide — common patterns, embedding model comparison, fully local RAG