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

Local deployment

Deploy, call, watch and remove a trusted HTTP container on a local Docker engine, with history in SQLite and every attempt in the audit log.

Alpha preview. This is a development-only, single-user runtime. It has run end to end on macOS; on Linux only the install and doctor have been checked. There is no production deployment target; the console runs these same commands.

Requirements for your image

  • A trusted, stateless HTTP container that returns HTTP 200 from its health path.
  • It runs as UID/GID 65532 with a read-only filesystem and listens on 0.0.0.0 at the manifest port inside the container.
  • The port is published on host loopback only. Health checks follow no redirects and use no proxies.
  • Images that declare VOLUME are rejected, as are non-local Docker transports. --local deploys only target: local manifests; see Kubernetes on kind for the other target.
  • Secrets are local files: agentbreeder secret set NAME < value stores one in <state-dir>/secrets/NAME. A manifest entry DATABASE_URL: secret://NAME is mounted read-only at /run/secrets/NAME, and the container gets DATABASE_URL_FILE. The value never appears in docker inspect, labels, logs or the audit log. Anyone who can docker exec into the container, or who owns the state directory, can read it.

Deploy your own image

Every deploy first passes the identity gate, so you need an operator config and an onboarded agent principal. Without them the deploy fails closed (CONTEXT_ENVIRONMENT_UNKNOWN). For a local trial, use the static adapter as the demo does; real operators point a provider at their IdP. Both files must be private (mode 0600).

umask 077
cat > principals.yaml <<'YAML'
principals:
  my-agent:
    kind: agent
    enabled: true
    environment: dev
    review_by: "2099-01-01"
    sponsors: [{id: me, name: me@example.com, active: true}]
YAML
cat > operator.yaml <<'YAML'
enforcement: enforce
default_environment: dev
environments:
  dev: {targets: [local]}
providers:
  trial: {type: static, authority: trial, file: principals.yaml}
YAML
export AGENTBREEDER_OPERATOR_CONFIG="$PWD/operator.yaml"

.venv/bin/agentbreeder example http-agent   # copies the sample to ./http-agent
docker build --iidfile image-id http-agent
cat > agent.yaml <<YAML
schema_version: 2
name: http-sample
image: $(cat image-id)
target: local
identity: {provider: trial, ref: my-agent, environment: dev}
YAML
.venv/bin/agentbreeder deploy agent.yaml --local --environment dev
curl -s -X POST ENDPOINT/invoke -d '{"message":"hello"}'

Keep AGENTBREEDER_OPERATOR_CONFIG set for later commands, so status can re-verify the principal:

.venv/bin/agentbreeder status DEPLOYMENT_ID --json
.venv/bin/agentbreeder remove DEPLOYMENT_ID --local

Call, watch and read logs

agentbreeder list                                  # deployments in this state
agentbreeder invoke NAME "hello"                   # one message to a ready local deployment
agentbreeder logs DEPLOYMENT_ID --follow           # redacted container logs
agentbreeder watch --stack DIR --json              # a stack's containers dying or restarting
agentbreeder events --unread                       # stored events: a container died, a gate failed

invoke calls only the loopback endpoint in local state, after Docker confirms it is the recorded container. Pass - to read the message from stdin: an argument is visible in ps. logs redacts the stack's stored secrets in their common encodings; it is best effort. With agent.yaml projects, add --stack DIR to each command.

Repeating a deploy with the same manifest resumes the same deployment. A changed manifest needs the earlier deployment removed first; in-place updates are later work. For agents built from agent.yaml, agentbreeder release replaces production after an eval gate and can roll back (see Build from agent.yaml).

status re-resolves the bound principal and reports compliant, noncompliant:<code> or unverifiable:<code>. The deployment state it shows is the last recorded observation, not a live health check.

Exit codes

CodeMeaning
0Deployment or removal verified, or status read of a deployment that has not failed
1Recorded runtime failure (including status of a failed deployment), an incomplete disable, unfinished blocked cleanup in reconcile, or an invalid chain in audit verify
2Invalid input, gate denial ([CODE]), audit-write failure, missing or inaccessible state (including a mistyped --state-dir) or prerequisite failure
3Deployment is pending a second-person approval
4reconcile found a noncompliant or unverifiable deployment

With --json, errors go to stderr only and stdout stays empty.

State and limits

  • State and event history live in ~/.agentbreeder/local (override with --state-dir). The directory must be 0700 and the database 0600, both owned by you. Keep the directory while resources exist.
  • 3.0.0a3 moves the state to schema v4. The first command that writes (deploy, status, remove, migrate) upgrades it in place; read-only commands ask you to run agentbreeder migrate. 3.0.0a2 can't read the state afterwards.
  • Anyone with access to the Docker socket can bypass these local controls.
  • Workloads can make outbound connections unless the operator turns on runtime enforcement.
  • The local tool adds no authentication to invocation. Don't publish the port externally.

Canonical reference: docs/local-deployment.md and docs/first-deployment.md.

On this page