What runs where

Kasm Session Runtime is one static binary. It runs inside the session container as the session user, next to the applications it drives, and needs nothing else installed in the image.

Starting the runtime

The binary has three subcommands. Two of them run in a session.

• mcp is the networked server that agents and scripts call. It stays off unless the session is started with KASM_RUNTIME_SESSION_TOKEN. With the variable set, the runtime starts with the session and listens for callers, and the same value is the credential every caller presents. The Kasm nix workspace images ship the runtime. Stock kasmweb/* images get it from a small addition in the SDK.
• run executes one or more scenario files, writes the report and stops. A test harness runs it in the session and collects the output directory when the DONE file appears.
• compile-plan turns the output of a finished run into a replayable plan. It runs anywhere.

See Enable the runtime on a workspace for the switch and CLI for the subcommands.

Connections inside the session

Target	How	What for
The X server (DISPLAY, default :1)	X11: screen capture, XTEST key and pointer injection, the window list	Screenshots, key chords, typing, clicks, window checks
Chromium-family browsers	Chrome DevTools Protocol at http://127.0.0.1:9222 by default	Acting on page elements directly. A non-loopback endpoint is refused unless KASM_RUNTIME_CDP_ALLOW_REMOTE=true
The accessibility bus	AT-SPI over D-Bus	Naming and pressing controls in GTK, Qt and Electron apps, and reading their state
Processes and files	The session user’s processes and file system	Process checks, launching commands, writing the output directory (KASM_RUNTIME_OUT)

The runtime has the session user’s rights, and the session container is the isolation boundary. See What the process can reach.

Connections outside the session

The only connection out of the session is to the model server, when one is configured. KASM_RUNTIME_VISION_ENDPOINT names any OpenAI-compatible chat-completions server, on your own hardware or hosted. The runtime calls it from inside the session, so the session must be able to reach it. With the variable empty the runtime makes no model calls. See When you need a model.

Callers

Under mcp, callers reach the runtime in one of two ways:

• Standard input and output, when no session token is set. A local MCP client starts the process and talks to it directly.
• HTTP on port 9434 (KASM_SESSION_RUNTIME_PORT), when a session token is set. Every request that acts must carry the token in the X-Kasm-Runtime-Session-Token header. From outside the session, requests go through Kasm’s own proxy. See Enable the runtime on a workspace.

Over HTTP the runtime serves:

Route	What it is
/mcp	MCP over HTTP, for agents
/v1/call/<method>	The same methods as plain HTTP calls, described by an OpenAPI document at /v1/openapi.json
/v1/files/, /v1/dirs/	File transfer, confined to the session user’s home directory and /tmp
/cdp/	A raw DevTools proxy, only when KASM_ENABLE_CDP is set, behind the same token
/events, /artifacts/	Read-only: a live copy of the run’s trace, and the output directory

A person watching the session sees the runtime through a sidebar in the KasmVNC viewer. Under run, the sidebar’s feed is served only when KASM_RUNTIME_OBSERVE=true. When KASM_RUNTIME_INBOX_TOKEN is set, the sidebar can also send messages to a running run. See People in the loop.

The full list of methods is in MCP methods and HTTP API.

Next

• When you need a model
• Ways to drive a session
• Security overview