Skip to main content

​
Overview

By default, every snapshot build is a full build — it starts from a clean base image, clones all repositories, and runs every blueprint from scratch. This ensures a completely reproducible environment, but can be slow when you only changed one blueprint out of many. Differential builds optimize this by reusing the previous successful build’s snapshot as a starting point. Only workspaces whose blueprints actually changed are rebuilt; unchanged workspaces are inherited as-is from the parent build. This can significantly reduce build times, especially for organizations with many repositories.

​
Enabling differential builds

1

Navigate to environment settings

Go to Settings > Environment > Advanced.
2

Enable the toggle

Turn on the Differential builds toggle. The description reads: “Faster builds by reusing unchanged workspaces.”
3

Trigger a build

Save a blueprint change or click Build snapshot. The next build will attempt to run as a differential build if a valid parent build exists.
Enabling differential builds does not force a full build. If a previous successful or partial build already exists for the same platform and machine configuration, the next build can use it as its parent and inherit its state. The next build runs as a full build only in the situations listed in When a full build runs instead. To start from a clean baseline, select Full build from the Build snapshot dropdown.

​
How it works

When a build is triggered with differential builds enabled, the system follows this process:

​
1. Find a parent build

The system looks for the most recent successful build (status success or partial) with a snapshot image for the same platform and machine configuration to use as a parent. If no qualifying parent exists, the build falls back to a full build automatically.

​
2. Compare blueprints

Each workspace’s configuration is compared against the parent build. The system computes a digest of each workspace’s inputs — including blueprint contents, attached files, and secrets — and checks what changed.

​
3. Assign workspace actions

Based on the comparison, each workspace gets one of three actions:
For inherited workspaces, initialize does not run again. Write maintenance so it is self-contained and can run independently after the latest code is pulled. It can use tools and runtimes already installed in the parent snapshot, but it must not require initialize to run immediately beforehand or rely on environment variables that initialize previously wrote to $ENVRC.

​
4. Execute the build

The build starts from the parent build’s snapshot image instead of a clean base. This means:
  • Inherited workspaces already have their tools, runtimes, and dependencies installed. The system pulls the latest code (git pull) and runs maintenance commands to update dependencies.
  • Rebuilt workspaces are set up from scratch — cloned fresh and run through the full initialize + maintenance sequence.
  • Removed workspaces have their directories cleaned up.
Organization and enterprise blueprints skip initialize during differential builds (since those tools are already present in the parent image) and run only maintenance.
$ENVRC is reset at the start of every build, including differential builds. Environment variables and PATH entries written to $ENVRC by a previous build are not inherited. If maintenance needs them, it must configure them itself.

​
When a full build runs instead

Even with differential builds enabled, a build runs as a full build in these situations:
  • You request a full build — you select Full build from the Build snapshot dropdown
  • The newest full build is too old — an automatic build, such as one triggered by saving a blueprint, runs as a full build when no full build exists for its platform or the newest one is older than the Full build refresh interval in Settings > Environment > Advanced (every 7 days by default)
  • No reusable parent build exists — there is no success or partial build with a snapshot image for the same platform and machine configuration
  • The parent build is incompatible — the platform, machine configuration, base image, or Clone repositories on all platforms setting changed since the parent build, or the parent build has no secret baseline to compare against
  • Organization or enterprise configuration changed — an organization or enterprise blueprint, blueprint file, or secret changed since the parent build
Changes scoped to individual repositories keep the build differential. New repositories, blueprint or secret changes for a repository, and repositories that failed in the parent build are rebuilt within the differential build. Reordering repositories does not trigger a full build. When a build that was requested as differential runs as a full build instead, the Build kind tooltip on the build detail page shows the reason.

​
Viewing build kind

After a build completes, you can see whether it ran as a differential or full build:
  1. Go to Settings > Environment > Snapshots
  2. Click on a build in the history
  3. The Build kind badge shows either Differential (blue) or Full build (default)
Hover over the badge for a tooltip explaining what each kind means:
  • Differential: “Only changed workspaces are rebuilt; unchanged ones are inherited from the last successful build with the same configuration”
  • Full build: “All workspaces are built from scratch”

​
Benefits

​
Manually triggering a full build

Even with differential builds enabled, you can force a full build from the Build snapshot button. Use the dropdown to select Full build instead of the default differential option. We recommend running a full build periodically to discard inherited state and verify that your blueprints can still create the environment from scratch. Also run one after removing or replacing setup that may have left stale files, tools, or dependencies in the snapshot. A full build reruns all initialize and maintenance steps.

​
FAQ

No. Sessions always boot from the final snapshot regardless of how it was built. The only difference is build speed.
Pin a previous known-good build from Settings > Environment > Snapshots, then trigger a full build to get a clean snapshot. You can also disable differential builds entirely to go back to full builds.
Yes. A build with status partial (some workspaces succeeded, some failed) can serve as a parent. The system inherits only from workspaces that succeeded in the parent.