Builds quickstart

Sylphx Build runs on its own. A project and a key are enough: you need no Hosting service, no connected repository and no deploy. A build runs one command, or builds one image, on a build machine that is leased for it and wiped afterwards. It returns the command's exit code, its log and, for an image, the image digest.

#1. Run a command as a build

--no-tree runs the command on the Build service with no input files. The build is recorded, its output streams back as the command runs, and the CLI exits with the command's own exit code:

sylphx build run --no-tree -- uname -a

--no-wait creates the build, prints its name and exits. You can read the output later:

sylphx build run --no-tree --no-wait -- sh -c 'echo hello; sleep 30; echo done'
sylphx build logs $BUILD_ID --follow

The same build over HTTP is one call to builds:run. It answers with an Operation whose target is the build:

sylphx api POST /v1/orgs/$ORG/projects/$PROJECT/builds:run \
-d '{"command":["uname","-a"],"size":"standard","timeout":"600s"}'

POST /v1/orgs/$ORG/projects/$PROJECT/builds with spec.command is the long form of the same call.

#2. Run a command over your work tree

Without --no-tree, sylphx build run copies the enclosing git work tree to a warm workspace on a build machine. It sends only the files that differ from the workspace, runs the command in the current directory there, and streams the output back:

sylphx build run -- cargo test
sylphx build run --artifact 'dist/**' -- bun run build

target/, package caches and toolchains stay warm on the workspace between runs, and the project's build cache is shared by every run. --artifact copies matching files back to .sylphx/out/<run>/.

#3. Build an image

sylphx build image builds an OCI image from the work tree, with an SBOM and signed provenance. It uses the Dockerfile if one is present and the zero-config frontend otherwise:

sylphx build image
sylphx build image --push registry.example.com/acme/shop:dev --registry-auth ~/.docker/config.json

The digest is printed when the build ends. With -o json the image metadata is the image field of the final result event.

#4. Read the build back

sylphx api GET /v1/orgs/$ORG/projects/$PROJECT/builds
sylphx api GET /v1/orgs/$ORG/projects/$PROJECT/builds/$BUILD_ID

The list is newest first.

GET .../builds/$BUILD_ID:readLogs?wait=20s returns a page of log lines. Pass each next_page_token back to follow a running build. POST .../builds/$BUILD_ID:cancel stops a queued or running build, and nothing is published. A build cannot change once it has ended.

#Builds under a deploy

A Hosting deploy also builds through Sylphx Build. Those builds are read on the management API, with GET /v1/builds?projectId=$PROJECT_ID and GET /v1/deployments/builds/{id}. The Hosting docs cover them.

#Next