Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

agentic-dev-loop

Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.

Describe your pipeline in one YAML file - agent steps, mechanical test gates, and trusted actions - and agentic-dev-loop runs it end to end: agent and command steps get kernel-level sandboxing via Docker, verdicts route the graph, every boundary is checkpointed, and nothing gets committed until every gate passes.

The live graph view - pipeline graph with fail loopbacks, summary tiles, per-stage consoles, and event log

Key features

  • A tool, not a wiring project. One CLI entry point, opinionated defaults, fixed safety policies. You write the pipeline and the agent definitions - nothing else.
  • Deterministic. Same pipeline + same state means the same routing. Verdicts are parsed from files and validated tool calls, retries are bounded, nothing is best-effort.
  • Sandboxed by default. The agent's shell and every command step run inside an always-on Docker sandbox: network off by default, writes only to declared mounts:, no .git. If no sandbox is available, the run stops instead of degrading.
  • Crash-safe and resumable. Every boundary is checkpointed; interrupt a run and resume it from the exact checkpoint with --resume, notes intact.
  • Watchable. A live browser graph view with per-stage consoles and an event log, a browsable run history, and markdown reports.
  • Gated commits. A single commit point that fires only when every gate passed and the worktree was clean at start.
  • Supply-chain careful. A digest-pinned dev image, a locked-by-default dependency policy, and a CVE-audited restore step.
  • Secret-safe. Secrets are refs in config, values in the host environment, opted in per step, and scrubbed from every engine-written output; the workspace may not contain .env* files.
  • Onboarding that stays honest. init scaffolds a working loop for your repo, doctor probes the host before every run, upgrade converges the install and the pinned version.
  • Extensible. Plugins add your own actions, tools, and document loaders, loaded from outside the workspace only.

Supported platforms

The engine is plain Linux under the hood and runs wherever a compliant Docker engine does:

Platform Support
Linux Native. Docker Engine, OrbStack, Colima, or podman with docker compat.
macOS Native. Docker Desktop, OrbStack, or Colima.
Windows Via WSL2 (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.

Quickstart

Prerequisites

Requirement Detail
Python >= 3.12
Docker engine Engine API >= 1.43 (Engine 24). Any compliant engine works - Docker Desktop, OrbStack, Colima, Rancher Desktop, podman docker-compat. On Windows, run under WSL2: the repo must live on the WSL filesystem, not /mnt/c.
LLM API key The env var named by your pipeline's api_key_env (e.g. OPENAI_API_KEY) must be set - a missing key fails fast, naming it. Alternatively, agentic-dev-loop copilot-login authenticates a Copilot subscription (see LLM providers).

Installation

pipx install agentic-dev-loop
agentic-dev-loop --version

Install with pipx: the engine's venv lives outside the workspace, so it is unmounted from the sandbox and never agent-writable. On the first run the engine pulls the digest-pinned dev image and verifies its digest. Setup details and troubleshooting live in the setup guide.

Your first loop

cd <your-repo>
agentic-dev-loop init --profile python                     # writes the pipeline + agents
export OPENAI_API_KEY=...                                  # whatever api_key_env names
agentic-dev-loop agentic-dev-loop/pipeline.yaml --dry-run  # validate - no LLM, no Docker
agentic-dev-loop agentic-dev-loop/pipeline.yaml            # run it

init scaffolds agentic-dev-loop/pipeline.yaml plus the agent files it names; --dry-run loads and validates with no LLM, no Docker, and no state writes. A minimal pipeline looks like:

name: my-construction-loop

llm:
  model: openai/deepseek-v4-pro
  base_url: https://api.deepseek.com
  api_key_env: OPENAI_API_KEY

max_attempts: 10
agents_dir: sdk_agents

steps:
  - name: dev
    agent: dev
    produces: implementation-summary.md
    on_pass: test

  - name: test
    command: .venv-sandbox/bin/python -m pytest tests/ -q
    on_pass: review
    on_fail: { goto: dev, retry: true }

  - name: review
    agent: review
    artifact: review-findings.md
    verdicts: { pass: APPROVED, fail: NEEDS CHANGES }
    on_pass: commit
    on_fail: { goto: dev, retry: true }

  - name: commit
    action: commit
    params: { message: "feat: construct {subject}" }

Every field - per-step isolation, mounts and egress, secrets, dependency policy, named LLM profiles - is in the pipeline.yaml reference.

Documentation

Page What it covers
Architecture The five layers, one full run end to end, and the host-boundary security model
CLI Run flags, resuming, the live view, reports, container management, and onboarding commands
pipeline.yaml The complete configuration reference: steps, isolation, secrets, networking, dependency policy
LLM providers OpenAI-compatible endpoints (OpenAI, DeepSeek, and others) and the GitHub Copilot subscription
Authoring a loop From init to a committed pipeline: agent files, stage lineup, adaptation checklist
Setup and troubleshooting Docker engines, the dev image, caching, error codes
Browser sandbox Running a browser inside the sandbox
Known issues Container lifecycle edge cases

Contributing

Read AGENTS.md first - it is the instruction set for both human and agent contributors - then see CONTRIBUTING.md for the development workflow and the OpenCode commands.


Built on OpenHands SDK and LangGraph.

Metadata

Release files for agentic-dev-loop 1.0.0b1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agentic-dev-loop 1.0.0b1
File Size Uploaded Provenance Actions
agentic_dev_loop-1.0.0b1.tar.gz 991.1 kB With provenance Details for agentic_dev_loop-1.0.0b1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agentic-dev-loop 1.0.0b1
File Interpreter ABI Platform Actions
agentic_dev_loop-1.0.0b1-py3-none-any.whl Python 3 none any Details for agentic_dev_loop-1.0.0b1-py3-none-any.whl

Total release size: 1.9 MB

Release files / agentic_dev_loop-1.0.0b1.tar.gz

Download URL agentic_dev_loop-1.0.0b1.tar.gz
Size 991.1 kB
Tags Source
SHA-256 checksum
How to use checksums
95716342eb5f45287698517a9490bdd1cbfd3609629dfa00ea232ed6c34f9dda
BLAKE2b-256 checksum
How to use checksums
942f2f3cd6dec3b38440fb3ed31e76e6472398c7a2adce390c6ca67da3880f41
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / agentic_dev_loop-1.0.0b1-py3-none-any.whl

Download URL agentic_dev_loop-1.0.0b1-py3-none-any.whl
Size 870.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
707c3011653e06496f5cd000a7f28a29fb12e040d320b0fc2617b9d67107c1e6
BLAKE2b-256 checksum
How to use checksums
d9ac9fcc3a1ae3dc9e213bc8fdcb884b67277f99aca583bdb285724399cb0b4b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for agentic-dev-loop 1.0.0b1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for agentic_dev_loop-1.0.0b1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page