Sign in

v4

latestOpenAPI 3.1.0Apache-2.0raw.githubusercontent.com2026-05-09283767.7 KB
builds

Build a snapshot from an image ref or Dockerfile

Submits an asynchronous build. The scheduler creates a build VM, runs buildah pull (image-only path) or buildah bud (Dockerfile path) inside it, snapshots the result, and tears the VM down.

At least one of imageRef or dockerfileContent must be provided. If dockerfileContent is set, the worker writes it verbatim into /tmp/buildctx/Dockerfile — buildah handles multi-stage, SHELL, RUN --mount, etc. natively.

For COPY instructions that need files, upload the build context first via POST /v1/build-contexts/presign and pass the returned download URL as contextDownloadUrl.

Response is 202 Accepted with a build ID; poll GET /v1/builds/{id} until status is completed or failed.

post/v1/builds

Request body

namestring

Optional human-readable name for the resulting snapshot. If omitted, the build ID is used.

imageRefstring

Docker image reference (e.g. python:3.13-slim, ghcr.io/user/repo:tag). Used directly on the no-Dockerfile path, and as a fallback FROM source otherwise.

dockerfileContentstring

Raw Dockerfile content to feed to buildah bud inside the build VM. Multi-stage, SHELL, RUN --mount, and every standard Dockerfile feature is supported (handled natively by buildah). Container-runtime metadata (CMD, ENTRYPOINT, EXPOSE, LABEL, HEALTHCHECK) is consumed by buildah but does not surface on the resulting FastVM snapshot — when the snapshot boots, systemd takes over, not the container's CMD.

machineTypestring

Machine size identifier (e.g. c1m2, c2m4). Controls CPU and memory allocation. Must be supplied on launch unless restoring from a snapshot.

diskGiBinteger

Disk size for the build VM. Defaults to 10 GiB if omitted.

contextDownloadUrlstring uri

Presigned GET URL for a tar.gz of the build context. The worker downloads and extracts this into /tmp/buildctx before invoking buildah, so COPY instructions resolve against the user's files. Obtain via POST /v1/build-contexts/presign.

Response

Build accepted; poll GET /v1/builds/{id} for status

idstring required

Build ID (UUID). Use this to poll status.

namestring
statusstring required

Current state. Known values: pending (accepted, not yet started), running (worker is executing), completed (snapshot is ready), failed (build did not produce a snapshot). Additional values may be introduced in future server versions; clients should treat unknown values as "in progress" rather than as hard errors.

snapshotIdstring

Set when status is completed. Fetch the corresponding Snapshot record via GET /v1/snapshots/{id}.

imageRefstring required
progressstring

Human-readable phase string while the build runs (e.g. creating build VM, buildah pull, buildah bud, applying image, settling VM, creating snapshot). Not present after a terminal status.

errorstring

Set when status is failed. Diagnostic from the worker (truncated to ~4 KiB).

createdAtstring date-time required