Note: On modern Linux (Python 3.11+), bare pip install outside a virtual environment will fail due to PEP 668. Use uv, pipx, or create a venv first.
Tip:[recommended] includes search, ingestion, and the dashboard so common workflows just work. Use [all] for every provider and feature. See Installation for the full list.
Or run with Docker (no Python required):
docker run --rm -e OPENAI_API_KEY vladkesler/initrunner:latest --version
Run the setup wizard to configure your provider and API key:
initrunner setup
The wizard walks you through the essentials: choose your LLM provider and model, validate your API key, and generate a ready-to-run role.yaml. See Setup Wizard for all options.
Shortcut: Already have an API key? Skip the wizard — just export it and go:
export OPENAI_API_KEY="sk-..."
Using Ollama? Make sure ollama serve is running. No API key needed — just run initrunner setup --provider ollama.
You should see a provider status table followed by a smoke test result:
╭───────────────────────────── Quickstart Result ──────────────────────────────╮│ Smoke test passed! ││ ││ Response: Hello! ││ Tokens: 97 | Duration: 2229ms │╰──────────────────────────────────────────────────────────────────────────────╯
If the smoke test can't find your API key, initrunner run asks for one inline and saves it to ~/.initrunner/.env (mode 0600) so the next run picks it up automatically. That only works in an interactive terminal. In CI or piped scripts it still exits with an error, so set the variable explicitly there:
export OPENAI_API_KEY=sk-...
See Troubleshooting for other common issues, or run initrunner doctor --fix to auto-repair detected problems.
You don't need to write any YAML yet. InitRunner ships with 18 ready-to-run starters (one-word names like helpdesk, scout, reviewer, writer) you can try right now:
initrunner run --list
Here are a few to start with:
Starter
Kind
What it does
helpdesk
Agent (RAG)
Drop your docs in, get an AI helpdesk with citations and memory
# Run a starter directlyinitrunner run helpdesk -i# Save locally to read and customize the YAMLinitrunner run helpdesk --save ./my-helpdesk/cd my-helpdesk && cat role.yaml
With --save, you get a local copy of the role.yaml that you can open and edit. It's the fastest way to see what a real agent config looks like before writing your own.
The easiest way to create a custom agent is initrunner new. Describe what you want in plain English and it generates the full config for you:
initrunner new "a code review bot that reads git diffs and suggests improvements"
The builder generates a role.yaml and shows it to you. You can refine it in a back-and-forth loop, or press Enter to save:
+-- code-reviewer -------------------- VALID --+| apiVersion: initrunner/v1 || kind: Agent || ... |+-----------------------------------------------+Refine (empty to save, "quit" to discard):> add memory so it remembers past reviews
Once saved, run your agent:
initrunner run role.yaml -p "Review the last commit"
Or skip the two-command dance by passing --run to initrunner new. It opens the refinement loop first, then fires off a run with your prompt as soon as you save:
initrunner new "a code review bot that reads git diffs and suggests improvements" \ --run "Review the last commit"
You can also start from a template (initrunner new --template rag) or a blank slate (initrunner new --blank). See Role Creation for all the options.
The generated file defines everything about your agent: its model, system prompt, tools, and safety limits. Here's what a basic one looks like:
apiVersion: initrunner/v1 # always this valuekind: Agent # single agent (also: Team, Flow)metadata: name: my-first-agent # lowercase, hyphens only description: A helpful assistantspec: role: | # the system prompt, tells the agent what to do You are a helpful assistant. You answer questions clearly and concisely. model: provider: openai # or: anthropic, google, groq, ollama, etc. name: gpt-5-mini guardrails: max_tokens_per_run: 10000 # cost safety net max_tool_calls: 5 timeout_seconds: 60
You can write this by hand too, or edit the one initrunner new generated. Validate it anytime with:
initrunner validate role.yaml
Tip:initrunner setup also generates a role.yaml for you as part of the setup wizard.
Note: YAML is indentation-sensitive. Use spaces, not tabs. If you get a validation error, check your indentation first.
Without tools, your agent can only chat from its training data. Tools let it interact with files, the web, and more. Add a tools section to your role.yaml under spec:
spec: role: | You are a helpful assistant. You answer questions clearly and concisely. model: provider: openai name: gpt-5-mini tools: - type: datetime # get current time - type: web_reader # fetch and read web pages timeout_seconds: 15 - type: filesystem # read local files root_path: . read_only: true guardrails: max_tokens_per_run: 10000 max_tool_calls: 5 timeout_seconds: 60
Run the agent with a prompt that requires a tool:
initrunner run role.yaml -p "What time is it right now?"
The agent uses the datetime tool and returns the current time. You can see which tools the agent calls in the output.
InitRunner has 27 built-in tool types, from filesystem, HTTP, shell, Python, git, MCP, and SQL to more specialized ones. See Tools for the full list.
So far you have used single-shot mode (-p "...") where the agent responds once and exits. Interactive mode starts a multi-turn conversation:
initrunner run role.yaml -i
You: What files are in the current directory?Agent: I found the following files: role.yaml, README.md, src/...You: Summarize README.md for meAgent: The README describes...You: quit
The agent keeps context within the session — it remembers what you discussed earlier. Type quit, exit, or press Ctrl+D to end the session.
To pick up where you left off in a future session:
initrunner run role.yaml -i --resume
Autonomous mode: For multi-step tasks where the agent works independently — planning, executing, and iterating without you prompting each step — use autonomous mode:
initrunner run role.yaml -a -p "Read all Python files in ./src and write a summary report"
See Autonomous Mode for budget controls and reasoning strategies.
