A high-performance minimal unikernel with a Python-based build system and automatic QEMU integration. MiniKraft demonstrates significant performance improvements over traditional Linux networking stacks.

Recent benchmarks show MiniKraft outperforming regular Linux:

• 71% faster latency: 0.19ms mean latency vs 0.67ms (Linux)
• 5.2% higher throughput: 96.8 packets/sec vs 92.0 packets/sec (Linux)
• Lower tail latency: More consistent performance with reduced standard deviation

Run sudo python3 benchmark_packets.py to run the echo server test and collect benchmarks. Optional dependencies (matplotlib, numpy) are in requirements.txt for generating plots.

• Minimal unikernel - Boots directly without an OS (Multiboot / PVH)
• Python build system - No Makefiles, pure Python
• Auto-run in QEMU - Automatically launches after build
• Virtio-net networking - UDP/TCP stack with low latency
• Threading support - Multi-threaded applications
• VGA graphics - Text mode and mode 13h (e.g. Pong demo)
• Input - Keyboard and mouse drivers, IDT and interrupt handling

Minikraft/
├── src/
│   ├── boot/           # Bootloader (boot.S, pvh.S)
│   ├── kernel/         # Kernel (console, memory, idt, vga, keyboard, mouse, thread)
│   ├── app/            # Application (app.c, pong.c)
│   ├── drivers/        # Virtio-net driver
│   ├── lib/            # Networking, virtio, PCI, socket driver, etc.
│   └── include/        # Headers (uk/, virtio/, sys/)
├── build.py            # Python build system
├── mklinux.py          # Linux image helper
├── benchmark_packets.py # Networking benchmarks
└── README.md

• GCC toolchain (gcc, as, ld)
• QEMU (qemu-system-x86_64)
• Python 3

Install on Ubuntu/Debian:

sudo apt-get install gcc qemu-system-x86 python3

Optional (for benchmark plots): pip install -r requirements.txt

cd Minikraft
python3 build.py

This will:

1. Clean the build directory
2. Build the unikernel
3. Automatically run it in QEMU

See QUICKSTART.md for a minimal walkthrough.

# Build only
python3 build.py build

# Clean build directory
python3 build.py clean

# Run in QEMU (builds if needed)
python3 build.py run

# Build and run (default)
python3 build.py all

# Print QEMU command without running
python3 build.py run --no-auto-run

# Network: user-mode (default) or TAP (requires root)
python3 build.py run --network user
python3 build.py run --network tap

# Bare metal build (no virtio/networking, e.g. for USB boot)
python3 build.py build --bare-metal

# Display: nographic (terminal) or VNC
python3 build.py run --nographic
python3 build.py run --vnc   # then vncviewer localhost:5900

# Enable logging / custom QEMU
python3 build.py run --enable-logging
python3 build.py run --qemu-path /path/to/qemu-system-x86_64

Press Ctrl+A then X to exit QEMU.

Edit src/app/app.c to add your application logic. The app_main() function is called after kernel initialization.

Add new source files in src/kernel/ (or src/lib/ for libraries) and they will be automatically compiled.

Edit build.py to modify compiler flags, linker script, QEMU arguments, and memory settings.

1. Bootloader (boot.S, pvh.S) - Multiboot/PVH entry, protected mode, jump to kernel
2. Kernel (kernel.c) - IDT, PIC, console, memory, VGA, keyboard, mouse, threading; then calls application
3. Application (app.c) - Your code runs here (or use Pong / echo server)
4. Drivers & lib - Virtio-net, PCI, socket layer, netdev, virtqueues
5. Build system (build.py) - Discovers sources, compiles, links, creates bootable image
6. QEMU - Runs the unikernel in a virtual machine

More detail: ARCHITECTURE.md.

• QUICKSTART.md - Minimal build and run
• ARCHITECTURE.md - Components and build process
• PONG_GAME.md - VGA Pong demo
• THREADING_README.md - Threading support
• CONTRIBUTING.md - How to contribute
• IP_STACK_README.md, NETWORKING_VERIFIED.md - Networking
• BOOTABLE_USB.md - Booting on real hardware

• Simpler - No complex library system
• Python build - Instead of Makefiles
• Minimal - Only essential features
• Self-contained - Everything in one directory

"No suitable GCC toolchain found"

• Install gcc: sudo apt-get install gcc
• Or cross-compiler: sudo apt-get install gcc-x86-64-elf

QEMU not found

• Install: sudo apt-get install qemu-system-x86

Build fails

• Check that all source files are present
• Verify GCC: gcc --version

Kernel doesn't boot

• Check QEMU output for errors
• Verify linker script
• Try python3 build.py run --no-auto-run to see the QEMU command

Display or input issues

• See QEMU_DISPLAY_FIX.md, QEMU_INPUT_FIX.md

The echo server receives Ethernet frames and echoes them back by swapping MAC addresses.

• Prints device info (MAC, MTU), waits for packets, echoes them and prints e.g. Echoed packet #N (X bytes).
• Run with: python3 build.py run

To verify:

1. Watch the console for "Echo Server Running" and "Echoed packet #N" messages.
2. Optional: sudo arping -c 5 10.0.2.15 (guest is often 10.0.2.15 with user-mode).

sudo ip tuntap add mode tap name tap0
sudo ip addr add 192.168.100.1/24 dev tap0
sudo ip link set tap0 up
python3 build.py run --network tap

See TEST_UDP_TAP.md, TEST_UDP_EXTERNAL.md for more.

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

This repository contains the open-source foundation of MiniKraft:

• Core unikernel (boot, kernel, memory, IDT, VGA, input)
• Virtio-net and UDP/TCP networking stack
• Build system and tooling
• Threading support
• Documentation

Proprietary components (not included in this repository):

• Metamorphic Compiler (Python-to-ASM toolchain)
• Micro-Slicing Algorithm
• PSADBW-Blockchain reliability layer
• Advanced SIMD optimizations
• Left-Right Threading optimizations

These are available through MiniKraft's commercial licensing. The open-source foundation provides a solid base and demonstrates core performance characteristics.

Contributions are welcome. Please see CONTRIBUTING.md. For major changes, open an issue first to discuss.

MiniKraft is inspired by Unikraft and aims to provide a simpler, more performant alternative for specific use cases.