Glossary
Terms these docs use with a specific meaning. Names in code format are the field, value or variable exactly as the runtime spells it.
Answer convention. The shape in which the vision model is asked to give a location when grounding: point (the default, a point with a found flag) or box2d (a bounding box, reduced to its centre). Coordinates are normalised to KASM_RUNTIME_VISION_GROUNDING_SCALE (default 1000); set the convention with KASM_RUNTIME_VISION_ANSWER_CONVENTION. See Vision models.
Backend. The mechanism a step used to reach the application, recorded in each steps[] row as backend: cdp, atspi, xtest, vision, shell or none, and rpc for a call from an outside agent. A grounded click is recorded with backend xtest and rung grounded: X input performed the click at a coordinate the model supplied.
Capture geometry. How a screenshot is shaped before it is sent to the vision model: native (the default, as captured) or square-padded (centred on a square canvas). Set it with KASM_RUNTIME_VISION_CAPTURE_GEOMETRY; it is independent of the model name.
Declared target. A named click position written into a scenario’s click_targets: map as fractions of the window, for example save-button: [0.92, 0.05], and used as click "save-button". It resolves at rung 1 and needs no model.
Deterministic-only. How the runtime runs when KASM_RUNTIME_VISION_ENDPOINT is empty, or after the model has failed repeatedly during a run: every step and check that needs no model still runs, nothing is judged visually, and the report says so. See When you need a model.
Grounding. Asking the vision model where a described element is on screen and getting back a screen coordinate. It is rung 3, the last rung of the ladder. A scenario’s click_grounded step must carry an expect: check, and the MCP method screen.ground returns the location and leaves the click to the caller. Grounding needs a model.
Inbox. The channel between people in the session and the run: messages to the run, typed questions from the run (ask_human), and control actions such as stop and finish_handoff. It is served on the observe port. See People in the loop.
Judge. The vision model answering a yes-or-no question about a screenshot: whether the application rendered, whether an expect: or observe: holds, or a screen.judge call. The judge can fail a check the scenario asked for, but it cannot turn a failed probe into a pass. Judging needs a model.
Observe port. The HTTP listener on KASM_SESSION_RUNTIME_PORT (default 9434) that serves /events, /artifacts/ and the inbox routes a sidebar reads. It is the same port as MCP over HTTP. kasm-session-runtime run opens it when KASM_RUNTIME_OBSERVE=1. See Sidebar protocol.
Operator file. An optional YAML file, named by KASM_RUNTIME_CONFIG_FILE, holding tuning that belongs to the deployment rather than the test: loop budgets, model sampling and transport, reply caps, waits, evidence limits and which built-in tools the model may use. Each setting also has its own environment variable. See Operator file.
Plan. A scenario’s plan: list: actions, each with at least one postcondition, replayed with no model call. If a step fails or its postcondition does not hold, the run hands over to the agentic loop from that point, so a scenario with a plan also needs a goal:. kasm-session-runtime compile-plan writes one from an earlier run’s transcript. See Plans and postconditions.
Postcondition. A fact that must be true after an action, declared in a post: list and waited for up to its timeout: url, dom, state, window, no_window, process, no_process, file or screen. All but screen are checked without a model. Required on every plan: step, optional on a steps: entry.
Rung. A level of the ladder that decides how a click finds its target. From most trusted to least, the rungs are a browser or keyboard action (no coordinate), a declared or literal window fraction (rung 1), an element the application names through accessibility (rung 2), and a vision-grounded coordinate (rung 3). Each click’s rung is recorded in its step row as center, declared, literal, element or grounded. See How an action reaches the app.
Scenario. A YAML file describing one job: the application, how to find its window, scripted steps:, and optionally a plan: and a goal: for the agentic loop. The runtime takes it as file paths given to kasm-session-runtime run, or as base64 in KASM_RUNTIME_SCENARIO_B64. See Scenario YAML.
Session token. The value of KASM_RUNTIME_SESSION_TOKEN. Setting it in a session’s environment switches the runtime on, and the same value is the credential for MCP, the /v1/ routes and the /cdp/ passthrough, sent in the X-Kasm-Runtime-Session-Token header. See What the process can reach.
Sidebar. A panel added to the Kasm viewer that shows the run as it happens and lets the person send messages, answer questions or stop the run. It reads the observe port. The bundled sidebar is named default, and a session picks one with KASM_RUNTIME_SIDEBAR. See Replace the sidebar.
Step. One entry in a scenario’s steps: list: an action, optionally with expect:, observe:, expect_state: or post:. Also one row in report.json’s steps[], which records every action the run took, including model tool calls and MCP calls. See Report.
- Scenario YAML: every field in a scenario.
- When you need a model: which of these terms involve the model.