kasm-use

kasm-use

AI エージェントが Kasm Workspaces のデスクトップを使えるようにします。セッションの開始、画面の確認、クリック、入力、キーの押下、スクロール、セッションの停止を、あらゆる MCP クライアント（Claude Code、Claude Desktop、OpenCode、Cursor、…）から自然言語で指示できます。また、ネイティブの Hermes Agent プラグインとしても利用できます。

ほかの Kasm MCP サーバーはセッションの管理（開始、一覧表示、停止）を行います。kasm-use は実際にセッションを使用します。エージェントは Kasm 内でデスクトップを見て操作します。computer-use や browser-use と同じように使えます。

• 標準の Kasm イメージで動作します。 ワークスペースに何も組み込む必要はありません。Kasm の API と、セッション固有の KasmVNC 接続を介してデスクトップを操作します。
• 作業を見守り、引き継げます。 セッションはあなたの Kasm ユーザーとして作成されるため、Kasm ダッシュボードに表示されます。セッションを開けば、エージェントの作業を見守ったり、ログインや CAPTCHA の操作を自分で行ったりできます。
• あなたの Kasm には、あなたのキーを。 自分の Kasm と同じ環境でサーバーを実行します。第三者を経由することはありません。

Kasm とは？

Kasm Workspaces は、使い捨てのデスクトップとアプリを、管理下のサーバー上にあるそれぞれ専用のコンテナからウェブブラウザーへストリーミングします。「Chrome」をクリックすると、ブラウザーのタブに新しい Chrome が起動し、閉じると消去されます。kasm-use を使えば、AI エージェントがデスクトップにアクセスし、人と同じように操作できます。

デモ（3 倍速）：Hermes Agent が kasm-use で 3 つのセッションのデモを実行します。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 のバージョン、インストール方法、ワークスペースのイメージ、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 で必要なのは、次の 5 つだけです（これらの権限だけを持つキーでエンドツーエンドのテストを実施済みです）。

  • Images View、User、Users Auth Session — セッションの開始に必要です（これらがないと、kasm_start は Unauthorized で失敗します）。
  • Sessions View — セッションの状態確認と kasm_list に必要です。
  • Sessions Delete — kasm_stop に必要です。

  Kasm の実行 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	いいえ	Kasm の自己署名証明書を受け入れる場合は false（デフォルトは true）
KASM_USE_TOKEN	HTTP のみ	クライアントが送信する必要のあるベアラートークン

起動方法

ローカル（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 ユーザーごとにレプリカを 1 つ実行してください。サーバーは各セッションで最後に使用したスクリーンショットのサイズをメモリに保持し、クリック座標のマッピングに使用します。

プライベートネットワーク（LAN、VPN、Tailscale）上で実行してください。トークンを持つ人は誰でも、デスクトップを操作できます。

Hermes Agent

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

plugins.enabled で kasm を有効にし、上記の環境変数を設定してから、新しい Hermes セッション（/new）を開始すると、ツールが読み込まれます。

安全性

これらのツールを使用するエージェントはネットワーク上の実際のデスクトップを操作するため、マウスとキーボードを誰かに渡すのと同じように扱ってください。

• 使い捨てのワークスペースを使用してください。 実際のアカウントにログインしたセッションでエージェントを作業させないでください。また、エージェントが使用するワークスペースイメージにパスワードを保存しないでください。
• ウェブページがエージェントに指示を出すことがあります。 エージェントが閲覧するページ上のテキストが、エージェントの誘導を試みる可能性があります（プロンプトインジェクション）。重要な操作を行う際は、人間が監視してください。
• 通信はお使いのネットワークから行われます。 エージェントの閲覧内容はすべて、Kasm ホストの IP アドレスからアクセスされます。Kasm のワークスペースごとの VPN／外部通信設定で、別の経路に切り替えられます。
• ツールの説明では、エージェントにパスワード、MFA コード、支払い情報を入力しないこと、および CAPTCHA の対応をユーザーに任せることを指示しています。ただし、これはモデルへの案内であり、強制されるものではありません。

セキュリティモデル

kasm-use が保証できることとできないことは、Kasm に関する次の 2 つの事実に左右されます。

• Kasm API キーはユーザーごとではなく、サーバー全体に適用されます。 Kasm には、キーを 1 人のユーザーに限定する方法がありません。 上記の権限があれば、すべてのユーザーのセッションを確認して停止でき、Users Auth Session （「別のユーザーに代わってログイン」）を使うと、あらゆるユーザーのログイン情報を取得できます。
• request_kasm が返すトークンは、1 つのセッションではなく KASM_USER_ID のログイン情報です。 そのユーザーのすべてのセッションを開けます（Kasm 1.19.0 で確認済み：あるセッションから取得したトークンで、VNC 経由で同じユーザーの別のセッションを開けました）。

そのため、境界となるのは kasm-use 自体です。

• 各ツールが操作するのは、この kasm-use プロセスが開始したセッションだけです。 それ以外の session_id（あなた自身のもの、別のユーザーのもの、再起動前のもの）は、kasm_look と kasm_stop も含めて拒否されます。 kasm_list に表示されるのは kasm-use 自身のセッションだけです。
• モデルには API キーもトークンも渡されず、9 つのツールだけが渡されます。
• exec もスクリーンショット API も使用しません。 kasm-use は、セッション内で root としてコマンドを実行できる Kasm の exec API も、スクリーンショット API も使用しないため、それらの権限は必要ありません。

利用する際の注意点は次のとおりです。

• API キーは管理者資格情報として扱い、信頼できるマシンでのみ kasm-use を実行してください。 キーを入手した人は、kasm-use のコードがどう動作するかにかかわらず、あなたの Kasm にアクセスできます。
• エージェント専用の Kasm ユーザーを用意し、KASM_USER_ID に設定してください。 kasm-use に問題が起きても、エージェントのセッションとトークンをあなた自身のセッションから分離できます。（これはシートベルトであり、壁ではありません。キー自体は引き続きすべてのユーザーにアクセスできます。）
• Kasm の使い捨て可能な性質は役に立ちますが、万能ではありません。 永続プロファイルを有効にしない限り、セッション終了時にセッションは破棄されるため、エージェントが行った操作はセッションをまたいで残りません。リスクがあるのは、まだ実行中のセッションです。アカウントにログインしているセッションや、あなたが作業しているセッションが該当します。
• 操作ごとのポリシー（レート制限、キーのブロック、「先に人間に確認する」など）はまだありません。 範囲チェックに通ると、入力はそのまま VNC に送られます。VNC が認識するのはピクセルとキー入力だけなので、「このウィンドウには入力しない」といったルールをこのレイヤーで強制することはできません。

制限事項

• 操作できるのは kasm-use が開始したセッションだけで、再起動するまでに限られます。 セッショントークンはメモリ上にあります。再起動後も以前のセッションは Kasm 上で実行されたままですが、kasm-use は操作できません。Kasm のダッシュボードから停止してください。
• 入力結果として報告されるのは「送信済み」であり、「成功」ではありません。 次のスクリーンショットで確認してください。
• CAPTCHA、パスワード、MFA、支払いの操作はあなたに引き継がれます。 ツールの説明で、それらを入力しないようエージェントに指示されています。Kasm でセッションを開いて操作を引き継いでください。
• ローカルのブラウザツールと比べると低速です。各ステップでスクリーンショットを往復させるためです。

仕組み

kasm-use は、request_kasm が返すログイントークンを使い、Kasm 独自のプロキシ （wss://<kasm>/desktop/<id>/vnc/websockify）経由で各セッションの KasmVNC サーバーに直接接続します。 VNC クライアントは組み込みで、Python 標準ライブラリのみを使用します。

• 目： VNC 経由でフレームバッファー全体を読み取ります（ZRLE を zlib でデコード）。PNG として返されます。 これらのセッションでは Kasm のスクリーンショット API は使用しません。この API はビューアーが 接続している間だけ更新されるため、誰も見ていない状態では古いフレームが返されます。
• 手： VNC のポインターイベントとキーイベントを送信します。KasmVNC のポインターメッセージは 11 バイト（16 ビットのボタンマスクとスクロール量）で、標準の RFB の 6 バイトとは異なります。
• クリック位置はスクリーンショット上のピクセルで指定し、デスクトップの現在のサイズに合わせて拡大・縮小します。このサイズは接続時に VNC から通知されます。誰かがセッションを開き、Kasm がそのウィンドウに合わせてサイズを変更すると、サイズも変わります。
• 各ツール呼び出しでは短時間の VNC 接続を開き、往復通信を行ってから切断するため、切断時に入力が失われません。オーナーは同時に接続したままにできます。

依存する仕組みについて。 これらは公式の Kasm API ではありません。Kasm 独自のウェブビューアーが接続する方法を、Kasm 1.19.0 で確認したものです。

• Kasm のプロキシは request_kasm が返す username と session_token の Cookie を受け付け、Kasm ホストと一致する Origin ヘッダーを必要とします。
• プロキシの背後では、KasmVNC は VNC 認証を提供し、空のパスワードを受け付けます（認証はプロキシですでに完了しています）。
• KasmVNC のポインターメッセージは 11 バイトです（オープンソースのウェブクライアントで確認できます）。

Kasm のアップデートや異なるインストール方式によって、これらが変わる可能性があります。kasm-use が接続できなくなった場合は、これが原因と考えられます。問題を報告する際は、Kasm のバージョンとインストール方式を記載すると役立ちます。

ライセンス

MIT