kasm-use

kasm-use

让 AI Agent 使用 Kasm Workspaces 桌面：启动会话、查看屏幕、点击、输入文字、按键、滚动并停止会话——只需使用自然语言，即可通过任意 MCP 客户端（Claude Code、Claude Desktop、OpenCode、Cursor 等）使用，也可以作为原生的 Hermes Agent 插件使用。

其他 Kasm MCP 服务负责管理会话（启动、列出、停止）。kasm-use 会实际使用这些会话：Agent 能看到桌面并进行操作，就像在自己的 Kasm 中使用 computer-use 或 browser-use 一样。

• 适用于原版 Kasm 镜像。 工作区中无需预装任何内容；它通过 Kasm API 和会话自身的 KasmVNC 连接来驱动桌面。
• 你可以旁观并接管。 会话以你的 Kasm 用户身份创建，因此会显示在你的 Kasm 控制面板中。打开会话即可旁观 Agent 的操作，或亲自处理登录和 CAPTCHA。
• 你的 Kasm，你的密钥。 你可以在自己的 Kasm 旁运行服务。一切都不会经过第三方。

什么是 Kasm？

Kasm Workspaces 会将临时桌面和应用流式传输到 Web 浏览器中，每个桌面和应用都在你控制的服务器上的独立容器中运行。点击“Chrome”，浏览器标签页中就会打开一个全新的 Chrome；关闭后，所有内容都会被清除。kasm-use 让 AI Agent 能够在这些桌面前就座，并像人一样使用它们。

演示（3 倍速）：Hermes Agent 通过 kasm-use 运行一个三会话演示。Chrome、Terminal 和 Minetest 会并行启动并接受操作，同时 Kasm 控制面板实时显示每个会话。

各部分的连接方式：

flowchart LR
    agent["AI agent<br/>(any MCP client or Hermes)"] -->|"tool calls:<br/>look, click, type"| ku["kasm-use"]
    ku -->|"start / list / stop<br/>(API key)"| api["Kasm API"]
    api -->|"starts container"| desk
    ku -->|"screenshots + input<br/>(VNC over websocket)"| proxy["Kasm proxy"]
    you["You, in the<br/>Kasm dashboard"] -->|"watch or take over"| proxy
    proxy --> desk["Session desktop<br/>(KasmVNC in a container)"]

状态：早期阶段——欢迎测试

kasm-use 在其开发所用的配置中运行良好（linuxserver 的 Docker 镜像中的 Kasm 1.19.0；Chrome、Terminal 和 Minetest 工作区；Claude Code 和 Hermes Agent 客户端）。它会调用 Kasm 中尚未编写文档的部分，因此其他版本和安装类型仍有很大未知数。如果你试用了它，无论是否成功，都请提交问题：最有用的信息包括你的 Kasm 版本、Kasm 的安装方式、工作区镜像以及 MCP 客户端。

工具

工具	功能
kasm_list	可启动的工作区，以及你正在运行的会话
kasm_start	启动工作区（例如 Chrome）；会话运行后返回
kasm_look	返回会话的实时屏幕截图（约 1 秒）
kasm_click	根据最新屏幕截图中的坐标，在 x、y 位置点击
kasm_drag	按住鼠标按键从一点拖到另一点（菜单、窗口、滑块、拖放操作）
kasm_type	在当前聚焦的字段中输入文字
kasm_key	按键或快捷键，例如 ctrl+l、Return、Tab
kasm_scroll	滚动，可指定位置
kasm_stop	销毁会话

要求

• Kasm Workspaces 1.19 或更高版本（已在 1.19.0 上测试）。

• Kasm API 密钥：依次进入 Admin → Settings → Developers → API Keys → Add，然后编辑其权限。 kasm-use 0.3 只需要以下五项权限（已使用仅具有这些权限的密钥完成端到端测试）：

  • Images View、User、Users Auth Session — 用于启动会话（缺少这些权限时，kasm_start 会因 Unauthorized 而失败）。
  • Sessions View — 用于查看会话状态和运行 kasm_list。
  • Sessions Delete — 用于运行 kasm_stop。

  它不再调用 Kasm 的 exec API（Sessions Modify）或截图 API（Session Recordings View），因此，如果你因使用 0.2 或更早版本而授予了这些权限，可以移除它们。缺少权限时，需要该权限的工具会返回 Unauthorized。请先阅读安全模型： 这些权限作用于整个服务。

• 你的 Kasm 用户 ID，以便会话归属于你：依次进入 Admin → Access Management → Users → 打开你的用户； ID 位于页面 URL 中。

• 任意工作区镜像。kasm-use 启动的会话中不会安装任何内容。

配置

变量	必需	含义
KASM_API_URL	是	例如：https://kasm.example.com
KASM_API_KEY / KASM_API_KEY_SECRET	是	API 密钥对
KASM_USER_ID	是	创建会话时使用的 Kasm 用户
KASM_VERIFY_TLS	否	设为 false 以接受自签名的 Kasm 证书（默认值为 true）
KASM_USE_TOKEN	仅限 HTTP	客户端必须发送的 bearer token

运行

本地运行（stdio）——常用方式

MCP 客户端会自行启动服务。安装 uv 后：

{
  "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：

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

作为服务运行（可流式传输的 HTTP）

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

客户端通过请求头 Authorization: Bearer <KASM_USE_TOKEN> 连接到 http://host:8000/mcp。 健康检查：GET /healthz。每位 Kasm 用户运行一个副本：服务会在内存中记住每个 会话上次的截图尺寸，以映射点击坐标。

请将其部署在专用网络上（LAN、VPN、Tailscale）。任何拥有此 token 的人都能操控你的桌面。

Hermes Agent

pip install kasm-use                      # into Hermes's Python environment
cp -r hermes-plugin/kasm ~/.hermes/plugins/kasm

在 plugins.enabled 下启用 kasm，设置上述环境变量，然后启动新的 Hermes 会话（/new），以加载工具。

安全

拥有这些工具的 Agent 可以操控你网络中的真实桌面，因此请将其视同把鼠标和键盘交给他人。

• 使用临时工作区。 不要让 Agent 在已登录你真实账户的会话中工作，也不要在它使用的工作区镜像中保存密码。
• 网页可以影响 Agent。 它访问的页面上的文本可能会试图引导它（提示词注入）。涉及重要事项时，请安排人员监督。
• 流量来自你的网络。 Agent 浏览的内容都会通过 Kasm 主机的 IP 地址发出。Kasm 的每工作区 VPN/出站流量设置可以将流量路由到其他位置。
• 工具说明会告知 Agent 不要输入密码、MFA 代码或付款信息，并将 CAPTCHA 交由你处理，但这只是对模型的指导，并非强制执行。

安全模型

Kasm 的两项特性决定了 kasm-use 能做什么、不能承诺什么：

• Kasm API 密钥是全服务器级别的，不针对单个用户。 Kasm 无法将密钥限制为仅用于一个用户。 使用上述权限，它可以查看并停止任何用户的会话，而 Users Auth Session （“以其他用户身份登录”）功能可让它获取任意用户的登录凭据。
• request_kasm 返回的令牌是 KASM_USER_ID 的登录凭据，而非针对单个会话的令牌。 它可以打开该用户的所有会话（已在 Kasm 1.19.0 上验证：一个会话的令牌通过 VNC 打开了同一用户的另一个会话）。

因此，边界在于 kasm-use 本身：

• 每个工具只对这个 kasm-use 进程启动的会话执行操作。 其他任何 session_id（你的、其他用户的，或重启前的）都会被拒绝，包括用于 kasm_look 和 kasm_stop 的情况。 kasm_list 只显示 kasm-use 自己的会话。
• 模型永远看不到 API 密钥或任何令牌，只能看到这九个工具。
• 没有 exec，也没有截图 API。 kasm-use 不使用 Kasm 的 exec API（它能以 root 身份在会话中运行命令）或截图 API，因此不需要这些权限。

这对你意味着：

• 请将 API 密钥视为管理员凭据，并且只在你信任的机器上运行 kasm-use。 任何拿到密钥的人都能访问你的 Kasm，无论 kasm-use 的代码做什么。
• 为 Agent 单独创建一个 Kasm 用户，并将 KASM_USER_ID 设置为该用户。这样，如果 kasm-use 出现问题，Agent 的会话和令牌就会与您自己的会话分开。（这只是安全带，不是防护墙：密钥本身仍可访问所有用户。）
• Kasm 的会话可丢弃特性有所帮助，但作用有限。 会话结束后就会被丢弃（除非启用了持久化配置文件），因此 Agent 的操作不会在会话之外留存。风险在于仍在运行的会话：已登录某个账户的会话，或你正在使用的会话。
• 目前没有针对单项操作的策略（速率限制、屏蔽密钥、“先询问用户”）。通过范围检查后，输入会直接发送到 VNC。VNC 只能看到像素和按键，因此无法在此层强制执行“绝不在此窗口中输入”等规则。

限制

• 只能操作 kasm-use 启动的会话，而且仅限其重启之前。 会话令牌保存在内存中。重启后，之前的会话仍会在 Kasm 中运行，但 kasm-use 不会操作它们；请从 Kasm 控制面板停止这些会话。
• 输入操作报告的是“已发送”，而非“已成功”。 下一张截图才能确认结果。
• CAPTCHA、密码、多因素认证和付款需要由你处理。 工具描述会告知 Agent 切勿输入这些内容；请在 Kasm 中打开会话并接管操作。
• 与本地浏览器工具相比速度较慢：每一步都需要经过一次截图往返。

工作原理

kasm-use 通过 Kasm 自己的代理（wss://<kasm>/desktop/<id>/vnc/websockify），使用 request_kasm 返回的登录令牌，直接连接每个会话的 KasmVNC 服务。 VNC 客户端内置其中，且仅使用 Python 标准库。

• **观察：**通过 VNC 读取完整帧缓冲区（ZRLE，使用 zlib 解码），并以 PNG 格式返回。 这些会话不会使用 Kasm 的截图 API：只有在有查看器连接时，它才会刷新；如果无人查看，返回的就是过期画面。
• **操作：**发送 VNC 指针和按键事件。KasmVNC 的指针消息为 11 字节（16 位按钮掩码加滚动增量），而不是标准 RFB 的 6 字节。
• 点击位置以截图像素为单位，并会按桌面当前尺寸缩放。VNC 会在连接时报告该尺寸；有人打开会话、Kasm 将其调整为适合其窗口的大小时，尺寸会发生变化。
• 每次工具调用都会建立一个短暂的 VNC 连接，并在关闭前完成一次往返，因此断开连接时不会丢失输入。所有者可以同时保持连接。

**依赖条件。**这些都不是官方 Kasm API；这是对 Kasm 自带网页查看器连接方式的观察，适用于 Kasm 1.19.0：

• Kasm 的代理接受 request_kasm 返回的 username 和 session_token Cookie，并要求 Origin 标头与 Kasm 主机匹配。
• 在代理后方，KasmVNC 提供 VNC 身份验证，并接受空密码（代理已完成身份验证）。
• KasmVNC 的指针消息为 11 字节（可在其开源网页客户端中看到）。

Kasm 更新或不同的安装类型都可能导致上述情况发生变化。如果 kasm-use 停止连接，这很可能就是原因；提交问题时请提供 Kasm 版本和安装类型，以便排查。

许可证

MIT