Installation

System Requirements

Operating System

Linux with kernel 4.14+ (required for KVM)

CPU

x86_64 or aarch64 with virtualization support

Memory

Minimum 2GB RAM (plus memory for VMs)

Storage

10GB+ for base system and VM images

Prerequisites Check

Verify KVM Support

Check if KVM is available and your user has access:

ls /dev/kvm && echo "KVM enabled" || echo "KVM not enabled"

If KVM is not enabled:

Check CPU virtualization support:

# For Intel
grep -E 'vmx' /proc/cpuinfo

# For AMD
grep -E 'svm' /proc/cpuinfo

Enable in BIOS/UEFI if not showing

Load KVM modules:

sudo modprobe kvm
sudo modprobe kvm_intel  # or kvm_amd

Install Required Tools

Ubuntu/Debian
RHEL/CentOS
Arch Linux

sudo apt-get update
sudo apt-get install -y git curl wget docker.io docker-compose-plugin

sudo dnf install -y git curl wget docker docker-compose
sudo systemctl enable --now docker

sudo pacman -S git curl wget docker docker-compose
sudo systemctl enable --now docker

Install Go

Hatch requires Go 1.21 or later:

# Download Go (replace version as needed)
wget https://go.dev/dl/go1.22.0.linux-amd64.tar.gz

# Install
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.22.0.linux-amd64.tar.gz

# Add to PATH
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

# Verify
go version

Clone Repository

git clone https://github.com/ThakerKush/Hatch.git
cd Hatch

Install Dependencies

The install-deps.sh script automates installation of Firecracker, kernel, rootfs, and system networking tools.

This script requires root access and will modify system network settings.

sudo ./scripts/install-deps.sh

What the Script Does

Verify environment

Checks that you’re running as root
Verifies Linux operating system
Confirms KVM is available at /dev/kvm

Install system packages

Installs required dependencies via apt:

dnsmasq-base    # DHCP server for VM networking
e2fsprogs       # ext4 filesystem tools
iproute2        # ip command for network config
iptables        # NAT and port forwarding
curl wget       # Download tools
ca-certificates # SSL support
util-linux      # System utilities

Enable IP forwarding

Configures the kernel to forward packets between VMs and the internet:

sysctl -w net.ipv4.ip_forward=1

Also persists the setting to /etc/sysctl.conf

Download Firecracker

Fetches the latest Firecracker release for your architecture
Installs binary to /usr/local/bin/firecracker
Makes it executable

Download kernel

Gets a Firecracker-compatible Linux kernel (5.10+)
Saves to /root/firecracker/vmlinux-5.10

Download rootfs

Downloads Ubuntu Noble cloud image
Includes cloud-init support for VM configuration
Saves to /root/firecracker/ubuntu-noble-rootfs.ext4

Output

The script prints environment variables to add to your .env file:

HATCH_FIRECRACKER_BIN=/usr/local/bin/firecracker
HATCH_DEFAULT_KERNEL_PATH=/root/firecracker/vmlinux-5.10
HATCH_DEFAULT_ROOTFS_PATH=/root/firecracker/ubuntu-noble-rootfs.ext4

Database Setup

Hatch uses PostgreSQL to store VM metadata, routes, and snapshots.

Using Docker Compose (Recommended)

The included docker-compose.yml provides Postgres and MinIO:

docker compose up -d

This starts:

Postgres 17 on localhost:5432
- User: hatch
- Password: hatch
- Database: hatch
MinIO on localhost:9000 (S3 API)
- Console: localhost:9001
- Access key: minioadmin
- Secret key: minioadmin

Manual Postgres Installation

If you prefer not to use Docker:

Ubuntu/Debian
RHEL/CentOS

sudo apt-get install -y postgresql postgresql-contrib
sudo systemctl enable --now postgresql

# Create database and user
sudo -u postgres psql <<EOF
CREATE DATABASE hatch;
CREATE USER hatch WITH PASSWORD 'hatch';
GRANT ALL PRIVILEGES ON DATABASE hatch TO hatch;
EOF

sudo dnf install -y postgresql-server postgresql-contrib
sudo postgresql-setup --initdb
sudo systemctl enable --now postgresql

# Create database and user
sudo -u postgres psql <<EOF
CREATE DATABASE hatch;
CREATE USER hatch WITH PASSWORD 'hatch';
GRANT ALL PRIVILEGES ON DATABASE hatch TO hatch;
EOF

S3 Storage Setup

S3-compatible storage is required for snapshot/restore functionality.

Using MinIO (Included in Docker Compose)

MinIO is already running if you started docker compose up -d. Create the snapshots bucket:

Open MinIO Console at http://localhost:9001
Login with minioadmin / minioadmin
Create a bucket named hatch-snapshots

Or use the MinIO CLI:

# Install mc (MinIO Client)
wget https://dl.min.io/client/mc/release/linux-amd64/mc
chmod +x mc
sudo mv mc /usr/local/bin/

# Configure
mc alias set local http://localhost:9000 minioadmin minioadmin

# Create bucket
mc mb local/hatch-snapshots

Using AWS S3

To use AWS S3 instead of MinIO, update your .env:

HATCH_S3_ENDPOINT=https://s3.amazonaws.com
HATCH_S3_BUCKET=your-bucket-name
HATCH_S3_REGION=us-east-1
HATCH_S3_ACCESS_KEY=your-access-key
HATCH_S3_SECRET_KEY=your-secret-key

Environment Configuration

Create your environment file:

cp .env.example .env

Edit .env with your configuration:

# Database
DATABASE_URL=postgres://hatch:[email protected]:5432/hatch?sslmode=disable

# API Server
HATCH_HTTP_ADDR=127.0.0.1:8080

# Reverse Proxy
HATCH_PROXY_ADDR=127.0.0.1:9090
HATCH_PROXY_BASE_DOMAIN=hatch.local

# Data directory for VM files
HATCH_DATA_DIR=/data

# S3 Configuration (MinIO)
HATCH_S3_ENDPOINT=http://127.0.0.1:9000
HATCH_S3_BUCKET=hatch-snapshots
HATCH_S3_REGION=us-east-1
HATCH_S3_ACCESS_KEY=minioadmin
HATCH_S3_SECRET_KEY=minioadmin

# Firecracker paths (from install-deps.sh output)
HATCH_FIRECRACKER_BIN=/usr/local/bin/firecracker
HATCH_DEFAULT_KERNEL_PATH=/root/firecracker/vmlinux-5.10
HATCH_DEFAULT_ROOTFS_PATH=/root/firecracker/ubuntu-noble-rootfs.ext4

# SSH forwarding
HATCH_SSH_ALLOWED_CIDR=0.0.0.0/0

# Idle timeout for auto-snapshot
HATCH_IDLE_TIMEOUT=45m
HATCH_IDLE_CHECK_INTERVAL=15m

Configuration Reference

Variable	Description	Default
`DATABASE_URL`	Postgres connection string	-
`HATCH_HTTP_ADDR`	API server listen address	`127.0.0.1:8080`
`HATCH_PROXY_ADDR`	Reverse proxy listen address	`127.0.0.1:9090`
`HATCH_PROXY_BASE_DOMAIN`	Base domain for subdomain routing	`hatch.local`
`HATCH_DATA_DIR`	Directory for VM data	`/data`
`HATCH_S3_ENDPOINT`	S3 endpoint URL	-
`HATCH_S3_BUCKET`	S3 bucket name	`hatch-snapshots`
`HATCH_S3_REGION`	S3 region	`us-east-1`
`HATCH_S3_ACCESS_KEY`	S3 access key	-
`HATCH_S3_SECRET_KEY`	S3 secret key	-
`HATCH_FIRECRACKER_BIN`	Path to Firecracker binary	-
`HATCH_DEFAULT_KERNEL_PATH`	Default kernel path	-
`HATCH_DEFAULT_ROOTFS_PATH`	Default rootfs path	-
`HATCH_SSH_ALLOWED_CIDR`	CIDR for SSH access	`0.0.0.0/0`
`HATCH_IDLE_TIMEOUT`	Time before auto-snapshot	`45m`
`HATCH_IDLE_CHECK_INTERVAL`	Idle check frequency	`15m`

If HATCH_S3_ENDPOINT is not set, snapshot/restore features will be disabled.

Running Hatchd

Start the Hatch daemon:

sudo go run ./cmd/hatchd

Root access is required for network configuration (bridge, TAP devices, iptables).

Expected Output

You should see structured JSON logs indicating:

{"level":"info","msg":"configuration loaded","http_addr":"127.0.0.1:8080","proxy_addr":"127.0.0.1:9090"}
{"level":"info","msg":"default image seeded","id":"default","kernel":"/root/firecracker/vmlinux-5.10"}
{"level":"info","msg":"S3 snapshot storage enabled","bucket":"hatch-snapshots"}
{"level":"info","msg":"API server listening","addr":"127.0.0.1:8080"}
{"level":"info","msg":"reverse proxy listening","addr":"127.0.0.1:9090","base_domain":"hatch.local"}

Build for Production

For production use, build a binary:

go build -o hatchd ./cmd/hatchd
sudo ./hatchd

Run as a Systemd Service

Create /etc/systemd/system/hatchd.service:

[Unit]
Description=Hatch MicroVM Platform
After=network.target docker.service postgresql.service

[Service]
Type=simple
User=root
WorkingDirectory=/opt/hatch
EnvironmentFile=/opt/hatch/.env
ExecStart=/opt/hatch/hatchd
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable hatchd
sudo systemctl start hatchd
sudo systemctl status hatchd

Verification

Health Check

curl localhost:8080/healthz

Expected response:

{
  "status": "healthy",
  "vm_count": 0,
  "route_count": 0
}

Create Test VM

Create a simple VM to verify everything works:

curl -X POST localhost:8080/vms \
  -H 'content-type: application/json' \
  -d '{
    "enable_network": true,
    "user_data": "#cloud-config\nusers:\n  - name: test\n    groups: [sudo]\n    shell: /bin/bash\n    sudo: [\"ALL=(ALL) NOPASSWD:ALL\"]\n    ssh_authorized_keys:\n      - '"$(cat ~/.ssh/id_rsa.pub)"'"
  }'

Verify Networking

Check that the bridge was created:

ip addr show fcbr0

You should see the bridge interface with IP 172.16.0.1.

Check Logs

Monitor hatchd logs for any errors:

# If running in foreground, logs appear in terminal

# If running as systemd service:
sudo journalctl -u hatchd -f

Troubleshooting

KVM Permission Denied

If you see “Permission denied” for /dev/kvm:

sudo chmod 666 /dev/kvm

Or add your user to the kvm group:

sudo usermod -aG kvm $USER
# Log out and back in

Database Connection Failed

Verify Postgres is running:

sudo systemctl status postgresql
# or for Docker:
docker ps | grep postgres

Test connection:

psql postgres://hatch:[email protected]:5432/hatch?sslmode=disable

S3 Connection Failed

Verify MinIO is running:

docker ps | grep minio
curl http://localhost:9000/minio/health/live

Firecracker Not Found

Verify Firecracker is installed and in PATH:

which firecracker
firecracker --version

If not found, re-run the install script:

sudo ./scripts/install-deps.sh

Next Steps

Quickstart Guide

Create your first VM

API Reference

Explore all API endpoints

Networking Guide

Deep dive into VM networking

Snapshots

Learn about snapshot/restore

Get Started

Core Concepts

Guides

Configuration

​System Requirements

Operating System

CPU

Memory

Storage

​Prerequisites Check

​Verify KVM Support

​Install Required Tools

​Install Go

​Clone Repository

​Install Dependencies

​What the Script Does

​Output

​Database Setup

​Using Docker Compose (Recommended)

​Manual Postgres Installation

​S3 Storage Setup

​Using MinIO (Included in Docker Compose)

​Using AWS S3

​Environment Configuration

​Configuration Reference

​Running Hatchd

​Expected Output

​Build for Production

​Run as a Systemd Service

​Verification

​Health Check

​Create Test VM

​Verify Networking

​Check Logs

​Troubleshooting

​KVM Permission Denied

​Database Connection Failed

​S3 Connection Failed

​Firecracker Not Found

​Next Steps

Quickstart Guide

API Reference

Networking Guide

Snapshots

Build docs developers (and LLMs) love

System Requirements

Prerequisites Check

Verify KVM Support

Install Required Tools

Install Go

Clone Repository

Install Dependencies

What the Script Does

Output

Database Setup

Using Docker Compose (Recommended)

Manual Postgres Installation

S3 Storage Setup

Using MinIO (Included in Docker Compose)

Using AWS S3

Environment Configuration

Configuration Reference

Running Hatchd

Expected Output

Build for Production

Run as a Systemd Service

Verification

Health Check

Create Test VM

Verify Networking

Check Logs

Troubleshooting

KVM Permission Denied

Database Connection Failed

S3 Connection Failed

Firecracker Not Found

Next Steps