feat : Add support for IncludeOS

[shivansh-source]

Description

This PR adds comprehensive support for IncludeOS, a unikernel framework written in C++ designed for building web and cloud applications, to the urunc container runtime. IncludeOS can execute on top of both solo5 (hvt/spt) and qemu hypervisors, making it a natural addition to urunc's growing unikernel ecosystem.

Changes Made

• pkg/unikontainers/unikernels/includeos.go - Core IncludeOS unikernel implementation with full Unikernel interface support

  • Network configuration with IPv4, gateway, and subnet mask
  • Block device management for storage
  • Compatible with both Solo5 (hvt/spt) and QEMU hypervisors

• pkg/unikontainers/unikernels/unikernel.go - Factory pattern integration for IncludeOS unikernel type registration

• tests/e2e/test_cases.go - Added Qemu-includeos and Hvt-includeos test cases

• docs/index.md - Updated support matrix to include IncludeOS

• docs/unikernel-support.md - Full IncludeOS documentation and usage guide

• docs/hypervisor-support.md - Added IncludeOS hypervisor reference and compatibility matrix

• docs/Sample-images.md - Added sample image documentation with building and deployment instructions

• README.md - Added IncludeOS to supported platforms table

Related issues

• Fixes Add support for IncludeOS #126

How was this tested?

Built IncludeOS applications using CMake and packaged as Docker containers with urunc labels to test both networking and non-networking scenarios.

Test Repository: https://github.com/shivansh-source/includeos-sample

Container Images Used:

• shivansh1111/includeos-sample:latest (simple "Hello, world!" application)
• shivansh1111/includeos-http-server:latest (HTTP server with networking)

Test Approach 1: Without Networking (Basic Application)

```bash
# Load image into containerd
docker save shivansh1111/includeos-sample:latest | \
  sudo ctr -n k8s.io images import -

# Run with urunc runtime
sudo ctr -n k8s.io run --rm --runtime io.containerd.urunc.v2 \
  docker.io/shivansh1111/includeos-sample:latest test

output

Hello, world!
Verified:

• ✅ IncludeOS unikernel boots successfully
• ✅ Application executes and outputs expected result ("Hello, world!")
• ✅ Container exits cleanly without crashes
• ✅ Runtime handles non-networked scenarios correctly

Test Approach 2: With Networking (HTTP Server)

# Load image into containerd
docker save shivansh1111/includeos-http-server:latest | \
  sudo ctr -n k8s.io images import -

# Run with urunc runtime
sudo ctr -n k8s.io run --rm --runtime io.containerd.urunc.v2 \
  docker.io/shivansh1111/includeos-http-server:latest http_test
# HTTP Server listening on port 8080...
# From another terminal, verify network connectivity and HTTP response
curl http://localhost:8080
# Response: Hello, world!

Verified:

• ✅ Network interface (virtio) attaches and initializes correctly
• ✅ HTTP server listens on configured port
• ✅ Network connectivity works: host can communicate with unikernel
• ✅ Application responds to network requests successfully
• ✅ No crashes during VM initialization with network device

E2E Test Coverage

• ✅ QEMU-IncludeOS test case: Verified QEMU hypervisor compatibility
• ✅ Hvt-IncludeOS test case: Verified Solo5 (hvt) hypervisor compatibility
• ✅ Local e2e tests pass: make test_docker

Docker Images Available:

• shivansh1111/includeos-sample:latest - https://hub.docker.com/r/shivansh1111/includeos-sample
• shivansh1111/includeos-http-server:latest - https://hub.docker.com/r/shivansh1111/includeos-http-server

LLM usage

N/A

Checklist

• I have read the contribution guide
• The linter passes locally (make lint)
• The e2e tests of at least one tool pass locally (make test_docker)
• Added appropriate documentation for IncludeOS support
• If LLMs were used: I have read the llm policy.

[netlify]

✅ Deploy Preview for urunc ready!

Name	Link
🔨 Latest commit	24d6d47
🔍 Latest deploy log	https://app.netlify.com/projects/urunc/deploys/6a0b637336e3bc0008028d7c
😎 Deploy Preview	https://deploy-preview-619--urunc.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[shivansh-source]

@cmainas PTAL at the approach then i will move forward

[cmainas]

Hello @shivansh-source ,

if a PR is WIP then you can mark it as draft. The approach is the same for all guests in urunc. The important thing is to test it. Please take a look at #540 and use it a as a guide.

[shivansh-source]

@cmainas tested and added proper testing methods . ready for review

[shivansh-source]

/cc @cmainas

[cmainas]

Hello @shivansh-source ,

please read the contribution guide. Have you also tested networking?

[shivansh-source]

/cc @cmainas the network is tested also working mentioned in the description with the image and github repo mentioned .

[cmainas]

Hello @shivansh-source ,

please correct me, but as I can see you run the container with ctr and no networking. How do you test networking if there is no network in the container? You can just run it with docker, no reason to import it in containerd.

Also, why the PR template has been removed?

[shivansh-source]

@cmainas i tested this pr in 2 different ways :
1.without networking : Simple "Hello, world!" application boots successfully
2. with networking : HTTP server running and responding to requests (verified with Docker's -p 8080:8080 port mapping and curl)

[shivansh-source]

really sorry about the pr description i made it really confusing .

[cmainas]

Hello @shivansh-source , in your docker test it seems you do not specify urunc as a runtime.

[shivansh-source]

@cmainas yes . you are right .I've now tested IncludeOS directly with the urunc runtime using containerd and ctr.


tests confirm that IncludeOS runs successfully with the urunc runtime. I've updated the PR description to include these verified test commands using ctr with --runtime io.containerd.urunc.v2.

[cmainas]

Sure, but we should also test it with networking.

[shivansh-source]

@cmainas i tested it with docker which make the networking also with urunc as a runtime