Skip to main content

​
Prerequisites

Before you begin, ensure you have:

Linux with KVM

A Linux machine with KVM virtualization enabled

Docker Compose

For running Postgres and MinIO dependencies

Go 1.21+

Required to build and run hatchd

Root Access

Needed for network configuration and Firecracker
Check if KVM is enabled:
ls /dev/kvm && echo "KVM enabled" || echo "KVM not enabled"

​
Quick Setup

1

Install dependencies

Run the provided script to install Firecracker, kernel, rootfs, and system tools:
cd hatch
sudo ./scripts/install-deps.sh
This script will:
  • Install dnsmasq, e2fsprogs, iproute2, iptables, and other system packages
  • Download and install the latest Firecracker binary
  • Download a compatible Linux kernel
  • Download Ubuntu Noble cloud image (with cloud-init support)
  • Enable IP forwarding
  • Print environment variables to add to your .env file
2

Configure environment

Copy the example environment file and update with the paths from the install script:
cp .env.example .env
The install script will output variables like:
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
Add these to your .env file.
3

Start services

Launch Postgres and MinIO with Docker Compose:
docker compose up -d
This starts:
  • Postgres on localhost:5432 (database for VM metadata)
  • MinIO on localhost:9000 (S3-compatible storage for snapshots)
  • MinIO Console on localhost:9001
4

Run hatchd

Start the Hatch daemon:
sudo go run ./cmd/hatchd
You should see logs indicating:
  • Configuration loaded
  • Database connected
  • Default image seeded
  • API server listening on :8080
  • Reverse proxy listening on :9090

​
Create Your First VM

Now that Hatch is running, let’s create a VM with network access and SSH enabled.
Replace <your-public-key> with your actual SSH public key (from ~/.ssh/id_rsa.pub or ~/.ssh/id_ed25519.pub)
curl -X POST localhost:8080/vms \
  -H 'content-type: application/json' \
  -d '{
    "enable_network": true,
    "user_data": "#cloud-config\nusers:\n  - name: hatch\n    groups: [sudo]\n    shell: /bin/bash\n    sudo: [\"ALL=(ALL) NOPASSWD:ALL\"]\n    ssh_authorized_keys:\n      - <your-public-key>"
  }'

​
Response

The API will return VM details including: 
{
  "id": "vm-abc123",
  "state": "running",
  "guest_ip": "172.16.0.10",
  "guest_mac": "aa:bb:cc:dd:ee:ff",
  "ssh_port": 16000,
  "vcpu_count": 1,
  "memory_mb": 512,
  "created_at": "2026-03-06T10:30:00Z"
}
The VM boots with cloud-init, so it may take 10-20 seconds for the SSH server to be ready.

​
Connect via SSH

Using the ssh_port from the response, connect to your VM: 
ssh -p 16000 hatch@<host-ip>
For local testing: 
ssh -p 16000 hatch@localhost
You should now be inside your microVM with full shell access.

​
What’s Next?

Installation Guide

Learn about all configuration options and advanced setup

API Reference

Explore all available API endpoints

Networking

Understand how Hatch networking works

Snapshots

Learn about snapshot/restore and wake-on-request

​
Common Commands

​
List all VMs

curl localhost:8080/vms

​
Get VM details

curl localhost:8080/vms/{id}

​
Stop a VM

curl -X POST localhost:8080/vms/{id}/stop

​
Snapshot a VM

curl -X POST localhost:8080/vms/{id}/snapshot

​
Delete a VM

curl -X DELETE localhost:8080/vms/{id}
For full API documentation, see the API Reference section.

Build docs developers (and LLMs) love

Get started for freeTalk to us