Using it with your own agent

If you already have an agent, such as Claude Code, Codex or any other MCP client, it can drive a Kasm session through Kasm Session Runtime. Your agent does the reasoning, and the runtime gives it tools inside the session and records every call.

A computer-use tool gives an agent a screenshot and a mouse and keyboard on a desktop you provide. The runtime gives an agent the same session with more ways in: the browser’s page structure over the Chrome DevTools Protocol, native applications’ controls over AT-SPI, processes, files, and pixels when nothing else works. The agent can click a button by its name instead of by coordinate, and the result says what was clicked.

Your agent needs no model in the runtime. Leave KASM_RUNTIME_VISION_ENDPOINT empty unless you want the runtime’s screen.judge, screen.ground or screen.ask methods, which use it.

Division of work

	Your agent	The runtime
Decides what to do next	yes	no
Sees the screen	through `screen.capture`, or the page and accessibility listings	captures it, reads the DOM and accessibility tree
Acts	chooses the method and its arguments	delivers the input, click or DOM action, and reports what happened
Checks a result	calls `dom.wait`, `a11y.action` with `expect_state`, or reads the screen	waits for the condition and returns a resolution error if it does not hold
Records	whatever your agent keeps	one row per call in `report.json`, `backend: "rpc"`, plus `trace.jsonl` and the sidebar timeline
Decides pass or fail	yes, in `mcp` mode	no verdict of its own in `mcp` mode

The runtime exposes 28 methods in groups: screen.*, input.*, proc.* with launch, shell and wait_while, dom.*, a11y.*, file.get and directory.get. See MCP methods.

Turning it on

On a chrome:nix workspace image the runtime is already in the image. Setting KASM_RUNTIME_SESSION_TOKEN in the session’s environment, through request_kasm’s environment map, both configures it and starts it. The MCP endpoint is then:

https://<host>/desktop/<kasm_id>/mcp/mcp

It takes two headers: X-Kasm-Runtime-Session-Token with the token, and Kasm’s session cookie, which only a real username and password login sets. Authorization cannot be used, because Kasm’s proxy overwrites it. For Claude Code, the 05-mcp-drive example in the SDK prints a line of this shape:

claude mcp add --transport http kasm-session "https://<host>/desktop/<kasm_id>/mcp/mcp" \
  --header "X-Kasm-Runtime-Session-Token: <token>" \
  --header "Cookie: session_token=<...>; username=<...>"

For other images, and what an administrator sets, see Enable the runtime on a workspace. For a tutorial, see Drive a session from Claude Code.

Working in the session

Use the page’s structure before pixels. In a browser, dom.list_interactive returns every interactive element with a short handle, and dom.click_described clicks by handle or text. A handle resolves against a fresh read of the page, so a page that changed underneath gives an error naming what is there now instead of a click on whatever moved into place. Neither needs a model.
For a native application, a11y.tree lists the controls it publishes and a11y.action invokes one by name, optionally reading its state back.
Where neither works, screen.capture and input.click at screen pixels do what a computer-use tool does. screen.ground can locate a described element, if a model is configured.
A person watching the viewer sees each call in the sidebar as you make it, and can send your agent messages through the inbox. See People in the loop.

Choosing a setup

Use your agent through the runtime when the task needs judgement you cannot script and you want a record of what was done, in an application the customer already runs in Kasm.

Use your agent’s own computer-use tool without the runtime when the desktop is somewhere else, or when a screenshot-and-click loop is all the task needs.

Use the runtime without your agent when the same job must run unattended, many times, or with a model that stays on your hardware: a scripted scenario, the runtime’s own loop with a local model, or a plan compiled from an earlier run. See Plans and postconditions.

Setup	Who owns the loop	Who sees the screen	Who acts	Record
Your agent with a computer-use tool, alone	your agent	your agent, from screenshots	your code, at pixel coordinates	what your agent and code keep
Your agent through the runtime	your agent	your agent, through the runtime’s methods	the runtime, by DOM, accessibility, keys or pixels	the runtime’s report, trace and sidebar
The runtime’s own loop	the runtime, with its model	the runtime’s model	the runtime, from a closed list of tools	the runtime’s report, with a verdict
A compiled plan	the plan, no model	nobody needs to	the runtime	the runtime’s report, with a verdict on deterministic evidence

Limits

In mcp mode the runtime does not judge the outcome. The report’s verdict covers only whether the session stayed healthy. Your agent decides whether its task succeeded.
The HTTP transport runs one call at a time.
The report stays in the session. Read it from /artifacts/report.json on the same base URL as /mcp; see Report.