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.
The four levels
Section titled “The four levels”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.
The instructions the agent gets
Section titled “The instructions the agent gets”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.
The packaged builders
Section titled “The packaged builders”| 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.
Start one
Section titled “Start one”cratis build connect --studio --organization acme # once per machine; a maintainer approves itcratis build run --level code # Cratis, deterministiccratis build run --level code-ai --agent claude --ai studio # Cratis, AI on top, calls through Studiocratis build run --level ai --agent claude --ai studio # Cratis, AI onlycratis build run --level code-ai --target axon --agent claude # Axon, AI on topcratis build run --level code --target axon # Axoncratis build run --level code --docker # the same, in the packaged imageThen choose the builder under Settings > Building of the application, as described in Choose who builds. The CLI documentation lists every option.
Run it in Docker
Section titled “Run it in Docker”--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 |
cratis build run --level code --docker # cratis/buildercratis build run --level code --target axon --docker # cratis/studio-axon-builderYou 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.
Model calls through Studio
Section titled “Model calls through Studio”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.
The Eventmodelers builder
Section titled “The Eventmodelers builder”Projects that already use the Eventmodelers BuildKit have a builder too. See The Eventmodelers builder.