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.
| Field | Type | What it is |
|---|---|---|
source | BuildSource | An exact commit. Select this or tree as the input. |
tree | BuildTree | An uploaded tree identified by its required root_digest, formatted as <sha256 hex>/<size in bytes>. Select this or source as the input. |
image | ImageTarget | An OCI image with an SBOM and signed provenance. Select this or command as the output. |
command | CommandTarget | A 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. |
size | BuildSize | The machine size; defaults to [build] size, otherwise STANDARD. |
timeout | Duration | The time limit; defaults to one hour, at most six hours. |
allow_hosts | string[] | Internet hosts the build may reach; defaults to [build] allow_hosts. Empty means in-cell mirrors and store only. |
cache | string | The BuildCache to read and write; the project’s default cache by default. |
When you select source, its first two fields are required:
| Field | Type | What it is |
|---|---|---|
source_link | stringrequired | The Hosting SourceLink naming the repository and its Connection. Required. |
commit | stringrequired | The full commit SHA to build. Required. |
root_directory | string | The 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:
| Field | Type | What it is |
|---|---|---|
service | string | The sylphx.toml service whose dockerfile and context apply; unset uses the fields below or detects the stack. |
dockerfile | string | A Dockerfile path relative to the input root; unset lets the zero-config frontend detect the stack. |
target | string | The Dockerfile stage to build. |
build_args | map<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.