Hyperlight

mcp-server-hyperlight

一个 MCP 服务，可在本地 Hyperlight 微型虚拟机中运行 Python，适用于任何 MCP 客户端：Claude Code、Claude Desktop、VS Code、Cursor 等。

该服务通过 hluk CLI，在独立的硬件隔离微型虚拟机中启动 Unikraft unikernel（Linux 上使用 KVM 或 MSHV，Windows 上使用 WHP，Apple silicon Mac 上使用 HVF）。无需账号、守护进程或 API 密钥，代码和数据都保留在你的计算机上。除非你通过 --net-allow 允许访问主机，否则来宾系统无法访问网络；除非挂载文件，否则也无法访问你的任何文件。

	Pyodide 服务	云端沙盒	mcp-server-hyperlight
隔离方式	Wasm，在 Deno 进程中运行	云端 VM 或容器	微型虚拟机，拥有独立内核
Python	仅 Pyodide 的软件包	完整	完整 CPython 3.12，原生 wheels
在你的计算机上运行	是	否	是
需要	Deno	账号、API 密钥	hluk 和虚拟机监控程序
就绪时间	数秒	数秒	约 40 毫秒（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）；每次运行一个调用：

[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 也支持将其作为桌面扩展使用，无需配置：从其发布页面下载 mcp-server-hyperlight-0.1.1.mcpb 并打开即可。它会通过 uv 从 PyPI 安装服务。其设置可配置 --timeout 和 --net-allow。

客户端启动服务时，服务会立即启动来宾系统。首次启动时，hluk 会拉取其发布版的 agent 镜像（约 400 MB，下载量为 130 MB），并保存该镜像启动后的热快照（约 800 MB），这需要数秒到几分钟；之后来宾系统即可在数毫秒内从快照启动。该镜像包含 CPython 3.12，以及 numpy、pandas、scipy、scikit-learn、matplotlib、pillow 和 requests。若要在客户端首次启动服务前完成准备，请运行 hluk run --runtime agent --exec 'print("ready")'。

工具

工具
run_python	运行 Python 代码。变量、导入项和函数会保留到下次调用，如同在 notebook 中一样。返回代码打印的内容（包括子进程的输出），以及末尾表达式在 Out: 后的值。发生错误时会返回回溯信息，并作为工具错误报告。
reset_sandbox	在代码结束运行或超时后，从热快照创建一个全新的来宾系统来替换当前系统；在 Linux 和 KVM 上约需 60 毫秒。通过 --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；可重复指定，或用逗号分隔多个主机或 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 的其他参数，每个选项对应一个参数：--hluk-arg=--mount --hluk-arg=/data:/data:ro 会以只读方式挂载 /data。
--startup-timeout SECONDS	300	等待虚拟机启动的最长时间；首次启动时会拉取镜像。

工具描述会告诉模型虚拟机具备什么：有哪些软件包、可访问哪些主机，以及能否看到你的任何文件。使用 --hluk-arg 挂载目录或开放网络后，描述就不再会说虚拟机两者皆无。

工作原理

此服务是 smolagents-hyperlight 执行器的轻量封装。执行器会将 hluk run 作为子进程启动，并通过控制台与虚拟机中的小型 Python 脚本通信。这两个软件包共用同一套虚拟机协议、测试，以及对虚拟机返回内容的限制。

• 一个虚拟机供服务的客户端使用，工具调用依次在其中执行，因此状态保持一致。若虚拟机启动失败，会在标准错误中报告，并在模型首次调用时告知模型；该次调用会重试启动。
• 两次调用之间，整个微型虚拟机都会暂停：调用结束后仍在运行的线程或子进程，只会在调用运行期间继续执行。
• 虚拟机不受信任：回复大小有限制（64 MiB，打印输出为 2 MiB），且服务使用前会进行检查。工具结果最多保留 100,000 个字符，截取开头和结尾；MCP 客户端所需的内容远少于 Agent 执行器。
• 服务通过标准输入和标准输出使用 MCP 通信，并将日志写入标准错误。hluk 自身的输出会单独保存；若虚拟机启动失败，会与错误信息一同提供。服务退出、输入关闭，或收到 SIGTERM 或 SIGINT 时，会停止虚拟机。

已知限制

• 仅支持 Python 和文本：代码生成的图像会以其 repr 返回。将图像保存到已挂载的目录中即可保留。
• 代码自行通过 pip 安装的软件包在重置后会消失；通过 --package 传入的软件包则会重新安装。
• 只有 1 个 vCPU，虚拟机中的线程会轮流运行，而非同时运行。
• 若服务退出时虚拟机仍在启动、拉取镜像或安装 --package 软件包，该虚拟机不会随服务一同停止，而会继续运行直至启动完成：在此之前，执行器不会向服务提供控制该虚拟机的句柄。
• 使用 hluk v0.19.1 或更早版本时，每个 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 用于测试本地构建的 hluk 及其 Agent 根文件系统，而非 PATH 中的 hluk 和已发布的镜像。