> For the complete documentation index, see [llms.txt](https://docs.sealsecurity.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sealsecurity.io/using-platform/working-with-seal-base-images.md).

# Working with Seal Base Images

Seal Base Images replace the public container base image you build on top of with a sealed counterpart published to Seal's image registry. The day-to-day work for this product is not the four-step review-decide-build-verify rhythm the rest of this section describes. There is no Seal CLI in the build, no Sealing Rules to manage, and no Protection page row to watch. The Protection page does not list packages from Seal Base Images deployments because nothing reports back to the platform — your container runtime is the only thing that touches Seal at runtime.

What this leaves is closer to a regular third-party-dependency upgrade cycle: stay informed about newer iterations Seal publishes, decide when to roll forward, change the `FROM` reference, test, deploy.

## The recurring cycle

The cycle has four moving parts, not a strict order:

1. **Stay informed** about new iterations of the base images you use.
2. **Decide** which iteration to be on, given your tolerance for moving and your build's stability requirements.
3. **Roll forward** by editing the `FROM` reference (or the equivalent Helm or Kubernetes manifest) and merging the change through your normal review process.
4. **Verify** by building, testing, and shipping the resulting image through whatever pipeline your team already runs.

Steps 3 and 4 are the same patterns as any base-image upgrade. The two pieces that are specific to Seal Base Images are step 1 (how you find out about new iterations) and step 2 (the pinning decision).

## Staying informed about new releases

Seal publishes new iterations of a base image when:

* A new vulnerability is disclosed in a package the base image contains and Seal has a backportable fix. The next sealed iteration (`sp2`, `sp3`, and so on) seals it.
* The upstream image author publishes a new build of the same tag (a new build-timestamp). Seal seals the new build.

Customers find out about new iterations through their Seal account team. The team tracks which sealed images each customer uses and notifies you when a newer iteration becomes available, including the rare high-severity disclosure that drives an out-of-cycle iteration.

The Protection page does not show Seal Base Image releases because the platform does not see your container builds. The [Repository page](/discovering/repository-page.md)'s Base images tab is browsable from a connected machine if you want to confirm what is currently available; that and the account team are the two channels.

## Pinning strategies

Every `FROM` reference resolves to one immutable image — there is no rolling tag for a sealed base image. The choice of strategy is in how you write the reference and how often you bump it. A few patterns customers use:

* **Pin to a specific sealed iteration, bump on notification.** The most common. Your `FROM` references a fully-qualified reference (build-timestamp plus `-sp[N]`); you roll it forward when your account team tells you a newer iteration is available and your release window allows. Predictable, reproducible builds, with the trade-off that you are responsible for moving forward.
* **Pin to a specific sealed iteration, bump on a schedule.** Same shape, but the bump is calendar-driven (monthly, quarterly) rather than event-driven. Lower coupling to Seal's release cadence, lower responsiveness to newly-disclosed vulnerabilities. Reasonable for stable workloads where the trade-off matches your risk tolerance.
* **Bump aggressively to the newest iteration.** Roll forward as soon as a new iteration is available — for security-critical services where the leverage of latest-sealed is worth the rebuild cost.

There is no automatic-rollover option for Seal Base Images. The deployment shape is pull-on-build, and the build references whatever is in your code at build time. If you want "always the newest sealed iteration", you implement it as policy — a bot that opens a PR on each new iteration, a scheduled job that bumps the reference — rather than as a platform feature.

## Iteration bumps vs build-timestamp bumps

Two distinct kinds of update flow through the same `FROM` change but warrant different test discipline:

* **Sealed-iteration bump** (`sp2` → `sp3`): the underlying upstream snapshot is unchanged; only more vulnerabilities are sealed. The blast radius is small — the same files in the same paths, only patched. Most customers treat these as low-risk and roll them forward without elaborate testing.
* **Build-timestamp bump** (`20250408T180700Z` → `20250612T134200Z`): the upstream image author published a new build of the same tag. Underlying packages may have moved (kernel headers, distro patches, third-party packages bundled with the language runtime). The blast radius matches that of an upstream base-image upgrade; review and test accordingly.

The setup chapter on [Updating to a new base image release](/setup-containers/seal-base-images/updating.md) has the diff-shape patterns for both. The day-2 message is: distinguish the two when planning the test cycle.

## Upgrade-safe patching

Sealed iterations are explicitly designed not to break compatibility — the package layout, file paths, and behavior are preserved from the upstream version. The main reason a sealed-iteration bump might cause trouble is if your test suite or your application has come to depend on the *vulnerable* behavior of an upstream package (a hash collision a fix prevents, a memory-management quirk a fix smooths out). This is rare in practice.

The general advice for an iteration bump: run your normal CI tests against the rebuilt image, do not skip integration tests in favor of unit tests, and pay attention to anything in your test suite that flags timing, randomness, or memory behavior. A test that has been quietly relying on a vulnerable side-effect will surface here.

For build-timestamp bumps, also rebuild any downstream images that derive from this one in your fleet, and validate that the moved upstream packages did not change something your application uses directly.

## Rolling back

Rollback is the same one-line change in reverse: repoint the `FROM` to the previous sealed iteration. The previous iteration stays available in Seal's registry indefinitely.

Rollbacks should be rare. Sealed iterations preserve the package layout and behavior of the upstream image, so a regression specific to a sealed iteration is uncommon. If you encounter one, roll back, then contact your Seal account team with the symptoms so they can investigate before you try to move forward again.

## What this deployment does not need

Seal Base Images sit outside the Sealing Rule model and outside the Protection-page workflow.

* The [Sealing rules tab](/discovering/protection-page/sealing-rules-tab.md) being empty is not a problem; a Seal Base Images deployment does not create or need Sealing Rules.
* The Vulnerable packages tab not listing the OS packages baked into a sealed base image is also not a problem; the substitution happened at image-pull time, not in a discoverable build step.
* No scan job, no `seal fix` invocation, no `SEAL_PROJECT`, no `SEAL_TOKEN` on the build agent. The credentials are only used at registry-pull time.

Customers running Seal Base Images alongside other Seal products (typically Seal Apps for application dependencies on top of the sealed base image, or Seal OS for additional OS-package work on top) operate those products through their own normal day-2 channels; the base-image side is the cleanest deployment of the five.

## Related

* [Seal Base Images](/setup-containers/seal-base-images.md): the setup chapter, including authentication, pulling, mirroring, and Kubernetes integration.
* [Updating to a new base image release](/setup-containers/seal-base-images/updating.md): the mechanics of the `FROM`-line bump, including the mirror-coordination step.
* [Browsing sealed base images](/discovering/repository-page/sealed-packages.md): the catalog view for what is available, browsable from any connected machine.
* [Working with the platform](/using-platform/working-with-the-platform.md): the cross-product framing that calls out Seal Base Images as the exception to the four-step rhythm.