# Quickstart

Get your first AI agent running in under five minutes.

## Prerequisites

- Python 3.11+ (Linux, macOS, or WSL — see [Installation](/docs/installation#platform-notes) for Windows details)
- An API key from a supported provider (OpenAI, Anthropic, Google, Groq, Mistral, Cohere, Bedrock, or xAI) — or a local Ollama instance

## Install

```bash
curl -fsSL https://initrunner.ai/install.sh | sh
```

Or install directly with a package manager:

```bash
uv tool install "initrunner[recommended]"
pipx install "initrunner[recommended]"
pip install "initrunner[recommended]"
```

> **Note:** On modern Linux (Python 3.11+), bare `pip install` outside a virtual environment will fail due to [PEP 668](https://peps.python.org/pep-0668/). Use `uv`, `pipx`, or create a venv first.

> **Tip:** `[recommended]` includes search, ingestion, the vector store, MCP, and the dashboard, so common workflows just work. Use `[all]` for every provider and feature. See [Installation](/docs/installation#what-to-install) for the full list.

Or run with Docker (no Python required):

```bash
docker run --rm -it -e OPENAI_API_KEY ghcr.io/vladkesler/initrunner:latest initrunner run -i
```

## Setup

Run the setup wizard to configure your provider and API key:

```bash
initrunner setup
```

The wizard walks you through the essentials: choose your LLM provider and model, validate your API key, and write `~/.initrunner/run.yaml`. It does not generate a role file. See [Setup Wizard](/docs/setup) for all options. To build a role, use [`initrunner new`](/docs/role-creation).

> **Shortcut:** Already have an API key? Skip the wizard — just export it and go:
> ```bash
> export OPENAI_API_KEY="sk-..."
> ```

> **Using Ollama?** Make sure `ollama serve` is running. No API key needed — just run `initrunner setup --provider ollama`.

## Verify Your Setup

Confirm everything works with a single command:

```bash
initrunner doctor --quickstart
```

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:

```bash
export OPENAI_API_KEY=sk-...
```

See [Troubleshooting](/docs/troubleshooting) for other common issues, or run `initrunner doctor --fix` to auto-repair detected problems.

## Your First Agent

The fastest way to chat, no YAML file needed:

```bash
initrunner run -p "What is the capital of France?"
```

InitRunner auto-detects your provider and returns a single response:

```
The capital of France is Paris.
```

## Try a Starter Agent

You don't need to write any YAML yet. InitRunner ships with ready-to-run starters (one-word names like `memory`, `helpdesk`, `scout`, `reviewer`, `writer`) you can try right now:

```bash
initrunner run --list
```

Here are a few to start with:

| Starter | Kind | What it does |
|---------|------|-------------|
| `memory` | Agent | Personal assistant that remembers across sessions |
| `helpdesk` | Agent (RAG) | Q&A over your docs with citations. Ships sample docs and shows **Ready (samples)** when `./knowledge-base/` is missing; an empty `knowledge-base/` is not Ready |
| `scout` | Agent | Search the web and produce structured briefings (`initrunner[search]`) |
| `reviewer` | Team | Multi-perspective review: architect, security, maintainer |
| `scholar` | Team | Planner, web researcher, and synthesizer with shared memory |
| `reader` | Agent | Index a codebase, chat about architecture, remember patterns |
| `writer` | Flow | Researcher, writer, editor/fact-checker pipeline |
| `mail` | Agent | Monitor inbox, triage, draft replies |
| `librarian` | Agent | Knowledge-base Q&A with document ingestion |

Run `initrunner run --list` to see the full set.

Pick one and go:

```bash
# Run a starter directly
initrunner run helpdesk -i

# Copy it locally to read and customize the YAML
initrunner examples copy helpdesk -o ./my-helpdesk/
cd my-helpdesk && cat role.yaml
```

`examples copy` gives you a local copy of the agent YAML, and its sample data, that you can open and edit. It's the fastest way to see what a real agent config looks like before writing your own. Filenames `agent.yaml` and `role.yaml` both work.

> **Changed in v2026.8.11:** `run --save` was removed in favour of `initrunner examples copy`, which also learned to copy bundled starters offline. It used to know only the GitHub-backed catalog, so `examples copy telegram` failed outright. Where a name is both a starter and a catalog example (`helpdesk`, `scout`), the starter wins and the output says so. Destinations are checked before anything is written, so a collision leaves the directory untouched.

See [Examples](/docs/examples) for 60+ more runnable agents.

## Create Your Own Agent

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:

```bash
initrunner new "a code review bot that reads git diffs and suggests improvements"
```

The builder generates an `agent.yaml` and shows it to you. You can refine it in a back-and-forth loop, or press Enter to save:

```
+-- code-reviewer -------------------- VALID --+
| name: code-reviewer                           |
| model: openai:gpt-5-mini                      |
| prompt: You review code for bugs and style.   |
| ...                                           |
+-----------------------------------------------+

Refine (empty to save, "quit" to discard):
> add memory so it remembers past reviews
```

Once saved, run your agent:

```bash
initrunner run agent.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:

```bash
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](/docs/role-creation) for all the options.

## Understanding Your agent.yaml

The generated file defines everything about your agent: its model, system prompt, tools, and safety limits. Here's what a basic one looks like:

```yaml
name: my-first-agent                # lowercase, hyphens only
description: A helpful assistant
model: openai:gpt-5-mini            # or: anthropic:..., google:..., ollama:..., etc.
prompt: |                           # the system prompt, tells the agent what to do
  You are a helpful assistant. You answer questions
  clearly and concisely.
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:

```bash
initrunner validate agent.yaml
```

> **Tip:** `initrunner new "a helpful assistant"` generates an `agent.yaml`. `initrunner setup` only configures the provider and `run.yaml`. Existing `role.yaml` files still work.

> **Note:** YAML is indentation-sensitive. Use spaces, not tabs. If you get a validation error, check your indentation first.

> **Still have `apiVersion` / `kind` / `spec`?** Those files still run. Convert a file or folder with `initrunner doctor --fix PATH --yes`. See [Envelope Migration](/docs/envelope-migration).

## Add Tools

Without tools, your agent can only chat from its training data. Tools let it interact with files, the web, and more. Add a `tools` list — a bare name enables defaults, a mapping adds options:

```yaml
name: my-first-agent
model: openai:gpt-5-mini
prompt: |
  You are a helpful assistant. You answer questions
  clearly and concisely.
tools:
  - datetime                        # get current time
  - web_reader:                     # fetch and read web pages
      timeout_seconds: 15
  - 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:

```bash
initrunner run agent.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 28 built-in tool types, from filesystem, HTTP, shell, Python, git, MCP, and SQL to more specialized ones. See [Tools](/docs/tools) for the full list.

## Interactive Mode

So far you have used single-shot mode (`-p "..."`) where the agent responds once and exits. Interactive mode starts a multi-turn conversation:

```bash
initrunner run agent.yaml -i
```

```
You: What files are in the current directory?
Agent: I found the following files: agent.yaml, README.md, src/...
You: Summarize README.md for me
Agent: 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:

```bash
initrunner run agent.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:
> ```bash
> initrunner run agent.yaml -a -p "Read all Python files in ./src and write a summary report"
> ```
> See [Autonomous Mode](/docs/autonomy) for budget controls and reasoning strategies.

## What's Next

Pick your path based on what you want to build:

- **Build a complete agent step by step** — [Tutorial](/docs/tutorial) walks you through `initrunner new`, the dashboard, memory, RAG, autonomy, triggers, teams, and flows
- **Add document search (RAG)** — [RAG in 5 Minutes](/docs/rag-quickstart) adds vector search over your files
- **Add persistent memory** — [Memory in 5 Minutes](/docs/memory-quickstart) lets your agent remember across sessions
- **Explore all tool types** — [Tools](/docs/tools) covers 28 built-in tools (HTTP, shell, Python, git, MCP, and more)
- **Full YAML schema** — [Configuration](/docs/configuration) is the complete reference for every agent file field
- **Convert old envelopes** — [Envelope Migration](/docs/envelope-migration) rewrites `apiVersion`/`kind` files with `doctor --fix`
- **Run on a schedule or webhook** — [Triggers](/docs/triggers) for cron, file watch, and webhook-driven agents
- **Telegram or Discord bot** — [Telegram](/docs/telegram) and [Discord](/docs/discord) setup guides with access control
- **API server** — [API Server](/docs/server) exposes any agent as an OpenAI-compatible endpoint
- **Web dashboard** — [Dashboard](/docs/dashboard) for visual agent management and monitoring
- **Browse community agents** — [InitHub](https://hub.initrunner.ai) marketplace for pre-built agents