agentbreeder quickstart # full local stack + 5 sample agentsagentbreeder init # scaffold a new agent.yamlagentbreeder validate # check agent.yamlagentbreeder deploy --target # local, ecs-fargate, cloud-run, container-apps ship full governance; app-runner is single-container; k8s + claude-managed in flight (see deploy table)agentbreeder chat <name> # talk to a deployed agentagentbreeder list agents # see what's deployedagentbreeder studio # open Studioagentbreeder down # stop the local stack
Authenticate against the AgentBreeder API. Tokens are stored in the OS keychain (macOS Keychain, GNOME libsecret, Windows Credential Manager). The AGENTBREEDER_API_TOKEN env var always wins over the keychain, so the same binary works on laptops and in CI.
Paste an existing JWT (e.g. issued by Studio) instead of using email/password.
--api-url
Override the API URL. Defaults to $AGENTBREEDER_URL, then http://localhost:8000.
Examples:
agentbreeder login # Interactiveagentbreeder login -e alice@example.com -p "$AB_PASSWORD" # Non-interactiveagentbreeder login --token "eyJhbGciOi…" # Paste a token from Studioagentbreeder whoami# email alice@example.com# role deployer# team (primary) engineering# active team opsagentbreeder logout # Clears the keychain entry
logout deletes the keychain entry. It does not revoke the token server-side — the JWT remains valid until its 24h expiry. See refresh-token issue #395 for revocation support.
Set the active team context. The active team is sent on every authenticated request as the X-AgentBreeder-Team header and is shown by agentbreeder whoami.
agentbreeder context use TEAMagentbreeder context showagentbreeder context clear
The context lives in ~/.agentbreeder/context.json.
Examples:
agentbreeder context use ops # Act as team "ops"agentbreeder context show # Active team: opsagentbreeder context clear # Fall back to your primary team
Check that this machine satisfies AgentBreeder's prerequisites. Run before quickstart (or any time a command exits with a missing-prerequisite error) to find out exactly what's missing and how to fix it.
agentbreeder doctor [--json]
Checks performed (each prints a copy-pasteable fix when it fails):
Check
Required
Python ≥ 3.11
yes
Container runtime installed and daemon reachable (Docker, Podman, or nerdctl)
yes
Free disk ≥ 8 GiB in the current working directory
yes
RAM ≥ 4 GiB (best-effort; warns on platforms where total RAM can't be detected)
yes when detectable
Exits 0 when every required check passes, 1 otherwise. Designed to return in well under two seconds.
Examples:
agentbreeder doctor # human-readable reportagentbreeder doctor --json # JSON for scripts and CI
quickstart runs the same checks at start and bails out fast if anything's missing. Use agentbreeder quickstart --skip-doctor to bypass (advanced; intended for CI sandboxes that intentionally skip the host checks).
Also deploy to cloud after local setup. aws (ECS Fargate), gcp (Cloud Run), and azure (Container Apps) all ship with full governance parity. This CLI path deploys into existing infra (plus auto-provisioned RDS/Redis data backends); greenfield provisioning ships via the Studio deploy wizard. Secret auto-mirror ships for GCP + Azure; on AWS, pre-create secrets in Secrets Manager. See the deploy-target status table.
--no-browser
Off
Don't open Studio at http://localhost:3001
--skip-seed
Off
Skip ChromaDB + Neo4j seeding (fast restart)
--dev
Off
Build API and Studio from local source instead of pulling images
--reset
Off
Tear down all docker volumes (postgres, redis, chromadb, neo4j) and start fresh
--no-ollama
Off
Cloud-only setup. Skip the Ollama install, daemon start, and model pull (saves ~1–2 min and a ~3 GB download). Equivalent to choosing Cloud at the interactive model-source prompt.
--ollama-model
gemma3
Pull a different default model for Ollama (e.g. llama3.2, phi4-mini)
--yes, -y
Off
Non-interactive mode for CI / scripted runs. Skip every yes/no prompt and use safe defaults: model-source falls back to the legacy "Both" path (or Cloud when --no-ollama is set), port conflicts get auto-killed, Ollama install/rebind/model-pull and Studio rebuild are auto-accepted. Blocking prompts that require human input (e.g. "press Enter once the daemon is up") exit fast instead of waiting. Does not auto-install Docker — runtime must already be present. Does not invent provider keys — export OPENAI_API_KEY (or equivalent) before running.
--skip-doctor
Off
Skip the prerequisite preflight (advanced; CI environments — pairs naturally with --yes).
Container-runtime diagnostics: When the daemon is installed but not reachable, quickstart names the specific cause and the exact fix command — no generic "could not connect" messages.
Detected condition
Cause line + fix
Stale $DOCKER_HOST
"Points at a missing socket: <path>" → unset DOCKER_HOST
Info note about bind-mount volume ownership (non-blocking)
The selected runtime line also echoes how to override it: export DOCKER_HOST=unix://<path>.
What it does:
Detects Docker / Podman; shows OS-specific install instructions if neither is found
Asks how you want to run models: Local (Ollama, ~3 GB), Cloud (BYO API key), or Both (default). Press Enter at the prompt to take the default; pass --no-ollama to short-circuit to Cloud. Non-interactive runs keep the legacy "Both" behavior.
Creates .env with secure random secrets if not present
Starts the full stack via docker-compose.quickstart.yml: API · Studio · PostgreSQL · Redis · ChromaDB · Neo4j · MCP servers · LiteLLM
Waits for all services with a live progress bar
Seeds ChromaDB (vector store) and Neo4j (knowledge graph) with sample data
Step 1 (Ollama): detects if Ollama is installed and running; shows OS-specific install instructions; presents a model picker with sizes and recommended use cases; runs ollama pull for the selected model.
Step 2 (cloud providers): walks through Anthropic, OpenAI, Google AI, and OpenRouter; shows exact URL to get each API key; validates key format; makes a live API call to verify the key works; saves to .env.
Examples:
agentbreeder setup # Full setup (Ollama + cloud providers)agentbreeder setup --ollama-only # Only configure Ollamaagentbreeder setup --providers-only # Only configure cloud provider keys
Seed registry tables (agents, prompts, tools, MCP servers, providers, knowledge bases) from examples/seed/. Idempotent — only empty tables are populated.
--examples-dir PATH
<repo>/examples/seed/
Custom path to seed YAMLs (registry mode only)
--docs PATH
deploy/seed/docs/
Directory of .md / .txt files to ingest into ChromaDB
--collection NAME
agentbreeder_knowledge
ChromaDB collection name
--cypher PATH
—
Custom .cypher file to run against Neo4j
--clear
Off
Wipe existing data before seeding
--list
Off
Show what is currently seeded (no writes)
Without --chromadb, --neo4j, or --registry, both ChromaDB and Neo4j are seeded.
The API server also runs the registry seeder automatically on first boot when
AGENTBREEDER_AUTO_SEED=true (default for AGENTBREEDER_INSTALL_MODE=dev,
disabled for cloud). Use agentbreeder seed --registry to populate registry
tables manually — e.g. against an already-running API.
Go scaffold (--lang go --framework custom) writes main.go, main_test.go, go.mod, agent.yaml, Dockerfile, .gitignore, .env.example, README.md. The agent uses the Go SDK and satisfies Runtime Contract v1 out of the box.
POST to the API server (RBAC + audit enforced). Auto-enabled when $AGENTBREEDER_URL is set.
--local
No
Auto
Run the deploy engine in-process. Use for dev / offline work; bypasses RBAC + audit.
--provision, -p
No
Off
Greenfield-provision the cloud footprint (VPC, subnets, NAT, cluster, IAM) for a fresh account before deploying, then inject the IDs into the deploy. AWS only; local mode only for now (--local --provision). The footprint is recorded in .agentbreeder/infra-state.json and removed by agentbreeder teardown.
--json
No
Off
Emit JSON to stdout (for CI/scripting).
Remote vs. local mode
agentbreeder deploy has two execution paths:
Remote (recommended for production) — POSTs /api/v1/deploys against the API server identified by $AGENTBREEDER_URL, then polls the job until it terminates. The bearer token comes from agentbreeder login (OS keychain) or $AGENTBREEDER_API_TOKEN. Team-scoped RBAC, audit logging, and team-scoped cloud credentials all fire on this path.
Local — runs the deploy engine in the CLI process. Useful for offline development and for the local Docker Compose target. It explicitly bypasses every server-side gate, so it should never be used to deploy production agents from a developer laptop.
Mode is picked by these rules, in order:
--local → local mode regardless of env
--remote → remote mode regardless of env
otherwise: remote when $AGENTBREEDER_URL is set, else local
Supported --target values:
This is the canonical deploy-target status table for AgentBreeder — other docs link here rather than repeating it. As of v2.6.0, the same agent.yaml deploys with full governance parity — the sidecar (guardrails, cost, tracing) plus secret mirroring — to Local, AWS ECS Fargate, GCP Cloud Run, and Azure Container Apps. AWS App Runner is single-container: it deploys without a sidecar and rejectsguardrails: / secrets: at validate-infra. Kubernetes and Claude-managed are in flight.
Greenfield vs. existing account. The CLI (agentbreeder deploy) deploys
into existing infrastructure — a VPC, subnets, cluster, and execution role you
already have (the per-cloud BYO contract) — or, on AWS, greenfield-provisions
that footprint from scratch with --provision. For GCP/Azure, greenfield ships
through the Studio deploy wizard (Step 3 → Provision for me); CLI --provision
for those clouds is on the
roadmap. Independently,
both surfaces auto-provision the data tier (RDS pgvector / ElastiCache Redis) when
an agent declares memory: or a knowledge base without a backend_url.
Target
Status
Greenfield provisioning
Sidecar (governance)
Secret auto-mirror
local (Docker Compose)
✅ Shipped
✅ (nothing to provision)
✅
n/a (local .env)
ecs-fargate (AWS)
✅ Shipped
✅ CLI --provision + Studio wizard¹
✅
🟡 Roadmap — pre-create in Secrets Manager
cloud-run (GCP)
✅ Shipped
✅ Studio wizard¹ · CLI BYO + auto data tier
✅
✅
container-apps (Azure)
✅ Shipped
✅ Studio wizard¹ · CLI BYO + auto data tier
✅
✅
app-runner (AWS)
✅ Shipped (single-container)
CLI BYO only — --provision/wizard provision ECS Fargate, not App Runner
❌ — rejects guardrails:/secrets:
❌ — not supported
kubernetes (EKS/GKE/AKS/self-hosted)
🟡 In flight
❌ — needs existing cluster + kubeconfig
✅ (when usable)
🟡 Roadmap
claude-managed (Anthropic)
🟡 In flight
n/a — runtime is Anthropic-managed
n/a
n/a
¹ AWS greenfield ships from the CLI today (agentbreeder deploy --target ecs-fargate --provision --local) and from Studio → Deploys → New deploy (the
/deploy-wizard flow) + the deployments job API (POST /api/v1/deployments with
infra_mode: "provision"). See Deployment → Greenfield mode
and Deploying from Studio. For GCP/Azure, CLI
--provision is not yet shipped — use the Studio wizard, deploy into existing infra
(BYO), or pre-create the footprint first.
Each --target value maps to one cloud + runtime combination:
agentbreeder list [ENTITY_TYPE] [--team TEAM] [--json]
Argument / Option
Required
Default
Description
ENTITY_TYPE
No
agents
One of: agents, tools, models, prompts
--team
No
—
Filter by team name
Examples:
agentbreeder list # List all agentsagentbreeder list agents # Same as aboveagentbreeder list tools # List MCP servers and toolsagentbreeder list models # List registered modelsagentbreeder list prompts # List prompt templatesagentbreeder list agents --team platform # Filter by teamagentbreeder list --json # JSON output
Push, list, and exercise prompts, tools, and agents in the AgentBreeder registry. Each entity has a kebab-case name, is resolved at agent startup via the file-first chain documented in the runtime, and is versioned in Postgres.
Calls POST /api/v1/registry/prompts/{prompt_id}/render and returns {output, model, duration_ms, error}.
Example:
agentbreeder registry prompt try microlearning-system \ --input "Pick a topic for a beginner ebook." \ --model gemini-2.5-flash --temperature 0.4# model: gemini-2.5-flash duration: 1842ms# output: How about "Spaced repetition for language learners"? It's narrow…
Persist an agent.yaml in the registry via POST /api/v1/agents/from-yaml. The record stores name, version, framework, deploy config, and refs to the prompts + tools the agent uses.
Send a message to a deployed agent's /invoke endpoint via the server-side proxy (POST /api/v1/agents/{id}/invoke). The proxy attaches the bearer token from --token (or env var AGENT_<UPPER_SNAKE>_TOKEN) so secrets never leave the API host.
agentbreeder registry agent invoke microlearning-ebook-agent \ --input "What is your job?" \ --endpoint https://microlearning-ebook-agent-sizukgalta-uc.a.run.app \ --token $AGENT_AUTH_TOKEN# status: 200 duration: 1.4s session: 7c3f…# output: My job is to turn any topic the user supplies into a polished microlearning# ebook a learner can complete in 20-40 minutes.
Upload and ingest one or more files into a registered RAG index. Resolves the index name (or UUID) and POSTs multipart/form-data to /api/v1/rag/indexes/{id}/ingest. Files are chunked, embedded, and indexed by the API.
Registered RAG index name (e.g. agentbreeder-knowledge) or its UUID
FILE...
path
—
One or more files to ingest
--replace
flag
off
Delete any existing chunks whose source matches one of the incoming filenames before ingest. Without this flag, ingest is idempotent: chunks whose SHA-256 content hash already exists in the index are skipped.
--json
flag
off
Print the raw API response as JSON
Allowed file types:.pdf, .txt, .md, .csv, .json (matches the API allow-list — unsupported extensions are rejected client-side before any upload).
Idempotency: by default, re-ingesting the same file is a no-op — the API hashes every chunk (SHA-256) and skips any chunk whose hash already exists in the index. Use --replace when you've edited the file and want the old chunks to be dropped first.
Example:
agentbreeder registry rag ingest agentbreeder-knowledge ./docs/intro.md ./docs/quickstart.pdf# ✓ Ingested 14 chunks from 2 file(s) into agentbreeder-knowledge (job=ca2e0c7a status=completed)# After editing intro.md, drop the old chunks and re-ingest:agentbreeder registry rag ingest agentbreeder-knowledge ./docs/intro.md --replace
Without an agent name, shows a summary table of all deployed agents with their status. With an agent name, shows detailed status including deploy pipeline progress.
Examples:
agentbreeder status # All agents summaryagentbreeder status my-agent # Detailed status for one agentagentbreeder status --json # JSON output
Cloud provider to clean up: gcp, aws, azure, or all
--dry-run
false
Preview what would be deleted without making any changes
--agent
—
Limit teardown to a single named agent across cloud targets
--region
—
Cloud region (GCP / AWS)
--project
—
GCP project ID
--destroy-resource-group
false
Also delete the Azure resource group itself
Removes Cloud Run services, ECS services/task definitions, Container Apps, Artifact Registry / ECR repositories, and associated secrets for all agents labelled managed-by: agentbreeder.
Examples:
# Single-agent local teardownagentbreeder teardown my-agent # Prompts for confirmationagentbreeder teardown my-agent --force # No confirmation# Bulk cloud teardownagentbreeder teardown --cloud gcp --project my-proj --region us-central1 --dry-runagentbreeder teardown --cloud aws --region us-east-1agentbreeder teardown --cloud azure --destroy-resource-groupagentbreeder teardown --cloud all # All three clouds at once# Limit to one agent across all cloudsagentbreeder teardown --cloud all --agent customer-support-agent --dry-run
Catalog providers (OpenAI-compatible):nvidia, openrouter, moonshot, groq, together, fireworks, deepinfra, cerebras, hyperbolic. See Providers for the full list and how to add your own.
API keys are stored in the project .env file (or ~/.agentbreeder/.env if no project). Catalog provider keys live only in your environment — only the env-var name is persisted, never the value.
List models in the registry. Supports --provider, --status, --per-page, --json.
show NAME
Show a single model's full record (id, status, context, pricing, lifecycle timestamps).
sync
Discover models from each configured provider and reconcile the registry. Supports --provider NAME (repeatable). Deployer role required.
sync-now
Run the daily sync sweep immediately, in-process (bypasses the API server). Talks directly to the database; useful for testing the cron and for self-hosted environments without the daily loop. Supports --json.
deprecate NAME
Manually mark a model deprecated. Supports --replacement NAME. Deployer role required.
The sync and deprecate subcommands talk to POST /api/v1/models/sync and POST /api/v1/models/{name}/deprecate respectively. Status flips emit audit events: model.added, model.deprecated, model.retired. See Providers → Model lifecycle for the full state machine.
Examples:
# Inspectagentbreeder model list # All models, status badgesagentbreeder model list --provider nvidia # Restrict to one provideragentbreeder model list --status deprecated --json # Machine-readable + filteredagentbreeder model show gpt-4o # Full record# Syncagentbreeder model sync # Every provider with an api-keyagentbreeder model sync --provider nvidia --provider groqagentbreeder model sync --json # Machine-readable result# Sync immediately, in-process (no API server required)agentbreeder model sync-now # Same sweep as the daily cronagentbreeder model sync-now --json # Machine-readable summary# Manual deprecate (operator override)agentbreeder model deprecate gpt-3.5-turbo --replacement gpt-4o-mini
Daily cron. Cloud workspaces (AGENTBREEDER_INSTALL_MODE=cloud) run a built-in daily sweep that auto-deprecates absent models and emits a model.sync.scheduled audit event. Self-hosted users opt in via AGENTBREEDER_MODELS_DAILY_SYNC=true. Models that disappear from a provider's /models endpoint are auto-deprecated on the next sweep; after 30 days of continuous absence they're auto-retired.
Generate a Full Code SDK scaffold from an existing agent.yaml or orchestration.yaml file. Enables tier mobility from Low Code (YAML) to Full Code (Python/TypeScript SDK) without losing any configuration.
Agent ejection recreates the YAML as a builder-pattern Agent(...) chain using Agent, Tool, Model, and Memory from agenthub. Includes commented scaffolding for middleware, event hooks, and custom routing.
Orchestration ejection recreates orchestration.yaml as the appropriate SDK class (Orchestration, Pipeline, FanOut, or Supervisor) with all agents, routes, shared state, and deploy config preserved.
What it generates (agents):
Agent(...) builder chain matching every field in the YAML
Model, prompt, tools, memory, guardrails, deploy, and tags
Commented middleware and hook examples
__main__ block that validates and prints YAML round-trip
What it generates (orchestrations):
Correct subclass (Pipeline, FanOut, Supervisor, or Orchestration)
All agents, routing rules, fallbacks, shared state, supervisor config
Commented custom Router subclass scaffold for advanced routing logic
Mirrors workspace secrets to a cloud secrets manager. This is the same
operation that runs implicitly inside agentbreeder deploy when the agent
declares deploy.secrets and targets aws or gcp. Run it manually to
pre-populate a new environment. Each mirrored secret emits a
secret.mirrored audit event.
Option
Required
Description
--target
Yes
Target cloud: aws, gcp, or vault
--workspace
No
Workspace name (default: workspace config)
--include
No
Restrict to specific secret names (repeatable)
--exclude
No
Skip these secret names (repeatable)
--prefix
No
Prefix in target backend (default: agentbreeder/)
--dry-run
No
Preview without writing
--json
No
Output as JSON
See the Secrets guide for full workspace + auto-mirror docs.
Standard cron expression, e.g. "0 8 * * *". Required unless --once.
--once
No
false
Run immediately once and exit (ignores --cron).
--dry-run
No
false
Print next 5 fire times and exit without running.
Examples:
agentbreeder schedule # Run cron schedule from current diragentbreeder schedule ./support-agent --cron "0 9 * * 1-5" # Weekdays at 9amagentbreeder schedule --once # Run once immediatelyagentbreeder schedule --dry-run --cron "0 * * * *" # Preview hourly fire times
agentbreeder template list # All templatesagentbreeder template list --framework langgraph # Filter by frameworkagentbreeder template list --category support # Filter by categoryagentbreeder template use customer-support-starter # Scaffold from template