Install
Install the AgentBreeder 3.0.0a3 preview from PyPI or npm with an exact version pin, and see what has been verified on macOS and Linux.
Always pin the version
3.0.0a3 is an alpha preview. A bare pip install agentbreeder, uvx agentbreeder or
pipx run agentbreeder installs 2.7.3, which is unmaintained and has known functional and
security issues (see Legacy 2.x). 3.x is a rebuild: no 2.x command, config or
data carries over.
Requirements
- macOS (verified end to end) or Linux (install,
--versionanddoctoronly, on3.0.0a3; see what has been verified). Windows is not supported. - A running Docker engine with a local context.
- For pip: Python 3.11 or newer.
- For uvx: uv 0.11.6 or newer.
- For npx: Node.js 18 or newer, and uv 0.11.6 or newer.
Install and run the demo
Pick one path. Each runs the same PyPI release.
python3 -m venv .venv
.venv/bin/python -m pip install "agentbreeder[eval]==3.0.0a3"
.venv/bin/agentbreeder quickstartuvx --from "agentbreeder[eval]==3.0.0a3" agentbreeder quickstartnpx agentbreeder@3.0.0-alpha.3 quickstartThe npm package is a launcher with no Python code of its own. It runs the pinned PyPI release
through uvx, and exits with install guidance if uvx is missing.
quickstart builds a sample image, deploys it through a demo identity gate, invokes it, retries
the same deployment, checks the saved history and removes the container. It needs no model account
or API key. The sample echoes JSON; it is not an AI agent. Add --dry-run to run doctor and
validate the sample without building or deploying anything. If it stops, run
agentbreeder doctor first.
Run more commands
npx and uvx run the CLI without installing an agentbreeder command. After either, a bare
agentbreeder is either not found or an older install. Repeat the prefix for every command
(npx agentbreeder@3.0.0-alpha.3 up), or install the command with uv:
uv tool install "agentbreeder[eval]==3.0.0a3"
agentbreeder --version # 3.0.0a3This puts agentbreeder in uv's executable directory (~/.local/bin in our run), which must be on
your PATH ahead of any older install. uv tool uninstall agentbreeder removes it. Run on macOS
in a clean sandbox: on 3.0.0a3 (2026-11-16), --version and doctor (which warns until uv's
executable directory is on your PATH); on 3.0.0a2 (2026-11-11),
--version, doctor and a real quickstart (5/5). up and Northwind have not been run this way.
An older agentbreeder on your PATH
If a bare agentbreeder fails with ModuleNotFoundError: No module named 'cli', or does not report
3.0.0a3, an older install comes first on your PATH:
which -a agentbreederlists every copy, inPATHorder.- Run each one by its full path with
--version. The one that fails or reports another version is the old one; leave the3.0.0a3copy alone. - Remove the old one with the tool that installed it:
pipx uninstall agentbreeder,brew uninstall agentbreeder, or for a pip installPYTHON -m pip uninstall agentbreeder, wherePYTHONis the interpreter on the first line of that script. If pip says it is not installed (a leftover from a deleted editable install), delete that script file. - Run
hash -ror open a new shell.
Try Northwind
Northwind is a customer support agent built from an agent.yaml. It needs GEMINI_API_KEY and
TAVILY_API_KEY, in the environment or in an env file. These commands need agentbreeder on your
PATH: after the pip install above, run export PATH=$PWD/.venv/bin:$PATH first, or use
uv tool install (Run more commands).
agentbreeder example northwind # copies it to ./northwind
cd northwind
agentbreeder services up --environment dev --env-file ~/.env --yes
agentbreeder release agent.yaml --stack . --environment devWith uvx or npx, replace agentbreeder with uvx --from "agentbreeder[eval]==3.0.0a3" agentbreeder
or npx agentbreeder@3.0.0-alpha.3. On 3.0.0a3 these CLI commands ran from the pip install
(61/61, a live invoke, full teardown); through uvx and npx they have not been run. On 3.0.0a2,
Northwind ran through the command center instead, started with npx and driven by a script through
its API, with no browser.
To use the command center, run npx agentbreeder@3.0.0-alpha.3 up and follow the steps in the
browser; see Local command center.
To tear it down, run agentbreeder remove ID --local --stack ., then
agentbreeder services down --purge --yes. See Backing services and
Build from agent.yaml.
What has been verified
3.0.0a3, installed from the public registries on 2026-11-16:
| pip | uvx | npx | |
|---|---|---|---|
macOS: real quickstart (5/5) | Passed | Passed | Passed |
macOS: Northwind through the CLI (services up, release 61/61, a live invoke, full teardown) | Passed | Not run | Not run |
macOS: agentbreeder up starts (scripted, no browser): one-time link redeemed, UI and API served, link reuse refused | Not run | Not run | Passed |
macOS: Northwind through up, or a kind cluster | Not run | Not run | Not run |
Linux: install, --version | Passed | Passed | Passed |
Linux: doctor passes every check | Passed | Ran, Docker unreachable | Ran, Docker unreachable |
Linux: real quickstart or Northwind | Not run | Not run | Not run |
- Northwind runs on
runtime/adk@1.3.0. Thenew agentstarter'sruntime/adk@1.4.0was not part of this run. - On Linux,
doctorpassed every check on the pip path once the user could reach the Docker socket and Compose v2 was installed. On the uvx and npx paths it ran as a user without socket access, and reported Docker as unreachable; it was not rerun with access. uv tool installon macOS:--versionanddoctor(doctorwarned thatagentbreederwas not onPATH, because uv's executable directory was not on it).- For a few minutes after the upload, uv reported that
agentbreeder==3.0.0a3did not exist while PyPI already listed it. It resolved on its own; if you see this right after a release, retry.
3.0.0a2, installed from the public registries on 2026-11-11:
| pip | uvx | npx | |
|---|---|---|---|
macOS: real quickstart (5/5) | Passed | Passed | Passed |
macOS: agentbreeder up starts, sign-in, UI served | Not run | Passed | Passed |
macOS: Northwind through up's API (scripted, no browser): release 61/61, kind promote 61/61, full teardown | Not run | Not run | Passed |
| Linux: anything | Not run | Not run | Not run |
uv tool install on macOS, 2026-11-11: --version, doctor and a real quickstart (5/5); up and Northwind
not run.
3.0.0a1, installed from the public registries on 2026-11-10:
| pip | uvx | npx | |
|---|---|---|---|
macOS: real quickstart (5/5) | Passed | Passed | Passed |
macOS: Northwind to 61/61, live /invoke, full teardown | Passed | Not run | Not run |
Linux: install, --version, doctor | Passed | Passed | Passed |
Linux: real quickstart or Northwind | Not run | Not run | Not run |
- macOS means macOS 13 with Docker Desktop, in a clean sandbox: a fresh
HOME(with~/.dockerlinked in for the Docker context), empty package caches and no checkout. Docker images and build layers on the host were not cleared. - Linux means Ubuntu 24.04 in a container, with Node 18.19.1.
For 3.0.0a3, the wheel and sdist on PyPI and the npm tarball are byte-identical to the ones
attested by the release workflow. Installing from the hashed requirements file worked on macOS with
pip and with uv pip (--version on both; doctor, every check passed, in the pip install).
For 3.0.0a2, the wheel and sdist on PyPI are byte-identical to the ones attested by the release
workflow, and installing the wheel with pip from the hashed requirements file passed doctor and
started up in the TestPyPI rehearsal on macOS (pip only; uv pip was not run on 3.0.0a2). For 3.0.0a1, the hashed install passed the install smoke test with
pip and uv pip, on macOS from PyPI and on macOS and Ubuntu from TestPyPI.
How long it took
Measured once each on macOS, each path in its own clean sandbox (the 3.0.0a1 rows on
2026-11-10, the 3.0.0a3 rows on 2026-11-16). Docker images and build layers already on the machine were not cleared, so a first run
on a new machine will take longer.
| Step | Time |
|---|---|
Create a virtual environment and pip install (3.0.0a1) | 9 s |
agentbreeder quickstart, cold sample build (3.0.0a1) | 62 s |
quickstart including the install, Docker image cache not cleared (3.0.0a2: pip, uvx, npx) | 22 s, 9 s, 11 s |
quickstart, Docker image cache not cleared (3.0.0a3): pip after a 10 s install; uvx and npx including the fetch | 15 s, 10 s, 12 s |
Northwind: services up (5 services, 3.0.0a3, pip) | 245 s |
Northwind: release (build, 61 evals, promote, 3.0.0a3, pip) | 277 s |
Command center: start services (5 services, 3.0.0a2) | 162 s |
Command center: release (build, 61 evals, promote, 3.0.0a2) | 189 s |
Command center: connect a kind cluster, then start services again after the grant change (3.0.0a2) | 45 s + 12 s |
Command center: promote to the cluster (push, deploy, 61 evals, 3.0.0a2) | 241 s |
Command center: remove both deployments, the cluster and the services (3.0.0a2) | 57 s |
Not measured: installing Docker, Python, uv or Node, or getting the API keys.
Install with hashes
The v3.0.0a3 GitHub release
carries requirements-3.0.0a3.txt, with a hash for every package, and a SHA256SUMS file.
uv pip install --require-hashes -r requirements-3.0.0a3.txt
# or
pip install --require-hashes -r requirements-3.0.0a3.txtNeither uvx nor npx enforces hashes. The npx launcher bounds what resolves with --exclude-newer
and a constraints file. The uvx command above pins only agentbreeder itself, so its dependencies
resolve to the newest versions allowed. On both paths, your uv index settings decide where the
packages come from.
Install from a checkout
Use a fresh virtual environment: an older install can expose the 2.x CLI.
git clone https://github.com/agentbreeder/agentbreeder.git
cd agentbreeder
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'Using 2.x
If you need 2.x, pin agentbreeder<3 and read Legacy 2.x first. There is no
migration path between 2.x and 3.x.
AgentBreeder overview
AgentBreeder builds, evaluates and deploys AI agents on local Docker behind a deploy-time identity gate. Open-source alpha preview, 3.0.0a3.
Your own agent
Write an agent in agent.yaml, start its services, build, test, release it through an eval gate and call it on local Docker, step by step.