Remote builders

Remote builders run Docker on Modal VMs and push image layers directly to registry.composal.ai. Your workstation sends the build context and receives progress; it does not need to upload the finished image layers through a slow internet connection. Keep build contexts small with .dockerignore: source files still need to reach the remote builder.

Each organization manages its own named builders, capacity policy, regions, and persistent caches. Rebuilds reuse unchanged layers and retained BuildKit cache when the Dockerfile and inputs permit it. A cold cache or changed inputs still require work.

Availability

The Linux com 1.17.42 release includes these commands. Production accepts read-only builder list and settings requests, but remote builds are not yet available: the platform gateway has not been deployed or configured. The macOS CLI release is also pending. The examples below describe the tested workflow and will work after the gateway is enabled.

In an isolated test organization, native builds enforced organization capacity, pushed directly to the v2 registry, and reused cached layers after a VM replacement. A 650-second build also renewed its session at the normal ten-minute lifetime. These tests establish the implementation behavior, not production availability.

Build and push remotely

Sign in with com login. Setup creates a missing named builder for an organization administrator; members connect to an existing builder. Use an existing image repository in the same organization, and install Docker locally for its client commands.

com docker-builder setup main --org acme --context com-acme-main

On Unix, setup returns the context, implicit Buildx builder, and private local endpoint as JSON. A background supervisor keeps the connection available and wakes the builder when Docker first connects. Configure registry authentication and use the context:

The first Docker connection checks gateway health before waking a sleeping VM. If the gateway is unreachable, the build reports an error without starting remote compute; run setup again after the gateway is restored.

com docker setup --registry registry.composal.ai
docker --context com-acme-main build -t registry.composal.ai/acme/my-image:dev .
docker --context com-acme-main push registry.composal.ai/acme/my-image:dev

Replace acme, main, and my-image with your organization, builder, and image repository slugs. The push destination is registry.composal.ai/<org-slug>/<image-repository-slug>:<tag>. These commands leave your current Docker context unchanged. The built image stays on the remote builder; a local image requires an explicit export or pull.

Use Composal Hub for repository management and hosting for deployments that consume your published images. Configure the v2 hostname explicitly for this workflow; legacy registry defaults elsewhere are separate.

Manage organization builders

--org accepts an organization slug or public ID and overrides the checkout organization and configured default. Builder commands accept a builder slug; omitted builder names default to main.

com docker-builder list --org acme
com docker-builder create main --org acme
com docker-builder status main --org acme
com docker-builder wake main --org acme
com docker-builder sleep main --org acme
com docker-builder recover main --org acme
com docker-builder list --org acme --json

Members can list, inspect, wake, and connect to builders. Organization administrators create builders, request sleep, and change organization policy. Creating the same slug again reuses its builder and cache. Organizations can create multiple builders, each with its own cache.

Wake provisions asynchronously: status changes from sleeping to starting and then ready. Sleep refuses active operations, checkpoints the cache, and terminates compute while retaining the builder and cache. Status can show stopping during that process.

An organization administrator can use recover when a lost response leaves an operation occupying the builder. Recovery stops the VM's Docker daemon, checkpoints the cache, marks unfinished operations failed, and sleeps the VM. It interrupts any build still running. New work is refused while recovery is in progress, and the slot stays occupied if the provider cannot confirm the checkpoint. The next build wakes a replacement VM with the same cache identity.

Configure organization policy

Read settings without flags; updates change only the fields you supply. Policy is shared across the organization's builders.

com docker-builder settings --org acme
com docker-builder settings --org acme --max-concurrency 2 --idle-timeout-seconds 600
com docker-builder settings --org acme --runtime-timeout-seconds 3600 --region us-east

Idle timeout must be shorter than maximum VM lifetime. Builds and pushes count toward organization capacity. Each individual builder admits one operation at a time to protect its cache; raising the organization limit allows independent builders to work concurrently. A competing operation is refused when capacity is occupied. Builder regions are separate from the deployment regions listed in the hosting guide.

Cache and VM lifecycle

Each builder uses a named Modal Volume containing a filesystem image for Docker layers and BuildKit state. The Volume survives VM sleep and replacement. The implementation uses this filesystem image because mounting Docker's cache directly on a Modal Volume did not satisfy the tested storage requirements. CloudBucketMount is not used for the live Docker cache.

In one isolated test, a Dockerfile created a 20 MiB random layer inside Modal from a 1 MiB source payload. Two builds and two direct registry pushes sent about 1.1 MiB from the workstation through the gateway, while the published image contained about 25.7 MiB of compressed layers. The second build reused the cached layer after the VM slept and restarted. Actual transfer and speed depend on your build context, Dockerfile, cache hits, and network.

An idle builder sleeps automatically. Orderly sleep stops Docker, checkpoints storage, and confirms VM termination. The next wake reuses the retained cache. Cache identity stays attached to the builder rather than the workstation or individual user. Persistence improves incremental builds; it does not guarantee every rebuild is fast or every step can be cached.

Access and connections

Background setup uses a private Unix socket; foreground connect accepts loopback TCP or a socket in a private directory. Both use your existing Composal login. Your workstation needs no Modal credentials or daemon certificates. Short-lived builder sessions are scoped to your organization, actor, builder, and VM generation. The proxy renews sessions while connected, installing the replacement before revoking the previous session. Background connections using your saved login reread it for API requests and refuse credentials if the login now belongs to another API. Explicit token overrides remain in memory; disconnect and rerun setup to replace an override.

The platform gateway checks current organization access and capacity for native build operations. This connection supports native Docker builds with embedded BuildKit, pushes, and permitted inspection APIs. It is not a general-purpose remote container execution endpoint; Docker-container Buildx drivers that require container creation or execution are not supported through this gateway.

The foreground proxy must remain running while Docker uses its context; the default Unix setup supervises it in the background. Stopping it closes local connections and stops accepting new ones. It does not prove an admitted remote operation has stopped or immediately release its capacity slot.

Failures and recovery

If Modal confirms a VM has terminated unexpectedly, reconciliation fails stranded operations and retains the builder's cache identity for replacement. Previously committed cache survives; writes interrupted before persistence may be lost. An uncertain provider status keeps capacity occupied instead of assuming a build has finished.

A final build result from the remote daemon releases capacity, including a failed Dockerfile step. Socket closure, expired sessions, cancellation requests, and lost daemon responses do not by themselves establish remote completion. An organization administrator can use com docker-builder recover to checkpoint and stop a still-running VM before releasing abandoned work. Inspect builder status if capacity remains occupied; reconnecting does not erase an existing operation.

Docker context setup

com docker-builder setup creates a Docker context and its implicit Buildx builder with the embedded docker driver. A missing slug is created through the organization API, which requires administrator permission; public IDs must already exist. It checks that the platform gateway is configured before changing local context metadata. An existing context is updated only if it belongs to the same organization builder and API; use --context to choose another name when a name is already in use. Docker and its Buildx plugin must be installed locally.

Unix setup uses a private per-user socket with a stable path. Repeating setup reuses a healthy supervisor. A failed worker is restarted on the same endpoint; workers also stop if their supervisor exits. Run setup again after stopping the supervisor or restarting your machine. Interruptions do not replay an in-progress remote build.

com docker-builder disconnect main --org acme
com docker-builder setup main --org acme --context com-acme-main --foreground

disconnect stops your local background connection; it does not sleep the remote builder or prove a remote build has finished. Foreground setup must remain running in its terminal. Background setup is currently Unix-only; use --foreground on other platforms. For manual context management, use com docker-builder connect main --org acme --listen 127.0.0.1:23750 and create a Docker context pointing to that endpoint. wake alone does not configure Docker.

See the CLI reference for the broader command surface and the API reference for organization builder and session contracts.