Compatibility
Kasm Session Runtime is one static Linux binary and needs no libraries from the image it runs in. From the session it needs an X display, and for some features a browser with its DevTools port open, the accessibility bus, or a model endpoint. This page lists the images, architectures and session settings it works with, and the settings that change its results.
Images
Section titled “Images”The runtime works in two kinds of Kasm workspace image.
kasm-nix images (such as chrome:nix) |
Stock kasmweb/* images |
|
|---|---|---|
| How the binary gets there | built into every image | an addition from the SDK adds it |
| What starts it | starts with the session, only when KASM_RUNTIME_SESSION_TOKEN is set |
the same, once the addition is applied |
| Framebuffer size | VNC_RESOLUTION is honoured; the images default to 1280x720 |
VNC_RESOLUTION is ignored; the SDK addition enables KVNC_DESKTOP_RESOLUTION_WIDTH and _HEIGHT, default 1024x768 |
| Refusing viewer resizes | VNC_FIXED_RESOLUTION=1, on recent core images |
KVNC_DESKTOP_ALLOW_RESIZE=false, once the SDK addition is applied |
| Sidebar | KASM_RUNTIME_SIDEBAR=<name> |
KASM_RUNTIME_SIDEBAR=<name>, once the SDK addition is applied |
| Accessibility | accessibility support is included | the SDK addition adds ACCESSIBILITY_ENABLE=1 for apps that publish nothing without it |
Without the session token, neither kind of image starts the runtime, and the session has no runtime process and no listener. The SDK addition was last verified on 2026-09-18 with kasmweb/chrome and kasmweb/libre-office at 1.19.0-rolling-weekly and runtime v0.2.102. Everything it adds is off until an environment variable turns it on, so an image built with it behaves like the stock image by default. Enable the runtime on a workspace walks through both.
Kasm sets a session’s environment from the workspace’s Docker Run Config, or from the environment map of an API request_kasm call. Kasm keeps that map only for a caller using an API key.
Architectures
Section titled “Architectures”Each release publishes linux/amd64 and linux/arm64 binaries, with a SHA256SUMS file, and one architecture-independent sidebar bundle. The stock-image build downloads the binary for its architecture and checks its SHA-256. A binary for the wrong architecture fails inside the container with exec format error.
Session geometry
Section titled “Session geometry”Run agent sessions at a fixed 1024x768 and stop viewers from resizing them. Every SDK example does this.
A coordinate is only correct at the frame size it was produced for. That covers a coordinate the vision model returns, a click target written as a fraction of the window, and a baseline screenshot that later captures are compared against. If the framebuffer changes size between writing a scenario and running it, or during a run, those clicks land in the wrong place and baseline comparisons read as drift, with no error reported. Runs that need no coordinates, such as a scenario made only of cdp_* steps or an outside agent using dom.*, are not affected.
The runtime reads the real framebuffer size and records it in report.json as screen. Check it there when a run’s clicks look wrong.
Causes of a size change
Section titled “Causes of a size change”- The nix images default to 1280x720. Set
VNC_RESOLUTION=1024x768. - Stock images ignore
VNC_RESOLUTIONand stay at 1024x768 unless theKVNC_*variables are set. - Kasm’s API overwrites
VNC_RESOLUTIONwith the request’sx_resandy_res, which default to 800 and 600. An orchestrator callingrequest_kasmmust sendx_resandy_resas well as the variable. This was read from Kasm 1.19.0. - An attached viewer can resize the framebuffer mid-run unless resizing is refused (
VNC_FIXED_RESOLUTION=1on nix images,KVNC_DESKTOP_ALLOW_RESIZE=falseon stock ones).
A person watching a fixed-size session should view it at exactly its size. See Known issues for what happens to their clicks otherwise.
Browsers
Section titled “Browsers”The dom.* methods, the cdp_* scenario steps and the /cdp/ passthrough use the Chrome DevTools Protocol. The SDK examples use Chrome. The browser must be started with a debugging port on loopback, and on Chrome 136 and later with a --user-data-dir too:
APP_ARGS="--start-maximized --remote-debugging-port=9222 --remote-debugging-address=127.0.0.1 \ --remote-allow-origins=* --user-data-dir=/home/kasm-user/.config/chrome-cdp-profile"- Without
--user-data-dir, Chrome 136 and later ignores--remote-debugging-portwithout any message, and everydom.*call fails to attach. APP_ARGSreplaces the image’s default arguments rather than adding to them, so repeat--start-maximized.- Chrome reads flags only when it first starts. Launching
google-chromeagain with new flags hands the URL to the running browser and drops the flags. - The runtime refuses a DevTools endpoint that is not on loopback unless
KASM_RUNTIME_CDP_ALLOW_REMOTE=true.
Native applications need no browser. They are driven through X11 input and, where the application publishes one, its accessibility tree over AT-SPI.
MCP clients
Section titled “MCP clients”Over stdio, the runtime accepts initialize only with protocol version 2024-11-05. Over HTTP, the client’s Mcp-Protocol-Version header chooses: 2026-07-28 and later use the stateless protocol, and earlier versions use sessions. See MCP methods.
Model servers
Section titled “Model servers”A model is optional. When you configure one, KASM_RUNTIME_VISION_ENDPOINT can be any server that speaks the OpenAI chat-completions format with images sent as base64 data URIs, local or hosted. The grounding accuracy the project has measured is for the Qwen3-VL family; for other models it is unmeasured. See Vision models and When you need a model.
- Enable the runtime on a workspace: set it up on either kind of image.
- Known issues: problems with a known condition and workaround.
- Environment variables: every setting mentioned here.