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.0at 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
VOLUMEare rejected, as are non-local Docker transports.--localdeploys onlytarget: localmanifests; see Kubernetes on kind for the other target. - Secrets are local files:
agentbreeder secret set NAME < valuestores one in<state-dir>/secrets/NAME. A manifest entryDATABASE_URL: secret://NAMEis mounted read-only at/run/secrets/NAME, and the container getsDATABASE_URL_FILE. The value never appears indocker inspect, labels, logs or the audit log. Anyone who candocker execinto 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 --localCall, 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 failedinvoke 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
| Code | Meaning |
|---|---|
| 0 | Deployment or removal verified, or status read of a deployment that has not failed |
| 1 | Recorded runtime failure (including status of a failed deployment), an incomplete disable, unfinished blocked cleanup in reconcile, or an invalid chain in audit verify |
| 2 | Invalid input, gate denial ([CODE]), audit-write failure, missing or inaccessible state (including a mistyped --state-dir) or prerequisite failure |
| 3 | Deployment is pending a second-person approval |
| 4 | reconcile 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 be0700and the database0600, both owned by you. Keep the directory while resources exist. 3.0.0a3moves the state to schema v4. The first command that writes (deploy,status,remove,migrate) upgrades it in place; read-only commands ask you to runagentbreeder migrate.3.0.0a2can'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.
MCP tools
MCP servers run behind a relay that holds the credential, forwards only granted, pinned tools and records every tool call in the audit log.
Kubernetes on kind
Promote a released agent image by digest to a local kind cluster behind restricted Pod Security and network policy. No production cluster has been tested.