Alpha preview: pin 3.0.0a3 when you install. A bare pip install agentbreeder still installs the unmaintained 2.x: known issues.
agentbreeder

Backing services

Declare the backing services an agent needs in stack.yaml. agentbreeder services up starts them on local Docker and writes a demo operator config.

Local-only preview

agentbreeder services runs on the local Docker engine only and is not production infrastructure. Run on macOS with Docker Desktop: Northwind started from scratch with services up and released 61/61 (from PyPI 3.0.0a1 on 2026-11-10, and in every later run from main), and services restart, services usage and the console's service screens ran from main. Linux has not been run.

An agent built from agent.yaml needs services before it can run: Postgres, a model gateway, a trace collector, sometimes project helpers. A project declares them in stack.yaml next to agent.yaml, and one command starts them:

agentbreeder example northwind   # copies it to ./northwind
cd northwind
agentbreeder services up --environment dev --env-file ~/.env   # shows the grant; --yes confirms
agentbreeder release agent.yaml --stack . --environment dev    # build, candidate, evals, promote
agentbreeder services status --json
agentbreeder services restart litellm                          # one container; --yes if agents use it
agentbreeder services usage --follow                           # CPU, memory, network and block IO
agentbreeder services down --purge --yes                       # remove everything up made

agent.yaml doesn't change and still grants nothing. services up writes the operator config for a local demo environment outside the repo, under ~/.agentbreeder/stacks/, and --stack DIR points build, deploy, eval, release, status, remove and reconcile at it.

stack.yaml

kind: stack
schema_version: 1
name: northwind
services:
  postgres:
    ref: service/postgres-pgvector@1.2.0
    with:
      databases: [support, litellm, phoenix]   # one database and one login role each
      init_sql: stack/db/commerce.sql          # schema, seed data and grants
      init_sql_database: support
      roles: [support_agent, support_ops]      # least-privilege roles in `support`
      roles_database: support
  litellm:
    ref: service/litellm@1.0.0
    with: {config: stack/litellm/config.yaml}
    wire: {database-url: postgres.databases.litellm}
  phoenix:
    ref: service/phoenix@1.0.0
    wire: {database-url: postgres.databases.phoenix}
environment:
  gateway: litellm
  models: [support-model, support-embedding, support-judge]
  ceilings: {budget_usd: 50, rpm: 300}
  bindings:
    DATABASE_URL: {ref: postgres.roles.support_agent}   # can't approve its own requests
  eval_database: {ref: postgres.databases.support}
  agents:
    northwind-support: {sponsor: support-lead@example.com, review_by: "2027-06-30", candidate: true}
  • with sets a service's params; wire connects its inputs to other services' outputs, so services never name each other.
  • Secret outputs are only ever used whole: wired to a service, or bound into the agent as a mounted file. They never appear in environment variables or labels.
  • stack.lock records the hash of every service version and file param; --locked refuses any change, and up --update accepts an edited project file (never a changed published version).
  • Give the agent the narrowest database role that works. In Northwind the agent can file cancellation requests but can't approve one or change an order; only the ops role can.

What services up does

  1. Locks the service versions and checks params, wiring and the gateway's model aliases.
  2. Prints the grant: every service and its image (built-in or project), egress, which networks can reach it, its 127.0.0.1 ports, imported variable names, what agents receive, the gateway's models and where each provider key goes. It needs --yes the first time and whenever the grant changes.
  3. Generates and imports secrets, builds project services, starts everything, waits for health, and runs one-shot init and bootstrap steps (creating database roles, minting Phoenix's ingest key).
  4. Writes the demo operator config and identities.

Every services write holds a per-stack lock; a second one fails at once with SERVICES_BUSY. A taken host port is PORT_BUSY, naming the port. A service still starting after 180 s gets up to 240 s more while its container runs, and up can be run again to continue.

Every service runs with a read-only root filesystem, no capabilities and no-new-privileges. Every HTTP port reachable outside the stack has a guard (a bearer key, LiteLLM auth, or Host and Origin checks). Agents join a separate network that reaches only the ports declared for them.

Built-in services

ServiceRunsGives
service/postgres-pgvector@1.2.0PostgreSQL 16 with pgvectora URL per database, each with its own role; least-privilege roles; an optional read-only console role for tool log
service/litellm@1.0.0the LiteLLM proxy as the model gatewayits URL; a master key only AgentBreeder uses
service/litellm@1.1.0as 1.0.0, plus Presidio guardrailsas 1.0.0
service/litellm@1.2.0as 1.1.0, plus Ollama on the host, and LiteLLM gets only an allow-list of variablesas 1.0.0
service/presidio-analyzer@1.0.0, service/presidio-anonymizer@1.0.0Microsoft Presidio, internal onlya URL for the gateway
service/phoenix@1.1.0Arize Phoenix with auth on, data in Postgresits URL; an ingest key for services and a read-only key for traces

Older versions stay available; a stack keeps the versions its stack.lock records until you change the ref.

Projects add their own versions under registry/service/, from a digest-pinned image or built from source with a strict Dockerfile subset.

MCP servers

Each mcp: entry in stack.yaml runs behind its own relay, which holds the credential and forwards only granted, pinned tools. See MCP tools.

Limits

  • Local Docker only; demo identities come from a generated static provider.
  • A deployed agent's endpoint is not authenticated.
  • Usage figures are of the Docker VM, and CPU is a share of one core, so it can pass 100%.

The canonical reference is services.md.

On this page