rchurro/kasm-use

Let an AI agent use a Kasm Workspaces desktop: start a session, look at the
screen, click, type, press keys, scroll, and stop it — in plain language, from any MCP client
(Claude Code, Claude Desktop, OpenCode, Cursor, …) or as a native Hermes Agent plugin.
Other Kasm MCP servers manage sessions (start, list, stop). kasm-use actually uses them: the agent
sees the desktop and operates it, like computer-use or browser-use, inside your Kasm.
Works with stock Kasm images. Nothing is baked into the workspace; it drives the desktop
through Kasm's API and the session's own KasmVNC connection.
You can watch and take over. Sessions are created as your Kasm user, so they show up in
your Kasm dashboard. Open one to watch the agent work, or to handle a login or CAPTCHA yourself.
Your Kasm, your key. You run the server next to your own Kasm. Nothing goes through a third party.
### What's Kasm?
Kasm Workspaces streams disposable desktops and apps to your web browser,
each running in its own container on a server you control. Click "Chrome" and you get a fresh
Chrome in a browser tab; close it and it's wiped. kasm-use lets an AI agent sit down at those
desktops and use them the way a person would.
Demo (3x speed): Hermes Agent runs a three-session demo with kasm-use. Chrome, Terminal and
Minetest are started and driven in parallel while the Kasm dashboard shows each one live.
How the pieces connect:
mermaid
flowchart LR
agent["AI agent (any MCP client or Hermes)"] -->|"tool calls: look, click, type"| ku["kasm-use"]
ku -->|"start / list / stop (API key)"| api["Kasm API"]
api -->|"starts container"| desk
ku -->|"screenshots + input (VNC over websocket)"| proxy["Kasm proxy"]
you["You, in the Kasm dashboard"] -->|"watch or take over"| proxy
proxy --> desk["Session desktop (KasmVNC in a container)"]
## Status: early — testers wanted
kasm-use works well on the setup it was built on (Kasm 1.19.0 in linuxserver's Docker image;
Chrome, Terminal and Minetest workspaces; Claude Code and Hermes Agent as clients). It talks to
parts of Kasm that aren't documented, so other versions and install types are the big unknown.
If you try it, please open an issue,
whether it worked or not: your Kasm version, how Kasm is installed, the workspace image and your
MCP client are the most useful details.
## Tools
| Tool | What it does |
| kasmlist | Workspaces you can start, and your running sessions |
| kasmstart | Start a workspace (e.g. Chrome); returns once the session is running |
| kasmlook | Live screenshot of the session, returned as an image (~1 s) |
| kasmclick | Click at x,y in the latest screenshot's coordinates |
| kasmdrag | Drag from one point to another with the button held (menus, windows, sliders, drag and drop) |
| kasmtype | Type text into the focused field |
| kasmkey | Keys/shortcuts, e.g. ctrl+l, Return, Tab |
| kasmscroll | Scroll, optionally at a point |
| kasmstop | Destroy the session |
## Requirements
Kasm Workspaces 1.19 or newer (tested on 1.19.0).
A Kasm API key: Admin → Settings → Developers → API Keys → Add, then edit its permissions.
kasm-use 0.3 needs exactly these five (tested end to end with a key that has only these):