Skip to content
DevContainer Features

envbuilder

Status

Section titled “Status”

Version: 1.1.2 | Tests: Passing

Usage

Section titled “Usage”
devcontainer.json 
{
    "features": {
        "ghcr.io/infrashift/trusted-devcontainer-features/envbuilder:latest": {
            "target_version": "1.3.0"
        }
    }
}

Options

Section titled “Options”
OptionTypeDefaultDescription
target_versionstring1.3.0Select a supported envbuilder version
target_checksumstring""SHA256 of the OCI layer holding .envbuilder/bin/envbuilder

Dependencies

Section titled “Dependencies”

None — this feature is independent and has no dependencies.

How It Works

Section titled “How It Works”

This feature installs envbuilder, which builds a development environment from a repository’s devcontainer.json or Dockerfile inside a running container, with no Docker daemon involved.

Like kaniko, envbuilder publishes no release binaries — its container image is the only distribution channel, and that image is a single layer containing just the binary. The Ansible role therefore downloads one blob directly from the registry. An OCI blob is addressed by the sha256 of its own bytes, so the pinned digest is simultaneously the download URL and the checksum that verifies it. Digests are pinned per version and per architecture, and an unpinned combination fails by name rather than downloading something unverified. Note that envbuilder’s image tags carry no v prefix, unlike kaniko’s.

The binary installs under ~/.local/share/envbuilder/<version>/ with a symlink into ~/.local/bin. The role never executes it, deliberately. envbuilder has no version subcommand: envbuilder version prints its startup banner and then goes on to attempt a build, and a bogus subcommand produces byte-identical output. A probe that starts a build engine is not a probe, so the version-scoped path answers “which version is installed” and the pinned layer digest is what proves it.

In normal use envbuilder is configured through ENVBUILDER_* environment variables rather than flags, and it is designed to run as a container’s entrypoint rather than as an interactive command. Running it bare in a shell will start a build against the current workspace, so treat it as a build engine you invoke deliberately, not a utility you can safely poke at.