Skip to content

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.

  • The address and your organization. Every request goes to https://<studio address>/builders/connect/<organization>. The hosted Studio is https://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.

Every request goes from the builder to Studio. Studio never calls the builder.

WHILE IT BUILDS POST /registrations · name, token POST /connect · protocol versions, manifest POST /work POST /work POST /work/{slice}/lease POST /work/{slice}/progress POST /work/{slice}/outcome POST /disconnect 201 · builder id and approval code 200 · agreed version, lease time (202 until approved) 204 · nothing yet, ask again 200 · the slice and its build order 200 · lease renewed 200 · settled 204 A maintainer approves the code THE BUILDER BUILDS A generator or a coding agent turns the order into code, runs the checks, commits and pushes ONCE Keeps its id and token EACH START Agrees a protocol version ONE OUTCOME Built, failed, nothing to do ANY LANGUAGE Your builder HTTPS AND JSON Studio
The whole conversation. Between asking for work and reporting the outcome, the builder builds.

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.

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/registrations
Content-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.q4W1v9n2Jx0a8yT6pL3sZ7bK5eR1uH9cM2dF4gN8wQ0
X-Studio-Builder-Credential: 8f0c6a8e-3f0b-4c39-9a3e-2b6f8e1d7c44.q4W1v9n2Jx0a8yT6pL3sZ7bK5eR1uH9cM2dF4gN8wQ0

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/connect
Content-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
POST /builders/connect/acme/work

Studio 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 Content means nothing yet. Ask again straight away.
  • 409 means the builder has not connected, or has said goodbye since. Go back to step 2.
  • 202, 401 and 403 mean the same as when connecting: go back to step 2, which handles them.
  • 200 OK means 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.

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/lease
Content-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.

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/progress
Content-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.

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.model and 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.context as 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, failed or notRun, 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.

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/outcome
Content-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.

When the builder stops, it says goodbye, and Studio shows it as offline:

POST /builders/connect/acme/disconnect

Studio 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.

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.