Hyperlight

mcp-server-hyperlight

An MCP server that runs Python in a local Hyperlight micro-VM, for any MCP client: Claude Code, Claude Desktop, VS Code, Cursor and others.

The server boots a Unikraft unikernel in its own hardware-isolated micro-VM (KVM or MSHV on Linux, WHP on Windows, HVF on Apple silicon Macs) through the hluk CLI. It needs no account, no daemon and no API key, and the code and its data stay on your machine. The guest has no network access unless you allow hosts with --net-allow, and none of your files unless you mount them.

Install

Install hluk v0.18.0 or later. On Linux or macOS:

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

On Windows, in PowerShell:

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

Then add the server to your client. It runs with uv's uvx, or with pip install mcp-server-hyperlight and the mcp-server-hyperlight command.

Claude Code:

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

Claude Desktop, Cursor and other clients that take a JSON config:

{

"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), with time for uvx to install the server on its first start, and for the first call to wait for the guest image (--startup-timeout, 300 s) and then run (--timeout, 30 s), one call at a time:

[mcp_servers.hyperlight]

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

The OpenAI Agents SDK runs it with MCPServerStdio(params={"command": "uvx", "args": ["mcp-server-hyperlight"]}, client_session_timeout_seconds=360), for the same first call; its default of 5 seconds is shorter than a call may run.

Claude Desktop also takes it as a Desktop Extension, which needs no config: download mcp-server-hyperlight-0.1.1.mcpb from its release and open it. It installs the server from PyPI with uv. Its settings set --timeout and --net-allow.

The server starts its guest as soon as the client starts it. The first time, hluk pulls the agent image of its release (about 400 MB, a 130 MB download) and saves a warm snapshot of it booted (about 800 MB), which takes some seconds to a few minutes; after that the guest starts from the snapshot in milliseconds. The image ships CPython 3.12 with numpy, pandas, scipy, scikit-learn, matplotlib, pillow and requests. To have both ready before a client first starts the server, run hluk run --runtime agent --exec 'print("ready")'.

Tools

A call that runs longer than --timeout (30 s by default) is stopped, and the guest replaced with a fresh one; so is a call that crashes the guest. The model is told its variables are gone. A call the client cancels before its turn does not run; one already running goes on until it ends or times out, as the server has no way yet to stop code short of its time limit.

Options

Pass them after the command, e.g. uvx mcp-server-hyperlight --net-allow pypi.org --net-allow files.pythonhosted.org --package sympy.

The tool descriptions tell the model what the guest has: its packages, which hosts it may reach, and whether it sees any of your files. With --hluk-arg, which can mount directories or open the network, they no longer say the guest has neither.

How it works

The server is a thin layer over smolagents-hyperlight's executor, which starts hluk run as a child process and talks to a small Python script in the guest over its console. The two packages share one guest protocol, its tests and its bounds on what the guest sends back.

• One guest serves the server's client, and tool calls take turns on it, so state stays consistent. A guest that fails to start is reported on the standard error, and to the model on its first call, which tries again.
• Between calls, the whole micro-VM is paused: a thread or subprocess a call leaves running only goes on while a call runs.
• The guest is not trusted: replies are bounded (64 MiB, 2 MiB of printed output) and checked before the server uses them. A tool result keeps at most 100,000 characters, its beginning and its end, as MCP clients take far less than an agent's executor does.
• The server speaks MCP on its standard input and output, and logs to its standard error. What hluk itself writes is kept apart, and comes with the error when a guest fails to start. It stops its guest as it exits, the input closed or on a SIGTERM or SIGINT.

Known limits

• Python only, and text only: an image the code makes comes back as its repr. Save it to a mounted directory to keep it.
• Packages installed by the code itself, with pip, are gone after a reset; those passed with --package are installed again.
• One vCPU, and threads in the guest take turns rather than run at once.
• A guest still starting when the server exits, pulling its image or installing --package packages, is not stopped with it, and runs until that start ends: the executor gives the server no handle on it before then.
• With hluk v0.19.1 or earlier, each Python subprocess, pip install included, leaves about 15 MiB of guest memory in use until the guest is restarted (a guest kernel bug, fixed in v0.20.0).
• CI tests the server on Linux (KVM) and Windows (WHP). hluk supports Apple silicon Macs too, but the server is not tested there yet.

Development

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

As for smolagents-hyperlight, HLUK_PATH, HLUK_INITRD and HLUK_SCRATCH_MB test a local build of hluk and its agent rootfs instead of the hluk on PATH and its published image.