Setup and troubleshooting
The agentic-dev-loop sandbox is always on: the agent terminal
tool and command steps run inside a Docker-based, kernel-enforced boundary.
There is no opt-out - the isolation: section configures the sandbox, it never
disables it. This guide covers the host-side setup: the Docker engine, the
dev image, caching, troubleshooting, and the security model. The
pipeline.yaml contract lives in the
pipeline reference.
1. Prerequisites
Install a compliant Docker engine with Engine API >= 1.43 (Engine 24):
- macOS - Docker Desktop.
- Windows - WSL2 with an Ubuntu distro. Enable Docker Desktop's WSL
integration (or run Docker Engine inside the distro) and keep the repo on
the WSL filesystem (
~/dev/...), not/mnt/c: bind-mounting a 9p path into containers breaks permissions and is slow. Everything else is the plain Linux setup. - Linux - Docker Engine, OrbStack, Colima, or a podman docker-compat machine.
Verify the engine:
docker run --rm hello-world
docker version --format '{{.Server.APIVersion}}' # must be >= 1.43
docker info --format '{{.OSType}}' # must be "linux"
If the API is older, or OSType is not linux, the pipeline refuses to run
with a fail-fast message pointing here.
2. First run
On first run the pipeline probes the daemon, then pulls the digest-pinned
dev image (ghcr.io/lukedawilson/agentic-dev-loop/dev) and verifies its
digest - the supply-chain check refuses to continue on a mismatch. Later runs
reuse the local image cache; the pull is retried (bounded) only on
connection/timeout errors, never on auth/not-found.
If the pinned digest constant is empty, startup fails fast with AE-SBX-005.
For a pre-publish dev loop, point the
engine at any image (tag or digest) via an environment override:
The override wins over the pinned digest and over any per-pipeline
isolation.image: - it is the explicit, never-silent escape hatch.
3. Onboarding: init and doctor
A new consumer repo starts with one command:
agentic-dev-loop init --profile python # or: --profile dotnet-node, rust
agentic-dev-loop init --profile ./my-profile.yaml --recipe python
agentic-dev-loop init --profile ./my-profile.yaml --recipe ./my-recipe.yaml
init detects solution files, package.json directories, lockfiles, README,
AGENTS.md, and a conformance script; asks only what it cannot detect; and
writes agentic-dev-loop/pipeline.yaml, the agent files,
agentic-dev-loop/.engine-version, missing premise files, gitignore
additions, and an env-file template. It refuses to overwrite an existing
agentic-dev-loop/ directory. See Authoring a loop for what
the generated layout looks like.
Custom images and unsupported toolchains
The engine ships profiles for a few toolchains; everything else is a
consumer profile and, when the built-in step shapes do not fit, a consumer
recipe. Both are plain YAML files passed to init by path.
A profile carries the toolchain's environment (image, caches, premise files, gitignore additions, doctor checks). Point it at any image:
name: my-go
engine_min: 0.9.2
description: Go project
isolation:
image: ghcr.io/acme/go-dev:1.24
cpus: 2
caches:
- .go-build
A recipe carries the step workflow (brief/dev/restore/test/... plus
the final commit), with __TOKEN__ placeholders that detection or prompts
fill in. Write one when the toolchain's install and test commands differ from
the bundled recipes:
name: go
placeholders:
__GOMOD__: .
steps:
- name: dev
kind: agent
agent: dev
setup: cd __GOMOD__ && go mod download
mounts: [{path: ".", mode: rw}]
- name: test
kind: command
command: cd __GOMOD__ && go test ./...
mounts: [{path: ".", mode: rw}]
- name: commit
kind: action
action: commit
params: {message: "feat: construct {subject} (agent dev loop)"}
init --profile ./my-profile.yaml --recipe ./my-recipe.yaml renders the
pipeline from both. init stores a path profile relative to the pipeline
directory, so the committed pipeline resolves from any working directory.
For an existing pipeline, two quicker knobs: isolation.image: in
pipeline.yaml (see pipeline.md) overrides just
the image, and the AGENTIC_DEV_LOOP_DEV_IMAGE environment variable
(section 2) wins over everything, per run.
doctor probes the host and repo before every run. Run it yourself: the CLI
never runs doctor or upgrade for you.
agentic-dev-loop doctor --fast # per-run gate: hard failures abort
agentic-dev-loop doctor --json # machine-readable results
Hard checks: engine import/version, installed version equals the
.engine-version pin, the pin is not behind the latest release, the engine
runtime is available with API >= 1.43 and a Linux OSType, the workspace is a
git repo, and no .env* files exist. Warnings: profile-contributed probes,
premise files, the LLM key env var, declared secret env vars, and
compose-service reachability. --fast skips checks needing more than one
quick network round trip; the pin-vs-latest check stays in.
agentic-dev-loop upgrade installs the latest release with pipx and rewrites
.engine-version to the installed version, so the host install and the
committed pin converge in one explicit action. Run it when doctor reports a
pin mismatch.
Secrets live in the host environment. A run reads the process environment by
default; pass --env FILE to load a host env file outside the workspace. A
named-but-missing file fails loudly, and values already set in the process
environment win over the file.
4. Caching
There is no stamp cache: every setup: hook re-runs fresh at the step
boundary (first entry, goto dev retries, all of it). To keep per-run warm-up
to minutes, declare toolchain stores in the top-level caches: list (see
caches and sync-excludes) - the
engine resolves each to a host-side dir under
~/.agentic-dev-loop/state/caches/<name> and bind-mounts it rw into the
export, so a fetch re-uses already-downloaded packages instead of re-fetching
them.
Declare a neutral store per toolchain (e.g. .nuget-packages, qa/.browsers,
a node cache dir) and point the toolchain at it with its cache env var (e.g.
NUGET_PACKAGES, PIP_CACHE_DIR, npm_config_cache) in the declaring step's
env: block - the provision container runs with that step's env.
Stores are content-addressed by design, so sharing them across repos is correct
and is the point. Cache pruning is manual for now: delete the dirs under
~/.agentic-dev-loop/state/caches/.
5. Troubleshooting
Run agentic-dev-loop doctor --fast first: it names the likeliest host-side cause and the fix command.
Every fail-fast error points here (AE-SBX-<NNN>):
| Code | Cause | Fix |
|---|---|---|
| AE-SBX-001 | docker not on PATH |
install an engine (section 1) |
| AE-SBX-002 | daemon unreachable | start your engine (section 1) |
| AE-SBX-003 | engine API < 1.43 | upgrade Docker (section 1) |
| AE-SBX-004 | OSType != linux |
switch Docker Desktop to Linux containers (section 1) |
| AE-SBX-005 | no pinned digest, no env override | set AGENTIC_DEV_LOOP_DEV_IMAGE (section 2) |
| AE-SBX-006 | image pull failed after retries | check connectivity/credentials (section 2) |
| AE-SBX-007 | post-pull digest mismatch | supply-chain check failed; re-pull |
| AE-SBX-008 | git mutation blocked | set isolation.allow_git_mutations: true (see the pipeline reference) |
| AE-SBX-009 | setup: command failed |
inspect its output tail; the run halts (no stamp concept) |
| AE-SBX-010 | container create/start/exec failure | inspect the docker error |
| AE-SBX-012 | daemon lost mid-run | restart the engine; cleanup is best-effort |
| AE-SBX-013 | networked container create/route failure | inspect the docker error; a step declared network: true but no bridge container started (see per-stage networking) |
| AE-SBX-016 | sync-back conflict | a host edit raced a step's declared-rw path; see sync-back conflicts |
| AE-SBX-019 | sandbox infrastructure failure (daemon-side) | check docker info / docker system df; restart Docker Desktop if the VM reports I/O errors |
| AE-SBX-020 | egress proxy start/attach failed | inspect the daemon stderr tail in the message (it names the real cause, e.g. "Address already in use") |
The audit trail of every sandboxed execution is at
~/.agentic-dev-loop/state/sandbox-audit.jsonl (rotates at 5 MB); run state
is under ~/.agentic-dev-loop/runs/.
The orphan-container reaper keeps a host-side registry at
~/.agentic-dev-loop/state/container-registry.jsonl and, at startup, removes
engine exec containers whose owning process is gone (a crashed run can no
longer leak sleep infinity containers).
Linux-host note: containers run as root inside the container, so
bind-mounted writes can land root-owned in your workspace. Recover with
sudo chown -R $USER <workspace>.
6. Security notes
This is kernel-level sandboxing - the host kernel enforces the boundary via
namespaces, cgroups, capability checks and seccomp-BPF syscall filters. The
execution container runs --network none (no egress) by default, --read-only
rootfs, --cap-drop ALL, and mounts a fresh .git-free export of the
workspace - writes land only in the step's declared-rw mounts:. A step that
declares network: true runs in a bridge-network container whose traffic is
forced through an engine-run per-policy egress proxy and reaches only its
egress: allowlist; network access otherwise exists only in the trusted
provision phase. The Docker socket is never mounted. The host-side commit
action, the LangGraph runtime, LLM calls, and the viz server stay host-side;
consumer actions run inside the sandbox like command steps.
Git hooks during the commit action are mitigated, not a residual risk: the
commit action runs git -c core.hooksPath=<trusted dir>, so repo hooks in
.git/hooks never execute. Residual risks: an agent can mutate setup outputs
inside the writable workspace (the git-mutation guard and the dirty-at-start
commit gate limit persistence), and an explicit in-workspace state_dir
choice is the author's accepted exposure.
A network: true command step is an agent-influence channel: an agent can
plant files (e.g. tests) that the networked command step then executes,
granting the agent indirect egress. A network: true agent step grants direct
egress for that stage. The networked container stays --read-only +
--cap-drop ALL, so the blast radius is data exfiltration and reachability,
not host compromise. Pipeline authors should reserve networked stages for
those that need them (QA, integration).
The full host-boundary model is in Architecture.
7. Secrets migration checklist
The secrets: contract lives in the
pipeline reference. When converting an existing repo:
- Replace secret-bearing workspace files with
secrets:refs and host env. - Read the values from environment variables in scripts (
qa/common.sh), not from a committed.env. - Delete the
.envfile - the run refuses to start while it exists. - Add the
secrets:block and the per-stepsecrets: [...]opt-in. - Run
--dry-run(validates schema/refs) then a full run against the real service with no.envin the workspace. - Prefer a mechanical
commandstep for secret-consuming work: the LLM and the secret never meet. Reserveagent+secretsfor steps whose job genuinely requires the agent to exercise them.