Custom Assembly on

How Guarded Entrypoint works

Tue, 06 Oct 2026 17:41:00 +0000

Note: Guarded Entrypoint is in beta. To use it, contact Chainguard customer support to enable it for your organization.

This page describes what the Guarded Entrypoint binary does when a container starts. The page calls the binary the wrapper. To turn Guarded Entrypoint on, see Guarded Entrypoint for Custom Assembly.

What the wrapper does

When you turn on Guarded Entrypoint, Chainguard rebuilds the image with /usr/bin/guarded-entrypoint as the first element of its entrypoint. The image’s original entrypoint follows it. Chainguard stores your settings in environment variables in the image configuration. The names of these variables start with GUARDED_. You can see them with docker inspect. The GUARDED_ prefix is reserved, and the API rejects it in your own environment keys.

Managing tag-based Custom Assembly with chainctl

Mon, 28 Sep 2026 16:33:22 +0000

Note: Tag-based Custom Assembly is in beta. Contact your Chainguard account team to enable it for your organization.

This guide shows how to use chainctl to apply Custom Assembly customizations to some of a repository’s tags. You create an overlay that holds the customizations, then bind it to a repository with a tag selector.

For an explanation of overlays, bindings, and tag selectors, see Overview of tag-based Custom Assembly.

Prerequisites

Before you start, you need the following:

Adding a package to a Chainguard Container

Wed, 09 Sep 2026 00:00:00 +0000

Chainguard Containers ship with only the packages their application needs, so sooner or later you’ll want one that isn’t there. Custom Assembly is the supported way to add it. You declare the package you want, Chainguard builds the image on its own infrastructure, and Chainguard rebuilds that image whenever the package is updated. You can drive Custom Assembly from the Chainguard Console, interactively with chainctl, or non-interactively with chainctl from a pipeline.

Overview of Chainguard Custom Assembly

Wed, 19 Feb 2025 11:07:52 +0200

Chainguard Custom Assembly enables organizations to build container images tailored to their internal requirements and application dependencies, without sacrificing security. By extending Chainguard’s hardened base images with additional packages, environment variables, user accounts, and certificates, teams can reduce CVE exposure while maintaining the flexibility their workflows demand.

This overview of Custom Assembly outlines how it works, its limitations, and how you can use container images customized with Custom Assembly.

You can drive Custom Assembly through any of the following interfaces. They produce the same result, so pick the one that matches how you work:

Guarded Entrypoint examples

Tue, 06 Oct 2026 17:41:00 +0000

Note: Guarded Entrypoint is in beta. To use it, contact Chainguard customer support to enable it for your organization.

This page has four example manifests for Guarded Entrypoint. Each one is a complete manifest for chainctl images repos build edit or chainctl images repos build apply. None of them contains a literal secret. Each secret is a reference that the wrapper resolves when the container starts.

Applying a manifest replaces the repo’s stored configuration. If your repo already has other customizations, such as packages, add the Guarded Entrypoint keys to your existing manifest instead of replacing it.

Managing tag-based Custom Assembly with Terraform

Mon, 28 Sep 2026 16:33:22 +0000

Note: Tag-based Custom Assembly is in beta. Contact your Chainguard account team to enable it for your organization.

This guide shows how to manage tag-based Custom Assembly with the Chainguard Terraform provider. You define overlays with the chainguard_image_overlay resource and bind them to repositories with the chainguard_image_overlay_binding resource.

For an explanation of overlays, bindings, and tag selectors, see Overview of tag-based Custom Assembly.

Prerequisites

Before you start, you need the following:

Using the Chainguard Console to manage Custom Assembly resources

Wed, 09 Jul 2025 11:07:52 +0200

Chainguard’s Custom Assembly feature allows you to build customized container images that include only the packages your application needs. This tutorial walks you through using the Chainguard console’s web interface to manage Custom Assembly resources, including selecting packages, building customized containers, and monitoring build status.

By the end of this guide, you’ll be able to create, customize, and manage your own container images through the Chainguard console, giving you full control over your container dependencies while maintaining Chainguard’s security and compliance standards.

Troubleshoot a wrapped container

Tue, 06 Oct 2026 17:41:00 +0000

Note: Guarded Entrypoint is in beta. To use it, contact Chainguard customer support to enable it for your organization.

This page covers two kinds of problems. A container that is built with Guarded Entrypoint can fail to start. A build can also fail because Chainguard refuses to wrap an image.

First move: set GUARDED_DISABLE

When a wrapped container fails to start, set the GUARDED_DISABLE environment variable on the container and redeploy. The wrapper then starts the image’s original entrypoint and arguments without doing anything else. You don’t need to rebuild the image.

Using chainctl to manage Custom Assembly resources

Thu, 01 May 2025 11:07:52 +0200

Chainguard’s Custom Assembly is a tool that allows customers to create customized containers with extra packages and annotations 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.

You can use chainctl, Chainguard’s command-line interface tool, to further customize your Custom Assembly builds and retrieve information about them. This guide provides an overview of the relevant chainctl commands and outlines how you can edit the configuration of Custom Assembly containers, as well as retrieve a list of a customized image’s builds and its build logs.

Overview of tag-based Custom Assembly

Mon, 28 Sep 2026 16:33:22 +0000

Note: Tag-based Custom Assembly is in beta. Contact your Chainguard account team to enable it for your organization.

Standard Custom Assembly applies one customization to every tag in a repository. This fails for images that ship several language or runtime versions side by side, because a package built for one version can’t install on the others.

For example, the python image publishes tags for Python 3.11, 3.12, 3.13, and 3.14. The py3.13-typer package depends on Python 3.13. If you add it with standard Custom Assembly, every tag tries to install it, and the 3.11, 3.12, and 3.14 builds fail.

Guarded Entrypoint trust boundary

Tue, 06 Oct 2026 17:41:00 +0000

Note: Guarded Entrypoint is in beta. To use it, contact Chainguard customer support to enable it for your organization.

This page states what the Guarded Entrypoint wrapper connects to, what it never does, and what anyone who can pull your image can read.

What the wrapper connects to

The wrapper connects only to the endpoints that your configuration names:

Using GitOps to manage Custom Assembly resources

Thu, 29 Jan 2026 11:07:52 +0200

Chainguard’s Custom Assembly is a tool that lets customers create customized container images with extra packages and annotations 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. It can be managed in the Chainguard Console, with chainctl, with the API, or from a CI/CD pipeline.

This guide shows how to use Chainguard Custom Assembly as code from a CI/CD pipeline, storing your configuration in Git and using automation to apply changes and trigger builds. The examples in this guide focus on GitHub Actions, and are adapted from Chainguard’s custom-assembly-as-code demo repository.

Using the Chainguard API to manage Custom Assembly resources

Thu, 01 May 2025 11:07:52 +0200

Chainguard’s Custom Assembly is a tool that allows customers to create customized containers 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.

You can use the Chainguard API to further customize your Custom Assembly builds and retrieve information about them. This tutorial highlights a demo application (which can be found in Chainguard Academy’s Demo Applications repository) which, when run, updates a Custom Assembly container’s configuration based on a provided YAML file.

Adding custom certificates with Custom Assembly

Thu, 12 Mar 2026 11:07:52 +0200

Many enterprise environments use internal certificate authorities (CAs) to issue certificates for internal services. These custom certificates need to be trusted by containers that communicate with the internal services. Custom Assembly allows you to build custom certificates directly into your container images, ensuring they trust your organization’s internal services without requiring manual certificate mounting at runtime.

Note: If you are looking for a way to embed certificates at build time, refer to our guide on How to use incert to create container images with built-in custom certificates.

Guarded Entrypoint for Custom Assembly

Tue, 06 Oct 2026 17:41:00 +0000

Note: Guarded Entrypoint is in beta. To use it, contact Chainguard customer support to enable it for your organization.

Guarded Entrypoint lets a Custom Assembly image run startup logic without a derived image build. You declare the logic as part of your Custom Assembly configuration. Chainguard builds it into the image and signs the result.

This page explains what Guarded Entrypoint is and how to turn it on. The other pages in this section cover the details:

Custom Assembly FAQs

Wed, 19 Feb 2025 11:07:52 +0200

What is Chainguard’s Custom Assembly?

Custom Assembly is a tool from Chainguard that allows users to build customized container images by assembling packages from a curated, secure set of base images provided by Chainguard.