Chainguard Custom Assembly: overview

Format: Markdown for a Hugo documentation site · Client: Chainguard · Published: 2025

Product documentation introducing Custom Assembly, a Chainguard tool for building customized container images. It explains what the tool does, where its limits are, and how to use the result. The audience is Chainguard customers — platform and security engineers — so it states constraints plainly and is careful to set expectations about what the tool does not do.

Read the full document on Chainguard Academy →

Excerpt:

Chainguard has created Custom Assembly, a tool that allows users to create customized container images with extra packages added. This enables customers to reduce their risk exposure by creating container images that are tailored to their internal organization and application requirements while still having few-to-zero CVEs.

In order to use the Custom Assembly tool, you will need to choose an appropriate source image from your organization’s collection of Production Chainguard Containers to serve as the base for your customized container image. Say, for example, you want to build a custom base for a Python application. In this case, you would likely choose to use the Python Chainguard Container as the source for your customized image.

After selecting the packages for your customized container image, Chainguard will kick off a build on Chainguard’s infrastructure. Once a customized image is built successfully, Chainguard will take care of its maintenance and rebuild it as necessary, such as when any of the packages in the image are updated.

Limitations

Custom Assembly only allows you to add packages into a given container image; you cannot remove the packages included in the source application image by default. For example, Chainguard’s Node.js container image comes with packages like nodejs-23, npm, and glibc by default. These packages can’t be removed from a Node.js image using the Custom Assembly tool but you can add other packages into it, and you can remove these added packages in later builds.

The changes you make to your customized container image may affect its functional behavior when deployed. Chainguard doesn’t test your final customized image and therefore doesn’t guarantee its functional behavior. Please test your customized images extensively to ensure they meet your requirements.

Excerpt from “Overview of Chainguard Custom Assembly,” Chainguard Academy. Back to all writing samples.