kasm-use 0.1.0__py3-none-any.whl

kasm_use/__init__.py

@@ -0,0 +1,2 @@
+"""Control Kasm Workspaces desktops from any MCP client."""
+__version__ = "0.1.0"

kasm_use/server.py

@@ -0,0 +1,115 @@
+"""kasm-use: Kasm Workspaces desktop control over MCP.
+
+  kasm-use                              stdio (the client launches it; the usual way)
+  kasm-use --transport http [--host 0.0.0.0] [--port 8000]
+                                        streamable HTTP at /mcp; requires KASM_USE_TOKEN,
+                                        sent by clients as `Authorization: Bearer <token>`
+"""
+import argparse
+import asyncio
+import contextlib
+import hmac
+import json
+import os
+import sys
+
+from mcp import types
+from mcp.server.lowlevel import Server
+
+from . import __version__, tools
+
+HANDLERS = {name: fn for name, fn, _, _ in tools._TOOLS}
+
+server = Server("kasm", version=__version__, instructions=(
+    "Operate Kasm Workspaces desktops. Typical loop: kasm_start (or reuse a running session "
+    "from kasm_list) -> kasm_look -> act (click/type/key/scroll) -> kasm_look to confirm. "
+    "Never type passwords, MFA codes or payment details; stop and ask the owner to take over. "
+    "Stop at CAPTCHAs and hand them to the owner. Call kasm_stop when done."))
+
+
+@server.list_tools()
+async def list_tools() -> list[types.Tool]:
+    return [types.Tool(name=n, description=d, inputSchema=p) for n, _, d, p in tools._TOOLS]
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict):
+    if name not in HANDLERS:
+        raise ValueError(f"Unknown tool {name}")
+    # The tools are blocking (urllib + sleeps); keep the event loop free.
+    result = await asyncio.to_thread(HANDLERS[name], arguments or {})
+    if isinstance(result, dict) and result.get("_multimodal"):
+        out = []
+        for part in result["content"]:
+            if part["type"] == "text":
+                out.append(types.TextContent(type="text", text=part["text"]))
+            elif part["type"] == "image_url":
+                header, b64 = part["image_url"]["url"].split(",", 1)
+                out.append(types.ImageContent(type="image", data=b64, mimeType=header[5:].split(";")[0]))
+        return out
+    parsed = json.loads(result)
+    if not parsed.get("ok", True):
+        # Surface tool errors as MCP tool errors so clients show them as failures.
+        raise RuntimeError(parsed["error"])
+    return [types.TextContent(type="text", text=result)]
+
+
+def _check_env() -> None:
+    missing = [v for v in tools._REQUIRED_ENV if not os.environ.get(v)]
+    if missing:
+        sys.exit(f"kasm-use: missing environment variables: {', '.join(missing)}")
+
+
+async def _stdio() -> None:
+    from mcp.server.stdio import stdio_server
+    async with stdio_server() as (read, write):
+        await server.run(read, write, server.create_initialization_options())
+
+
+def _http(host: str, port: int) -> None:
+    import uvicorn
+    from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
+    from starlette.applications import Starlette
+    from starlette.responses import JSONResponse
+    from starlette.routing import Mount, Route
+
+    token = os.environ.get("KASM_USE_TOKEN")
+    if not token:
+        sys.exit("kasm-use: KASM_USE_TOKEN is required for --transport http")
+    manager = StreamableHTTPSessionManager(app=server, stateless=True)
+
+    async def mcp_app(scope, receive, send):
+        given = dict(scope.get("headers") or []).get(b"authorization", b"").decode()
+        if not hmac.compare_digest(given, f"Bearer {token}"):
+            await JSONResponse({"error": "unauthorized"}, status_code=401)(scope, receive, send)
+            return
+        await manager.handle_request(scope, receive, send)
+
+    async def health(_request):
+        return JSONResponse({"ok": True, "version": __version__, "tools": len(HANDLERS)})
+
+    @contextlib.asynccontextmanager
+    async def lifespan(_app):
+        async with manager.run():
+            yield
+
+    app = Starlette(routes=[Route("/healthz", health), Mount("/mcp", app=mcp_app)], lifespan=lifespan)
+    uvicorn.run(app, host=host, port=port, log_level="info")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(prog="kasm-use", description="Kasm Workspaces desktop control over MCP")
+    ap.add_argument("--transport", choices=["stdio", "http"], default=os.environ.get("KASM_USE_TRANSPORT", "stdio"))
+    ap.add_argument("--host", default=os.environ.get("KASM_USE_HOST", "127.0.0.1"))
+    ap.add_argument("--port", type=int, default=int(os.environ.get("KASM_USE_PORT", "8000")))
+    ap.add_argument("--version", action="version", version=__version__)
+    args = ap.parse_args()
+    _check_env()
+    if args.transport == "stdio":
+        asyncio.run(_stdio())
+    else:
+        _http(args.host, args.port)
+
+
+if __name__ == "__main__":
+    main()

kasm_use/tools.py

@@ -0,0 +1,312 @@
+"""Kasm Workspaces desktop control tools — work with any stock Kasm image.
+
+Shared by the MCP server (kasm_use.server) and the Hermes Agent plugin (register() below).
+
+Eyes  : POST /api/public/get_kasm_screenshot            (KasmVNC in the session renders a JPEG)
+Hands : POST /api/public/exec_command_kasm + xdotool     (installed into the session at start;
+                                                          stock images don't ship it)
+
+Configuration comes from the environment only:
+  KASM_API_URL, KASM_API_KEY, KASM_API_KEY_SECRET  - a Kasm API key (session permissions only)
+  KASM_USER_ID       - the Kasm user sessions are created for, so the owner can watch/take over
+  KASM_VERIFY_TLS    - "false" to accept a self-signed Kasm certificate (default: verify)
+
+Coordinates: every click/scroll uses the coordinate space of the most recent kasm_look image for
+that session. The real desktop is usually much larger (and changes when the owner connects and
+KasmVNC resizes it), so we scale inside the session using `xdotool getdisplaygeometry`.
+
+Lessons baked in:
+- exec_command_kasm is fire-and-forget: it never returns command output.
+- The screenshot keeps the desktop's aspect ratio, so the returned JPEG is NOT the requested
+  size — always read its real dimensions (a 1280x720 request on a 3840x2008 desktop gives
+  1280x669; scaling Y by 720 put clicks ~35 real px too high).
+- Screenshots right after an action can be stale for a few seconds.
+"""
+from __future__ import annotations
+
+import base64
+import json
+import os
+import re
+import ssl
+import struct
+import time
+import urllib.error
+import urllib.request
+
+TOOLSET = "kasm"
+_REQUIRED_ENV = ["KASM_API_URL", "KASM_API_KEY", "KASM_API_KEY_SECRET", "KASM_USER_ID"]
+_SHOT_W, _SHOT_H = 1280, 800
+_INSTALL_WAIT_S = 90
+_CTX = (ssl.create_default_context() if os.environ.get("KASM_VERIFY_TLS", "true").lower() not in ("0", "false", "no")
+        else ssl._create_unverified_context())
+
+# kasm_id -> (image_width, image_height) of the last screenshot shown to the model.
+# Per process: one server instance serves one Kasm user.
+_LAST_SHOT: dict[str, tuple[int, int]] = {}
+
+
+# ----------------------------------------------------------------------------------- API
+def _call(endpoint: str, raw: bool = False, **payload):
+    body = dict(api_key=os.environ["KASM_API_KEY"], api_key_secret=os.environ["KASM_API_KEY_SECRET"], **payload)
+    req = urllib.request.Request(
+        f"{os.environ['KASM_API_URL'].rstrip('/')}/api/public/{endpoint}",
+        data=json.dumps(body).encode(), headers={"Content-Type": "application/json"})
+    try:
+        resp = urllib.request.urlopen(req, timeout=120, context=_CTX)
+        data = resp.read()
+    except urllib.error.HTTPError as e:
+        raise RuntimeError(f"Kasm {endpoint} HTTP {e.code}: {e.read()[:200]!r}") from None
+    if raw:
+        return data
+    parsed = json.loads(data or b"{}")
+    if isinstance(parsed, dict) and parsed.get("error_message"):
+        raise RuntimeError(f"Kasm {endpoint}: {parsed['error_message']}")
+    return parsed
+
+
+def _user() -> str:
+    return os.environ["KASM_USER_ID"]
+
+
+def _exec(kasm_id: str, cmd: str, env: dict | None = None, root: bool = False) -> None:
+    cfg = {"cmd": cmd, "environment": {"DISPLAY": ":1", **(env or {})}}
+    if root:
+        cfg["user"] = "root"
+    _call("exec_command_kasm", kasm_id=kasm_id, user_id=_user(), exec_config=cfg)
+
+
+def _jpeg_size(data: bytes) -> tuple[int, int] | None:
+    """(width, height) from a JPEG's SOF marker."""
+    i = 2
+    while i < len(data) - 9:
+        if data[i] != 0xFF:
+            i += 1
+            continue
+        marker = data[i + 1]
+        if marker in (0xC0, 0xC1, 0xC2):
+            h, w = struct.unpack(">HH", data[i + 5:i + 9])
+            return w, h
+        i += 2 + struct.unpack(">H", data[i + 2:i + 4])[0]
+    return None
+
+
+def _ok(**fields) -> str:
+    return json.dumps({"ok": True, **fields})
+
+
+def _err(msg: str) -> str:
+    return json.dumps({"ok": False, "error": msg})
+
+
+def _resolve_session(args: dict) -> str:
+    kid = (args.get("session_id") or "").strip()
+    if kid:
+        return kid
+    mine = [k for k in _call("get_kasms").get("kasms", [])
+            if str(k.get("user_id", "")).replace("-", "") == _user().replace("-", "")]
+    if not mine:
+        raise RuntimeError("No running Kasm session. Start one with kasm_start first.")
+    return mine[-1]["kasm_id"]
+
+
+# --------------------------------------------------------------------------------- tools
+def kasm_list(args, **kw):
+    try:
+        images = [{"workspace": i.get("friendly_name"), "image": i.get("name")}
+                  for i in _call("get_images").get("images", []) if i.get("enabled")]
+        sessions = [{"session_id": k["kasm_id"], "workspace": (k.get("image") or {}).get("friendly_name"),
+                     "status": k.get("operational_status")}
+                    for k in _call("get_kasms").get("kasms", [])
+                    if str(k.get("user_id", "")).replace("-", "") == _user().replace("-", "")]
+        return _ok(workspaces=images, sessions=sessions)
+    except Exception as e:
+        return _err(str(e))
+
+
+def kasm_start(args, **kw):
+    workspace = (args.get("workspace") or "Chrome").strip().lower()
+    try:
+        images = [i for i in _call("get_images").get("images", []) if i.get("enabled")]
+        matches = [i for i in images if workspace in (i.get("friendly_name") or "").lower()]
+        if not matches:
+            return _err(f"No workspace matching {workspace!r}. Available: "
+                        + ", ".join(sorted({i.get('friendly_name') for i in images})))
+        # Prefer the newest image tag when the same workspace exists more than once.
+        img = sorted(matches, key=lambda i: i.get("name") or "")[-1]
+        started = _call("request_kasm", image_id=img["image_id"], user_id=_user(), enable_sharing=False)
+        kid = started["kasm_id"]
+        for _ in range(60):
+            status = (_call("get_kasm_status", kasm_id=kid, user_id=_user()).get("kasm") or {}).get("operational_status")
+            if status == "running":
+                break
+            time.sleep(5)
+        else:
+            return _err(f"Session {kid} did not reach 'running'.")
+        # Hands: stock images lack xdotool; install it (Debian/Ubuntu images). Fire-and-forget,
+        # so wait for apt to finish.
+        _exec(kid, "sh -c 'command -v xdotool >/dev/null || { apt-get update -qq && "
+                   "DEBIAN_FRONTEND=noninteractive apt-get install -y -qq xdotool; } >/tmp/.kasm-use-xdotool.log 2>&1'",
+              root=True)
+        time.sleep(_INSTALL_WAIT_S)
+        return _ok(session_id=kid, workspace=img.get("friendly_name"), image=img.get("name"),
+                   note="Session is running and visible in the owner's Kasm dashboard. Call kasm_look next.")
+    except Exception as e:
+        return _err(str(e))
+
+
+def kasm_look(args, **kw):
+    try:
+        kid = _resolve_session(args)
+        time.sleep(float(args.get("wait_seconds", 2)))
+        img = b""
+        for _ in range(8):
+            img = _call("get_kasm_screenshot", raw=True, kasm_id=kid, user_id=_user(), width=_SHOT_W, height=_SHOT_H)
+            if img[:2] == b"\xff\xd8":
+                break
+            time.sleep(3)
+        if img[:2] != b"\xff\xd8":
+            return _err("Screenshot not available yet (the desktop may still be starting). Try again.")
+        size = _jpeg_size(img) or (_SHOT_W, _SHOT_H)
+        _LAST_SHOT[kid] = size
+        summary = (f"Screenshot of Kasm session {kid[:8]} ({size[0]}x{size[1]}). Give kasm_click / kasm_scroll "
+                   f"coordinates in THIS image's pixels. The view can lag a few seconds behind actions.")
+        return {
+            "_multimodal": True,
+            "content": [
+                {"type": "text", "text": summary},
+                {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64," + base64.b64encode(img).decode()}},
+            ],
+            "text_summary": summary,
+        }
+    except Exception as e:
+        return _err(str(e))
+
+
+def _scaled_xy(kid: str, x: int, y: int) -> tuple[str, str]:
+    w, h = _LAST_SHOT.get(kid, (0, 0))
+    if not w:
+        raise RuntimeError("Call kasm_look first so coordinates can be mapped to the screen.")
+    x, y = max(0, min(int(x), w - 1)), max(0, min(int(y), h - 1))
+    return f"$(( {x} * WIDTH / {w} ))", f"$(( {y} * HEIGHT / {h} ))"
+
+
+def kasm_click(args, **kw):
+    try:
+        kid = _resolve_session(args)
+        sx, sy = _scaled_xy(kid, args["x"], args["y"])
+        button = {"left": 1, "middle": 2, "right": 3}.get(args.get("button", "left"), 1)
+        repeat = "--repeat 2 " if args.get("double") else ""
+        _exec(kid, f"sh -c 'eval $(xdotool getdisplaygeometry --shell); "
+                   f"xdotool mousemove {sx} {sy} sleep 0.1 click {repeat}{button}'")
+        return _ok(session_id=kid, clicked=[args["x"], args["y"]])
+    except Exception as e:
+        return _err(str(e))
+
+
+def kasm_type(args, **kw):
+    text = args.get("text", "")
+    if not text:
+        return _err("text is required")
+    try:
+        kid = _resolve_session(args)
+        # Text travels as an env var, never inside the shell string: no quoting/injection issues.
+        _exec(kid, "sh -c 'xdotool type --delay 35 -- \"$KASM_USE_TEXT\"'", env={"KASM_USE_TEXT": text})
+        if args.get("press_enter"):
+            time.sleep(min(0.05 * len(text) + 0.5, 15))
+            _exec(kid, "sh -c 'xdotool key Return'")
+        return _ok(session_id=kid, typed_chars=len(text), pressed_enter=bool(args.get("press_enter")))
+    except Exception as e:
+        return _err(str(e))
+
+
+_KEY_RE = re.compile(r"^[A-Za-z0-9_+]+$")
+
+
+def kasm_key(args, **kw):
+    keys = [k for k in re.split(r"[\s,]+", args.get("keys", "")) if k]
+    bad = [k for k in keys if not _KEY_RE.match(k)]
+    if not keys or bad:
+        return _err(f"keys must be xdotool key names like ctrl+l, Return, Tab, Escape (invalid: {bad})")
+    try:
+        kid = _resolve_session(args)
+        _exec(kid, "sh -c 'xdotool key " + " ".join(keys) + "'")
+        return _ok(session_id=kid, keys=keys)
+    except Exception as e:
+        return _err(str(e))
+
+
+def kasm_scroll(args, **kw):
+    try:
+        kid = _resolve_session(args)
+        button = {"up": 4, "down": 5, "left": 6, "right": 7}.get(args.get("direction", "down"), 5)
+        amount = max(1, min(int(args.get("amount", 5)), 30))
+        move = ""
+        if "x" in args and "y" in args:
+            sx, sy = _scaled_xy(kid, args["x"], args["y"])
+            move = f"eval $(xdotool getdisplaygeometry --shell); xdotool mousemove {sx} {sy}; "
+        _exec(kid, f"sh -c '{move}xdotool click --repeat {amount} {button}'")
+        return _ok(session_id=kid, direction=args.get("direction", "down"), amount=amount)
+    except Exception as e:
+        return _err(str(e))
+
+
+def kasm_stop(args, **kw):
+    try:
+        kid = _resolve_session(args)
+        _call("destroy_kasm", kasm_id=kid, user_id=_user())
+        _LAST_SHOT.pop(kid, None)
+        return _ok(session_id=kid, stopped=True)
+    except Exception as e:
+        return _err(str(e))
+
+
+# ------------------------------------------------------------------------------ schemas
+_SID = {"session_id": {"type": "string", "description": "Kasm session id. Omit to use your newest running session."}}
+
+_TOOLS = [
+    ("kasm_list", kasm_list, "List Kasm workspaces you can start and your running sessions.",
+     {"type": "object", "properties": {}}),
+    ("kasm_start", kasm_start,
+     "Start a Kasm workspace session (e.g. 'Chrome', 'Terminal') as the owner, so they can watch it. "
+     "Takes ~2 minutes (it installs the input tool). Then call kasm_look.",
+     {"type": "object", "properties": {"workspace": {"type": "string", "description": "Workspace name, e.g. Chrome"}}}),
+    ("kasm_look", kasm_look,
+     "Screenshot the Kasm session so you can see it. Always look before clicking, and look again after "
+     "each action to confirm it worked.",
+     {"type": "object", "properties": {**_SID, "wait_seconds": {"type": "number", "description": "Pause before capturing (default 2)."}}}),
+    ("kasm_click", kasm_click, "Click at x,y in the coordinate space of the latest kasm_look image.",
+     {"type": "object", "required": ["x", "y"], "properties": {
+         **_SID, "x": {"type": "integer"}, "y": {"type": "integer"},
+         "button": {"type": "string", "enum": ["left", "right", "middle"]},
+         "double": {"type": "boolean"}}}),
+    ("kasm_type", kasm_type,
+     "Type text into the focused field of the Kasm session. NEVER type passwords, MFA codes, or payment "
+     "details — stop and ask the owner to take over the session for those.",
+     {"type": "object", "required": ["text"], "properties": {
+         **_SID, "text": {"type": "string"}, "press_enter": {"type": "boolean"}}}),
+    ("kasm_key", kasm_key, "Press keys/shortcuts in the Kasm session, e.g. 'ctrl+l', 'Return', 'Tab', 'Escape'.",
+     {"type": "object", "required": ["keys"], "properties": {**_SID, "keys": {"type": "string"}}}),
+    ("kasm_scroll", kasm_scroll, "Scroll the Kasm session, optionally at x,y from the latest kasm_look image.",
+     {"type": "object", "properties": {
+         **_SID, "direction": {"type": "string", "enum": ["up", "down", "left", "right"]},
+         "amount": {"type": "integer", "description": "Wheel clicks, 1-30 (default 5)"},
+         "x": {"type": "integer"}, "y": {"type": "integer"}}}),
+    ("kasm_stop", kasm_stop, "Stop (destroy) a Kasm session when the task is finished or the owner asks.",
+     {"type": "object", "properties": {**_SID}}),
+]
+
+
+def _available() -> bool:
+    return all(os.environ.get(v) for v in _REQUIRED_ENV)
+
+
+def register(ctx) -> None:
+    """Hermes Agent plugin entry point (see hermes-plugin/)."""
+    for name, handler, description, params in _TOOLS:
+        ctx.register_tool(
+            name=name, toolset=TOOLSET,
+            schema={"name": name, "description": description, "parameters": params},
+            handler=handler, check_fn=_available, requires_env=_REQUIRED_ENV,
+            description=description, emoji="🖥️",
+        )

kasm_use-0.1.0.dist-info/METADATA

@@ -0,0 +1,140 @@
+Metadata-Version: 2.5
+Name: kasm-use
+Version: 0.1.0
+Summary: Let AI agents drive Kasm Workspaces desktops (look, click, type) over MCP — works with stock Kasm images
+Project-URL: Homepage, https://github.com/rchurro/kasm-use
+Project-URL: Issues, https://github.com/rchurro/kasm-use/issues
+Author: rchurro
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,computer-use,hermes,kasm,kasm-workspaces,mcp
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Desktop Environment
+Requires-Python: >=3.10
+Requires-Dist: mcp<2,>=1.9
+Description-Content-Type: text/markdown
+
+# kasm-use
+
+Let an AI agent use a [Kasm Workspaces](https://kasmweb.com) 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](#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 own API.
+- **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.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `kasm_list` | Workspaces you can start, and your running sessions |
+| `kasm_start` | Start a workspace (e.g. `Chrome`) — takes ~2 min, see [Limitations](#limitations) |
+| `kasm_look` | Screenshot of the session, returned as an image |
+| `kasm_click` | Click at x,y in the latest screenshot's coordinates |
+| `kasm_type` | Type text into the focused field |
+| `kasm_key` | Keys/shortcuts, e.g. `ctrl+l`, `Return`, `Tab` |
+| `kasm_scroll` | Scroll, optionally at a point |
+| `kasm_stop` | Destroy the session |
+
+## Requirements
+
+- Kasm Workspaces **1.19 or newer** (the screenshot API needs 1.19 images).
+- A Kasm **API key**: Admin → Settings → Developers → API Keys → Add. Grant it only the session
+  permissions (create/list/destroy sessions, screenshot, exec). It does not need user or admin rights.
+- Your Kasm **user ID**, so sessions belong to you: Admin → Access Management → Users → open your user;
+  the ID is in the page URL.
+- A workspace image based on Debian/Ubuntu (all official `kasmweb/*` images are).
+
+## Configuration
+
+| Variable | Required | Meaning |
+| --- | --- | --- |
+| `KASM_API_URL` | yes | e.g. `https://kasm.example.com` |
+| `KASM_API_KEY` / `KASM_API_KEY_SECRET` | yes | the API key pair |
+| `KASM_USER_ID` | yes | the Kasm user sessions are created for |
+| `KASM_VERIFY_TLS` | no | `false` to accept a self-signed Kasm certificate (default `true`) |
+| `KASM_USE_TOKEN` | HTTP only | bearer token clients must send |
+
+## Run it
+
+### Locally (stdio) — the usual way
+
+Your MCP client starts the server itself. With [uv](https://docs.astral.sh/uv/) installed:
+
+```json
+{
+  "mcpServers": {
+    "kasm": {
+      "command": "uvx",
+      "args": ["kasm-use"],
+      "env": {
+        "KASM_API_URL": "https://kasm.example.com",
+        "KASM_API_KEY": "…",
+        "KASM_API_KEY_SECRET": "…",
+        "KASM_USER_ID": "…"
+      }
+    }
+  }
+}
+```
+
+Claude Code:
+
+```bash
+claude mcp add kasm -e KASM_API_URL=https://kasm.example.com -e KASM_API_KEY=… -e KASM_API_KEY_SECRET=… -e KASM_USER_ID=… -- uvx kasm-use
+```
+
+### As a service (streamable HTTP)
+
+```bash
+docker run -d -p 8000:8000 \
+  -e KASM_API_URL=https://kasm.example.com -e KASM_API_KEY=… -e KASM_API_KEY_SECRET=… \
+  -e KASM_USER_ID=… -e KASM_USE_TOKEN="$(openssl rand -hex 32)" \
+  ghcr.io/rchurro/kasm-use:latest
+```
+
+Clients connect to `http://host:8000/mcp` with the header `Authorization: Bearer <KASM_USE_TOKEN>`.
+Health check: `GET /healthz`. Run **one replica** per Kasm user: the server remembers each
+session's last screenshot size in memory to map click coordinates.
+
+Keep it on a private network (LAN, VPN, Tailscale). Anyone with the token can drive your desktops.
+
+### Hermes Agent
+
+```bash
+pip install kasm-use                      # into Hermes's Python environment
+cp -r hermes-plugin/kasm ~/.hermes/plugins/kasm
+```
+
+Enable `kasm` under `plugins.enabled`, set the environment variables above, and start a new
+Hermes session (`/new`) so the tools load.
+
+## Limitations
+
+- **First start is slow (~90 s extra).** Stock images don't include `xdotool`, so `kasm_start`
+  installs it in the session as root. Reusing a running session skips this.
+- **Screenshots can lag** a few seconds behind actions; the agent is told to look again to confirm.
+- **Kasm's exec API returns no output**, so actions report "sent", not "succeeded". The next
+  screenshot is the confirmation.
+- **CAPTCHAs, passwords, MFA and payments are handed to you.** The tool descriptions tell the agent
+  never to type them; open the session in Kasm and take over.
+- It's slow compared to a local browser tool: every step is a screenshot round trip.
+
+## How it works
+
+- **Eyes:** `POST /api/public/get_kasm_screenshot` (KasmVNC renders a JPEG).
+- **Hands:** `POST /api/public/exec_command_kasm` running `xdotool` inside the session.
+- Clicks are given in screenshot pixels and scaled to the real desktop size inside the session
+  (`xdotool getdisplaygeometry`), using the JPEG's actual dimensions — Kasm keeps the desktop's
+  aspect ratio, so the image is often not the size requested.
+
+## License
+
+MIT

kasm_use-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+kasm_use/__init__.py,sha256=1-gsZGuiR4Du8w0Nom8p0Y_uaPk76ErkhtxexE5_p-Y,82
+kasm_use/server.py,sha256=XwOnUXq1EJ4cOiW_KXWe22Xfds1BZL228N5z32ZR3YE,4601
+kasm_use/tools.py,sha256=CNiBv_WeQ8O3cjtUb0SIdDoZT9bEWXGBAdmMzQ9-0SI,14144
+kasm_use-0.1.0.dist-info/METADATA,sha256=UX_-2X06xdku9sws11pt8ZmnTxylKy2fEK7ZchhED8Y,5719
+kasm_use-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+kasm_use-0.1.0.dist-info/entry_points.txt,sha256=3AeHBUbYDuAExun8JMZcM73tIqQAy21kjcshycLa3BI,50
+kasm_use-0.1.0.dist-info/licenses/LICENSE,sha256=1xRbCUam2PldiO0CleiBfnPtHrd0mejKz-7aPzKQVn0,1064
+kasm_use-0.1.0.dist-info/RECORD,,

kasm_use-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

kasm_use-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+kasm-use = kasm_use.server:main

kasm_use-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rchurro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.