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 --pip-args="--pre" agentic-dev-loop   # latest release is currently a pre-release
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.0rc2

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.0rc2
File Size Uploaded Provenance Actions
agentic_dev_loop-1.0.0rc2.tar.gz 994.4 kB With provenance Details for agentic_dev_loop-1.0.0rc2.tar.gz

Built distribution (wheel)

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

Total release size: 1.9 MB

Release files / agentic_dev_loop-1.0.0rc2.tar.gz

Download URL agentic_dev_loop-1.0.0rc2.tar.gz
Size 994.4 kB
Tags Source
SHA-256 checksum
How to use checksums
712763fdc86351173d5dbec945f991cce2a558a5f4eb77fd9b966f65a989b3a3
BLAKE2b-256 checksum
How to use checksums
5543acc42c95db6250d74128aedbb08fee188837c4138ead30069e47caa6b78e
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 13, 2026.

Transparency log

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

Download URL agentic_dev_loop-1.0.0rc2-py3-none-any.whl
Size 871.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b21d03ff6439b8ef05a60e7ec1a312ec5ce4d323173c13401f2ec015f73fa877
BLAKE2b-256 checksum
How to use checksums
bc6e1b4b40e70b9e14f0fed019063883b2b4bda3baea5fede8bd9b9a9a224a22
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 13, 2026.

Transparency log

Security for agentic-dev-loop 1.0.0rc2

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.0rc2.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 13, 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