pipeline.yaml reference
One file declares the whole loop: the stage graph, the LLM connection,
per-step isolation, secrets, and the commit policy. agentic-dev-loop init
scaffolds a working copy; this page is the complete reference.
Full example
name: my-construction-loop
extensions:
- agentic_dev_loop.engine.extensions.aidlc:AidlcExtension # bundled AI-DLC doc loader
additional_files:
- ../README.md # shared context for every agent step
llm:
model: openai/deepseek-v4-pro
base_url: https://api.deepseek.com
api_key_env: OPENAI_API_KEY
# reasoning_effort: medium # optional: low | medium | high | xhigh | none
# Named LLM profiles: a step names one with `llm: <name>` to move the whole
# profile (model, endpoint, key, effort default) together. The `llm:` block
# above remains the default.
# llms:
# review:
# model: openai/deepseek-v4-pro
# base_url: https://api.deepseek.com
# api_key_env: REVIEW_API_KEY
# reasoning_effort: xhigh
max_attempts: 10 # CLI --max-attempts overrides
agents_dir: sdk_agents # your <name>.agent.md files
steps:
- name: brief
reasoning_effort: medium
brief_inputs:
include: [AGENTS.md, coding-standards-ddd.yaml]
sections: [Repo rules digest, Unit scope digest, Environment facts, Open risks]
env_facts: ["the workspace is an export with no .git; verify with find/ls, never git status"]
on_pass: dev
- name: dev
agent: dev
produces: implementation-summary.md
terminal_timeout: 900
# forbidden_commands: ["npm install", "npm ci"] # per-step tool deny-list; engine defaults are git mutations + docker
on_pass: test
- name: test
command: .venv-sandbox/bin/python -m pytest tests/ -q -m "not docker"
setup: python -m venv .venv-sandbox && .venv-sandbox/bin/pip install -e ".[dev]"
timeout: 600
on_pass: review
on_fail: { goto: dev, retry: true }
- name: review
agent: review
artifact: review-findings.md
verdicts: { pass: APPROVED, fail: NEEDS CHANGES }
# reasoning_effort: xhigh # per-step override of the effective profile's effort
# llm: review # select a named `llms:` profile for this step
on_pass: qa
on_fail: { goto: dev, retry: true }
- name: qa
agent: qa
artifact: qa-report.md
verdicts: { pass: PASS, fail: FAIL }
max_iterations: 100
finalize_nudge_turns: 10
on_pass: commit
on_fail: { goto: dev, retry: true }
- name: commit
action: commit
params: { message: "feat: construct {subject} (agent dev loop)" }
Field reference
| Key | Notes |
|---|---|
agent: / command: / action: / brief_inputs: |
Exactly one per step. Agents live in agents_dir as <name>.agent.md; commands run sandboxed (mechanical, never an LLM call). commit is the sole host-side built-in action; consumer actions are sandbox-executed scripts (see host boundary). |
produces: / artifact: + verdicts: |
Hygiene-tracked outputs vs structured-verdict routing. The verdict comes from a validated record_verdict tool call, never from prose; stale artifacts are deleted at each attempt start. |
brief_inputs: |
A native brief step: { include: [<paths/globs>], env_facts: [<strings>], sections: [<headings>] }. It digests the included docs into an engine-owned attempt-brief.md that later agents read, and re-runs only when its inputs change. |
on_pass: / on_fail: |
A step name, terminal success/failure, or {goto: X, retry: true}. No loops happen unless you write them. |
env: / setup: / network: |
env: declares step vars (fixed safe base + declared vars only); setup: runs fresh at every step boundary in a one-shot provision container targeting the export (command or agent steps; network ON); network: true grants egress scoped by egress: (default off) - see per-stage networking. |
mounts: / egress: |
Per-step workspace isolation. mounts: lists {path, mode} entries (rw/ro, default ro), strict-by-default: empty/missing mounts nothing, and only declared-rw paths sync back to the repo. egress: names the hosts a networked step may reach ({class, presets, targets}). See mounts and egress. |
secrets: (top-level) / step secrets: |
Declares secret refs only - never values; each step opts in to the refs it needs. Resolved host-side and injected into that step's exec env only. See secrets. |
profile: (top-level) |
Names a bundled toolchain profile (python, dotnet-node, rust) or a consumer profile file path, merged at load time: isolation key-wise with the pipeline winning, caches unioned profile-first. A path-shaped ref resolves relative to the pipeline file's directory, so path profiles work from any working directory. |
isolation: (optional) |
Configures the sandbox - image override, resource caps, allow_git_mutations, seccomp_profile. It can never disable it. See isolation. |
terminal_timeout: |
Optional agent-step per-action timeout in seconds; overrides the SDK tool default. |
finalize_nudge_turns: |
Optional agent-step final-response nudge; requires max_iterations: and must be less than it. |
deps_policy: / lockfiles: |
locked (default) or open. The human-owned lockfile is the source of truth under locked; see dependency policy. |
caches: / sync_excludes: |
Top-level run-wide lists. caches: names toolchain cache dirs bind-mounted rw from host-side stores (a setup: hook can warm them); sync_excludes: names non-gitignored scratch paths skipped from export and sync-back. |
merge_on_conflict: |
Top-level list of append-style logs. A concurrent host edit to a listed path is union-merged instead of raising; see sync-back conflicts. |
llms: (top-level) / step llm: / reasoning_effort: |
Named LLM profiles, each a full LlmConfig; a step selects one whole with llm: <name>. reasoning_effort (low/medium/high/xhigh/none) is opt-in on the llm block, a profile, or a step. See reasoning effort. |
Isolation
The isolation: section is optional (opinionated defaults apply when
absent):
isolation:
image: ghcr.io/org/custom-dev@sha256:... # override (digest required)
memory: 4g # execution-container memory cap
cpus: 2 # execution-container cpu cap
allow_git_mutations: false
state_dir: ~/.agentic-dev-loop/state # host-side caches + audit (never mounted)
env:(per step) -VAR: valuesets it in the sandbox;VAR: nullinherits the host value. The sandbox env is the fixed safe base (PATH/HOME/LANG/LC_ALL/TERM) plus declared vars only - the globalenv_allowlistnever leaks in and the LLM key is never auto-added. Inside sandbox steps, the literal token{export}in a declared value is replaced with the container-side path of the export/workspace root, so recipes can point absolute-path tool env vars (e.g.CARGO_HOME: '{export}/.cargo-cache') at bind-mounted cache directories.setup:(command and agent steps) - a trusted author command (e.g.python -m venv .venv-sandbox && .venv-sandbox/bin/pip install -e ".[dev]") that runs fresh at the step boundary in a one-shot provision container with network ON, before the step's first turn, targeting the per-run export (never the real workspace). Setup outputs land in the export and are visible to the step's exec container immediately. Steps withoutsetup:trigger nothing; brief and action steps rejectsetup:at load.network:(command, agent, and sandbox-action steps) -network: trueruns the step in a bridge-network container whose traffic is forced through the engine-run per-policy egress proxy and reaches only the step'segress:allowlist (--read-only,--cap-drop ALL). Default isfalse- every step stays network-off unless it opts in. The host-side built-incommitaction rejectsnetwork:(refused once the registry is known).- Git mutations are blocked by default inside the sandbox (commit, push,
branch/tag create/delete, rebase); reads (
status/log/diff) always work.allow_git_mutations: truere-allows them per-pipeline. state_dir(run state) defaults to~/.agentic-dev-loop/runs/<pipeline-hash>/- the checkpoint DB andlast-error.mdlive there, outside the workspace mount, unreachable by the sandbox. An explicitstate_dir:keeps working unchanged; pointing it inside the workspace is an author-accepted exposure.
Mounts and egress
Per-step workspace isolation: a step mounts only what its mounts: declares
(strict-by-default - empty/missing mounts: mounts nothing), and a
network: true step reaches only the hosts its egress: allowlist names.
steps:
- name: dev
agent: dev
mounts: [{path: ".", mode: rw}] # source + tests rw for this step
- name: restore
command: .venv-sandbox/bin/pip install -e ".[dev]"
network: true
mounts: [{path: ".venv-sandbox", mode: rw}]
egress: { presets: [package-registries] } # pypi/npm/NuGet/cargo + VCS
- name: review
agent: review
mounts: [{path: ".", mode: ro}] # read-only review
mounts:- a list of{path, mode}entries.pathis repo-relative (no absolute paths, no..traversal, never.gitor a host-only dir, and neverstate_dir);modeisrworro(defaultro). Strict-by-default: an empty/missingmounts:mounts nothing. A.entry mounts the whole export with its mode; subpath entries mount the export root read-only and add a writable submount for each declared-rwpath (declared-writes). Only declared-rw paths sync back to the real repo after the step. A malformed declaration fails loudly at load, naming the step.egress:-{class, presets, targets}.class: browseris the explicit broad-but-logged browser class (every connection logged, nothing filtered); the default is a strict allowlist.presets:references an engine-shipped preset (package-registriestoday);targets:adds explicithost/host:portentries. An allowlist miss denies the connection at the engine-run egress proxy and logs an enforcement event. The engine never adds an undeclared target, and an unknown preset or malformed target fails load.network:routes through a per-policy egress proxy (the container is pointed at it viaHTTP_PROXY/HTTPS_PROXYand reaches it through thehost.docker.internalhost-gateway mapping); it does not mean unrestricted egress. The host-side built-incommitaction rejectsmounts:/egress:/network:(refused once the registry is known).
Per-stage networking
The sandbox is network-off by default. A step that legitimately needs egress
declares network: true and names exactly what it may reach:
steps:
- name: fetch-docs
command: curl -fsSL https://example.com/spec.json -o spec.json
mounts: [{ path: ".", mode: rw }] # the cwd + a place to write spec.json
network: true # egress for this step only
egress: { targets: [example.com] } # ...and only these hosts
- name: restore
command: .venv-sandbox/bin/pip install -e ".[dev]"
mounts: [{ path: ".", mode: rw }]
network: true
egress: { presets: [package-registries] } # pypi/npm/NuGet/cargo + VCS
network: trueis scoped by theegress:allowlist, structurally: the step's traffic is forced through a containerized egress proxy on a per-run internal docker network with no route to the host, and a request to an undeclared host is denied and logged.egress: { class: browser }is the explicit broad-but-logged class (every connection logged, nothing filtered); otherwise the allowlist is strict.- A networked step that writes output must also declare a writable mount:
with no
mounts:a step mounts nothing, socurl ... -o spec.jsonhas no writable cwd. - Host services are reachable through the proxy's
host.docker.internalhost-gateway alias, so an S3 SDK against a local MinIO works through the enforced, logged path. Sandbox containers have no host route. - Command, agent, and sandbox-action steps may declare it; the host-side
commitaction never takes it. Author opt-in is the control - reserve it for stages that need it (QA, integration).
Caches and sync-excludes
Two top-level, run-wide lists declare which host-side stores are toolchain
caches and which paths are scratch (never copied into the export, never synced
back). Both default to [].
caches:- repo-relative toolchain cache dirs resolved host-side to{state_dir}/caches/<name>(content-addressed, shared across runs and repos) and bind-mounted rw into the export at the same relative paths. The host dir is created at startup (a missing workspace path is fine) and becomes the mount source; caches are never synced back. Validation rejects traversal, absolute paths,.git, and a step mount under a cache (the rw cache submount would defeat a declaredromount there). A whole-tree.mount stays fine - the cache submount layers on top. Declaring a cache on a gitignored path (e.g.node_modules) is the normal, correct case.sync_excludes:- scratch paths. A literal entry (no wildcard) excludes the dir and everything under it (qa/.artifacts). A wildcard entry isfnmatchon the full posix relpath, and*spans path separators, so**/bin/**matches a literal/bin/segment at any depth and*.dllmatches at any depth. Excluded paths are skipped in both snapshots and never classify as added/modified/deleted/conflict - no copy-back, no deletion mirroring, and no conflict from host-side build-artifact drift. They are also skipped at export materialisation (no bind-mount), so a step cannot read pre-existing excluded content: in-sandbox builds are clean builds. Put the reusable part (restore inputs) incaches:instead.- Artifact shadowing footgun: a step's
artifact:/produces:path that matches async_excludes:entry will never sync back. Load warns (non-fatal) naming the step and path - wildcard overlap is fuzzy, so it is a warning, not a hard failure.
Sync-back conflicts (merge_on_conflict)
Only declared-rw paths sync back to the real repo. If the host edits a
declared-rw path while a step is running, sync-back is a loud failure
(AE-SBX-016), never an overwrite. Two fixes land on top of that guard:
- Absorb, not wedge. The conflict is printed to the console
(
[isolation] sync-back conflict: ...), the host's version wins, and the baseline is re-snapshotted before the raise. The conflicted step's edits to those paths never land; the next step - evenecho hello- syncs clean instead of re-raising the same conflict forever. - Append-style logs can opt into a union merge. Declare them in the
top-level
merge_on_conflict:list:
For a concurrent edit on a listed path the engine does a three-way union
merge: the host file keeps its lines, the sandbox's export-only lines are
appended in export order, and nothing is ever deleted. Both sides converge
(host and export are written identically), the baseline is re-snapshotted,
the run continues, and the console prints
[isolation] merged concurrent edits: <path> (<n> sandbox lines appended).
Entries use the same vocabulary as sync_excludes: (literal = component
prefix; wildcard = fnmatch on the full posix relpath; * spans separators).
Single strings coerce to a one-item list. Validation rejects traversal,
absolute paths, .git, host-only dirs, and a literal entry under a literal
sync_excludes: or caches: entry (those paths never sync, so they can never
conflict). Declaring a non-append file here is the pipeline author's
responsibility - the merge only ever appends, it never reconciles in-place
edits.
Dependency policy (locked by default)
The supply-chain dial is a pipeline-level deps_policy: field, locked by
default. The engine injects the policy into every agent step's context:
deps_policy: locked # or: open (default: locked)
lockfiles: [uv.lock] # or: [packages.lock.json, package-lock.json]
locked- the human-owned lockfile is the source of truth; the agent may not add dependencies. If the design requires a missing dependency, the agent declares it in its final response under## Missing dependencies, which fails the run fast with one human lockfile edit - not a retry loop.open- the agent may add exact-pinned manifest entries directly (never a package-manageraddcommand); the network-on restore step fetches them.
A locked pipeline with no lockfiles: entry fails fast at load. The
restore step runs the toolchain's locked mode and fails when the
manifest and lockfile disagree:
| Toolchain | Locked restore | Lockfile |
|---|---|---|
| .NET | dotnet restore --locked-mode |
packages.lock.json |
| node | npm ci |
package-lock.json |
| python | uv sync --locked |
uv.lock |
The restore step also fails on known-CVE findings (per-toolchain thresholds:
NuGetAudit at error, npm audit --audit-level=high, pip-audit). A human
generates the lockfile once, on a network machine, and commits it - the
engine never fetches on the agent's behalf.
Banned commands (forbidden_commands:)
forbidden_commands: is a per-step list of regex patterns checked against
every agent command before any shell spawn; a match returns a structured
[forbidden: <label>] observation instead of running. The engine defaults
(git mutations and docker) always apply and have no disable switch; a
toolchain profile may add tool-specific rules (for example the python
recipe denies pip install, uv add, and pip-compile on agent steps).
Command steps bypass the filter by design.
Reasoning effort (opt-in)
reasoning_effort is an opt-in latency dial on the pipeline llm block, a
named llms: profile, and individual agent steps. Unset means reasoning is
off - the field is forwarded as none and reasoning is stripped from requests.
A thinking model without an effort level is invalid config and fails fast
with an actionable engine error rather than a provider 400. A step's value
overrides the effective profile's value.
Recommended lane defaults (guidance only, not enforced):
| Lane | reasoning_effort | Why |
|---|---|---|
| brief | medium | digest and classify, no design work |
| dev | high | the most demanding construction work |
| qa | medium | classification discipline must stay reliable |
| review | xhigh | highest stakes: a missed detection sails past the last gate into commit |
Secrets
Secret values never belong in the pipeline yaml, the workspace, or
state_dir. Declare the refs at the top level and opt each step into the
refs it needs:
secrets: # refs only - never values
kinde-client-secret:
from: env # provider name (env ships first)
key: KINDIE_CLIENT_SECRET # host env var to read + step env name
steps:
- name: qa
command: ./qa/run-against-kinde.sh
secrets: [kinde-client-secret]
- Resolution is host-side, once, at run start. The
envprovider reads the named host environment variable. A missing variable fails fast naming the ref, the declaring step(s), and the provider error. There is no silent degradation. - Injection is per step. A resolved value reaches a step's exec env only
when that step lists the ref - the same path step
env:uses. It never reaches the provision container,state_dir, an agent's context, or any other step. - Providers.
envandfileship. Thefileprovider reads a host file:keyis the file path andjson_keyselects one string field (the whole file content when absent). A missing file fails fast namingagentic-dev-loop copilot-login. - LLM keys. The
llm:block takes exactly one ofapi_key_env(the existing shape) orapi_key_secret(aSecretSpec, file provider usable). Neither or both fails at load. The resolved LLM key joins the run's redaction set. .env*ban. Before anything else runs, the workspace root is scanned for.env*files. Any hit fails fast, naming the files, with the remedy text ("move these values intosecrets:refs / host env and delete the files"). The convention fixtures.env.example,.env.template,.env.sampleare whitelisted. The ban applies regardless ofnetwork:flags - the workspace must simply not contain secrets.- Output scrubbing. Every resolved value is scrubbed from captured step
output, retry notes, artifacts, and
state_dirfiles before they are written. This is hygiene, not a control: the declaring step's agent has already seen the value in its own env. - Prefer a mechanical
commandstep for secret-consuming work so the LLM and the secret never meet; anagentstep holds a secret only when its job genuinely requires it. See the migration checklist when converting an existing repo.
LLM profiles
Named profiles let one pipeline carry several LLM lanes (for example a flash
model for dev and a stronger model for review). Each profile is a full
LlmConfig; a step opts in with llm: <name>, moving model, endpoint, key,
and effort default together. The top-level llm: block remains the default
for steps that name none. See LLM providers for the
provider-side setup.