Skip to content

The Cratis builder

The Cratis builder renders an application’s Screenplay model into a .NET application on Cratis Arc and Chronicle, with a React frontend on Cratis Components. It is cratis build run with a level, and the renderer is the one cratis render uses, so the code it commits is what you get by rendering the model yourself.

  • The Cratis CLI, signed in to Studio with cratis build connect --studio --organization <name>, and the builder approved by a maintainer. See Connect a builder and approve it.
  • A clean clone of the application’s repository, with Git credentials that can push to it.
  • For the Code and AI and AI levels, a coding agent, and an AI provider configured in Studio under Settings > AI if its calls go through Studio.
  • Without --docker: the .NET 11 SDK and Node.js on the machine. With it, only Docker.
Terminal window
cratis build run --level screenplay
cratis build run --level code
cratis build run --level code-ai --agent claude --ai studio
cratis build run --level ai --agent claude --ai studio

For every slice Studio hands it, the builder:

  1. Writes the model. The Screenplay documents of the order go to the screenplay folder of the project, so the model is committed beside the code it produced.
  2. Renders at the Code and Code and AI levels: the model becomes the application’s backend and, with the Cratis target, its frontend, in the project. A model the renderer refuses fails the build with the renderer’s reason, and is not retried.
  3. Adds the AI layer at the Code and AI level: the agent implements what the slices’ descriptions, the described handlers and queries, the specifications and the feedback ask for, on top of the rendered code. It completes the bodies the renderer left and adds files where the behavior needs them. At the AI level nothing is rendered, and the agent writes the slices from the model and the same instructions. Either way it runs with the build kit’s permissions and never commits. See The instructions the agent gets.
  4. Verifies with the --verify commands and the kit’s, such as dotnet build and dotnet test. A failing command makes the outcome failed, whatever the agent said.
  5. Commits and pushes on the branch Studio names, and reports the outcome, with the commit and branch.

A re-render never overwrites a generated file someone edited: it refuses, and says which file. Complete what the renderer leaves for you in the places it leaves them, not by editing what it owns.

  1. In Studio, open the application, then Settings > Building.
  2. Set Builder to the machine you connected.
  3. Mark a slice Ready for implementation. Studio offers it to the builder, and the builder claims it.

You can also choose the builder for the backend or the screens separately, or for one slice. See Choose who builds.

Terminal window
cratis build run --level code --docker

The image is cratis/builder on Docker Hub. It holds the .NET SDK, Node.js, Git, a JDK and Maven, and the latest Cratis CLI. It is built from the Cratis Grip repository, versioned with it and published with every Grip release. The CLI uses the newest version, tells you when a newer one is out, and cratis update pulls it. See Run a builder locally for what is passed in.

--ai studio makes the agent’s model calls on the organization’s providers, counted in Studio’s usage. See Model calls through Studio.