nox-mirage unikernels#
Runnable examples for nox-mirage.eio. Each example is one direct-style Eio
program: it runs as a normal host process during development and cross-compiles
unchanged to Solo5, WASI, Xen, or Unikraft when that backend is available.
The examples declare only the devices they need. The same declaration builds the runtime arguments, connects the Eio resources, and produces the guest manifest.
See them run#
Install#
The examples are distributed as independent unikernel-<name> packages. Add
the BlackSun opam overlay, then install only the examples you want:
$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install unikernel-hello-world unikernel-sqlite unikernel-grpc
The packages install same-named commands:
unikernel-hello-world
unikernel-sqlite
unikernel-grpc
From this checkout, use the public command name through Dune:
dune exec -- unikernel-sqlite
The native backend presents network devices through an in-process gateway and block devices as files named after the declared device. This gives the guest the same device shape it receives under a tender while keeping the normal host debugging loop.
Build a guest#
Set up the cross toolchain once, then build or run any example directory:
mrg up
mrg build -t solo5 unikernels/bin/storage/sqlite
mrg run --disk disk:disk unikernels/bin/storage/sqlite
mrg also accepts the other configured targets, such as wasi, xen, and
unikraft. An example's README documents any network ports, block images, or
peer process needed for its particular demo.
Examples#
Network#
The paired client/server examples walk up the guest network stack:
- Ethernet, ARP, IPv4, and IPv6
- ICMP, UDP, and TCP
- iperf3 measures the real guest TCP data path in
both directions against the stock
iperf3implementation. - DNS, HTTP, WebSocket, TLS, and SSH
Each link points to the client; its sibling server lives alongside it.
Storage#
- tar reads a host-built archive as a read-only asset store.
- FAT formats a blank volume and demonstrates persistence across two boots.
- KV contrasts a persistent notafs store with an in-memory store of the same shape.
- SQLite persists a relational database on a block device; SQL shell exposes one over SSH.
- Git client and Git server clone and serve repositories stored on notafs.
- etcd serves the v3 KV API over gRPC and is driven by
etcdctl.
Applications#
- gRPC, Docker, Stripe, and OAuth are complete protocol appliances driven by ordinary clients.
- DHCP, DNS resolution, Happy Eyeballs, and firewall/NAT demonstrate higher-level network policy.
IoT, space, and AI#
- Bluetooth LE and the Matter controller/device pair cover connected-device protocols.
- TM downlink receives CCSDS transfer frames, reassembles packets, and stores telemetry in SQLite.
- Object detection and TESSERA offload inference through vAccel without shipping a model runtime in the guest.
Introspection#
- pstree renders live TCP connections and their application layers.
- self-sql exposes the running TCP stack as a SQL table.
- observability producer streams runtime events to a host collector.



