Flora

A lightweight microVM, built with KVM.

Features • Installation • Usage

Features

• MicroVM Engine: Runs a 64-bit Linux guest with custom boot configuration using hardware virtualization
• Virtio Device Support: Guest I/O is equipped with supported implementations for virtio block, console, and network devices
• Network Isolation: Per-VM TAP interfaces and bridge-based networking with private IP allocation
• Custom Boot Pipeline: Boots Linux bzImage kernels with support for generic disk images and instance-specific entry scripts defined at launch
• Runtime Daemon: Rust-based daemon with a CLI for managing VM lifecycle operations

Installation

Prerequisites

• Linux (x86-64 with KVM support and sudo privileges)
• Rust (with cargo)
• clang
• make

Build

git clone https://github.com/shriramrav/flora.git
cd flora
make all

# add binaries to PATH for convenience  
export PATH="$(pwd)/build/crates/debug:$PATH"

Usage

1. Configure Environment

The runtime is configured via environment variables. A .env example configuration is shown below:

FLORA_ENGINE=./build/engine/main
FLORA_BOOT_BZIMAGE_PATH=./bzImage
FLORA_BOOT_INITRAMFS_PATH=./build/rootfs/root
FLORA_BOOT_USER_INIT_PATH=./build/flora/user_init/user_init
FLORA_BOOT_DISK_PATH=./debian-12-genericcloud-amd64.raw
FLORA_NET_TAP_NAME=tap0
FLORA_NET_TAP_PREFIX=flora-tap
FLORA_NET_BRIDGE_NAME=flora0
FLORA_NET_NETNS_NAME=flora
FLORA_NET_SUBNET=10.0.2.0/24
FLORA_NET_GATEWAY=10.0.2.1
FLORA_NET_NETMASK=255.255.255.0
FLORA_NET_CIDR_PREFIX=24
FLORA_NET_UPLINK_IF_NAME=eth0
FLORA_NET_NETNS_SCRIPT_PATH=./scripts/netns.sh
FLORA_NET_TAP_SCRIPT_PATH=./scripts/tap.sh
FLORA_RUNTIME_LISTEN_ADDR=127.0.0.1:3000

Load the configuration (e.g., source .env) before running the daemon or using the CLI.

2. Start Daemon

Initialize networking:

$ bash ./scripts/netns.sh

Start the runtime daemon:

$ florad

3. Launch a VM

A cpio archive with a custom flora/entry.sh script is provided at launch to handle instance-specific setup such as networking or SSH.

$ flora launch --mem 256 --entry ./user_init
created vm 454dd946-03cf-4a39-b5c1-7a0199a61f7c

4. List VMs

$ flora list
ID                                       IP              TAP             PID   
454dd946-03cf-4a39-b5c1-7a0199a61f7c     10.0.2.32       flora-tap0      92939 
b2701e5a-8557-4dd3-9371-9ea99b429495     10.0.2.33       flora-tap1      97279 

5. Stop a VM

$ flora stop --id b2701e5a-8557-4dd3-9371-9ea99b429495
stopped vm b2701e5a-8557-4dd3-9371-9ea99b429495