Quickstart

python3 -m pip install agentbreeder

python3 -m pip works on every Python install regardless of whether pip, pip3, or neither is on your PATH. If you see agentbreeder: command not found after, see Troubleshooting.

We recommend pipx because it installs agentbreeder into an isolated environment and puts the executable on PATH automatically — no shell-rc edits, no clashes with other tools.

AgentBreeder needs three things on the machine:

• Python 3.11+ — install via pyenv (see below)
• One container runtime — Docker Desktop, OrbStack, Colima, Podman, or nerdctl
• macOS 12+ · Linux · or Windows 11 + WSL2 · ~8 GiB free disk · ~4 GiB RAM

Not sure? Run agentbreeder doctor after installing — it checks every prerequisite, exits in under two seconds, and prints copy-pasteable fix commands for whatever's missing.

Using pyenv is the simplest way to avoid the most common AgentBreeder install issue: stale editable installs from earlier source checkouts that quietly shadow the PyPI release and break the agentbreeder CLI with ModuleNotFoundError: No module named 'cli'.

macOS:

brew install pyenv
echo 'eval "$(pyenv init -)"' >> ~/.zshrc && exec zsh
pyenv install 3.12.11
pyenv global 3.12.11

Linux:

curl -fsSL https://pyenv.run | bash
echo 'eval "$(pyenv init -)"' >> ~/.bashrc && exec bash
pyenv install 3.12.11
pyenv global 3.12.11

Verify:

python --version   # should print Python 3.12.11
which python       # should be under ~/.pyenv/shims

Then pipx install agentbreeder (or python -m pip install agentbreeder) installs cleanly into the pyenv-managed interpreter. Switching Python versions later is one command (pyenv global 3.13.x) and never collides with system Python.

agentbreeder quickstart is an interactive wizard. It asks a handful of questions (container runtime, model source, API keys, port conflicts) and pulls ~3 GB if you choose local models. Expect ~3 minutes on a cold first run.

Want zero prompts for CI? Use the scripted path:

agentbreeder quickstart --yes --no-ollama --no-browser

--yes skips every yes/no prompt and uses safe defaults. --no-ollama keeps you on the cloud path (set OPENAI_API_KEY etc. before running). --no-browser skips opening Studio.

Skip the ~3 GB Ollama download with the --no-ollama flag:

agentbreeder quickstart --no-ollama

Equivalent to choosing Cloud at the model-source prompt. You'll be asked for OpenRouter first (one key, 100+ models), then optionally for OpenAI / Anthropic / Google direct keys.

Docker containers reach your host machine via host.docker.internal — not localhost. If Ollama is bound to 127.0.0.1 only (the macOS default), the AgentBreeder API container can't reach it even though ollama run works fine in your terminal.

Quickstart detects this and will attempt to rebind Ollama to 0.0.0.0:11434 (opt-in). If the auto-rebind fails — for example because a brew/launchd supervisor restarts Ollama or because the Ollama.app process can't be killed cleanly — quickstart will print the manual rebind steps below.

Manual rebind:

launchctl setenv OLLAMA_HOST 0.0.0.0:11434
pkill -f Ollama.app && open -a Ollama   # pkill avoids the "really quit?" GUI dialog

If you skip the rebind, agents that need local models will fall back to cloud providers.

Email: admin@agentbreeder.local · Password: plant

Studio will force you to set a new password on first sign-in — the default is publicly documented and unsafe to leave in place.

The chat builder drives a Claude model to generate your agent.yaml. You need to add your Claude API key once — either inline in Studio (open /agents/new → Chat to build tab; the Claude API Key card appears above the chat input until the key is set) or from the CLI (agentbreeder secret set AGENTBREEDER_CLAUDE_BUILDER_KEY — see the CLI reference). Either path stores it in the workspace secrets backend — never written to the database, returned to the browser, or logged. Get a key at console.anthropic.com.

The builder works identically whether you are running locally or on AgentBreeder cloud at console.agentbreeder.io.