DEV Community: Ivan SZKIBA

Dev Containers: The Missing Runtime for Agentic Teams

Ivan SZKIBA — Sat, 04 Apr 2026 13:48:15 +0000

The agentic era of software engineering is already here. We have moved beyond autocomplete into a world where tools like Claude Code and Cursor can inspect codebases, run tests, refactor modules, and propose meaningful changes with very little supervision.

But there is still a quiet productivity killer in many AI-assisted workflows: environmental friction.

If you have ever watched an agent fail because a compiler is missing, a runtime version is wrong, or a dependency exists on one machine but not another, then you have seen the real problem. In professional teams, the answer is not just better prompts. It is better infrastructure.

Imagine an agent opens your repo, sees pom.xml, confidently writes Java 21 code, and then fails because the actual machine still has Java 17 installed. That is not an AI problem. That is an environment problem.

Most teams are trying to solve this with prompts, conventions, and Markdown files. Those things matter, but they are not enough. The missing layer in agentic software engineering is a shared, versioned runtime.

If AI agents are becoming contributors to the codebase, they need the same thing every good teammate needs on day one: a working development environment.

The Dev Container Advantage: A Shared Runtime

When a new contributor joins a project, the goal is simple: get them productive quickly and predictably.

A Dev Container gives both humans and agents the same starting point:

The same operating system base image
The same toolchain versions
The same project dependencies
The same terminal commands and failure modes

That matters because "ready to work" should mean the same thing for every contributor touching the repository, whether they are typing or delegating to an agent. In practice, the onboarding target is no longer just a developer. It is a developer-agent pair working against the same codebase.

Why Markdown Isn't an Environment

Files like AGENTS.md, SKILLS.md, and .cursorrules are useful. They capture conventions, workflows, and expectations. But they do not create a reproducible runtime on their own.

They are governance artifacts, not infrastructure. They can tell a contributor what should happen, but they cannot guarantee that the required tools, runtimes, or permissions actually exist.

1. For Humans: Manual setup does not scale

Asking every developer to manually recreate the project environment is expensive and error-prone.

The DX tax: Every new teammate burns time on brew install, apt install, language managers, and local machine quirks.
The drift problem: One missed package, one wrong version, or one skipped step is enough to create a broken setup.

2. For Agents: Instructions are not guarantees

Telling an agent "Use Java 21" only helps if Java 21 is actually available in the execution environment.

Re-verification waste: Agents spend time and tokens checking whether the machine matches the written instructions.
Host pollution risk: If the fallback plan is "install whatever is missing on the host," your workstation accumulates conflicting global installs that are hard to untangle later.

Markdown tells contributors how to work. A Dev Container defines where that work happens. Strong teams usually need both, but only one of them actually constrains the execution environment.

Why Dev Containers Work for Team-Owned Projects

For a shared codebase, the environment should be version-controlled alongside the application itself. A .devcontainer/devcontainer.json lets the team treat the runtime as part of the project, not tribal knowledge.

1. Less version drift

In a polyglot project using Java, Go, Rust, and Python, consistency is hard to maintain by hand.

The risk: An agent writes code using Java 21 features while CI is still running Java 17.
The improvement: You update the container config once, rebuild or reopen the workspace, and the whole team moves toward the same baseline.

2. Shared debugging context

Supervising an agent is much easier when you are not dealing with a hidden machine state.

If you and the agent work inside the same container:

You see the same files and the same toolchain.
You hit the same compiler and test errors.
You can step into the exact same shell session pattern and rerun the same command the agent just executed.

That removes the classic "works on my machine" translation layer before it starts.

A Minimal Polyglot Setup

You do not always need a custom Dockerfile. For many teams, a single devcontainer.json with a base image plus features is enough to create a strong shared workspace.

Example `.devcontainer/devcontainer.json`

{
  "name": "Polyglot Team Workspace",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/devcontainers/features/java:1": { "version": "21" },
    "ghcr.io/devcontainers/features/go:1": { "version": "1.24" },
    "ghcr.io/devcontainers/features/rust:1": { "version": "latest" },
    "ghcr.io/devcontainers/features/python:1": { "version": "3.13" },
    "ghcr.io/devcontainers/features/github-cli:1": {}
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "vscjava.vscode-java-pack",
        "golang.go",
        "rust-lang.rust-analyzer",
        "ms-python.python"
      ]
    }
  },
  "remoteUser": "vscode"
}

The exact versions should match what your project and CI actually support. The important part is not these specific numbers. It is that the environment definition lives in the repository and can evolve with the code.

How Teams Actually Use It

One of the best parts of the Dev Container standard is that it does not force a single editor or workflow. Different tools can still share the same environment definition.

Workflow A: IDE-first

The setup: Open the project in a supporting editor using the repository's dev container configuration.
For humans: You get language servers, debugging, extensions, and terminal access without installing every SDK on the host.
For agent-assisted editors: The exact UX varies by tool, but the editor and its built-in agent features can operate against the containerized workspace instead of a drifting host setup.

Workflow B: Terminal-first

The setup: Use a tool like DevPod or the Dev Container CLI to create the workspace and attach a shell.
For humans: You can stay in Neovim, tmux, or your preferred shell workflow while still using the shared toolchain.
For CLI agents: Agents launched from inside that container inherit the same runtimes, compilers, and project dependencies available to the human operator.

The result is not that every tool behaves identically. The result is that they start from the same runtime assumptions.

Security: Reduce the Blast Radius

A Dev Container is not magic security. It does not automatically make an agent harmless, and it should not be treated as a complete security boundary.

What it does give you is a cleaner way to reduce exposure:

Keep project tooling inside the container instead of on the host
Mount only what the task actually needs
Avoid exposing personal SSH keys, cloud credentials, or global config by default
Separate experimental agent workflows from your everyday workstation setup

That is a practical security improvement. Not perfect isolation, but a smaller blast radius and a more deliberate operating model.

Conclusion: Build for the Team, Not Just the Prompt

Software teams now include both people and agents as active contributors. If we want that model to work reliably, we need environments that belong to the project rather than to whoever happens to run the task.

The industry is quickly learning how to write better prompts and better agent instructions. The next lesson is that guidance without runtime control is incomplete infrastructure.

When the environment is versioned, reproducible, and shared, both people and agents can contribute with less setup friction, less guesswork, and less machine-specific chaos.

Treat the runtime as part of the product. In the agentic era, the repository is not enough. The team has to version the environment too.

Are you using Dev Containers in your AI workflows today? What has worked well, and where is the friction still showing up?

Git-Native Agent Orchestration: A Stateless Maker-Checker Pattern

Ivan SZKIBA — Mon, 23 Mar 2026 18:05:03 +0000

This guide introduces a drop-in architectural pattern for teams building multi-agent AI systems. It utilizes native Git features to orchestrate a stateless, collision-free Maker-Checker loop without relying on complex Python frameworks, external databases, or heavy memory management.

The Problem with Current Agent Frameworks

When building autonomous Maker-Checker loops (e.g., a Developer Agent writing code and a Reviewer Agent testing it), engineers often encounter three major friction points:

State Management: Passing large chunks of code, architectural plans, or evaluation feedback back and forth via JSON payloads or database entries is bulky and prone to token-limit failures.
Workspace Pollution: Agents operating in the same directory overwrite each other's files, trigger race conditions, or cause file-lock crashes.
PR Noise: Trial-and-error AI commits clutter the remote repository, making human code review a nightmare.

The Git-Native Solution

This workflow entirely eliminates those issues by treating the Git database itself as the state machine. The Orchestrator is reduced to a "dumb" trigger, while the agents manage the state autonomously using the following mechanisms:

Git Worktrees: Agents are physically isolated in ephemeral sibling directories (foo-wt/maker and foo-wt/checker), completely preventing file collisions while sharing the same underlying .git repository.
Context-Aware Agents: Agents are not hardcoded with static prompts. Instead, their first action upon waking up is to execute git branch --show-current. They dynamically parse their branch name scheme to determine their role, phase, and task context.
Agent-Driven Handoffs via Git Notes: Instead of communicating via an API, the agents leave prompts for each other directly on the commits. The Maker creates a commit and uses git notes add to request a review. The Checker evaluates the code and uses git notes append to attach its Markdown feedback. Neither agent ever overwrites history.
Auto-Generated Transcripts & Memory: Before squash merging, the Orchestrator dumps the complete git notes history into a Markdown transcript (history-XXX.md) and saves it to an isolated root branch (devlog). This auto-generates a perfect "AI thought process" engineering blog draft without polluting the production codebase.
Squash Merging: Only the final, Checker-approved iteration is squash-merged into the integration branch, resulting in a pristine Pull Request for human reviewers.

Want the raw files? If you just want to drop this into your own project, you can download the original ORCHESTRATION.md from my GitHub Gist. For the full architectural deep dive, read on.

The Architecture: Multi-Agent Orchestration Workflow (Maker-Checker)

This outlines the workflow architecture for the multi-agent system. The core engine of this system relies entirely on a Maker-Checker pattern to iteratively generate, evaluate, and refine artifacts—ranging from software code to design specifications and whitepapers.

(Note on Terminology: In this document, foo represents your actual repository name. XXX represents a URL-friendly task identifier, exactly like the branch names GitHub automatically generates from issue titles—e.g., 123-add-auth.)

1. Core Principles

General Purpose: This workflow applies to any text-based artifact (Code, Markdown, JSON, etc.).
Physical Isolation: Agents operate in strictly isolated file systems using Git Worktrees.
Autonomous State Machine: The Orchestrator is a "dumb" trigger. The agents themselves drive the state machine by passing prompts and feedback to each other exclusively through git notes.
The Golden Rule of Notes:
- The Maker creates new commits and exclusively uses git notes add to attach review requests.
- The Checker never creates commits; it exclusively uses git notes append to add feedback to the Maker's commit. Neither agent ever overwrites history.
Read-Only Checker: The Checker agent strictly evaluates work. It may execute tests and append git notes, but it must never modify project files or create standard commits.
Context-Aware Agents: Agents determine their exact role, phase, and task dynamically upon initialization by executing git branch --show-current.
Agnostic Orchestrator: The "Orchestrator" does not need to be a complex AI framework. It can be a simple Bash script, a CI/CD pipeline, or even a human developer manually typing Git commands in the terminal. Its only job is to trigger the agents and manage the final merge.

2. Infrastructure & Environment

To prevent file-lock collisions and environment drift, the repository is split into the Orchestrator context and active Worktree sandboxes.

Directory Structure

workspace/
├── foo-wt/                  # Ephemeral worktree sandboxes
│   ├── feature/             # The integration baseline
│   ├── maker/               # Maker's workspace
│   └── checker/             # Checker's workspace
└── foo/                     # Main Orchestrator repository
    ├── .git/                # Shared Git repository
    └── ORCHESTRATION.md     # This file

3. Branching & Push Strategy

For every new task or document generation (XXX), the Orchestrator manages a strict branching lifecycle. Strict remote isolation is enforced to prevent repository pollution.

Branch	Worktree	Remote Policy	Purpose
`feature/XXX`	`foo-wt/feature/`	Pushed	The integration branch. Pushed to remote for final PR review.
`devlog`	`N/A`	Pushed	Isolated root branch. Acts as the permanent knowledge base for AI plans.
`maker/XXX`	`foo-wt/maker/`	Never Pushed	Branched from `feature` or `devlog`. Contains the Maker's raw, messy iterative commits.
`checker/XXX`	`foo-wt/checker/`	Never Pushed	Branched from `feature` or `devlog`. The Checker pulls the Maker's commits here to run evaluations safely.

4. The Workflow Execution Loop

The Maker and Checker never communicate directly via API or memory. They pass code forward via Git commits and pass execution prompts backward and forward via git notes.

To prevent agent hallucination and ensure strict context, every prompt written to a git note must explicitly reference the exact commit hash it applies to (e.g., [REVIEW] Evaluate commit 7a8b9c0).

The Step-by-Step Handoff Protocol

The Anchor (Orchestrator): The Orchestrator creates an empty commit on maker/XXX and adds a git note containing the initial, completely stateless task prompt. (Example: git notes add -m "[TASK] Add a /health endpoint to server.js returning 200 OK"). Notice there is no complex persona or framework context—just the raw task.
Maker Iteration: The Maker reads the note on HEAD, writes code, and creates Commit A. The Maker then runs git notes add on Commit A, tagging it with a [REVIEW] prompt asking the Checker to evaluate it (e.g., [REVIEW] Evaluate commit 7a8b9c0).
Checker Iteration: The Checker reads the note on Commit A, evaluates the code, and runs git notes append on Commit A with its feedback, tagging it with a [REVISE] prompt for the Maker to fix the identified issues (e.g., [REVISE] Fix null pointer in commit 7a8b9c0).
The Loop Continues: The Maker reads the updated note on Commit A, fixes the code, creates Commit B, and executes a new git notes add review request.
Approval: Once the Checker's evaluation passes, it appends an [APPROVED] note. The Orchestrator sees this, generates the transcript, and squash merges the branch.

Max Iterations Guardrail
To prevent infinite loops, the Orchestrator enforces a strict limit (e.g., 5 iterations). If the Maker fails to achieve Checker approval within this limit, the loop aborts and escalates to a human.

5. Merging & Feedback Storage Rules

To maintain a pristine project history while simultaneously preserving the AI's "thought process" for documentation, strict rules are enforced.

Rule 1: Transcript Generation (For Engineering Blogs)
Before the Orchestrator merges the Maker's code into production, it compiles the complete AI conversation history. To prevent polluting the production codebase, this transcript is always saved directly to the isolated devlog knowledge-base branch.

Because every prompt, Maker commit, and Checker critique is stored in the Git notes, the Orchestrator simply dumps this into a Markdown transcript:

# 1. Generate the transcript from the Maker's branch
git log maker/XXX --show-notes --pretty=format:"### Commit: %h%n**Maker:** %B%n%N%n---" > history-XXX.md

# 2. Save it exclusively to the devlog branch
git checkout devlog
mv history-XXX.md transcripts/
git add transcripts/history-XXX.md
git commit -m "docs: save iteration transcript for task XXX"

# 3. Return to the target branch to merge the actual code
git checkout feature/XXX

Rule 2: Squash Merging Only
Once the transcript is safely committed to devlog, the Orchestrator must squash merge the actual code from maker/XXX into the target integration branch (typically feature/XXX) using git merge --squash maker/XXX. This condenses dozens of broken, AI-generated trial-and-error commits into a single, clean commit for human reviewers.

6. Cleanup Guardrails

Upon successful PR creation or plan approval, the Orchestrator enforces strict teardown:

(If applicable) Destroy the Maker and Checker containerized environments.
Execute git worktree remove for both sandbox directories.
Delete local maker/XXX and checker/XXX branches.

7. Agent System Instructions

Because the system runs entirely through Git state, the Orchestrator does not generate complex prompts. Instead, the AI agents are configured with the following baseline system instructions regarding how they interact with the Git database:

Maker Agent System Prompt

"When triggered, run git notes show HEAD to read your current instructions. If it is a new task, write the code. If it is Checker feedback, fix the code. Once your work is done, you must create a standard git commit. Then, you must run git notes add -m '[REVIEW] <your review request>' HEAD to attach a prompt for the Checker to evaluate your new commit."

Checker Agent System Prompt

"When triggered, run git merge maker/XXX to pull the Maker's latest commit into your workspace. Run git notes show HEAD to read the Maker's review request. Run tests and evaluate the code. You must never create a new commit. Instead, you must run git notes append -m '[REVISE] <your feedback>' HEAD to attach your feedback to the Maker's commit. If the code is perfect, append [APPROVED]."

8. Advanced Pattern: Plan & Execute (Optional)

For complex tasks, large language models perform significantly better when planning is separated from execution. The Orchestrator can utilize a two-phase "Plan & Execute" pattern using an isolated knowledge-base branch.

The devlog Knowledge Base
Instead of storing AI plans in the main branch, a dedicated isolated root branch named devlog is maintained. This acts as the long-term memory for the AI system. Plans are generated here by the Maker and Checker, and the resulting transcripts/history-XXX.md acts as a perfectly formatted draft for an engineering blog post detailing how the system designed the feature.

Standardizing Plans with Frontmatter
To ensure plans are machine-readable, the Maker agent is instructed to include standard YAML frontmatter at the top of every plan-XXX.md file.

Example plan-XXX.md format:

---
title: "Implement OAuth2 Authentication"
task_id: "123-add-oauth"
date: 2026-03-16
---

Phase 1: The Planning Phase
The Orchestrator initiates the Maker-Checker loop targeting the devlog branch. The Orchestrator's anchor commit note tells the Maker: "Draft the architecture plan for task XXX." The loop runs until the Checker appends [APPROVED]. The Orchestrator generates the transcript and squash merges into devlog.

Phase 2: The Execution Phase
The Orchestrator initiates a second Maker-Checker loop, this time targeting the feature/XXX branch. The Orchestrator reads the approved plans/plan-XXX.md from devlog and attaches it to the empty anchor commit as the Maker's instructions. The loop runs until [APPROVED], ending in a clean feature PR.

Origin Story: Grafana Hackathon 16

This Git-native architecture wasn't born in a vacuum—it evolved from real developer friction.

During Grafana Hackathon 16, I was heavily experimenting with autonomous AI agent coding. I quickly ran into the pain points of managing state and passing files between multiple agents. To fix this on the fly, I intuitively built a two-agent feedback loop. It wasn't until later, while reading up on AI architecture, that I realized I had naturally arrived at the industry-standard Maker-Checker pattern.

However, while the pattern worked, the underlying plumbing was still messy. After the hackathon, reflecting on the friction of file-locks and state management, the "Git-Native" concept finally clicked. I realized we didn't need to build complex ways to pass files between agents—Git was already the perfect, battle-tested state machine for the job.

A massive thank you to Grafana for consistently providing access to the latest AI technologies and models. Furthermore, the hackathon itself provided the perfect dedicated space to experiment with new ideas. That freedom to just "build and break things" is exactly what made this architecture possible.

What's Next: Executable Skills & Battle Testing

This orchestration document is just the foundation. Over the coming weeks, I am taking this theoretical architecture and battle-testing it inside a live, production-scale project.

Once the pattern is fully refined under real-world conditions, I will be publishing Git-Native Agent Skills (utilizing the new Anthropic SKILL.md format) in a dedicated, full GitHub repository.

These drop-in skills will allow CLI agents like Claude Code to natively understand and execute this exact Maker-Checker Git loop with zero extra framework configuration.

(This article was originally published on my blog at codecommis.hashnode.dev)

Follow me on GitHub to get notified when the official repository and executable skills drop!

Testable Example Code

Ivan SZKIBA — Tue, 09 Jan 2024 18:10:22 +0000

There is no worse developer experience than bad example code in the documentation.

It is easy to make mistakes in code slightly more complicated than a Hello World program. In fact, in Hello World as well.

How can you avoid it?

It is advisable to test the example codes in the documentation, like all code. Since the example codes also change over time, this testing should be done automatically, built into the documentation release process.

Basically, we can choose from two options if we want to test the example codes embedded in the documentation.

Create the example code in a separate file and embed this file, or part of it, in the documentation
The example code included in the documentation is extracted into a file, if necessary, supplemented to make it a valid source file

In both cases, finally, testing the example code is a normal testing task. So the example code can be tested using the standard test framework in the given programming environment. This testing step can be integrated into the build process, guaranteeing that the example codes work correctly.

Required tooling

For the above, we need a tool that can embed source files or a part of them in the documentation or can create valid source files from the example codes in the documentation (supplementing them if necessary).

Today, the most popular format for developer documentation is the Markdown format. Example code pieces can be placed in a Markdown document using so-called fenced code blocks.

The mdcode command-line tool was created for the development and testing of Markdown fenced code blocks. It supports both example code testing/development processes: it is able to keep Markdown code blocks in sync with external source files, or part of them.

Show me the code!

Using mdcode is super easy. The first line of the fenced code block, the so-called info-string, must be supplemented with some metadata after the programming language. Such metadata is the file, which specifies the name of the file belonging to the code block. The mdcode extract command writes the contents of the code block into this file, and the mdcode update command updates the contents of the code block from here.

Sticking to the Hello World example:

console.log("Hello, Testable World!")

Here's how to add the file metadata:

```js file=hello.js
console.log("Hello, Testable World!")
```

The content of this code block can be saved to file (hello.js) using the mdcode extract command. Then the Hello World example can be tested with the following test code:

const assert = require("node:assert")
const test = require("node:test")

test("hello", (t) => {
    console.log = function (message) {
        assert.equal(message, "Hello, Testable World!")
    }
    require("./hello.js")
})

This test code can be embedded without being visible in the markdown document:

<!--<script type="text/markdown">
```js file=hello.test.js
const assert = require("node:assert")
const test = require("node:test")

test("hello", (t) => {
    console.log = function (message) {
        assert.equal(message, "Hello, Testable World!")
    }
    require("./hello.js")
})
```
</script>-->

It is advisable to include the test code in the document as well, because in this way the example codes can be tested by anyone with the following commands:

mdcode extract testable-markdown-code-blocks.md
node --test

Where testable-markdown-code-blocks.md is the name of the document. Of course, any test framework can be used for testing.

A more realistic example

A slightly more realistic case when the example code is only a fragment, for example a function:

function factorial(n) {
    if (n > 1) {
        return n * factorial(n - 1)
    }

    return 1
}

Many editors (such as Visual Studio Code) support the use of so-called #region comments for code folding. Regions marked in this way are usually named for readability. To avoid having to learn new, useless syntax, mdcode uses #region comments to mark embeddable parts of the source code. Simply add a region metadata to the fenced code block which contains the name of the region you want to embed.

This is how the code block above can be embedded from the region named function in the factorial.test.js file:

```js file=factorial.test.js region=function
function factorial(n) {
    if (n > 1) {
        return n * factorial(n - 1)
    }

    return 1
}
```

To do this, in the factorial.test.js file, you simply mark the part of the code you want to embed with a #region comment:

const assert = require("node:assert")
const test = require("node:test")

// #region function
function factorial(n) {
    if (n > 1) {
        return n * factorial(n - 1)
    }

    return 1
}
// #endregion

const testvect = [1, 1, 2, 6, 24, 120, 720, 5040, 40320, 362880, 3628800]

test("factorial with test vector", (t) => {
    for (var i = 0; i < testvect.length; i++) {
        assert.equal(factorial(i), testvect[i])
    }
})

And to make the document self-contained, you can embed the test code in the following way:

<!--<script type="text/markdown">
```js file=factorial.test.js outline=true
const assert = require("node:assert")
const test = require("node:test")

// #region function
// #endregion

const testvect = [1, 1, 2, 6, 24, 120, 720, 5040, 40320, 362880, 3628800]

test("factorial with test vector", (t) => {
    for (var i = 0; i < testvect.length; i++) {
        assert.equal(factorial(i), testvect[i])
    }
})
```
</script>-->

It is important to place this invisible code block before the visible code block in the document, because mdcode extract processes the code blocks in order.

It is worth noting that this code block only contains the outline of the file, so the #region part is empty. mdcode extract will automatically fill in the part between the #region comment, and mdcode update will automatically delete it during embedding. Such outline code blocks are marked by the outline metadata value true.

How do I edit the examples?

The example codes can also be edited within the markdown document. Most IDEs also provide syntax highlighting support within markdown fenced code blocks. However, we don't get actual programming language support (code formatting, IntelliSense, etc.)

It is more convenient to develop and test the example codes in actual source files. The parts you want to embed simply have to be marked with #region comments and can be updated in the markdown document using the mdcode update command.

The examples in this document and the corresponding tests can be extracted into files with the following command:

mdcode extract testable-markdown-code-blocks.md

As a result, the following files are created:

factorial.test.js
hello.js
hello.test.js

These can be modified and then tested with the following command:

node --test

After that, the document can be updated using the command below:

mdcode update testable-markdown-code-blocks.md

You can find the original post here: https://gist.github.com/szkiba/d9b7b4601efb7dc68aa2c58548b8b271

Cover photo by Nik on Unsplash

PhantAuth: Random User Generator + OpenID Connect Provider

Ivan SZKIBA — Tue, 09 Jul 2019 11:49:48 +0000

Let me introduce PhantAuth: Random User Generator + OpenID Connect Provider. Like Lorem Ipsum, but for user accounts and authentication. PhantAuth was designed to simplify testing for applications using OpenID Connect authentication by making use of random generated users. Check PhantAuth Developer Portal for more information: https://www.phantauth.net