Talk to Studio directly
The simple way to build slices is the Cratis CLI with a generator or a coding agent of your own: see Build a builder. The CLI holds the whole conversation with Studio for you.
This section is for the cases where that does not fit: a machine that cannot run the CLI, or a team that wants its builder inside a host of its own. A builder that talks to Studio directly is any program that can make HTTPS requests and read and write JSON. It needs no SDK, no Cratis package and no inbound port, and it can be written in any language.
The Cratis CLI is open source, so its source on GitHub is a complete, working implementation of everything on this page. Read it beside this walkthrough when you write your own.
Before you start
Section titled “Before you start”- The address and your organization. Every request goes to
https://<studio address>/builders/connect/<organization>. The hosted Studio ishttps://app.cratis.studio. The Connect a builder panel under Settings > Building shows the full address for your organization. - A maintainer to approve the builder. A new builder builds nothing until a maintainer of the organization approves it. See Connect a builder and approve it.
- A clone of the application’s repository that the builder may commit to, with Git credentials of its own if it pushes. Studio never hands a builder a repository credential.
- An application that uses the builder. Once the builder is approved, choose it for an application or a slice. See Choose who builds.
The conversation
Section titled “The conversation”Every request goes from the builder to Studio. Studio never calls the builder.
The steps below show each exchange with a trimmed body. The builder protocol is the full reference, with every status code. Every request and answer is JSON, with camelCase members and enum values.
1. Register once
Section titled “1. Register once”The builder creates its own secret token first: 32 random bytes, written in URL-safe base64, is enough. It then registers with its name, the machine it runs on, and the token.
POST /builders/connect/acme/registrationsContent-Type: application/json
{ "name": "Build server", "machine": "ci-01", "token": "q4W1v9n2Jx0a8yT6pL3sZ7bK5eR1uH9cM2dF4gN8wQ0" }HTTP/1.1 201 Created
{ "builderId": "8f0c6a8e-3f0b-4c39-9a3e-2b6f8e1d7c44", "code": "K7QF-2M9D", "expires": "2026-11-09T12:15:00+00:00" }Keep the builderId and the token somewhere only the builder can read, so a restart reuses them. Studio keeps only a hash of the token and cannot give it back, so a builder that loses its token registers again.
Show the code on the builder’s machine. A maintainer types it in Studio to approve the builder, within 15 minutes. The code proves that the builder in Studio’s list is the one you started.
From now on, every request carries the builder’s credential, <builderId>.<token>, twice:
Authorization: Bearer 8f0c6a8e-3f0b-4c39-9a3e-2b6f8e1d7c44.q4W1v9n2Jx0a8yT6pL3sZ7bK5eR1uH9cM2dF4gN8wQ0X-Studio-Builder-Credential: 8f0c6a8e-3f0b-4c39-9a3e-2b6f8e1d7c44.q4W1v9n2Jx0a8yT6pL3sZ7bK5eR1uH9cM2dF4gN8wQ02. Connect, and wait for approval
Section titled “2. Connect, and wait for approval”Each time the builder starts, it connects. It names the protocol versions it speaks and a manifest of what it can build.
POST /builders/connect/acme/connectContent-Type: application/json
{ "protocolVersions": [1, 2], "manifest": { "stacks": ["dotnet"], "parts": ["backend", "ui"], "sliceTypes": [], "screenplayVersions": ["1"], "contractVersions": ["1", "2", "3"], "kit": "my-kit", "gitHandling": ["studioManaged", "builderManaged"] }}Studio offers a builder only the slices its manifest covers. An empty sliceTypes means every slice type. contractVersions says which versions of build orders and outcomes the builder reads; only a builder that reads version 3 gets removal orders.
| Answer | What the builder does |
|---|---|
200 with protocolVersion, waitSeconds and leaseSeconds |
It is connected. Keep the two numbers for the next steps |
202 with code |
A maintainer has not approved it yet. Keep showing the code and connect again in a few seconds |
403 |
The registration was declined or expired. Forget the credential and register again |
401 |
Studio does not know the builder, or a maintainer removed it. Stop, and tell the owner |
409 |
There is no protocol version both sides speak. The reason says which side to upgrade |
422 |
The manifest cannot be read. problems says why |
3. Ask for work
Section titled “3. Ask for work”POST /builders/connect/acme/workStudio holds the request open for up to waitSeconds, 20 by default, while it looks for a slice that is this builder’s to build. So give the request a timeout longer than that.
204 No Contentmeans nothing yet. Ask again straight away.409means the builder has not connected, or has said goodbye since. Go back to step 2.202,401and403mean the same as when connecting: go back to step 2, which handles them.200 OKmeans the builder now holds a slice:
{ "sliceId": "0b9c7f4e-2a51-4f6d-8e3a-6c1d5b7a9e20", "leaseExpires": "2026-11-09T12:02:00+00:00", "git": { "gitHandling": "studioManaged", "branch": "studio/invoicing/pay-invoice", "commitMessage": "Build PayInvoice (backend)", "pullRequests": "perSlice" }, "order": { "contractVersion": "3", "orderId": "6f0c3d5e-2b1a-4f7e-9a51-0d2c8e4b7a10", "part": "backend", "...": "..." }}order is the build order: the slices to build, the Screenplay model they live in, their specifications as acceptance criteria, each slice’s description of what it is supposed to do as hints, and feedback from people. order.part says whether to build the backend, the ui, or, for a removal order, to remove what was built for slices that were deleted. git says who does the repository work.
4. Renew the lease while you build
Section titled “4. Renew the lease while you build”The slice is held for the builder for leaseSeconds, 120 by default. Renew the lease on a timer, about every third of that, until you report the outcome:
POST /builders/connect/acme/work/0b9c7f4e-2a51-4f6d-8e3a-6c1d5b7a9e20/leaseContent-Type: application/json
{ "orderId": "6f0c3d5e-2b1a-4f7e-9a51-0d2c8e4b7a10" }200 returns the new leaseExpires. 410 Gone means the lease is lost: it ran out, the build passed its deadline, someone cancelled it, or another builder holds the slice. Stop, throw the work away, and do not report an outcome.
5. Report progress
Section titled “5. Report progress”With contract version 2 or later, the builder can tell people what it is doing. Studio shows the step and the log on the slice while it builds.
POST /builders/connect/acme/work/0b9c7f4e-2a51-4f6d-8e3a-6c1d5b7a9e20/progressContent-Type: application/json
{ "contractVersion": "3", "orderId": "6f0c3d5e-2b1a-4f7e-9a51-0d2c8e4b7a10", "step": "Running the specifications", "log": [{ "occurred": "2026-11-09T12:01:10Z", "level": "information", "text": "dotnet test" }]}A progress report does not renew the lease, so keep the timer running. Never put a credential in a step or a log line. See Reporting progress.
6. Build
Section titled “6. Build”This is the part that is yours. Studio does not care how the builder turns the order into code:
- Call a generator. Read the Screenplay documents in
order.modeland render code from them with templates or your own generator. - Hand the order to a coding agent. Give it the model, the specifications as acceptance criteria, and the hints and feedback in
order.contextas its instructions, and let it write the code. The hints are the slices’ descriptions, the summary of what each is supposed to do. - Run your checks. Build the code and run its tests. Report each specification as
passed,failedornotRun, and list the assumptions you made where the model was silent. People review them on the slice.
Then do the repository work that git asks for:
git.gitHandling |
The builder |
|---|---|
studioManaged |
Commits on git.branch with git.commitMessage and pushes the branch. Studio opens the pull request |
builderManaged |
Chooses the branch and the commit message itself, and may open a pull request of its own |
See Git handling for what each choice requires of the outcome.
7. Report the outcome
Section titled “7. Report the outcome”Report exactly one outcome for the order. It repeats the order’s contractVersion and orderId.
POST /builders/connect/acme/work/0b9c7f4e-2a51-4f6d-8e3a-6c1d5b7a9e20/outcomeContent-Type: application/json
{ "contractVersion": "3", "orderId": "6f0c3d5e-2b1a-4f7e-9a51-0d2c8e4b7a10", "kind": "built", "commit": "4f2c9e1", "branch": "studio/invoicing/pay-invoice", "files": ["Source/Billing/Invoicing/PayInvoice/PayInvoice.cs"], "specifications": [{ "id": "8e1f2a3b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", "result": "passed" }], "assumptions": ["An invoice that is already paid is refused"]}kind |
When | Also carries |
|---|---|---|
built |
The code is built and committed | at least one of commit, branch and pullRequest, plus files, specifications and assumptions |
nothingToDo |
Nothing needed to change, or a removal found the code already gone | nothing more |
failed |
The attempt went wrong | error, and retryable: whether trying again can help |
blocked |
The model leaves a question only a person can answer | reason and questions |
A removal order is answered the same way: built with the commit that removed the code, or nothingToDo when there was nothing left to remove.
Studio answers 200 with the status it settled the build on. 400 with problems means the outcome does not follow the schema; that is a bug in the builder, so report a failed outcome instead of pretending it worked. 409 means the lease is lost, or the outcome does not fit the repository handling; reason says which.
Then go back to step 3 and ask for the next slice.
8. Disconnect
Section titled “8. Disconnect”When the builder stops, it says goodbye, and Studio shows it as offline:
POST /builders/connect/acme/disconnectStudio answers 204. A builder that stops without saying goodbye is shown as offline once Studio has not heard from it for three minutes. A slice it holds is offered again when its lease runs out.
Start from the reference implementation
Section titled “Start from the reference implementation”The cratis build command of the Cratis CLI is a complete builder with this whole conversation: it registers and keeps its credential in the operating system’s credential store, waits for approval, connects, asks for work, renews its lease on a timer, reports the outcome and disconnects. Its source is at github.com/Cratis/cli, and the CLI’s build reference describes what it does.
Related
Section titled “Related”- The builder protocol: every request, answer and status code.
- Build orders and outcomes: the documents a builder reads and writes, with their JSON schemas.
- The build loop: how Studio offers slices, holds leases, retries and settles them.
- Build a builder: the simple path, where the Cratis CLI holds this conversation for you.
- Use the reference builder: the Cratis CLI’s builder, with its kits and options.