Skip to content

Connect a builder and approve it

A builder connects from the machine that should build, and builds nothing until a maintainer of the organization approves it with a short code. Connect one when you want slices built on your own machine or build server, on another stack, or with your own coding agent.

YOUR MACHINE STUDIO registers a maintainer types the code for the application, its backend or screens, or a single slice RUN build connect SHOWS A CODE K7QF-2M9D WAITING FOR Approval MAINTAINER Approve BUILDER IS Online CHOOSE WHO Builds
From the connect command to a builder you can choose. Only the approval needs a maintainer.
  • Approving a builder needs a maintainer of the organization. Anyone who can change the application can choose among the builders that are approved. A member who is not a maintainer sees Only organization maintainers can see and approve builders. Connect yours, then ask a maintainer to approve it.
  • The machine must reach Studio over HTTPS. Builders only dial out, so it needs no inbound port.
  • Until you choose another builder, an application builds with Studio’s own generation. Connecting a builder changes nothing by itself.
  1. Open the application, then Settings > Building. Under Connected builders, the Connect a builder panel shows the command for your organization. A maintainer finds the same panel in Organization settings > Builders. It looks like this:

    Terminal window
    cratis build connect --studio --organization <organization>

    --studio alone means the hosted Studio. On another Studio the command names its address: --studio https://<studio host>.

  2. Select Copy, and run the command on the machine that should build. The Cratis CLI is the builder: it runs your coding agent or your own generator. A builder you wrote against the builder protocol registers at the same address, which the panel also shows.

  3. The builder creates its own credential, registers, and shows a short code such as K7QF-2M9D on its own machine. In Studio it appears in the list as Waiting for approval, with the address and machine it asked from.

  1. Open Organization settings > Builders and find the builder marked Waiting for approval.

  2. Select Approve. In Approve this builder?, enter the code the builder showed in Code, and approve it. The code is good for 15 minutes. After that the builder registers again for a new one.

The Builders page in the organization settings, with the Connect a builder instructions and the address builders register at
Organization settings, Builders. Approve a builder with the code it shows on its own machine.

The builder is now listed as Online while it is running, and Offline when it is not. Beside it you see what it Builds (its stacks, slice types and kit), the protocol version it speaks, when it was last seen, and what it is doing: Idle, building a slice, or removing what it built for one.

Status What it means
Waiting for approval Registered, with a code, and not approved yet
Online Approved and running. It takes work as soon as it asks for it
Offline Approved, but not running right now. It can still be chosen, and its slices wait for it
Registration expired The code was not approved within 15 minutes. Run the command again for a new one
Declined A maintainer declined it. Register again to ask once more
Not connected yet The builder has not connected to Studio yet

A builder that speaks an older protocol is marked This builder speaks an older protocol. Upgrade it. It needs upgrading before it can take work.

Approving does not change who builds. Next, choose who builds for the application or for a slice.