Hyperlight

mcp-server-hyperlight

あらゆる MCP クライアント（Claude Code、Claude Desktop、VS Code、Cursor など）向けに、ローカルの Hyperlight マイクロ VM で Python を実行する MCP サーバーです。

このサーバーは hluk CLI を介して、専用のハードウェア分離型マイクロ VM（Linux では KVM または MSHV、Windows では WHP、Apple シリコン搭載 Mac では HVF）内で Unikraft のユニカーネルを起動します。アカウントもデーモンも API キーも不要で、コードとデータはお使いのマシン内にとどまります。--net-allow でホストを許可しない限り、ゲストはネットワークにアクセスできません。また、マウントしない限り、ファイルにもアクセスできません。

	Pyodide サーバー	クラウドサンドボックス	mcp-server-hyperlight
分離	Deno プロセス内の Wasm	クラウド VM またはコンテナー	マイクロ VM、独自のカーネル
Python	Pyodide のパッケージのみ	フル機能	フル機能の CPython 3.12、ネイティブホイール
マシン上で実行	はい	いいえ	はい
必要なもの	Deno	アカウント、API キー	hluk とハイパーバイザー
起動時間	数秒	数秒	約 40 ms（Linux、KVM）

インストール

hluk v0.18.0 以降をインストールします。Linux または macOS の場合：

curl -fsSL https://raw.githubusercontent.com/hyperlight-dev/hyperlight-unikraft/main/install.sh | sh

Windows の場合は、PowerShell で：

irm https://raw.githubusercontent.com/hyperlight-dev/hyperlight-unikraft/main/install.ps1 | iex

続いて、サーバーをクライアントに追加します。uv の uvx を使うか、pip install mcp-server-hyperlight を実行して mcp-server-hyperlight コマンドを使います。

Claude Code：

claude mcp add hyperlight -- uvx mcp-server-hyperlight

Claude Desktop、Cursor、その他の JSON 設定を使うクライアント：

{
  "mcpServers": {
    "hyperlight": {
      "command": "uvx",
      "args": ["mcp-server-hyperlight"]
    }
  }
}

VS Code（.vscode/mcp.json）：

{
  "servers": {
    "hyperlight": {
      "command": "uvx",
      "args": ["mcp-server-hyperlight"]
    }
  }
}

Codex（~/.codex/config.toml）では、初回起動時に uvx がサーバーをインストールする時間と、初回の呼び出しでゲストイメージを待つ時間（--startup-timeout、300 s）、その後に実行する時間（--timeout、30 s）を確保します。呼び出しは一度に 1 件ずつ処理されます。

[mcp_servers.hyperlight]
command = "uvx"
args = ["mcp-server-hyperlight"]
startup_timeout_sec = 60
tool_timeout_sec = 360

OpenAI Agents SDK では、同じ初回呼び出しに対して MCPServerStdio(params={"command": "uvx", "args": ["mcp-server-hyperlight"]}, client_session_timeout_seconds=360) を使って実行します。デフォルトの 5 秒では、呼び出しの実行時間に足りない場合があります。

Claude Desktop では、設定不要の Desktop Extension としても利用できます。リリースから mcp-server-hyperlight-0.1.1.mcpb をダウンロードして開いてください。uv を使って PyPI からサーバーをインストールします。設定では --timeout と --net-allow を指定します。

クライアントがサーバーを起動すると、サーバーはすぐにゲストを起動します。初回は hluk がリリースの agent イメージ（約 400 MB、ダウンロードサイズは 130 MB）を取得し、起動済みのイメージのウォームスナップショット（約 800 MB）を保存します。この処理には数秒から数分かかります。その後、ゲストはスナップショットから数ミリ秒で起動します。イメージには、numpy、pandas、scipy、scikit-learn、matplotlib、pillow、requests を含む CPython 3.12 が同梱されています。クライアントが初めてサーバーを起動する前に両方の準備を済ませるには、hluk run --runtime agent --exec 'print("ready")' を実行します。

ツール

ツール
run_python	Python コードを実行します。ノートブックと同様に、変数、インポート、関数は次の呼び出しまで保持されます。サブプロセスの出力も含め、コードが出力した内容と、末尾の式の値を Out: の後に返します。エラーの場合はトレースバックをツールエラーとして返します。
reset_sandbox	実行中のコードが終了するかタイムアウトした後、約 60 ms でウォームスナップショットから新しいゲストに置き換えます（Linux、KVM の場合）。--package で指定したパッケージは、--net-allow を使って再インストールされます。

--timeout（デフォルトは 30 s）を超えて実行される呼び出しは停止され、ゲストは新しいものに置き換えられます。ゲストがクラッシュした場合も同様です。モデルには変数が失われたことが通知されます。クライアントが実行順になる前にキャンセルした呼び出しは実行されません。すでに実行中の呼び出しは終了するかタイムアウトするまで続行されます。サーバーには、時間制限に達する前にコードを停止する手段がまだないためです。

オプション

コマンドの後に指定します。例：uvx mcp-server-hyperlight --net-allow pypi.org --net-allow files.pythonhosted.org --package sympy。

オプション	デフォルト
--net-allow HOST	なし	ゲストが接続できるホストまたは IP です。複数指定する場合は繰り返すか、コンマで区切ります。何も指定しない場合、すべての接続が拒否されます。
--package NAME	なし	イメージに含まれていない場合に、起動時とリセット後にゲストへインストールするパッケージです。インストールには、パッケージインデックス用の --net-allow が必要です。
--timeout SECONDS	30	呼び出しの最長実行時間です。そのため、リセットまたは次の呼び出しで待機する最長時間でもあります。
--runtime NAME	agent	実行する公開イメージです。名前または完全な参照で指定します。
--initrd PATH		代わりに実行する独自のルートファイルシステム CPIO です（CPython 3 が必要です）。
--scratch-mb MIB	イメージの値	ゲストメモリの MiB 数です。
--hluk-path PATH	PATH 上の hluk	それ以外の場合、インストール先は $HLUK_INSTALL_DIR、インストールスクリプトの ~/.local/bin（Windows では %LOCALAPPDATA%\hluk\bin）、または Cargo の $CARGO_HOME/bin（~/.cargo/bin）です。別の PATH でサーバーを起動するクライアント向けのオプションです。
--hluk-arg ARG		hluk run に渡す追加引数です。オプションごとに 1 つ指定します。--hluk-arg=--mount --hluk-arg=/data:/data:ro を指定すると、/data を読み取り専用でマウントします。
--startup-timeout SECONDS	300	ゲストの起動を待つ最長時間です。初回起動時にはイメージがプルされます。

ツールの説明では、ゲストが利用できるもの、つまりパッケージ、接続可能なホスト、自分のファイルが見えるかどうかをモデルに伝えます。ディレクトリをマウントしたりネットワークを開いたりできる --hluk-arg を使うと、ゲストにどちらもないとは説明されなくなります。

仕組み

このサーバーは、smolagents-hyperlight のエグゼキューター上に構築された薄いレイヤーです。子プロセスとして hluk run を起動し、コンソール経由でゲスト内の小さな Python スクリプトと通信します。2 つのパッケージは、ゲストプロトコルとそのテスト、およびゲストから返されるデータの上限を共有しています。

• 1 つのゲストがサーバーのクライアントに対応し、ツール呼び出しは順番に実行されるため、状態の一貫性が保たれます。起動に失敗したゲストは標準エラーに報告され、最初の呼び出しではモデルにも報告され、その呼び出しで再試行されます。
• 呼び出しの間、マイクロ VM 全体が一時停止します。呼び出し後も実行を続けるスレッドやサブプロセスも、呼び出しの実行中にのみ動作します。
• ゲストは信頼されていません。応答にはサイズ上限（64 MiB、出力は 2 MiB）が設けられ、サーバーが使用する前に検証されます。MCP クライアントがエージェントのエグゼキューターよりもはるかに少ない文字数しか扱わないため、ツールの結果は最大 100,000 文字に制限され、先頭と末尾が保持されます。
• サーバーは標準入力と標準出力で MCP を通信し、標準エラーにログを出力します。hluk 自身の出力は分離して保持され、ゲストの起動に失敗した場合はエラーとともに出力されます。サーバーの終了時、入力が閉じられたとき、または SIGTERM か SIGINT を受け取ったときに、ゲストを停止します。

既知の制限

• Python のみ、テキストのみです。コードが生成した画像は repr として返されます。画像を保持するには、マウントしたディレクトリに保存してください。
• コード自体で pip を使ってインストールしたパッケージは、リセット後に消えます。--package で指定したパッケージは再インストールされます。
• vCPU は 1 つです。ゲスト内のスレッドは同時に実行されず、順番に動作します。
• サーバー終了時に、イメージのプル中または --package のパッケージのインストール中で、まだ起動中のゲストはサーバーとともに停止せず、起動処理が終わるまで実行されます。それまではエグゼキューターがサーバーにそのゲストへのハンドルを渡さないためです。
• 各 Python サブプロセス（pip install を含む）は、ゲストを再起動するまで約 15 MiB のゲストメモリを使用します（ゲストカーネルのバグです）。
• CI では Linux（KVM）と Windows（WHP）上でサーバーをテストします。hluk は Apple シリコン搭載 Mac もサポートしていますが、サーバーはまだそこでテストされていません。

開発

pip install -e ../smolagents -e '.[test]'
pytest                    # unit tests, and the server end to end with a stand-in for hluk
RUN_ALL=1 pytest          # also the tests in a real micro-VM, with the hluk on PATH

smolagents-hyperlight と同様に、HLUK_PATH、HLUK_INITRD、HLUK_SCRATCH_MB を使うと、PATH 上の hluk とその公開イメージの代わりに、ローカルビルドの hluk とその agent ルートファイルシステムをテストできます。