Menu
Platform
AI
App store purchases
Credits
Database
Flags
Generated Assets
Monitoring
Notifications
Organizations
Payments
- Payments
- Payments quickstart
- Checkout policies
- Checkout sessions
- Customer subscriptions
- Entitlement grants
- Exchange rates
- Licence keys
- Licence tokens
- Merchant accounts
- Portal sessions
- Price catalogs
- Revenue
- Revenue facts
- Revenue sources
- Tax threshold statuses
- Usage events
- Usage invoices
- Usage meter prices
- Usage meters
- Usage reservations
- Usage settings
- Usage tiers
Sandboxes
Webhooks
Getting Started
Authentication
KV Store
Deploy & Infrastructure
Reference
Builds
What a build turns one commit into, 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 turns one commit into an image, an SBOM, and signed provenance. It is immutable once created: it is never edited, only read. A build ends one of two ways — with the digests of what it produced, or with a typed failure that says why it produced nothing.
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
The only required part of a build is its source: a commit, read exactly.
| Field | Type | What it is |
|---|---|---|
source | BuildSourcerequired | The exact source. Required. |
dockerfile | string | A Dockerfile path relative to the root directory; unset lets the zero-config frontend detect the stack. |
target | string | The Dockerfile stage to build. |
build_class | string | The class, sylphx-<os>-<size>; the default is sylphx-linux-standard. |
build_args | map | Build arguments. Secret values bind through Kernel Secrets, never here. |
cache | string | The BuildCache to read and write; the project’s default cache by default. |
The source is three fields of its own, and the first two 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. |
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 without changing the call.
#Names are paths
A build lives in the project whose repository it builds:
- 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;
everything that changes one needs build:write.