Run the Cratis builder locally
Studio builds slices in the cloud with its own builder. The same builder runs on your machine. It is cratis build run with a level, and it talks to Studio the way every other builder does, so a slice built locally shows the same status, commits and pull requests in Studio as one built in the cloud.
The four levels
Section titled “The four levels”A level says how much of the application the builder produces, and how. Each one is an implementation mode Studio offers for an application in the cloud, so you can pick the same mode for a local builder.
| Level | --level |
Studio mode | What the builder does | Calls a model |
|---|---|---|---|---|
| Screenplay | screenplay |
Screenplay only | Commits the Screenplay model to the screenplay folder of the project and writes no code. The model is the application: run it with cratis run. |
No |
| Code | code |
Static code | Commits the model and renders it into code with the CLI’s renderer. The same model always gives the same code. | No |
| Code and AI | code-ai |
Static code refined by AI | Renders the model deterministically, then an agent implements the behavior the model describes on top of the generated structure. Needs --agent. |
Yes |
| AI | ai |
AI only | Commits the model and renders nothing: an agent implements the slices from the model, following the build kit’s conventions, permissions and verification commands. Needs --agent. |
Yes |
cratis build connect --studio --organization acme # once per machinecratis build run --level screenplaycratis build run --level codecratis build run --level code-ai --agent claude --ai studiocratis build run --level ai --agent copilotWhat the agent is told
Section titled “What the agent is told”At code-ai and ai the agent gets the same instructions Studio’s own AI modes use. The CLI spells them out at the end of the prompt, under Instructions from the model, and they are in the build order too:
- Slice descriptions. The summary of what each slice is supposed to do, from the order’s
context.hints. - Described handlers and queries. The command handler descriptions and query descriptions written in the Screenplay documents.
- Specifications. Every specification of the slices is an acceptance criterion the agent reports a result for.
- Feedback. The comments people left on the slices, from
context.feedback.
At code-ai the renderer has already produced the structure. The agent does not regenerate it and does not edit files with a managed header, except the places the renderer leaves open. It completes the bodies the renderer left (the Axon renderer lists them in UNSUPPORTED.md and runtime/UnsupportedImplementations.java) and adds code in new files, or files without a managed header, where the behavior needs it.
At ai no renderer runs. The agent writes the application from the model in the screenplay folder, following the kit’s instructions and the patterns already in the project.
At both levels the agent does not invent behavior the model does not describe. Where the model leaves a decision open, the agent records it as an assumption in the outcome, and Studio shows it with the slice. Then it runs the verification commands, and the CLI verifies again before it commits.
To try a level without Studio, build an exported order with cratis build once. It writes the outcome and commits the result, and pushes only with --push:
cratis build once --order order.json --level code-ai --agent copilotRun them in a clean clone of the application’s repository. The CLI still verifies with --verify commands, commits on the branch Studio names, pushes with your Git credentials and reports the outcome. Choose this builder for an application, or for one slice, under Settings > Building in Studio.
Render targets
Section titled “Render targets”--target says what the model is rendered into.
--target |
Result |
|---|---|
cratis (default) |
A .NET application on Cratis Arc and Chronicle, with a React frontend. Backend and user interface slices. |
axon |
A Java application on Axon Framework, from the Axon Stage renderer. Backend slices only. See Axon. |
At the ai level the target is not rendered: it says what the agent writes.
cratis build run --level code --target axoncratis build run --level code-ai --target axon --agent claudecratis build run --level ai --target axon --agent copilotThe builder tells Studio what it can build when it connects, so Studio offers it only the parts its target produces. It names itself by target and level, such as cratis-code-ai or axon-ai.
Run it in Docker
Section titled “Run it in Docker”cratis build run --level code --docker--docker runs the same cratis build run inside the packaged builder image instead of on your machine. Nothing but Docker and the CLI is needed on the host.
- The project is mounted at
/workspace. - The builder’s connection travels in the environment:
CRATIS_STUDIO_URL,CRATIS_STUDIO_ORGANIZATION,CRATIS_BUILDER_IDandCRATIS_BUILDER_TOKEN. Docker takes the token from the CLI’s own environment, so it is never on a command line or indocker ps. - Agent sign-ins that are set on your machine (
ANTHROPIC_API_KEY,CLAUDE_CODE_OAUTH_TOKEN,OPENAI_API_KEY,GEMINI_API_KEY,GITHUB_TOKEN,GH_TOKEN) are passed on. Your~/.gitconfigis mounted read-only. - The image follows the target:
cratis/builderforcratis, andcratis/studio-axon-builderforaxon(the Axon builder).--imagepicks another one, such ascratis/studio-eventmodelers-builder.
Inside a container there is no operating system credential store, so a container reads the connection from the environment. Outside Docker the same four variables work too, for a build server that has no CLI configuration:
export CRATIS_STUDIO_URL=https://studio.example.com CRATIS_STUDIO_ORGANIZATION=acmeexport CRATIS_BUILDER_ID=<id> CRATIS_BUILDER_TOKEN=<token>cratis build run --level codeWhich version runs
Section titled “Which version runs”The builder images are released with Studio, so their versions follow Studio’s, not the CLI’s. The CLI picks the version for you:
-
If a version of the image is already on your machine, the newest one is used.
-
If none is, the CLI asks Docker Hub for the newest version and pulls it, showing the progress. Without a network connection and with nothing pulled yet, the run stops and says so.
-
When Docker Hub has a newer version than the one on your machine, the CLI tells you after a command, the way it does for the Stage image:
↑ Builder image update available: cratis/builder 1.5.0 - run 'cratis update' -
cratis updatepulls the newest version of every builder image already on your machine.
The check is cached and only looks at images you have pulled, and CRATIS_NO_UPDATE_CHECK switches it off. An image with a tag, such as --image cratis/builder:1.4.0, runs exactly as given.
Use your own image
Section titled “Use your own image”Build an image on top of the packaged builder, give it a tag and pass it with --image. A tag tells the CLI to run the image as it is rather than look it up on Docker Hub:
cratis build run --level code --docker --image my-builder:1.0.0Make model calls through Studio
Section titled “Make model calls through Studio”An agent normally signs in on its own and calls its own provider. With --ai studio, every model call the agent makes goes to Studio instead, and Studio runs it on the AI providers the organization configured under Settings > AI.
cratis build run --level code-ai --agent claude --ai studioThat changes three things:
- Usage is counted in Studio. Tokens land in the organization’s usage, per provider and model, with the calls Studio makes itself.
- Pooling and limits apply. The organization’s provider pool, rate-limit handling and agent choices decide which model answers.
- No model credential on the machine. A builder on a build server or in a container needs none.
The CLI starts a small server on the loopback address of the machine, and points the agent at it with the environment variables agents read (ANTHROPIC_BASE_URL, OPENAI_BASE_URL and their keys). It speaks the OpenAI chat completions and Anthropic messages APIs, with tool calls and streaming, and forwards each call to Studio over the builder protocol. The address needs a random token only the agent is given, and a call is only accepted while a slice is being built, under that slice’s lease: a builder that loses its lease loses its access.
A generator started with --exec receives the same variables, plus STUDIO_AI_URL and STUDIO_AI_TOKEN, so a deterministic generator can ask a model for help without any model SDK or credential. See Write a generator.
--ai studio needs a Studio that speaks builder protocol version 2. The CLI says so and stops when the connection agreed an older version. --ai local is the default.