Skip to content
Console
On this page

Builds

What a build reads, what it runs, and what it leaves behind.

What is served today

Command builds are served at api.sylphx.com: builds:run, CreateBuild with spec.command, get, list, cancel and :readLogs, with only an organization, a project and a key. The Builds quickstart shows them. Image builds run from the CLI (sylphx build image); builds:buildImage and builds from a commit (spec.source) are not served yet. Builds started by a Hosting deploy are read on the management API with GET /v1/builds.

A Build runs one command or builds one image over a commit or an uploaded tree. A command produces an exit code and named artifacts; an image build produces an OCI image, an SBOM, and signed provenance. A Build is immutable once created: it is never edited, only read. It ends with its output or a typed failure.

Every Hosting deploy builds through Sylphx Build today: the image a Service runs comes from a build of an exact commit, and that build is a record you can read back.

What you name, and what the build decides

Choose one input (source or tree) and one output (image or command). These are two separate oneof groups in BuildSpec, not four required fields. The contract fields are listed below; the served-today note above describes which calls are available now.

FieldTypeWhat it is
sourceBuildSourceAn exact commit. Select this or tree as the input.
treeBuildTreeAn uploaded tree identified by its required root_digest, formatted as <sha256 hex>/<size in bytes>. Select this or source as the input.
imageImageTargetAn OCI image with an SBOM and signed provenance. Select this or command as the output.
commandCommandTargetA required argv list of the program and its arguments, plus optional artifacts globs relative to the input root. Select this or image as the output.
sizeBuildSizeThe machine size; defaults to [build] size, otherwise STANDARD.
timeoutDurationThe time limit; defaults to one hour, at most six hours.
allow_hostsstring[]Internet hosts the build may reach; defaults to [build] allow_hosts. Empty means in-cell mirrors and store only.
cachestringThe BuildCache to read and write; the project’s default cache by default.

When you select source, its first two fields are required:

FieldTypeWhat it is
source_linkstringrequiredThe Hosting SourceLink naming the repository and its Connection. Required.
commitstringrequiredThe full commit SHA to build. Required.
root_directorystringThe directory inside the repository to build; the root by default.

When you select image, the image settings are nested under spec.image, not top-level BuildSpec fields:

FieldTypeWhat it is
servicestringThe sylphx.toml service whose dockerfile and context apply; unset uses the fields below or detects the stack.
dockerfilestringA Dockerfile path relative to the input root; unset lets the zero-config frontend detect the stack.
targetstringThe Dockerfile stage to build.
build_argsmap<string, string>Build arguments. Secret values bind through [build.secrets], never here.

A Dockerfile is optional. Unset, the zero-config frontend detects the stack, which is why a repository builds without one and can add one later.

Names are paths

A build lives in a project, whether its input is a commit or an uploaded tree:

Build
orgs/{org}/projects/{project}/builds/{build}
Build id
bld_<cell><ulid>
Build cache
orgs/{org}/projects/{project}/build_caches/{build_cache}
Cache id
bch_<cell><ulid>

An id is never reused. build:read covers reading a build and its caches; creating or cancelling builds and clearing caches needs build:run.