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 madeagent.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}withsets a service's params;wireconnects 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.lockrecords the hash of every service version and file param;--lockedrefuses any change, andup --updateaccepts 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
- Locks the service versions and checks params, wiring and the gateway's model aliases.
- Prints the grant: every service and its image (built-in or project), egress, which
networks can reach it, its
127.0.0.1ports, imported variable names, what agents receive, the gateway's models and where each provider key goes. It needs--yesthe first time and whenever the grant changes. - Generates and imports secrets, builds project services, starts everything, waits for health,
and runs one-shot
initandbootstrapsteps (creating database roles, minting Phoenix's ingest key). - 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
| Service | Runs | Gives |
|---|---|---|
service/postgres-pgvector@1.2.0 | PostgreSQL 16 with pgvector | a URL per database, each with its own role; least-privilege roles; an optional read-only console role for tool log |
service/litellm@1.0.0 | the LiteLLM proxy as the model gateway | its URL; a master key only AgentBreeder uses |
service/litellm@1.1.0 | as 1.0.0, plus Presidio guardrails | as 1.0.0 |
service/litellm@1.2.0 | as 1.1.0, plus Ollama on the host, and LiteLLM gets only an allow-list of variables | as 1.0.0 |
service/presidio-analyzer@1.0.0, service/presidio-anonymizer@1.0.0 | Microsoft Presidio, internal only | a URL for the gateway |
service/phoenix@1.1.0 | Arize Phoenix with auth on, data in Postgres | its 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.
Sub-agents and skills
agent.yaml can declare sub-agents and skills and the registry stores skill versions, but no runtime runs them yet, so build refuses them. Schema and build only.
Models and gateway
Every model call goes through the stack's LiteLLM gateway on a per-deployment key with a budget, rate limit and fallbacks. Which providers have run end to end.