Quickstart
Zero to running AI agents in one command.
Two commands. Three minutes. Done.
pipx install agentbreeder
agentbreeder quickstartNo pipx? Use the standard installer instead
python3 -m pip install agentbreederpython3 -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.
Before you start
AgentBreeder needs three things on the machine:
- Python 3.11+ (we recommend installing via
pyenv) - 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.
What to expect
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.
agentbreeder quickstart is interactive and walks you through everything:
- Detects (or installs) Docker, Podman, or nerdctl
- Asks how you want to run models — Local, Cloud, or Both.
- If Ollama is already running with models, Local is the default (press Enter — free, no key).
- Otherwise the default is Both (install Ollama + add cloud keys).
- Sets up the path you chose:
- Local — installs Ollama if needed, pulls
gemma3(~2 GB). No API key required. - Cloud — prompts for OpenRouter first (one key, 100+ models — recommended), then optionally for direct OpenAI / Anthropic / Google keys behind a single yes/no gate.
- Both — local Ollama plus cloud keys.
- Local — installs Ollama if needed, pulls
- (macOS only, if Ollama is bound to 127.0.0.1) Optionally rebinds Ollama to
0.0.0.0:11434so the Docker stack can reach it viahost.docker.internal. This is opt-in (default: skip) — it restarts Ollama. Skipping is fine if you're using cloud or gateway models. - Frees any conflicting ports for you on confirmation
- Starts the full stack — API · Studio · Postgres · Redis · ChromaDB · Neo4j · MCP servers · LiteLLM
- Seeds RAG docs, the knowledge graph, MCP servers, and prompts
- Deploys 5 sample agents (
assistant,rag-agent,graph-agent,search-agent,a2a-orchestrator) - Opens Studio at http://localhost:3001
Already have a cloud API key?
Skip the ~3 GB Ollama download with the --no-ollama flag:
agentbreeder quickstart --no-ollamaEquivalent 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.
Ollama and the Docker stack
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 offers to rebind Ollama to 0.0.0.0:11434 (opt-in). You can also do it
manually:
launchctl setenv OLLAMA_HOST 0.0.0.0:11434
osascript -e 'tell application "Ollama" to quit' && open -a OllamaIf you skip the rebind, agents that need local models will fall back to cloud providers.
Default login
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.
After it finishes
agentbreeder chat assistant # talk to an agent
agentbreeder list agents # see what's deployed
agentbreeder down # stop everything
agentbreeder quickstart --reset # nuke and start freshDeploy to cloud from the same setup:
agentbreeder quickstart --cloud aws # also: gcp | azureBuild your own agent
agentbreeder init # scaffold agent.yaml + code
agentbreeder validate agent.yaml
agentbreeder deploy agent.yaml --target local # also: aws | gcp | azure | kubernetesThe 8-step deploy pipeline (parse → RBAC → resolve deps → build container → provision → health check → register → return endpoint) is atomic. If anything fails, the whole deploy rolls back.
Useful flags
| Flag | What it does |
|---|---|
--yes / -y | Non-interactive mode for CI. Skip every yes/no prompt and use safe defaults. Pair with --no-ollama and --no-browser for a fully scripted bootstrap. |
--no-ollama | Skip the Ollama install/start/pull bootstrap |
--ollama-model NAME | Pull a different default model (e.g. llama3.2, phi4-mini) |
--no-browser | Don't open Studio at the end |
--skip-seed | Skip seeding sample data (faster restart) |
--reset | Tear down all volumes and start fresh |
--dev | Build API/Studio images from source instead of Docker Hub |
--skip-doctor | Skip the prerequisite preflight (advanced; CI environments) |
When something goes wrong
| Problem | Fix |
|---|---|
agentbreeder: command not found | pip's script directory isn't on PATH. Either re-install with pipx install agentbreeder (recommended), or find the dir with python3 -c "import sysconfig; print(sysconfig.get_path('scripts'))" and prepend it to PATH in your shell rc. Running agentbreeder welcome once it works prints the same hint. |
Port conflict (:5432 already in use etc.) | Quickstart will offer to kill the conflicting process. Accept with y, or stop it manually. |
| Container daemon not running | Quickstart will tell you what to start (Docker Desktop, OrbStack, Colima, Podman, systemd, etc.) and re-detect after you confirm. |
| Stack already up, ports stuck | agentbreeder down --clean then retry. |
| No LLM provider | Quickstart prompts to install Ollama; or run agentbreeder setup separately for the full provider wizard. |
Studio at :3001 is blank | Stale rajits/agentbreeder-dashboard:latest cached locally. docker rmi it, then agentbreeder quickstart --dev to rebuild from source. Full steps: FAQ → |
migrate-1 shows Exited | Expected — migrate is a one-shot job that runs alembic upgrade head and exits. Only worry if the exit code is non-zero. |
DOCKER_HOST points at a dead socket | Quickstart detects this and points at the missing path. Run unset DOCKER_HOST (and remove the export line from your shell rc). |
permission denied on /var/run/docker.sock (Linux) | Your user isn't in the docker group. Quickstart prompts you to run sudo usermod -aG docker $USER && newgrp docker. |
| Snap / Flatpak Docker — "cannot connect to daemon" | Quickstart detects the socket-path mismatch and tells you the exact export DOCKER_HOST=unix://<path> to run. |
Docker socket reachable but docker CLI missing | Partial install. Quickstart prints the distro-specific install command (brew install docker, apt-get install docker-ce-cli, etc.). |
| Rootless Docker volume permission errors | Quickstart prints a one-liner heads-up when rootless is detected. Bind-mounts are owned by your user, not root. |
Next
| You want to… | Go here |
|---|---|
| See every CLI command | CLI reference → |
See every agent.yaml field | agent.yaml reference → |
| Deploy to AWS / GCP / Azure / Kubernetes | How-To: Deploy → |
| Add knowledge bases (RAG / GraphRAG) | RAG → · GraphRAG → |
| Add tools / MCP servers | MCP servers → |
| Visual builder | No Code → |
| Python / TypeScript SDK | Full Code → |