Cratis Stage: run models and plan application source

Cratis Stage performs a Cratis Screenplay .play model as an application sandbox, so you can try its commands and queries before implementing the application. Start a session, submit a command, and inspect the resulting state and recorded events in Cratis Chronicle. Stage executes a supported subset of Screenplay; it is not a production host. Rendering application source and running modeled specifications are separate paths.

Stage executes the admitted model directly; you do not need to generate and build an application first.

A sandbox, not a production runtime

Use Stage for temporary model exploration. Its bundled Chronicle kernel uses in-memory storage with authentication disabled; replacing the container loses session state. Compilation does not mean every construct can execute. Check admission and keep the session private on loopback. A sandbox session or model check does not establish that a rendered application works.

Start here

Have the Cratis CLI installed, Docker running, and a complete Screenplay model in ./screenplays. The CLI selects its compatible Stage image; first use may need to pull it. This short path is for a model without declared authentication; see the CLI run reference for authenticated models.

1. Author a Screenplay model with commands, event productions, read models, projections, and queries. A read model is a view built from events; its projection describes how those events update the view. Include the concepts and policies the model references, since introductory excerpts alone are not a complete application. Screens are optional: Stage can compose a default UI.

2. Run the model folder:

   cratis run ./screenplays

   Stage compiles the source and reports readiness or refusals. The CLI mounts the model read-only and binds the standalone API and Workbench to loopback by default; do not add --allow-remote.

3. Open the application and the interactive API reference, Scalar. Check status and admission for behavior Stage cannot execute. Then submit a supported command using its model-specific schema. Query the corresponding read model or view its screen to see the resulting state.

Continue with Start a disposable session for the Docker alternative, command-to-state checks, and event inspection.

What you get

The session exposes mapped commands, queries, and validation endpoints through HTTP, with OpenAPI and Scalar for discovering their schemas. Unsupported behavior can return a refusal or HTTP 501, so a responding host alone is not proof that an operation works.

For the UI, Stage uses authored Scene screens or composes default per-slice screens from admitted commands and read models. These let you try the model; they are not a finished custom product interface. Accepted commands produce facts in the bundled Chronicle event log. Projections and queries expose the sandbox’s in-process read state, while Workbench lets you inspect events, not semantic projection views.

To check authored expectations, request a separate specification run and inspect each outcome. Startup does not run a passing suite, and unsupported specifications are not passes.

Choose your next step

Run and inspect the model, check specifications, or plan reviewable application source. Each path admits its own supported constructs.

Run your Screenplay

Start a private session, use the application, and inspect state and events.

Check model behavior

Run specifications separately and read their outcomes.

Plan application source

Inspect a render plan before publishing files.

Author the model

Describe commands, facts, views, and queries in Screenplay.

Why use Stage

Use a sandbox session to check how a modeled command changes the state a query returns. When you want to implement the application, Stage’s renderer turns supported declarations into concrete commands, event mappings, queries, and project files for a specific Cratis target.

You can review the output before writing it. Semantic planning returns normalized paths, exact bytes, SHA-256 hashes, and typed diagnostics in memory; publishing is a separate operation. The Cratis.Stage.Rendering.Cratis package owns dependency pins, scaffold inputs, and renderer identity, so callers choose project and namespace names without reconstructing a profile.

Choose application, module, feature, or slice scope for the work at hand. Common artifacts have the same bytes when their inputs match across scopes. Unsupported reachable semantics block publication by default; explicit refusal modes have narrower guarantees.

Stage does not require Studio: .play files are its input. Cratis Studio is an optional paid collaborative design workspace built on Chronicle, open for sign-up with a 14-day free trial and per-seat pricing. Studio’s Play uses Stage. Arc and Chronicle can also be used without the model-first layer.

What works today

Renderer

Rendering produces source you own, rather than starting the sandbox. Use CratisRendering.Plan when your caller already has an executable semantic model and an admitted execution plan. This C# excerpt assumes those existing semanticModel and executionPlan values; it is not a standalone program:

Plan artifacts from an admitted model

using Cratis.Stage.Contracts.Rendering;
using Cratis.Stage.Rendering.Cratis;

var options = new CratisRenderingOptions("Projects", "Projects");
var scope = new ArtifactRenderScope(
    ArtifactRenderScopeKind.Application, semanticModel.Application.Id);
var plan = CratisRendering.Plan(semanticModel, executionPlan, scope, options);

if (!plan.Success)
{
    foreach (var diagnostic in plan.Diagnostics)
    {
        Console.Error.WriteLine($"{diagnostic.Code}: {diagnostic.Message}");
    }
}

Plan creates the package-owned profile; no target version or template bytes need to be invented by the caller. Inspect diagnostics and require plan.Success before considering publication. The plan does not write your files. For loading .play source and checking a destination before writing, continue with Plan artifacts from Screenplay sources.

Lower-level callers can use CratisRendering.CreateProfile(...) with ArtifactRenderRequest; a reconstructed or modified profile is not interchangeable. See renderer compatibility for profile admission and legacy syntax-renderer contracts, and rendering reference for current semantic capabilities.

Runtime host

The cratis/stage container starts Arc, an in-memory Chronicle kernel, OpenAPI/Scalar, and the admitted model API. The semantic engine is the default. It evaluates supported behavior and refuses unsupported constructs rather than silently dropping them. See semantic execution for admission and operational limits. The legacy eventmodel engine is deprecated and scheduled for removal in Stage v6.

Specification runner

cratis/stage-specrunner compiles the model, checks its declared specifications, writes results.json, and exits. Choose --engine semantic for behavioral model checks; the deprecated default structural engine checks model consistency. Semantic reports use stage-spec-run/1, not the legacy structural schema. Read each reported outcome: a completed run can exit 0 even when specifications fail or are unsupported.

Curtain up

For the full model-to-application flow, follow Start a disposable session. You need an existing Screenplay model before starting the container; an empty mounted folder exits before startup. The Cratis CLI also wraps the container in cratis run.

Packages and containers

What	Image / package	Purpose
The Stage host	cratis/stage	Disposable semantic runtime with Arc, Chronicle, and the admitted model API.
The specification runner	cratis/stage-specrunner	Run-to-completion model-level specification verification.
The renderer	Cratis.Stage.Rendering.Cratis	Semantic artifact planning plus the syntax-based compatibility renderer.
The contracts	Cratis.Stage.Contracts	Internal/tooling seams and specification results.

Where to go next

• Customize a rendered application — add services, dependencies, and frontend styling from unmanaged files.
• Build a renderer target — implement a deterministic Screenplay-to-code target with Stage’s planning contracts.
• URLs of a running Stage — look up runtime endpoints and their current behavior.
• Scene UI render plans — inspect resolution for each ui profile and its diagnostics.