# buildg: Interactive Dockerfile Debugging with BuildKit

> buildg adds breakpoints, step execution, shell access, and DAP integration to Dockerfile builds. It suits developers investigating complex BuildKit builds, but its unmerged BuildKit patches and Linux execution requirements narrow adoption.

**ktock/buildg** — Interactive debugger for Dockerfile, with support for IDEs (VS Code, Emacs, Neovim, etc.)

- Repository: https://github.com/ktock/buildg
- Stars: 1,503 · Forks: 40
- Language: Go
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/ktock-buildg

## buildg's Dockerfile debugging boundary

buildg targets developers who need to inspect what happens inside an individual Dockerfile build step, rather than only reading command output after BuildKit has finished or failed. It provides source-level inspection, breakpoints, step execution, and an interactive shell at a stopped step. That combination is useful for multi-stage builds where one stage creates files that a later stage copies, or where a simple layer error message does not explain the filesystem state at the relevant instruction.

The project is specifically tied to Dockerfiles processed by BuildKit. It is not a general shell debugger, container inspector, or replacement for the complete BuildKit control plane. Its audience includes people using Dockerfile builds from the command line, as well as editors that consume the Debug Adapter Protocol, such as VS Code, Emacs, and Neovim.

The repository labels buildg as early-stage software. Its implementation uses BuildKit with patches that have not been merged upstream, according to the README. That boundary matters more than the feature list. The debugger can expose execution state that ordinary BuildKit output omits, but its compatibility path depends on project-specific changes rather than only released BuildKit behavior.

## Breakpoints and shells inside BuildKit execution

A buildg session starts with the build context and presents the Dockerfile at an interactive prompt. A developer can set a breakpoint by Dockerfile line, continue the build, and enter a shell when execution reaches that line. The `exec` command shown in the README opens a shell in the stopped step, after which ordinary shell commands can inspect files created by earlier instructions.

The documented example creates `/hello` in one `RUN` instruction, sets a breakpoint on the following instruction, and executes shell commands that read both `/hello` and `/world`. The displayed output contains `hello` and `world`, illustrating that the shell is attached to state produced by the partially completed build. This is materially different from inspecting only the final image because the debugger is positioned within the Dockerfile execution sequence.

The architecture is described as BuildKit based, with unmerged patches added by buildg. The visible repository layout supports a terminal front end and a DAP path: Go files implement commands such as breakpoints, execution, listing, logging, reloading, and exit, while `examples/dap/` contains editor integration material. The README does not specify the internal transport or the exact patch boundaries, so those details should not be inferred from the command-line interface alone.

## Installing buildg on Linux for a first breakpoint session

The README distributes binaries through GitHub releases. Native execution is supported only on Linux. The README says Go 1.23+, while the repository's `go.mod` declares Go 1.24.0. The documented source build starts by cloning the repository, changing into it, compiling with `make`, and installing the binary under `/usr/local/bin` by default.

```bash
$ git clone https://github.com/ktock/buildg
$ cd buildg
$ make
$ sudo make install
```

After installation, point `debug` at a directory containing a Dockerfile and build context. The first session begins with this command:

```bash
buildg debug /path/to/build/context
```

The README's terminal example uses a multi-stage Dockerfile that writes two files in the `dev` stage and copies them into the final `scratch` stage. After the build reaches the debugger prompt, the documented first interactions are:

```console
(buildg) break 3
(buildg) continue
```

When the prompt reports that `Dockerfile:3` has been reached, `exec` opens the interactive shell. In the example, the shell reads `/hello` and `/world`; `quit` then ends the session. A developer should expect build output from BuildKit before and between these prompts, including image metadata and step completion messages.

## Rootless execution and containerized use

For native Linux operation, the README lists `runc` as a requirement. RootlessKit and `slirp4netns` are optional requirements for rootless execution. The two release archive forms differ here: `buildg-full-<version>-<os>-<arch>.tar.gz` includes the required runtime components, while `buildg-<version>-<os>-<arch>.tar.gz` does not. That distinction is important when selecting a release artifact.

IDE debugging through DAP requires rootless execution. The project therefore has a stricter runtime path for VS Code, Emacs, and Neovim than its basic terminal use implies. On systems other than Linux, the documented option is to run buildg in a Linux VM, with Lima given as an example.

A container image is published at `ghcr.io/ktock/buildg`. The README's direct Docker command mounts the context read-only and runs the debugger inside the container:

```bash
$ docker run --rm -it --privileged -v /path/to/ctx:/ctx:ro ghcr.io/ktock/buildg:0.4 debug /ctx
```

The image can also be built from the repository. The README notes that mounting a volume at buildg's root allows cache reuse between invocations:

```bash
$ docker run --rm -it --privileged \
  -v buildg-cache:/var/lib/buildg \
  -v /path/to/ctx:/ctx:ro \
  buildg debug /ctx
```

The cache volume is optional in the example. The documented invocation uses `--privileged` and a read-only context mount, without stating that they are defaults.

## DAP integration versus terminal-only debugging

The DAP integration is the clearest distinction between buildg and lower-level container tools. The README says that editors supporting the Debug Adapter Protocol can perform visual and interactive Dockerfile debugging. The repository includes `examples/dap/`, which is the specific documentation path to consult for editor configuration. It also uses `github.com/google/go-dap` as a dependency in `go.mod`.

This approach keeps the debugger's execution logic separate from the editor interface. The editor communicates through DAP, while buildg continues to manage the Dockerfile session and its BuildKit-based execution. That is more convenient for a developer who already uses breakpoint markers, source navigation, and interactive controls in an editor. It does not remove the Linux and rootless constraints documented for DAP use.

The README does not document a complete configuration file for every supported editor in its main text. Consequently, an adoption decision should check `examples/dap/README.md` for the exact adapter invocation and editor settings before assuming that a particular editor is ready to connect. The documented list includes VS Code, Emacs, and Neovim, with a link to the DAP implementors list for the broader compatibility boundary.

## Maintenance, release age, and compatibility cost

The repository is not archived, and its last push was on 2026-07-30. That is the maintenance fact available here, but it does not establish that every unmerged patch is compatible with the newest BuildKit or container runtime. The README itself describes the project as early-stage software and says its patches are not yet merged upstream. Those statements make upgrade behavior an explicit adoption concern.

Recent releases listed for the project are `v0.5.3` on 2025-05-12, `v0.5.2` on 2025-04-25, and `v0.5.1` on 2025-04-25. The README does not provide a release-to-BuildKit compatibility matrix, rollback instructions, or a documented policy for carrying local BuildKit patches into later releases. It also does not state how migrations should be handled when an IDE adapter or Docker image changes.

The project is distributed under Apache-2.0. That license permits use and modification under its terms, but this review does not interpret the license or provide legal advice. Source builds require Go, a compatible host environment, and the runtime binaries or container setup. Operators using the Docker route must account for privileged container execution and cache storage. These are practical costs of adoption, separate from the debugger's interactive features.

## Why buildctl and cntr solve different problems

BuildKit's `buildctl` is the closest conceptual alternative, but it does not provide buildg's interactive Dockerfile debugging experience. The README describes `buildctl` as having debug commands for inspecting `buildkitd`, LLB, and related state, while buildg focuses on stepping through a Dockerfile and entering a shell at a selected line.

`cntr` takes another route. It allows attaching to and debugging containers, but it does not offer interactive debugging of the Dockerfile build itself. This distinction matters when the failure occurs between instructions or depends on files produced by an earlier stage. Attaching to a container can be appropriate after a container exists; buildg is aimed at the build process itself.

`ctr` from containerd controls and inspects containerd resources such as contents and snapshots. It is useful at the runtime resource layer, but it does not provide the Dockerfile breakpoint workflow described by buildg. These tools can therefore coexist: buildg for a build-level investigation, and `buildctl`, `cntr`, or `ctr` when the question concerns daemon state, a running container, or storage resources.

## Conclusion

Developers debugging complex Dockerfiles on Linux should first verify that their environment meets buildg's runtime requirements and accept its dependence on unmerged BuildKit patches. Projects that only need normal build diagnostics or image inspection should retain BuildKit tooling instead. The first release-specific check should be the exact binary, runc, and rootless package combination selected for the installation.

## FAQ

### How do I install buildg?

The README lists binaries in GitHub releases and documents a source build using `make` and `sudo make install`. Native execution is supported only on Linux, and `runc` is required.

### How do I set a breakpoint in buildg?

In the documented session, enter `break 3` at the `(buildg)` prompt, then enter `continue`. When the debugger reports that `Dockerfile:3` has been reached, enter `exec` to open a shell.

### Can buildg debug Dockerfiles in VS Code?

Yes, through the Debug Adapter Protocol. The README names VS Code, Emacs, and Neovim, but DAP use requires rootless execution and the exact editor setup is documented under `examples/dap/`.

## Sources

- [Issues](https://github.com/ktock/buildg/issues)
- [ktock/buildg on GitHub](https://github.com/ktock/buildg)
- [License: Apache-2.0](https://github.com/ktock/buildg/blob/main/LICENSE)
- [README](https://github.com/ktock/buildg/blob/main/README.md)
- [Releases](https://github.com/ktock/buildg/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ktock-buildg