Skip to content

Getting Started

This guide will walk you through installing Herd, initializing your host environment, and deploying your first microVM.

🛠️ Prerequisites

  • Host OS: Linux (A recent kernel with KVM support).
  • Virtualization: Hardware virtualization (VT-x or AMD-V) must be enabled in the BIOS/UEFI.
  • KVM Access: The /dev/kvm device must exist and be accessible. 
    ls -l /dev/kvm
  • Root Access: Most herd commands require sudo.

📦 1. System Dependencies

Before installing Herd, ensure your system has containerd and iptables installed:

sudo apt update && sudo apt install -y containerd iptables

📦 2. Installation

The fastest way to get Herd up and running is with our official installation script:

curl -sSL https://raw.githubusercontent.com/herd-core/herd/main/scripts/install.sh | bash

This script will download: - The herd CLI binary. - The firecracker hypervisor. - The herd-guest-agent (runs inside the VMs).

🚀 2. Initialization

Before you can spawn microVMs, Herd needs to prepare your host system's storage and networking. Run the interactive init command:

sudo herd init

Alternatively, you can run in non-interactive mode (useful for scripts and CI/CD):

sudo herd init --yes

What this does: - Sets up the devmapper thin-pool for high-speed rootfs snapshotting. - Provisions the chroot base directory (/srv/jailer) owned by root. - Configures a dynamic UID pool for multi-tenant isolation (no system users required). - Dynamically allocates a unique UID for each microVM from a pool (starting at 300000) for secure jailer isolation. - Configures host-wide NAT routing for microVM internet access. - Downloads a optimized Linux kernel (vmlinux) if one isn't provided. - Generates a configuration file at ~/.herd/herd.yaml.

🛰️ 3. Start the Daemon

Once initialized, start the Herd daemon to begin managing traffic and sessions:

sudo herd start

This command launches the Control Plane (REST API) and the Data Plane (HTTP Reverse Proxy).

🏗️ 4. Your First Deployment

Deploy a standard OCI image directly into a Firecracker microVM:

herd deploy --image nginx:latest

Herd will automatically: 1. Pull the image via containerd. 2. Create a snapshot of the root filesystem. 3. Allocate an internal IP. 4. Spawn the Firecracker process. 5. Provide you with a Session ID and a Proxy URL.

You can now access your application via the proxy, which intelligently routes traffic to your dedicated microVM.

🌐 5. Port Publishing (Hybrid Mode)

If you need to expose a specific port (e.g., for a database or a web server on a custom port), use the --publish flag:

# Explicitly map host port 5432 to guest port 5432
herd deploy --image postgres:latest -e POSTGRES_PASSWORD=test --publish 5432:5432

# Mapping to a random available host port
herd deploy --image nginx:latest --publish :80

Network Prerequisites: For loopback access (127.0.0.1) to work with published ports, Herd automatically enables net.ipv4.conf.all.route_localnet=1 during initialization. This allows loopback traffic to be routed through the NAT stack to your microVMs.