Overview

dcb builds and runs development containers from a devcontainer.json. It reads the same configuration as the Dev Container CLI, installs the same OCI features, and runs the same lifecycle commands.

• Build. dcb build turns a configuration into an image. It builds on the Docker daemon’s built-in BuildKit, installs each feature as a separate cached step, and can load, push, or export the result for one or more platforms.
• Run. dcb up builds the image when needed, then creates and starts the container and runs the lifecycle commands. dcb exec runs a command in it, and dcb down removes it.
• Read. Commands other than outdated write one JSON result line to stdout, except help, a valid exec invocation, and archive exports to stdout. Logs go to stderr. Exit codes separate operation failures from invalid invocations.

Relation to the Dev Container CLI

dcb is a separate implementation of the Dev Container specification. The goal is feature parity with the upstream devcontainers/cli: the same configuration gives the same image and the same container. Command names and flags follow upstream where the concept is the same.

Containers carry the upstream labels (devcontainer.local_folder, devcontainer.config_file) and lifecycle marker files, so upstream tools and editors find a container that dcb created, and the other way around.

Parity is measured, not assumed. The repository’s parity harness runs both CLIs on the upstream test fixtures and scores the matching results: the JSON result, image metadata, container environment, labels, mounts, user, working directory, and lifecycle and feature output. See the harness. Some upstream behavior is not yet matched.

Differences from upstream:

dcb	Upstream CLI
One static binary.	Node.js package.
Builds through the Docker Engine API on the daemon’s BuildKit.	Runs the docker and docker buildx commands.
One JSON result line for commands other than outdated, except help, a valid exec invocation, and archive exports to stdout.	Output format varies by command.
Docker only.	Docker, or Podman through --docker-path.
Can install the VS Code server into the image at build time.	The editor installs the server when it attaches.
Adds down, inspect, generate, server, and skills.	Also has upgrade and more Template commands.
dcb features stages configuration Features; features package packages local Features; features generate-docs writes local Feature READMEs; features info reports published Feature information; features resolve-dependencies reports the configuration dependency graph and installation order; templates generate-docs writes local Template READMEs.	features also tests and publishes Features.

Process credentials

See Git workspace discovery for process credentials, account lookup, and Git format differences.

outdated writes a text table by default, or a version report with --output-format json.

Requirements

dcb needs a Docker Engine that it can reach with the standard DOCKER_HOST and related environment variables. The docker command is not needed. Both the containerd image store and the classic image store work. Podman is not supported.

Builds use the daemon’s built-in BuildKit. To use a separate BuildKit, set BUILDKIT_HOST or pass --buildkit-addr. See Docker and BuildKit.

Release binaries are for Linux and macOS on amd64 and arm64.

Libraries

The Go packages behind dcb can be used directly: build an image, run a container against the Docker Engine, or project a configuration into a Kubernetes Pod. See Go libraries.