Skip to content

Run a builder locally

Studio builds slices with its own generation in the cloud. You can run the same builder yourself, on a laptop, a build server or in Docker, and get the same statuses, commits and pull requests in Studio. A packaged builder is the Cratis CLI with a level and a target, so it is built on the same builder system as every builder you connect, and it speaks the same builder protocol.

A level says how much of the application the builder produces, and how. Each one matches an implementation mode Studio offers in the cloud, so a local builder covers the same range.

Level --level Studio mode What the builder does Calls a model
Screenplay screenplay Screenplay only Commits the Screenplay model to the project and writes no code. The model is the application, and Stage plays it. No
Code code Studio: static code Commits the model and renders it into code with the renderer of the target. The same model always gives the same code. No
Code and AI code-ai Studio: static code refined by AI Renders the model deterministically, then a coding agent implements the behavior the model describes on top of the generated code. Yes
AI ai Studio: AI only Commits the model and renders nothing. A coding agent implements the slices from the model, following the build kit’s conventions. Yes

A local builder chosen for an application replaces Studio’s own generation for that application.

At Code and AI and AI, the agent works from the same instructions Studio’s own AI modes use. They come with the build order, and the CLI lists them in the agent’s prompt under Instructions from the model:

  • What each slice is supposed to do. The description you wrote for the slice in the event model, in the order’s context.hints.
  • Described handlers and queries. The descriptions of command handlers and queries in the Screenplay documents.
  • Specifications. Each specification of the slice is an acceptance criterion, and the agent reports a result for it.
  • Feedback. The comments people left on the slice, in context.feedback.

At Code and AI the renderer has already written the structure: commands, events, read models, wiring and specifications. The agent leaves that code alone, except the places the renderer leaves open, and adds the behavior on top: method bodies, rules, validation, and new files where the behavior needs them. It does not invent behavior the model does not describe. Where the model leaves a decision open, the agent records it as an assumption, and Studio shows it with the slice. Then the checks run, and only work that passes them is committed.

The better a slice’s description and specifications, the better the result. Describe the rules in plain words, and add a specification for each case that matters.

Builder Builds Target Page
Cratis .NET on Cratis Arc and Chronicle, with a React frontend cratis The Cratis builder
Axon Java on Axon Framework axon The Axon builder

Both are one builder: the Cratis CLI, with the render target chosen by --target. Studio shows what each can build, so it offers the Axon builder backend slices only and the Cratis builder backend and screens.

Terminal window
cratis build connect --studio --organization acme # once per machine; a maintainer approves it
cratis build run --level code # Cratis, deterministic
cratis build run --level code-ai --agent claude --ai studio # Cratis, AI on top, calls through Studio
cratis build run --level ai --agent claude --ai studio # Cratis, AI only
cratis build run --level code-ai --target axon --agent claude # Axon, AI on top
cratis build run --level code --target axon # Axon
cratis build run --level code --docker # the same, in the packaged image

Then choose the builder under Settings > Building of the application, as described in Choose who builds. The CLI documentation lists every option.

--docker runs the same builder inside a packaged image, so a machine needs only Docker and the CLI. The project is mounted into the container, and the builder’s connection travels in the environment, so its token is never on a command line. Each packaged builder has an image on Docker Hub, built from the Cratis Grip repository, versioned with it and published with every Grip release:

Builder Image
Cratis cratis/builder
Axon cratis/studio-axon-builder
Terminal window
cratis build run --level code --docker # cratis/builder
cratis build run --level code --target axon --docker # cratis/studio-axon-builder

You don’t choose the image or its version. --docker picks the image for the target and uses its newest version, pulling it the first time. When Studio has released a newer one, the CLI tells you, and cratis update pulls it. To run another image, such as the Eventmodelers builder, name it with --image.

A container that runs a builder on its own, in a pipeline for example, takes the same four variables the CLI passes on: CRATIS_STUDIO_URL, CRATIS_STUDIO_ORGANIZATION, CRATIS_BUILDER_ID and CRATIS_BUILDER_TOKEN. Register the builder once with cratis build connect, have a maintainer approve it, and keep its token in the pipeline’s secret store.

An agent normally signs in on its own and calls its own provider. With --ai studio, every call goes to Studio instead, and Studio runs it on the organization’s AI providers:

  • Usage is tracked. Tokens count in the organization’s usage, per provider and model.
  • Pooling and limits apply. The agent and provider pool the organization chose decide which model answers.
  • No model credential on the machine.

The CLI starts a small server on the loopback address of the machine and points the agent at it, speaking the OpenAI and Anthropic APIs, with tool calls and streaming. Behind it, each call is one request of the AI gateway of the builder protocol, made under the slice’s lease. The gateway is part of protocol version 2, so every builder, whatever it is built with, uses it the same way. A builder you write calls it directly.

The organization needs an AI provider configured under Settings > AI. Without one, Studio refuses the call and says so, and the build fails with that reason rather than falling back to a credential on the machine.

Projects that already use the Eventmodelers BuildKit have a builder too. See The Eventmodelers builder.