Depot container builds

Building a Docker image using Depot is up to 40x faster than on your local machine or CI provider. See a live benchmark.

At a high level, here's what happens when you run depot build:

1. We send your build context to a remote builder instance running an optimized BuildKit implementation.
2. BuildKit performs the build and sends the resulting image back to your machine or a remote registry (according to the options you passed in the build command).
3. Your Depot project's persistent cache stores the resulting layer cache from the build automatically.
4. Your team or CI provider accesses the persistent cache for subsequent builds.

Switching to Depot

Switching to Depot for your container builds is usually a one-line code change: replace docker build with depot build. For example, if you're running build or bake commands locally, you can switch to using the same commands with the Depot CLI:

# to replace docker build
depot build -t my-image:latest --platform linux/amd64,linux/arm64 .
# to replace docker bake
depot bake -f docker-bake.hcl

The depot build command accepts the same arguments as docker build, so you can use it in your existing workflows without any changes. Depot's build infrastructure for container builds requires zero configuration and automatically includes a persistent build cache and support for native multi-platform image builds.

To see a Depot container build in action, try the quickstart.

Use cases for Depot container builds

Depot container builds benefit any team that builds and ships containerized applications. Opportunities to optimize your development workflows include:

• Building your Docker image is slow in CI: Many CI providers force you to save and load your Docker layer cache via bulky tarballs over slow, flaky networks. Sometimes CI providers offer limited resources like slower CPUs, memory, and disks that result in longer overall build times.

  Depot works within your existing workflows: When you replace docker build with depot build, your Docker layer cache is automatically persisted to a fast NVMe SSD and your build runs on a remote BuildKit host. You don't need to save and load layer cache over networks. For more information, see Continuous integration.

• You're building images for multiple platforms or multiple architectures: Maybe you're stuck with managing your own build runner or relying on slow emulation to build multi-platform images (x86 and ARM). For example, CI providers usually run their workflows on Intel (x86) machines. If you want to create a Docker image for ARM, you either have to launch your own BuildKit builder for ARM and connect to it from your CI provider, or build your ARM image with slow QEMU emulation.

  Depot can build multi-platform and ARM images natively with zero emulation and without running additional infrastructure.

• Building your Docker image on your local machine is slow or expensive: Docker can hog resources on developer machines, taking up valuable network, CPU, and memory resources.

  Depot executes builds on remote compute infrastructure and the remote builder instance takes care of the CPU, memory, disk, and network resources required for your builds. Learn more about local development with Depot.

• You want to share build results with a team: Without shared infrastructure, each developer and CI job has to rebuild Docker layers that teammates have already built, wasting time and compute resources.

  Depot projects provide persistent, remotely accessible build caches. Your whole team can send builds to the same project and automatically reuse each other's Docker layer cache. If your coworker has already built an image, your depot build command for the same image reuses those layers without rebuilding them.

Feature summary

The following table summarizes the key features of Depot container builds.

How Depot container builds work

Understand the core concepts of Depot container builds.

Projects

A project in Depot is a cache namespace that's isolated from other projects in your organization at a cache and hardware level. You can use a project for a single application, git repository, or Dockerfile.

All your container builds run within a project. You can create multiple projects within an organization to manage your container builds.

Once you create a project, you can use Depot container builds from your local machine or an existing CI workflow by swapping docker for depot.

Builds

Builder instances are ephemeral. They terminate after each build. Your build cache is persistent and remains available across builds. Within a project, every new builder instance uses the project's persistent cache.

Builder instances

Default builder instances come with 16 CPUs and 32 GB of memory. If you're on a Startup or Business plan, you can configure larger builders in your project settings, with up to 64 CPUs and 128 GB of memory. Builder instances run an optimized version of BuildKit.

By default, all builds for a project are routed to a single builder instance per architecture you're building.

Depot can build images on both x86 and ARM machines supporting the following platforms:

• linux/amd64
• linux/arm64
• linux/ARM/v6
• linux/ARM/v7
• linux/386

Both architectures build native multi-platform images with zero emulation.

Build cache

By default, the image built on a Depot builder instance stays in your project's persistent build cache for reuse in future builds.

You can also download the image to your local Docker daemon with depot build --load or push it directly to a registry with depot build --push. When you use --push, we push the image directly from the remote builder instance to your registry over high-speed network links, not through your local network. Learn more about pushing to private Docker registries like Amazon ECR or Docker Hub.

Open-source repository build isolation

For open-source repositories, builds launched by fork pull requests are isolated to ephemeral builder instances with no read or write access to the project cache. Isolating these builds prevents cache poisoning and protects sensitive data from untrusted code. You'll see these types of builds labeled as isolated in the Depot dashboard.

Configurable cache size per project

The default cache size for a Depot project is 50 GB. You can specify a cache storage policy up to 500 GB in your project settings. The cache storage policy defines how much cache to keep for each architecture you build. When the cache exceeds the specified size, we delete the oldest cache entries.

Deep dive: Technical architecture

A deeper dive into the design and architecture of Depot container builds.

The architecture for Depot remote container builds consists of the Depot CLI, a control plane, an open-source cloud-agent, and builder instances (virtual machines) running our open-source machine-agent and BuildKit with associated cache volumes.

The flow of a Docker image build using Depot looks like this:

1. The Depot CLI asks the Depot API for a new builder machine connection (with organization ID, project ID, and the required architecture) and polls the API for when a machine is ready.
2. The Depot API stores the pending request for a builder.
3. A cloud-agent process periodically reports the current status to the Depot API and asks for any pending infrastructure changes.
4. For a pending build, the cloud-agent process receives a description of the machine to start and then launches it.
5. When the machine launches, a machine-agent process running inside the virtual machine registers itself with the Depot API and receives the instruction to launch BuildKit with specific mTLS certificates provisioned for the build.
6. After the machine-agent reports that BuildKit is running, the Depot API returns a successful response to the Depot CLI, along with new mTLS certificates to secure and authenticate the build connection.
7. The Depot CLI uses the new mTLS certificates to directly connect to the builder instance, using that machine and cache volume for the build.

We use the same architecture for Depot Managed builders, the only difference being where the cloud-agent and builder virtual machines launch.

Pricing

Depot remote container builds are available on all of our pricing plans. Each plan includes a bucket of both Docker build minutes and GitHub Actions minutes. Business plan customers can contact us for custom plans.

Container builds FAQ

depot build -t <your-registry> --push --provenance=false .

depot build \ --output "type=image,name=repo/image:tag,push=true,compression=estargz,oci-mediatypes=true,force-compression=true" \ .

depot build \ --output type=image,name=$IMAGE_URI:$IMAGE_TAG,oci-mediatypes=true,compression=zstd,compression-level=3,force-compression=true,push=true \ .

Next steps

• Quickstart for Depot container builds
• Optimal Dockerfiles for Depot container build cache
• Local development with Depot container builds