4.5 Running

Run deploys an environment descriptor to a karpfen runtime and starts it. The IDE runs the runtime in a Docker container of its own and shows the run in the Runtime tool window: the model as it changes, the events, the active states and the log of the runtime. What the runtime does with a model is the subject of 3 Execution.

4.5.1 The runtime container#

A model runs in the IDE's own Docker container and nowhere else. Docker Desktop or another local Docker engine must be running.

  • Each open folder gets its own container. It listens on 127.0.0.1 only, on a free port.
  • The first run builds the runtime image from the runtime that comes with the IDE. This takes a few minutes once.
  • The image holds Python 3 with numpy, scipy, sympy, pandas, regex, python-dateutil and chardet for the EVAL blocks.
  • The container starts with the first run and keeps running after the run stops, so the next run starts fast.
  • Closing the folder or the IDE stops and removes the container. The image stays.

Run > Start Runtime starts the container without a run, and Run > Stop Runtime stops and removes it. The buttons Start runtime and Stop runtime in the Runtime tool window do the same. The containers and the image carry the label io.karpfen.ide.runtime=true, see 1.12 Closing and cleaning up.

To run a model on a runtime of your own, without the IDE, see 3.3 Running the runtime.

4.5.2 Starting a run#

Run > Run (Shift+F10) starts a run. On a Mac keyboard you may have to hold Fn. The run goes through these steps.

  1. It picks the descriptor: the one in the active editor, otherwise the only descriptor of the project, otherwise it asks in the dialog Run with the sentence Choose the environment descriptor to run:, with the last choice selected. A project without a descriptor gets an error that says how to create one.
  2. It saves every open file, because it uploads the saved files.
  3. It validates the whole project. An error blocks the run, see 4.4.6 Validation before a run.
  4. It opens the run dialog.
  5. It stops an earlier run of the same descriptor that still runs.
  6. It prepares the deployment from the saved files and checks it.
  7. It starts the container if it is not running and waits for the runtime.
  8. It deploys the descriptor and starts the environment.

4.5.3 The run dialog#

The dialog Run opens with every run, also with Run again.

In the dialogEffect
One box per bridge file of the projectThe ticked bridges start with the run, see 4.7 Bridges.
Capture run to fileThe run writes the whole log of the runtime to a file, see 4.5.8 Captured logs.
Run, CancelStarts the run, or ends it here.

The boxes ticked last time are ticked again. The choices are kept in .karpfenproject.

4.5.4 The Runtime tool window#

The Runtime tool window opens with every run and then takes three quarters of the window's height. The status bar shows Runtime: stopped, building image, starting, running, failed or stopping, and a click on it shows the tool window.

The button at the right end of the tool window's title bar moves it into a window of its own, for example onto a second screen. Its place in the main window closes, and the editor gets the room. In the separate window the same button shows the dock icon and moves the tool window back to its place, with the height it had. Closing the separate window also docks the tool window. The separate window has the same menus as the main window, so Run, Stop and the keys of the debugger work there too. It follows the theme and the zoom of the main window, and it closes with the project and with the main window.

While the tool window is detached, a new run, a click on the runtime status in the status bar and View > Runtime show it in its own window and bring that window to the front. View > Runtime hides a shown tool window, which closes the separate window. Showing it again opens the separate window again, because the tool window stays detached until it is docked.

The runs, the selected run, observation and the log carry over between both places. The scroll positions and the widths of the Model, Events and Log panes start anew. Whether the tool window is detached is kept in .karpfenproject as pane.runtime = shown 400 detached, see 4.1.6 The project file, so a project that was closed with it detached opens it in its own window again. The place and size of the separate window are kept in ~/.karpfen-ide/settings.json. A place on a screen that is no longer connected is dropped, and the window opens in the middle of the screen.

4.5.4.1 The runtime line#

The first line says what the container does, with the buttons Start runtime and Stop runtime.

TextMeaning
Docker: not startedNo container runs.
Docker: checking the Docker engineThe IDE looks for the Docker engine.
Docker: building the runtime imageThe first run builds the image. A detail of the build step may follow.
Docker: creating the container, Docker: starting the containerThe container is being set up.
Docker: waiting for the runtimeThe container runs, and the runtime in it starts.
Docker: running at 127.0.0.1:<port>The runtime is ready.
Docker: stoppingThe container is being stopped and removed.
Docker: <problem>The container could not be started. The text is red and can be selected.

4.5.4.2 The runs#

The second line lists the runs, each with its name, the key of its environment once known, and its phase. The name is the file name of the descriptor without .kenv.json. A click selects a run, and the panes below show the selected run.

PhaseMeaning
preparingThe run prepares the deployment from the saved files.
blockedThe preparation found errors. The run never reached the runtime.
waiting for the runtimeThe run waits for the container.
deployingThe run uploads the files and configures the environment.
runningThe environment runs.
readyThe environment is activated but not started.
stoppedThe environment was stopped.
failedThe runtime, the deployment or the environment failed, or the environment ended on its own.

The buttons Run again, Stop and Clear finished follow. Run again starts the selected run anew, through the steps of 4.5.2 Starting a run. Stop stops it. Clear finished removes every run that is blocked, stopped or failed from the list.

With breakpoints switched on, a third line holds the debugger, see 4.6 Debugging.

Below these lines three panes show the selected run side by side: Model, Events and Log.

4.5.4.3 The Model pane#

The Model pane shows the model of the running environment as a tree. Expand all and Collapse all open and close every row.

RowMeaning
relation: key : TypeAn object, under the relation that holds it.
name = valueA property and its value.
relation -> keyA knows reference. A click on the key selects that object.
created at run timeMarks an object that the state machines created.

The switch Observation decides how the tree follows the run. With observation on, the runtime reports every change, and the tree, the active states and the statecharts follow at once. With observation off, the tree stays as it is, and Pull reads the current model once. A run starts with observation on. The status next to the switch reads, for example, Observation on, live at revision 12 or Observation off, pulled at revision 30. Other states are predicted, nothing read yet, synchronizing, and final at revision N after the environment stopped. Once a run has ended, the switch and Pull are greyed out, since the runtime no longer holds its environment.

4.5.4.4 The Events pane#

The Events pane sends events into the run and lists the events of the environment.

  1. Under 1. Domain, choose a domain. The domains are those the state machines use. A domain with an event that the event metamodel declares is in bold. A domain whose events no event metamodel declares is marked (used only).
  2. Under 2. Event, choose an event. Each reads as name: PayloadType, or with (used only) when the event metamodel does not declare it.
  3. Under 3. Payload, edit the payload as JSON. It starts as a template of the payload type and is checked after every change. An event without a payload type reads This event has no payload type. It is sent without a payload.
  4. Click Send <event>. The button is greyed out while the payload has an error or while events cannot be sent.

After a send, the line next to the button reads Sent. It shows in the list below once the runtime has published it. or Not sent: with the reason. A line below it says whether events can be sent now:

TextMeaning
Events cannot be sent yet, because the environment is not deployed.The deployment has not reached the environment.
The environment has not started yet. An event sent now waits until it starts.The environment is activated but not started.
The environment is running. An event is delivered at once.Events go in now.
Events cannot be sent: and a reasonThe run has ended or the connection is lost.

The list Events in this environment, newest first shows the events sent from here, from other clients and from bridges, and the events the state machines raise. Its columns are Time, Domain, Event, Source and Payload. The source is external for an event from outside and internal for an event a state machine raised. A click on an event shows its whole payload. An empty list reads No events yet. Events you send and events the state machines raise appear here.

An event waits until a state machine takes it or until its time to live runs out, see eventTtlMs in 4.1.2 Environment descriptors and 3.1 Execution semantics.

4.5.4.5 The Log pane#

The Log pane has the switch Simplified, which is on at first, Follow, which keeps the newest line in sight, and Clear. Above the log it shows what the run has to tell:

  • The runtime could not be started: with the problem of the container.
  • Captured to karpfen-runs/<file> when the run is captured, or The run could not be captured to a file: with the reason.
  • Findings that block the run with the problems of the preparation. A click on one leads to its place.
  • The active states of each state machine instance, as lamp: on > full, outermost state first. An instance of a definition also names its definition, as gen_Bulb_0 (glowing): lit, see 4.5.4.7 State machine instances.
  • One line about the deployment: Deployment done, 16 steps, Deploying: <step> or Deployment failed at: <step>. A click on it shows the details: the environment, the connection, every step, and the problems of the run.
  • One line per bridge of the run, see 4.7.6 The bridges of a run.

All of this text can be selected and copied.

With Simplified on, the log shows only the steps of the state machines and the errors, one line each with the time, the object or engine, and the text:

14:17:03.887  lamp        attaches its state machine
14:17:03.888  lamp        starts in off
14:17:03.889  wallSwitch  attaches its state machine
14:17:03.890  wallSwitch  starts in down
14:17:03.892  engine      Engine started with 2 state machine(s), tickDelay=500ms
14:17:03.895  lamp        runs the entry actions of off
14:17:04.896  lamp        off -> full
14:17:04.898  wallSwitch  down -> up
14:17:05.397  lamp        runs the entry actions of on
14:17:05.399  lamp        runs the entry actions of full

The times are those of the runtime's clock, which is UTC in the container.

A state machine that splits runs on several paths at once until they join again, see 2.3.4.3 Splits and joins. The runtime numbers the paths of each object. While an object runs on more than one path, each of its lines begins with the path it belongs to, and the split and the join name the paths they start and end:

14:17:04.896  lamp        split off -> test bulb, test switch into paths 1, 2
14:17:04.898  lamp        path 1: runs the entry actions of test bulb
14:17:04.899  lamp        path 2: test switch -> check position
14:17:05.397  lamp        join bulb ok, switch ok -> on from paths 1, 2
14:17:05.399  lamp        runs the entry actions of on

An object that runs on one path shows no path, so a run without splits never shows one.

An empty simplified log reads No step of a state machine yet. Switch Simplified off to see the whole output of the runtime. With Simplified off, the log shows every line of the runtime's output, with its error output in red.

4.5.4.6 The deployment steps#

The details of the deployment list each step with its state, pending, running, done, skipped or failed, and a detail. These are the steps of the lamp.

Checking the runtime at http://127.0.0.1:65457: done, The runtime is up and supports the IDE
Creating the environment: done, env-1794579423685
Connecting to the environment: done, Connected as karpfen-ide-254666e10161
Uploading lamp.kmeta: done
Uploading lamp-events.kmeta: done
Uploading lamp.kmodel: done
Attaching lamp.kstates to lamp: done
Attaching switch.kstates to wallSwitch: done
Setting the tick delay to 500 ms: done
Setting the event time to live to 5000 ms: done
Listening to 2 event domains: done, service, switch
Switching on runtime features: skipped, The project switches on no language feature that needs one
Activating the environment: done
Switching observation on: done, The runtime read the model as analyzed
Starting the environment: done
Confirming the start: done, Every state machine reported its state

A descriptor with definitions has a step Uploading the definition glowing.kstates for each, among the attaching steps in the order of the descriptor. Confirming the start waits for every instance the start built, also those of the definitions.

A descriptor with fragments has a step Uploading the fragment bulb_test.frag.kstates for each, also in the order of the descriptor, see 4.5.4.8 Pages.

With histories and tick limits switched on, the step reads Switching on History, TickLimit, see 4.1.7 Language features. With Parallel branches on threads switched on as well, it reads Switching on History, TickLimit, TrueParallel. A runtime that does not know TrueParallel fails the step with The runtime at <address> does not know the feature TrueParallel, so it is older than the IDE.

4.5.4.7 State machine instances#

A run has one state machine instance for each object that runs a state machine. The descriptor attaches state machines to objects by their keys and lists attachable state machines as definitions, see 4.1.2.3 Definitions. The runtime gives objects instances of definitions and takes them away while the run goes on, as 3.1.13 State machine management and lifecycle describes:

  • At the start, each object whose type behaves after a definition gets an instance of it.
  • An object that a rule creates gets an instance of the definition its type behaves after, or of the one its ATTACH names.
  • EXCHANGE ends the instance of an object and gives the object an instance of another definition, which starts in its initial state.
  • An object that leaves the model takes its instance with it.

The Runtime tool window follows the instances. The active states above the log name the object, and the definition in parentheses for an instance of a definition. A new instance shows the initial state of its definition until its first step, and an instance that ends disappears with its states. The diagram of a definition shows one instance at a time, see 4.3.10 While a model runs. With Simplified on, the log says when an object gets or loses an instance:

14:20:11.000  bulb        attaches glowing
14:20:11.001  bulb        starts in lit
14:20:16.500  bulb        exchanges glowing for flickering
14:20:16.501  bulb        starts in on
14:20:18.500  gen_Bulb_0  attaches glowing
14:20:18.501  gen_Bulb_0  starts in lit
14:20:19.000  bulb        detaches flickering

At each start the log has an attaches line for every instance, and a state machine the descriptor attached reads attaches its state machine, or exchanges its state machine for flickering when an EXCHANGE ends it. The initial state of an instance follows right after the line that gives the object the instance.

The preparation checks the definitions against the descriptor before anything reaches the runtime:

  • A type that behaves after a state machine that the descriptor does not list blocks the run with deploy-definition-not-listed, because the runtime would refuse to activate the environment.
  • An ATTACH or EXCHANGE that names a state machine the descriptor does not list gives the warning deploy-attached-definition-not-listed at the state machine. The runtime fails such an action when it runs and writes the failure to its log. A name that an EVAL or a MACRO computes is not checked.

The example in examples/spares shows all of this. Each bulb runs glowing from the start, the event stock of the domain service puts a new bulb with glowing on the shelf, flicker exchanges the state machine of the bulb in the lamp for flickering, and replace screws in a new bulb, so the old one leaves with its instance.

4.5.4.8 Pages#

A state machine composed of pages has container states that run fragments, see 2.3.12 Pages. The descriptor lists every fragment a run needs, without attachedTo, also the fragments that only other fragments use, see 4.1.2.5 Fragments. The deployment uploads each of them as it stands, before it activates the environment. When the runtime activates the environment, it puts the fragments into the container states and runs one flat state machine for each object.

In the flat state machine the states of a fragment carry the name of their container state in front, separated by a slash. When the container state self test of the lamp in examples/pages uses bulb_test, whose container state wiring uses wiring_check, its states read self test/wiring and self test/wiring/measuring. The Runtime tool window shows these names everywhere it names states: in the active states above the log, as lamp: self test > self test/wiring > self test/wiring/measuring, in the simplified log, and in the debugger line. One fragment that two container states use runs as two copies, each with the name of its own container state.

The preparation checks the pages against the descriptor before anything reaches the runtime:

  • A fragment that a state machine of the run uses, directly or through another fragment, and that the descriptor does not list blocks the run with deploy-fragment-not-listed at the descriptor. The problem names the fragment, its file and the file that uses it. The project validation, which runs before, reports the same cause as project.unknown-fragment, see 4.4 Validating.
  • A composition that does not flatten blocks the run with deploy-not-flattened, with the words of dsl-tools, at the state it concerns. Examples are a container state that uses an attachable state machine and a macro that two files of the composition define differently.

If the runtime refuses the activation nevertheless, the run fails with one problem per line of the refusal, with the runtime's own words, at the file of the state machine the line names.

How the statecharts show a run in pages is described in 4.3.10 While a model runs.

4.5.5 Stopping a run#

Stop in the line of the runs, or Run > Stop (Cmd+F2 / Ctrl+F2), stops the selected run. The run turns stopped, the Model pane keeps the last model, and the Send button is greyed out. The container keeps running. A new run of the same descriptor stops the run before it.

A stop ends the run for good. The IDE reads the model a last time and then drops the environment, so the runtime forgets it and no longer lists it; Run again deploys a fresh environment. The runtime by itself would only freeze a stopped environment, as 3.1.13.9 Stop and start, forcing and clients describes. Every way a run ends drops its environment the same way: Stop, a new run that replaces the run before it, closing the project, Stop runtime, quitting the IDE, and the end of a run on the command line. After the drop the IDE asks the runtime nothing more about the environment, so the Model pane, the Events pane, the debugger and the bridges show what the run saw last.

A drop can fail, for example because the runtime is gone or is an older runtime that cannot drop environments. The run still ends as stopped, and the Log pane notes the problem environment-left-behind with the reason, such as The runtime at http://127.0.0.1:65457 cannot drop environments, so it is older than the IDE; the environment env-1794579423685 stays there. The IDE waits at most ten seconds for a drop.

When another client stops the environment of a run, the run also turns stopped. The Log pane notes The runtime reports that the environment stopped. and that the environment was stopped by somebody else than the session, so the run ended. The IDE then reads the model a last time and drops the environment as after its own stop.

When another client drops the environment of a run, the run turns stopped as well. The Log pane notes that the environment was dropped by somebody else than the session, so the run ended, and the Model pane keeps what the run saw last, since nothing of the environment is left to read.

When the runtime ends while a run is live, for example because its container was removed outside the IDE, the run turns failed with the problem environment-lost.

4.5.6 A failed run#

A run can end before or after it reaches the runtime.

What happensWhere it shows
The project has errors.The dialog Run Blocked: the Project Has Errors, see 4.4 Validating.
The preparation finds a problem, such as a state machine attached to a missing key.The run is blocked, and the Log pane lists the problems under Findings that block the run.
Docker is not running.The run is failed. The runtime line and the Log pane read Cannot connect to the Docker engine at ... and Start Docker Desktop or the local Docker engine, then try again.
The container stopped.The runtime line names the container and asks to run again.
A step of the deployment fails.The run is failed, and the Log pane reads Deployment failed at: <step>. The details list the problems.
The runtime refuses an uploaded file.One problem per error of the file, at its line and column, as lamp.kstates:13:1: <message>. A click leads to the place.
The runtime refuses the form of a state machine.One problem at the file, with the runtime's text, such as A state machine without attachedTo must have the attachable form ....
The runtime refuses to activate the environment, because a type behaves after a state machine it does not hold or that is not attachable to the type.One problem at the descriptor with the runtime's text.
The runtime refuses to activate the environment, because a state machine does not flatten with the fragments it holds.One problem per line of the runtime's text, at the file of the state machine it names, as The runtime refused the activation, because lamp.kstates cannot be flattened: <message>.
The environment ends on its own.The run is failed with the problem engine-halted. The log of the runtime has the reason.

The problems of the preparation and the deployment have these codes.

CodeSeverityMeaning
deploy-no-contextErrorThe descriptor could not be read. Its own problems say why.
deploy-save-failedErrorA file could not be saved before the deployment.
deploy-unsaved-fileErrorA file was edited while the run prepared. Run again.
deploy-context-errorsErrorA file of the context has errors, one problem per file at its first error.
deploy-no-metamodel, deploy-no-modelErrorThe context has no metamodel or no model, or it could not be read.
deploy-unknown-attachmentErrorA state machine is attached to a key that no object of the model has.
deploy-definition-not-listedErrorA type behaves after a state machine that the descriptor does not list as a definition.
deploy-attached-definition-not-listedWarningAn ATTACH or EXCHANGE names a state machine that the descriptor does not list as a definition.
deploy-fragment-not-listedErrorA state machine of the run uses a fragment, directly or through another fragment, that the descriptor does not list.
deploy-not-flattenedErrorA state machine of the run does not flatten with the fragments the descriptor lists.
deploy-duplicate-attachmentErrorTwo state machines are attached to the same key.
deploy-attachment-typeWarningThe attached object's type differs from the type after ATTACHED TO.
deploy-reference-loopErrorAn object is reachable from itself through has and knows, which the runtime cannot read.
deploy-domain-is-attachmentWarningAn event domain is named like an attached object key.
deploy-tick-delay-range, deploy-tick-delay-zero, deploy-event-ttl-never-expiresSee 4.1.2.1 KeysThe timing of the descriptor.
deploy-model-differsWarningThe model the runtime read back differs from the model the IDE read, one problem per object.
runtime-unreachableErrorThe runtime could not be reached.
runtime-incompatibleErrorThe runtime does not answer like a karpfen runtime that supports the IDE.
runtime-no-answerErrorThe runtime did not answer in time, or the connection broke during a call.
runtime-rejectedErrorThe runtime refused a call, with its reason. A refused upload gives one problem per error of the file.
runtime-errorErrorThe runtime failed with an internal error.
handshake-rejectedErrorThe runtime refused the WebSocket connection.
connection-lostError or warningThe connection could not be opened or was given up. A warning after the deployment.
engine-haltedErrorThe environment ended on its own.
engine-silentWarningNot every state machine instance reported its state after the start.
observation-out-of-syncWarningObservation is on, but the model could not be read again. The tree stays as it was until the next Pull.
environment-lostErrorThe runtime no longer knows the environment, usually because it ended or restarted.
environment-left-behindInfoAn environment stays on the runtime, because dropping it failed or took too long.

4.5.7 Several runs#

The list of runs keeps every run until Clear finished removes it. Runs of different descriptors can run at the same time in the same container. Each has its own environment and its own panes. A finished run keeps its panes after its environment was dropped, until Clear finished removes it.

4.5.8 Captured logs#

With Capture run to file ticked, the run writes the whole log of the runtime into the folder karpfen-runs of the project, in a file named after the date and time of the start, such as 2026-11-13_14-32-05.log. If the name is taken, -2, -3 and so on are added. The folder does not show in the Project tool window. The Log pane names the file of the selected run.

The file starts with lines that begin with #: the descriptor, the start, the address of the runtime and, once known, the environment. Then every line of the runtime's log follows from the deployment to the end of the run, also the lines of each tick that the Log pane leaves out, each marked stdout or stderr.

The file holds the log of the whole runtime while its run lives. With two runs at once, each file also holds the lines of the other run. Lines that the runtime writes before the deployment are not in the file.

# karpfen run capture
# Descriptor: lamp.kenv.json
# Started: 2026-11-13 14:32:05
# Runtime: the IDE's Docker container at http://127.0.0.1:65457
# Environment: env-1794579423685

Source: this page on GitHub at commit 3b6029f, refreshed 16 November 2026. The whole reference as a PDF.