README
¶
dcb
dcb builds and runs development containers from a
devcontainer.json. It builds images on the Docker daemon's built-in BuildKit,
and creates, starts, and runs lifecycle commands in containers through the
Docker Engine API. Every command writes one JSON result line to stdout, except
help and a valid exec invocation.
Documentation is at wyrd.foo/docs/dcb, published
from docs/.
Install
| Method | Command |
|---|---|
| Homebrew | brew install wyrd-company/tools/dcb |
| npm | npm install --global @wyrd-company/dcb |
| APT | sudo apt install dcb |
| RPM | sudo dnf install dcb |
| AUR | paru -S dcb-bin |
| Go 1.26+ | go install github.com/wyrd-company/devcontainer-builder/cmd/dcb@latest |
APT and RPM need the repo.wyrd.foo package repository. Installation gives the setup commands and the release archives.
dcb runs on Linux and macOS, on amd64 and arm64. It needs a Docker Engine
that it can reach through the standard DOCKER_HOST environment; the docker
command is not needed. Podman is not supported.
Use
dcb up --workspace-folder .
dcb exec --workspace-folder . -- sh -c 'id && pwd'
dcb down --workspace-folder .
{"containerId":"3f1c…","outcome":"success","remoteUser":"vscode","remoteWorkspaceFolder":"/workspaces/project"}
Build an image and push it for two platforms:
dcb build --workspace-folder . \
--image-name registry.example.com/team/dev:1.0 \
--platform linux/amd64 --platform linux/arm64 \
--push
dcb --help lists every command. Exit code 0 is success, 1 is an
operation failure, and 2 is an invalid invocation, with a JSON error result.
After exec starts the container command, it passes the command's output
through and returns its exit code. See Usage
and Configuration.
dcb skills install writes an agent skill that describes these commands for
coding agents.
Relation to the Dev Container CLI
dcb is a separate implementation of the
Dev Container specification, with
the goal of feature parity with
devcontainers/cli. It uses the same
container labels and lifecycle marker files, so each tool finds containers that
the other created. Command names and flags follow upstream where the concept is
the same.
The parity harness runs both CLIs on upstream fixtures and reports the share of results that match. Some upstream behavior is not yet matched. Overview lists the differences.
Not yet supported
These upstream command families are not yet supported:
Go libraries
The packages under pkg/ build images, run containers on Docker or
Kubernetes, and convert configurations into Kubernetes Pods. They can be
embedded in a service or an operator. See
Go libraries.
Development
See CONTRIBUTING.md. task check runs the checks that a
change must pass; task parity runs the parity harness.
License
MIT. The npm launcher and some release scripts are adapted from
other Wyrd Company projects under the Apache License 2.0; see
npm/NOTICE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
dcb
command
Command dcb builds and manages development containers through the Engine API.
|
Command dcb builds and manages development containers through the Engine API. |
|
internal/render-k8s-testdata
command
|
|
|
internal
|
|
|
datafolder
relationships:
|
relationships: |
|
dockerimage
Package dockerimage shares native Engine image pulls between hosts.
|
Package dockerimage shares native Engine image pulls between hosts. |
|
dockertest
Package dockertest holds helpers for Docker integration tests.
|
Package dockertest holds helpers for Docker integration tests. |
|
testgit
Package testgit isolates Git commands used by test fixtures.
|
Package testgit isolates Git commands used by test fixtures. |
|
pkg
|
|
|
builder
Package builder is the top-level orchestrator.
|
Package builder is the top-level orchestrator. |
|
buildkit
Package buildkit drives image builds via direct integration with the BuildKit Go client.
|
Package buildkit drives image builds via direct integration with the BuildKit Go client. |
|
cli
--- relationships:
|
--- relationships: |
|
dockerfile
Package dockerfile generates a Dockerfile that wraps a devcontainer base image (or upstream Dockerfile) with feature install scripts and a pre-staged VS Code server.
|
Package dockerfile generates a Dockerfile that wraps a devcontainer base image (or upstream Dockerfile) with feature install scripts and a pre-staged VS Code server. |
|
features
relationships:
|
relationships: |
|
host/docker
Package docker brings a devcontainer up against a Docker Engine by talking to the engine API directly — no `docker` CLI shell-out, so the package is safely embeddable in services and operators.
|
Package docker brings a devcontainer up against a Docker Engine by talking to the engine API directly — no `docker` CLI shell-out, so the package is safely embeddable in services and operators. |
|
host/dockercompose
relationships:
|
relationships: |
|
host/kubernetes
Package kubernetes brings a devcontainer up against a Kubernetes apiserver: discover-or-create the Pod, exec lifecycle phases through the pod-exec subresource, port-forward, delete on teardown.
|
Package kubernetes brings a devcontainer up against a Kubernetes apiserver: discover-or-create the Pod, exec lifecycle phases through the pod-exec subresource, port-forward, delete on teardown. |
|
host/runner
relationships:
|
relationships: |
|
lifecycle
Package lifecycle plans the post-build / post-start commands a devcontainer expects to run, in the order required by the spec, with the marker-file scheme that the upstream devcontainer CLI uses.
|
Package lifecycle plans the post-build / post-start commands a devcontainer expects to run, in the order required by the spec, with the marker-file scheme that the upstream devcontainer CLI uses. |
|
metadata
relationships:
|
relationships: |
|
oci
Package oci is a small read-only OCI Distribution v2 client.
|
Package oci is a small read-only OCI Distribution v2 client. |
|
platform
Package platform translates between Go's runtime platform names, OCI platform strings, Docker buildx platform strings, and the labels used by the VS Code server downloads.
|
Package platform translates between Go's runtime platform names, OCI platform strings, Docker buildx platform strings, and the labels used by the VS Code server downloads. |
|
projection/kubernetes
Package kubernetes projects a parsed devcontainer.json (plus its resolved features) into the Kubernetes API objects that would launch the same container on a cluster.
|
Package kubernetes projects a parsed devcontainer.json (plus its resolved features) into the Kubernetes API objects that would launch the same container on a cluster. |
|
registryauth
Package registryauth reads registry credentials from the Docker client configuration, as the docker CLI does: static "auths" entries in config.json, and the credential-helper protocol (docker-credential-<name> get) for "credsStore" and "credHelpers".
|
Package registryauth reads registry credentials from the Docker client configuration, as the docker CLI does: static "auths" entries in config.json, and the credential-helper protocol (docker-credential-<name> get) for "credsStore" and "credHelpers". |
|
spec
Package spec contains types and parsers for the devcontainer specification as documented at https://containers.dev/implementors/json_reference/.
|
Package spec contains types and parsers for the devcontainer specification as documented at https://containers.dev/implementors/json_reference/. |
|
substitute
Package substitute resolves the ${variable} placeholders that devcontainer.json and feature configs use.
|
Package substitute resolves the ${variable} placeholders that devcontainer.json and feature configs use. |
|
vscode
Package vscode resolves and downloads the VS Code Server tarball that matches a given platform.
|
Package vscode resolves and downloads the VS Code Server tarball that matches a given platform. |
|
workspace
Package workspace decides where a local workspace folder is mounted in a single-container devcontainer and which container folder is its workspace folder.
|
Package workspace decides where a local workspace folder is mounted in a single-container devcontainer and which container folder is its workspace folder. |
|
test
|
|
|
integration/kubernetes
Package kubernetes holds validation checks for rendered manifests.
|
Package kubernetes holds validation checks for rendered manifests. |
|
parity
command
relationships:
|
relationships: |