3.3 Running the runtime

The runtime is one program that listens for HTTP requests and WebSocket connections on one port, by default http://127.0.0.1:8080 and ws://127.0.0.1:8080/ws. It runs on your machine with Java or in a Docker container. The IDE builds and starts the container itself, as 4.5 Running describes.

3.3.1 Requirements#

Way to runNeeds
On your machineJava 21. Python 3 on the path as python3, python or py for state machines with Python code, with the packages that this code imports
In DockerDocker. The image brings Java 21 and Python 3 with the packages numpy, scipy, sympy, pandas, regex, python-dateutil and chardet

State machines whose EVAL blocks and macros the runtime computes itself need no Python, as 3.1.6 EVAL and macros describes.

The runtime is built with the KStates, KMeta and KModel readers of karpfen-dsl-tools, which is a git submodule in the folder karpfen-dsl-tools. Clone the repository with its submodule:

git clone --recurse-submodules https://github.com/karpfenproject/karpfen-runtime.git
cd karpfen-runtime

3.3.2 Running on your machine#

The script run_local.sh builds the runtime and starts it from the folder of the repository:

./run_local.sh

The build runs without tests and ends in build/install/karpfen-runtime/bin/karpfen-runtime. The runtime reads application.conf from the folder it starts in. To start it without the script, from the folder of the repository:

./gradlew installDist -x test
./build/install/karpfen-runtime/bin/karpfen-runtime

./gradlew run builds and starts the runtime in one step, also with application.conf from the folder of the repository.

At the start the runtime prints the configuration it uses:

[Main] Configuration loaded:
[Main]   Server: 127.0.0.1:8080
[Main]   WebSocket enabled: true
[Main]   Log level: INFO
[Main]   Engine tracing: false
[Main]   Default tick delay: 50ms
[Main]   Default event TTL: 3000ms
[Main]   Event consumption on fire: true

3.3.3 Running in Docker#

The script run_docker.sh builds the image karpfen-runtime from the Dockerfile of the repository and runs it:

./run_docker.sh
./run_docker.sh /var/log/karpfen

The script hands the container a copy of application.conf in which server.host is 0.0.0.0, so the runtime can be reached from outside the container. It maps port 8080 of the container to port 8080 of your machine. When you change server.port, change the port in the script too. The folder in the first argument, by default logs in the folder of the repository, is mounted as /app/logs in the container. For trace logs on your machine, set engineTracing.tracingLogDirectory to /app/logs. The container is removed when it ends.

The image has no application.conf of its own. A container started without one runs with the defaults of the table below, and with server.host at 127.0.0.1 it cannot be reached from outside the container. To run the image without the script, mount a configuration file at /app/application.conf:

docker build -t karpfen-runtime .
docker run --rm -p 8080:8080 -v "$PWD/docker.conf:/app/application.conf:ro" karpfen-runtime

3.3.4 Configuration#

The runtime reads application.conf from the folder it starts in. Without the file it uses the defaults. The file has one option per line in the form name = value, grouped in blocks:

server {
  host = "127.0.0.1"
  port = 8080
}
engine {
  defaultTickDelayMs = 50
  defaultEventTtlMs  = 3000
}

The runtime finds an option by its name inside the block and does not look at the name of the block. A line that starts with # is a comment, and so is text after # when two blanks or a tab stand before it. A value may stand in quotes. A number that cannot be read gives the default. A boolean is true for true in any case and false for anything else.

OptionDefaultIn the shipped fileMeaning
server.host127.0.0.1127.0.0.1The address the runtime listens on. 0.0.0.0 listens on all addresses
server.port80808080The port for HTTP and the WebSocket
websocket.enabledtruetrueWith false, the runtime pushes no messages to WebSocket clients
websocket.queueTimeoutMs10001000Read and not used
logging.levelINFOINFOPrinted at the start and not used
logging.consoleOutputtruefalseRead and not used
engine.defaultTickDelayMs100050The tick delay of an environment without setTickDelay, in milliseconds
engine.defaultEventTtlMs10003000The time to live of events in an environment without setEventTtl, in milliseconds. 0 means events never expire
engine.eventConsumptionOnFiretruetrueWith false, an event that fires a transition is not consumed by it, as 3.1.7.3 Consumption describes
engineTracing.tracingEnabledfalsefalseWith true, the runtime writes a trace log per environment
engineTracing.tracingLogDirectorynonelogsThe folder of the trace logs, relative to the folder the runtime starts in or absolute. Without it no trace file is written
engineTracing.tracingConsoleOutputfalsefalseWith true and tracing on, the runtime also prints every trace line
engineTracing.simpleTracetruetrueRead and not used

A tick delay of 0 lets an environment tick without any pause and keeps one processor core busy.

3.3.5 Trace log#

With engineTracing.tracingEnabled set to true, the runtime writes one trace log per environment to <tracingLogDirectory>/engine-trace-<envKey>.log. The file is opened when the environment is run and closed when the runtime ends. A stop and a start of the environment go on writing to it.

Every line has the time, the key of the environment, the key of the object of the state machine or * for the whole environment, the type of the entry, a message and details:

[HH:mm:ss.SSS] [<envKey>] [<object>] <TYPE>: <message> | <name>=<value>, <name>=<value>

The beginning of the trace of the lamp:

# Engine Trace Log — Engine: env-1763035112345 — Started: 2026-11-13T09:12:01.120Z
[10:12:01.124] [env-1763035112345] [lamp] STATE_MACHINE_ATTACHED: State machine of the run configuration attached | stateMachine=, path=0
[10:12:01.125] [env-1763035112345] [lamp] INITIAL_STATE: Initial state stack: off | path=0, stack=off
[10:12:01.126] [env-1763035112345] [wallSwitch] STATE_MACHINE_ATTACHED: State machine of the run configuration attached | stateMachine=, path=0
[10:12:01.126] [env-1763035112345] [wallSwitch] INITIAL_STATE: Initial state stack: down | path=0, stack=down
[10:12:01.127] [env-1763035112345] [*] ENGINE_START: Engine started with 2 state machine(s), tickDelay=500ms
[10:12:01.128] [env-1763035112345] [lamp] TICK_START: Tick #1 | path=0, stack=off, currentStates=off, parallel=false
[10:12:01.129] [env-1763035112345] [lamp] STATE_ENTRY_EXEC: Executing onEntry for state 'off' | path=0, state=off, stack=off
[10:12:01.131] [env-1763035112345] [lamp] STATE_DO_SKIP: onDo for state 'off' is empty — skipped | path=0, state=off, stack=off
[10:12:01.131] [env-1763035112345] [lamp] TICK_END: Tick #1 completed | path=0, stack=off, currentStates=off, parallel=false

The types of entries:

TypeWritten whenMessage
INITIAL_STATEA state machine gets its start stack, right after it is attached or exchanged, or a client forces a stateInitial state stack: on > full or Forced state: on > full
ENGINE_STARTThe environment starts, or continues after a stopEngine started with 2 state machine(s), tickDelay=500ms or Engine continued after tick 42 with 2 state machine(s)
ENGINE_STOPThe environment stopsEngine stopped after 42 ticks
STATE_MACHINE_ATTACHEDA state machine instance joins on an object without oneState machine 'glowing' attached, or State machine of the run configuration attached for an attached state machine
STATE_MACHINE_DETACHEDA state machine instance leaves and no other takes its placeState machine 'glowing' detached
STATE_MACHINE_EXCHANGEDEXCHANGE ended the instance on an object and started another one in its placeState machine 'glowing' exchanged for 'blinking', or State machine of the run configuration exchanged for 'blinking'
TICK_STARTA state machine begins its stepTick #3
TICK_ENDA state machine ends its stepTick #3 completed
STATE_ENTRY_EXECAn ENTRY block runsExecuting onEntry for state 'on'
STATE_ENTRY_SKIPA state with an empty ENTRY block is enteredonEntry for state 'on' is empty — skipped
STATE_DO_EXECA DO block runsExecuting onDo for state 'on'
STATE_DO_SKIPThe innermost state has an empty DO blockonDo for state 'on' is empty — skipped
TRANSITION_STARTA transition beginsoff -> full
TRANSITION_FIREDA transition changed the active statesoff -> full
TRANSITION_SKIPPED_LOOPA NOT LOOPING transition was skippedSkipped NOT LOOPING transition
SPLIT_START, SPLIT_FIREDA split begins and is doneoff -> test bulb,test switch
JOIN_START, JOIN_FIREDA join begins and is donebulb ok,switch ok -> on
ACTION_ERRORAn action failedError in onEntry for state 'off': <error>

Every entry of a state machine names a path. A path is one stretch of the state machine on an object that a single branch runs from its beginning to its end. The numbers count per object from 0 and are never given twice while the environment lives, so the object and the path number together name one stretch, and grouping the lines by object and path separates everything, also the lines of branches that interleave while the feature TrueParallel is on. The first state machine on an object runs on path 0. Each target of a split starts a new path, a join ends the paths of the split and starts one more, a forced state ends the current paths and starts one more, and a state machine that EXCHANGE or a later attachment brings to the same object starts with the next number. A stop and a start keep the paths.

The details, in the order in which they appear:

TypeDetails
STATE_MACHINE_ATTACHEDstateMachine (the name, empty for a state machine of the run configuration), path
STATE_MACHINE_DETACHEDstateMachine, then path, or paths while the state machine is split
STATE_MACHINE_EXCHANGEDended (the name of the state machine that ended, empty for one of the run configuration), started, ends (the paths that ended), path (the path of the new state machine)
INITIAL_STATEpath, stack; after a forced state first ends, the paths the force ended
TICK_START, TICK_ENDpath, or paths while the state machine is split; stack (the active states of all branches), currentStates (the innermost state of each branch, in the order of paths), parallel
entries of statespath, state, stack (the stack of the branch)
TRANSITION_START, TRANSITION_FIREDpath, from, to, stack
TRANSITION_SKIPPED_LOOPpath, stack
SPLIT_STARTpath, from, to
SPLIT_FIREDpath (the path that splits), starts (the new paths, in the order of the targets), from, to
JOIN_STARTpaths (the paths about to be joined), from, to
JOIN_FIREDends (the joined paths), path (the new path), from, to
ACTION_ERRORpath, state, stack

A detail that lists several paths separates them with commas. The entries of the whole environment, under *, name no path. A line about a state machine as it stands names path, or paths while it is split; a line that changes the paths names those it ends in ends and those it starts in starts or path.

Some lines of a lamp that tests its bulb and its switch in two branches and joins them in on, shortened to object, type, message and details:

[lamp] TRANSITION_FIRED: idle -> off | path=0, from=idle, to=off, stack=off
[lamp] SPLIT_FIRED: off -> test bulb,test switch | path=0, starts=1,2, from=off, to=test bulb,test switch
[lamp] TICK_END: Tick #2 completed | paths=1,2, stack=test bulb,test switch, currentStates=test bulb,test switch, parallel=true
[lamp] STATE_ENTRY_EXEC: Executing onEntry for state 'test bulb' | path=1, state=test bulb, stack=test bulb
[lamp] TRANSITION_FIRED: test switch -> check position | path=2, from=test switch, to=check position, stack=check position
[lamp] STATE_ENTRY_EXEC: Executing onEntry for state 'bulb ok' | path=1, state=bulb ok, stack=bulb ok
[lamp] JOIN_FIRED: bulb ok,switch ok -> on | ends=1,2, path=3, from=bulb ok,switch ok, to=on
[lamp] STATE_ENTRY_EXEC: Executing onEntry for state 'on' | path=3, state=on, stack=on

An exchange of the state machine of the bulb, which ran on path 0, for blinking writes one line, followed by the start stack of the new state machine:

[bulb] STATE_MACHINE_EXCHANGED: State machine 'glowing' exchanged for 'blinking' | ended=glowing, started=blinking, ends=0, path=1
[bulb] INITIAL_STATE: Initial state stack: off | path=1, stack=off

Two exchanges of one object in the same tick write one line that names the state machine that ran before the tick and the one named last. EXCHANGE on an object without a state machine writes STATE_MACHINE_ATTACHED. A client that observes the state machines still gets stateMachineDetached and then stateMachineAttached for an exchange (see 3.5.3.6).

3.3.6 Stopping the runtime#

Ctrl+C in the terminal of the runtime, or the end of the Docker container, stops it. The runtime closes the WebSocket connections of all environments with code 1001 and the reason Runtime stopped, ends their engines with their Python processes and trace logs, closes its server and ends. It keeps nothing: all environments, models and recordings are gone.

A single environment ends for good with POST /dropEnvironment of 3.4.2 Environments while the runtime goes on. Its connections close with code 1000 and the reason Environment dropped, and its trace file stays in the trace directory. A runtime that runs for a long time and serves many runs should have its clients drop the environments they no longer need, since a stopped environment keeps its model, its engine and its Python processes in memory until it is dropped.

The runtime prints what it does on its console, also when tracing is off: environments that start and stop, clients that register, payloads it cannot read, failed actions and failed EVAL clauses.

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