{"id":50261790,"url":"https://github.com/hyperlight-dev/hyperlight-unikraft","last_synced_at":"2026-05-27T10:40:33.402Z","repository":{"id":356782163,"uuid":"1233969751","full_name":"hyperlight-dev/hyperlight-unikraft","owner":"hyperlight-dev","description":"Run Unikraft unikernels on Hyperlight","archived":false,"fork":false,"pushed_at":"2026-05-27T07:23:38.000Z","size":1963,"stargazers_count":6,"open_issues_count":15,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-27T10:39:54.176Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyperlight-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":"GOVERNANCE.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-09T15:25:04.000Z","updated_at":"2026-05-26T19:51:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hyperlight-dev/hyperlight-unikraft","commit_stats":null,"previous_names":["hyperlight-dev/hyperlight-unikraft"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/hyperlight-dev/hyperlight-unikraft","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperlight-dev%2Fhyperlight-unikraft","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperlight-dev%2Fhyperlight-unikraft/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperlight-dev%2Fhyperlight-unikraft/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperlight-dev%2Fhyperlight-unikraft/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperlight-dev","download_url":"https://codeload.github.com/hyperlight-dev/hyperlight-unikraft/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperlight-dev%2Fhyperlight-unikraft/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33562772,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-27T10:40:32.573Z","updated_at":"2026-05-27T10:40:33.391Z","avatar_url":"https://github.com/hyperlight-dev.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n    \u003ch1\u003eHyperlight\u003c/h1\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/hyperlight-dev/hyperlight/refs/heads/main/docs/assets/hyperlight-logo.png\" width=\"150px\" alt=\"hyperlight logo\"/\u003e\n    \u003cp\u003e\u003cstrong\u003eHyperlight is a lightweight Virtual Machine Manager (VMM) designed to be embedded within applications. It enables safe execution of untrusted code within \u003ci\u003emicro virtual machines\u003c/i\u003e with very low latency and minimal overhead.\u003c/strong\u003e \u003cbr\u003e We are a \u003ca href=\"https://cncf.io/\"\u003eCloud Native Computing Foundation\u003c/a\u003e sandbox project. \u003c/p\u003e\n\u003c/div\u003e\n\n# hyperlight-unikraft\n\nRun [Unikraft](https://unikraft.org/) unikernels on [Hyperlight](https://github.com/hyperlight-dev/hyperlight), a lightweight Virtual Machine Manager (VMM) designed for embedded use within applications.\n\n## Overview\n\nThis project enables running Linux applications (Python, Node.js, Go, Rust, C/C++) on Hyperlight micro-VMs using Unikraft as the guest kernel. It provides:\n\n1. **hyperlight-unikraft** - A CLI host that loads and runs Unikraft kernels on Hyperlight\n2. **Example configurations** - Ready-to-use kraft configs for building various applications\n\n## Architecture\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│  Your Application (Python, Node.js, Go, Rust, C/C++)         │\n│  (runs as ELF binary inside the VM)                          │\n├──────────────────────────────────────────────────────────────┤\n│  Unikraft Kernel (ELF loader + VFS + POSIX)                  │\n│  - Mounts initrd as ramfs                                    │\n│  - Loads and executes application ELF                        │\n├──────────────────────────────────────────────────────────────┤\n│  hyperlight-unikraft (embedded Hyperlight host)              │\n│  - Loads kernel ELF + initrd                                 │\n│  - Passes arguments via magic header in initrd               │\n├──────────────────────────────────────────────────────────────┤\n│  Hyperlight VMM (hypervisor interface)                       │\n│  - Creates micro-VM with identity-mapped page tables         │\n│  - Provides PEB structure with memory regions                │\n├──────────────────────────────────────────────────────────────┤\n│  KVM (Linux) / MSHV (Windows)                                │\n└──────────────────────────────────────────────────────────────┘\n```\n\n### How It Works\n\n1. **Host loads kernel and initrd**: `hyperlight-unikraft` reads the Unikraft kernel ELF and optional initrd (CPIO archive)\n2. **Arguments embedded in initrd**: Application arguments are prepended to the initrd with a magic header (`HLCMDLN\\0`)\n3. **VM starts**: Hyperlight creates a micro-VM with identity-mapped memory and jumps to the kernel entry point\n4. **Kernel extracts initrd**: Unikraft mounts the initrd as a RAM filesystem, extracts the embedded cmdline\n5. **Application runs**: The ELF loader loads and executes the application binary (e.g., `/usr/bin/python3`)\n6. **Output via console**: Application output goes through `outb` to port 0xE9, which Hyperlight captures\n\n### Key Features\n\n- **Thin, opt-in host surface** — by default, the guest has no access to the host filesystem, network, or any host functions. When you enable features like `--mount`, `--net`, or `--enable-tools`, a single `__dispatch` JSON-RPC bridge is registered as the only guest→host channel. See [HOST_FUNCTIONS.md](HOST_FUNCTIONS.md) for the full list of dispatchable operations\n- **Identity-mapped memory** - Simplified memory layout (vaddr == paddr)\n- **Generic cmdline mechanism** - Pass arguments to any application via `-- arg1 arg2 ...`\n- **Fast cold start** - Hyperlight's lightweight design enables millisecond startup times\n\n### Benchmarks\n\nPerformance and density benchmarks run on every push to `main` and on PRs. Historical trends are available at:\n\n- [Linux benchmarks](https://hyperlight-dev.github.io/hyperlight-unikraft/dev/bench/linux/)\n- [Windows benchmarks](https://hyperlight-dev.github.io/hyperlight-unikraft/dev/bench/windows/)\n\n## Prerequisites\n\nCommon on both Linux and Windows:\n\n- [Rust](https://rustup.rs/) 1.89+\n- [Docker](https://www.docker.com/) (builds the rootfs CPIO archives)\n- [`just`](https://github.com/casey/just) (build runner — replaces Make)\n\nLinux-only (needed to build Unikraft kernels locally):\n\n- KVM (`/dev/kvm` readable/writable)\n- Go 1.25+ (builds `kraft-hyperlight`)\n\nWindows-only:\n\n- Windows Hypervisor Platform (`Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform`; reboot)\n- Developer Mode enabled (Settings → For developers → Developer Mode)\n- Kernels are pulled pre-built from GHCR; `kraft-hyperlight` is not required.\n\n## Setup\n\n### Linux — from scratch\n\n```bash\n# 1. Toolchain\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\ncargo install just\n\n# 2. kraft-hyperlight (builds Unikraft kernels)\ngit clone --branch plat-hyperlight https://github.com/unikraft/kraftkit/\ncd kraftkit \u0026\u0026 go build -o kraft-hyperlight ./cmd/kraft\nsudo mv kraft-hyperlight /usr/local/bin/ \u0026\u0026 cd ..\n\n# 3. This repo + host CLI\ngit clone https://github.com/hyperlight-dev/hyperlight-unikraft.git\ncd hyperlight-unikraft/host\ncargo build --release\nsudo cp target/release/hyperlight-unikraft /usr/local/bin/\ncd ..\n\n# 4. Run any example\ncd examples/helloworld-c\njust build      # build the Unikraft kernel with kraft-hyperlight\njust rootfs     # build the rootfs CPIO via Docker\njust run\n```\n\n### Python on Hyperlight with `pyhl`\n\nFor Python workloads specifically, the `pyhl` binary wraps the\n`python-agent-driver` image (kernel + CPIO with numpy/pandas/pydantic/\nyaml/jinja2/bs4/tabulate/click/tenacity/tqdm/openpyxl/pypdf/markdown-it-py/\npillow/lxml/cryptography/dateutil/dotenv preloaded) behind a simple\n`setup` / `run` workflow:\n\n```bash\n# One-time: build the driver image (kernel + CPIO)\ncd examples/python-agent-driver\njust rootfs \u0026\u0026 just build\ncd ../..\n\n# Install pyhl\ncargo install --git https://github.com/hyperlight-dev/hyperlight-unikraft \\\n    hyperlight-unikraft-host --bin pyhl\n\n# Point pyhl at the image you just built — creates ./.pyhl/ in cwd\npyhl setup --from examples/python-agent-driver\n\n# Run Python\npyhl run -c 'import pandas as pd; print(pd.DataFrame({\"x\":[1,2,3]}).sum().to_dict())'\npyhl run my_script.py\npyhl run my_script.py --repeat 4      # 5 hermetic invocations\n```\n\nEach `pyhl run` process pays a one-time warmup (~3 s for `Py_Initialize` +\npreloaded imports) on first call, then snapshots the post-warmup state.\nEvery invocation thereafter (including subsequent calls in the same process\nand `--repeat` iterations) restores from the snapshot and runs hermetic\nat ~100 ms — `__main__` globals and `sys.modules` don't leak between runs.\n\n`pyhl setup` is idempotent — re-running reports the existing install and\nexits 0; pass `--force` to overwrite. Artifacts are found via\n`--dest`/`$PYHL_HOME` / `./.pyhl/` / `~/.local/share/pyhl/`, in that order.\n\n### Windows — from scratch\n\n```powershell\n# 1. Toolchain\n# Install Rust via https://www.rust-lang.org/tools/install\ncargo install just\n\n# 2. This repo + host CLI\ngit clone https://github.com/hyperlight-dev/hyperlight-unikraft.git\ncd hyperlight-unikraft\\host\ncargo build --release\nCopy-Item target\\release\\hyperlight-unikraft.exe $env:USERPROFILE\\.cargo\\bin\\ -Force\ncd ..\n\n# 3. Run any example (kernel pulled from GHCR)\ncd examples\\helloworld-c\njust build      # docker pull ghcr.io/hyperlight-dev/hyperlight-unikraft/helloworld-c-kernel\njust rootfs     # docker build + extract CPIO\njust run\n```\n\n### What each recipe does\n\n| Recipe | Linux | Windows |\n|--------|-------|---------|\n| `just build` | `kraft-hyperlight build` | `docker pull` the pre-built kernel from GHCR |\n| `just rootfs` | `docker build --target cpio` + extract the CPIO | same |\n| `just run` | `hyperlight-unikraft \u003ckernel\u003e --initrd ...` | same |\n| `just clean` | remove `.unikraft/` and the CPIO | same |\n\n## Examples\n\n| Example | Binary | Notes |\n|---------|--------|-------|\n| `helloworld-c` | Static PIE C binary | Compiled with `musl-gcc` |\n| `rust` | Static PIE Rust binary | Compiled with `rustc --target x86_64-unknown-linux-musl` |\n| `python` | CPython 3.12 | Rootfs from Docker, script passed via cmdline |\n| `go` | Static PIE Go binary | Compiled with musl via Docker for CGO support |\n| `nodejs` | Node.js 21 | Rootfs from Alpine, script passed via cmdline |\n| `hostfs-posix-c` | C + unmodified POSIX | `open`/`read`/`write`/`mkdir` against `/host`, forwarded by `lib/hostfs` |\n| `hostfs-posix-py` | Python + stdlib | Same as `hostfs-posix-c` using `open()`/`os.mkdir`/`os.stat` |\n\n### Host filesystem sandbox\n\n`--mount HOST_DIR[:GUEST_PATH]` preopens a host directory for the guest:\n\n```bash\n# Default: guest-visible at /host\nhyperlight-unikraft kernel --initrd app.cpio --mount ./work\n\n# Custom guest mount point\nhyperlight-unikraft kernel --initrd app.cpio --mount ./work:/data\n```\n\n`lib/hostfs` in the guest auto-mounts `HOST_DIR` at `GUEST_PATH` (default\n`/host`); unmodified POSIX calls (`open`, `read`, `write`, `stat`,\n`mkdir`, `truncate`, …) are forwarded by the VFS driver to the host's\n`FsSandbox` tool handlers. The guest mount point is advertised runtime\nvia an `HLHSMNT` TLV in init_data, so one kernel build can serve\ndifferent mount points. Reserved kernel dirs (`/`, `/bin`, `/dev`,\n`/proc`, `/sys`, `/usr`) are refused to avoid shadowing the initrd.\n\nEvery path the guest sends is resolved relative to `HOST_DIR` and any\nescape (via `..` or symlinks) is rejected host-side.\n\nKnown limitation: `opendir`/`readdir` don't work yet (see\n[lib/hostfs/README.md](https://github.com/unikraft/unikraft/blob/plat-hyperlight/lib/hostfs/README.md)). Stat and enumerate known paths instead.\n\n### Running ad-hoc code (no initrd rebuild)\n\n`--exec CODE` / `-e CODE` feeds a snippet to the guest interpreter as\n`-c CODE`. The host handles all the argparse-escape quoting internally,\nso you can pass arbitrary whitespace, quotes, and newlines without\nwrapping:\n\n```bash\nhyperlight-unikraft python-kernel --initrd python.cpio --memory 96Mi \\\n    --exec 'for i in range(3): print(i * i)'\n```\n\nWorks for any interpreter that treats `-c` as \"run the next arg as\ncode\" — CPython, `sh`, etc. `node -e` works identically with `-e`.\n\n`examples/hostfs-posix-py` wraps it in two Justfile recipes:\n\n```bash\njust exec \"print('hi'); print(2 + 2)\"\njust run-file path/to/myscript.py   # file's contents → --exec\n```\n\nNo `--mount` involved. No `/host/…` path contract. The host just passes\nargv.\n\n#### Passing extra script arguments\n\n`--exec` and positional `-- args` are mutually exclusive (clap enforces\nit at parse time) — they both populate argv, so letting both through\nwould silently lose one. If you need inline code *plus* extra `sys.argv`\narguments, drop back to the raw `--` form and do the quoting yourself:\n\n```bash\nhyperlight-unikraft python-kernel --initrd python.cpio --memory 96Mi \\\n    -- -c '\"import sys; print(sys.argv[1:])\"' alpha beta gamma\n# =\u003e ['alpha', 'beta', 'gamma']\n```\n\nThe inner `-c` payload is wrapped in outer double-quotes so `uk_argparse`\npreserves whitespace, with internal quotes backslash-escaped. Anything\nafter is plain argv.\n\n### Running with Arguments\n\nFor interpreted languages, pass the script path after `--`:\n\n```bash\n# Python\nhyperlight-unikraft kernel --initrd python.cpio --memory 256Mi -- /script.py arg1 arg2\n\n# Node.js\nhyperlight-unikraft kernel --initrd node.cpio --memory 512Mi -- /app/server.js --port 8080\n```\n\n## CLI Options\n\n```\nhyperlight-unikraft [OPTIONS] \u003cKERNEL\u003e [-- \u003cAPP_ARGS\u003e...]\n\nArguments:\n  \u003cKERNEL\u003e              Path to the Unikraft kernel binary\n  \u003cAPP_ARGS\u003e...         Arguments passed to the application (after --)\n\nOptions:\n      --initrd \u003cCPIO\u003e          Path to initrd/rootfs CPIO archive\n  -m, --memory \u003cMEMORY\u003e        Memory allocation (e.g., 256Mi, 512Mi, 1Gi) [default: 512Mi]\n      --stack \u003cSTACK\u003e          Stack size (e.g., 8Mi) [default: 8Mi]\n  -q, --quiet                  Quiet mode — suppress host-side status messages\n      --enable-tools           Enable tool dispatch via __dispatch host function\n      --mount \u003cHOST[:GUEST]\u003e   Preopen a host directory for the guest's sandboxed filesystem\n                               (repeatable; default guest path: /host)\n      --net                    Enable guest networking (off by default)\n      --net-allow \u003cHOST_OR_IP\u003e Restrict networking to listed hosts/IPs (implies --net; repeatable;\n                               conflicts with --net-block)\n      --net-block \u003cHOST_OR_IP\u003e Block listed hosts/IPs, allow everything else (implies --net;\n                               repeatable; conflicts with --net-allow)\n      --port \u003cPORT\u003e            Allow guest to bind (listen) on this port (implies --net; repeatable)\n      --repeat \u003cN\u003e             Run the application N additional times via snapshot/restore [default: 0]\n  -e, --exec \u003cCODE\u003e            Inline code snippet — interpreter invoked with -c \u003cCODE\u003e\n                               (conflicts with positional -- \u003cAPP_ARGS\u003e)\n  -h, --help                   Print help\n  -V, --version                Print version\n```\n\n## Project Structure\n\n```\nhyperlight-unikraft/\n├── host/                    # Rust host (hyperlight-unikraft CLI + pyhl)\n├── examples/                # Ready-to-use kraft configs\n│   ├── helloworld-c/       # C (musl-gcc)\n│   ├── rust/               # Rust (musl)\n│   ├── python/             # CPython 3.12\n│   ├── python-agent-driver/# Python with pre-loaded packages (pyhl)\n│   ├── go/                 # Go (musl via Docker)\n│   ├── nodejs/             # Node.js 21\n│   ├── hostfs-posix-c/     # Host filesystem sandbox (C)\n│   ├── hostfs-posix-py/    # Host filesystem sandbox (Python)\n│   ├── dotnet/             # .NET\n│   ├── powershell/         # PowerShell\n│   ├── shell/              # Shell\n│   └── ...\n├── runtimes/                # Dockerfiles for runtime images\n└── demos/                   # Demo materials\n```\n\n## Dependencies\n\nThis project builds on the following upstream repositories:\n\n| Repository | Description |\n|------------|-------------|\n| [hyperlight-dev/hyperlight](https://github.com/hyperlight-dev/hyperlight) | Hyperlight VMM |\n| [unikraft/unikraft](https://github.com/unikraft/unikraft) | Unikraft core with Hyperlight platform support |\n| [unikraft/app-elfloader](https://github.com/unikraft/app-elfloader) | ELF loader application |\n| [unikraft/kraftkit](https://github.com/unikraft/kraftkit) | Kraft build tool with Hyperlight machine driver |\n\n## Join our Community\n\nPlease review the [CONTRIBUTING.md](./CONTRIBUTING.md) file for more information on how to contribute to\nHyperlight.\n\nThis project holds fortnightly community meetings to discuss the project's progress, roadmap, and any other topics of interest. The meetings are open to everyone, and we encourage you to join us.\n\n- **When**: Alternating Wednesdays at 09:00 and 07:00 (PST/PDT) [Convert to your local time](https://dateful.com/convert/pst-pdt-pacific-time?t=09)\n- **Where**: Zoom! - Agenda and information on how to join can be found in the [Hyperlight Community Meeting Notes](https://hackmd.io/blCrncfOSEuqSbRVT9KYkg#Agenda). Please log into hackmd to edit!\n\n## Chat with us on the CNCF Slack\n\nThe Hyperlight project Slack is hosted in the CNCF Slack #hyperlight. To join the Slack, [join the CNCF Slack](https://www.cncf.io/membership-faq/#how-do-i-join-cncfs-slack), and join the #hyperlight channel.\n\n## More Information\n\nFor more information, please refer to the main [Hyperlight project](https://github.com/hyperlight-dev/hyperlight).\n\n## Code of Conduct\n\nSee the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperlight-dev%2Fhyperlight-unikraft","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperlight-dev%2Fhyperlight-unikraft","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperlight-dev%2Fhyperlight-unikraft/lists"}