Depot Container Builds Depot runs Docker image builds on remote high-performance builders (16 CPU, 32 GB RAM, NVMe SSD cache). depot build is a drop-in replacement for docker build / docker buildx build . depot bake replaces docker buildx bake . Key Concepts Builds run remotely on ephemeral EC2 instances — images stay in remote cache by default Use --load to download to local Docker, --push to push to a registry, --save to store in Depot's ephemeral registry Cache is fully automatic on persistent NVMe SSDs — no manual cache config needed Multi-platform builds use native CPU builders (no QEMU emulation) for amd64 and arm64 simultaneously All team members on a project share the same layer cache depot build — Essential Patterns

Build remotely (image stays in remote cache)

depot build -t repo/image:tag .

Build + download to local Docker daemon

depot build -t repo/image:tag . --load

Build + push directly to registry (fast — doesn't route through local network)

depot build -t repo/image:tag . --push

Multi-platform build (native CPUs, no emulation)

depot build --platform linux/amd64,linux/arm64 -t repo/image:tag . --push

Save to Depot ephemeral registry (default 7-day retention)

depot build --save . depot build --save --save-tag my-tag .

Suppress provenance metadata (fixes "unknown/unknown" platform in registries)

depot build -t repo/image:tag --push --provenance = false .

Lint Dockerfile before building

depot build -t repo/image:tag . --lint

Build with secrets

depot build --secret id = mysecret,src = ./secret.txt -t repo/image:tag .

Build with SSH forwarding

depot build --ssh default -t repo/image:tag .

Specify a Depot project explicitly

depot build --project < project-id

-t repo/image:tag . Key Flags Flag Description --load Download image to local Docker daemon --push Push to registry --save Save to Depot ephemeral registry --save-tag Custom tag for Depot Registry --platform Target platforms ( linux/amd64 , linux/arm64 , or both) --build-platform Force build to run on specific arch ( dynamic default) --project Depot project ID --token Depot API token --lint Lint Dockerfile before build --provenance Control provenance attestation (set false to fix unknown/unknown) --no-cache Disable cache for this build -f / --file Path to Dockerfile -t / --tag Image name and tag --target Build specific stage --build-arg Set build-time variables --secret Expose secrets ( id=name[,src=path] ) --ssh Expose SSH agent --output / -o Custom output ( type=local,dest=path ) depot bake — Multi-Image Builds Drop-in replacement for docker buildx bake . Builds multiple images in parallel. depot bake

Default file lookup

depot bake -f docker-bake.hcl

Specific HCL file

depot bake -f docker-compose.yml --load

Build compose services + load locally

depot bake --save --save-tag myrepo/app:v1

Save to Depot Registry

depot bake --print

Print resolved config without building

Default file lookup order: compose.yaml → compose.yml → docker-compose.yml → docker-compose.yaml → docker-bake.json → docker-bake.override.json → docker-bake.hcl → docker-bake.override.hcl HCL Bake File Example variable "TAG" { default = "latest" } group "default" { targets = [ "app" , "worker" ] } target "app" { dockerfile = "Dockerfile" platforms = [ "linux/amd64" , "linux/arm64" ] tags = [ "myrepo/app: $ { TAG } " ] args = { NODE_VERSION = "20" } } target "worker" { dockerfile = "Dockerfile.worker" tags = [ "myrepo/worker: $ { TAG } " ] contexts = { app = "target:app" }

Share base between targets

} Override variables: TAG=v2.0 depot bake Docker Compose with Per-Service Project IDs services : api : build : dockerfile : ./Dockerfile.api x-depot : project-id : abc123 web : build : dockerfile : ./Dockerfile.web x-depot : project-id : def456 Docker Compose Integration

Preferred: build all services in parallel, then load

depot bake -f docker-compose.yml --load docker compose up

Alternative: zero code change (less efficient, each service = separate build)

depot configure-docker docker compose build Migration from Docker

docker build → depot build (same flags, one-line swap)

depot build -t my-image .

docker buildx bake → depot bake

depot bake -f docker-bake.hcl

Zero code change via Docker plugin

depot configure-docker docker build .

Routes through Depot (look for [depot] prefix in logs)

When migrating, remove these flags — Depot handles caching automatically: --cache-from type=gha — causes "services aren't available" errors --cache-to type=gha — same issue Any manual BuildKit cache configuration Common Mistakes Mistake Fix Using --cache-from type=gha or --cache-to type=gha Remove them. Depot caches automatically on NVMe SSDs. Multi-platform image shows unknown/unknown platform Add --provenance=false Expecting image locally after depot build Add --load to download, or --push to push to registry .git directory missing in build context Add --build-arg BUILDKIT_CONTEXT_KEEP_GIT_DIR=1 Build hangs or "failed to mount" errors Reset cache in project settings or via depot cache reset "401 Unauthorized" pulling base images Docker Hub rate limit — authenticate with docker login or use public.ecr.aws/docker/library/ mirror "Keep alive ping failed" / OOM Scale up builder size in project settings or enable autoscaling Builder Sizes Size CPUs RAM Per-Minute Plans Default 16 32 GB $0.004 All Large 32 64 GB $0.008 Startup+ Extra Large 64 128 GB $0.016 Startup+ Billed per-second. Bake counts as one build regardless of target count. Depot Registry

Save image to Depot Registry

depot build --save -t myapp .

Pull a saved image

depot pull --project < id

< build-id

Push saved image to another registry

depot push --project < id

-t registry/image:tag < build-id

Docker auth for Depot Registry

docker login registry.depot.dev -u x-token -p < depot-token

Registry URL: registry.depot.dev/:

Special Output Formats

estargz (lazy-pulling for faster container startup)

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

zstd compression (faster Fargate/K8s startup)

depot build --output type = image,name = repo/image:tag,oci-mediatypes = true,compression = zstd,compression-level = 3 ,force-compression = true,push = true .