Skip to main content
This guide walks you through creating and managing microVMs using the Hatch API.

​
Creating a Basic VM

1

Create a minimal VM

The simplest way to create a VM is with an empty POST request. Hatch will use the default image and configuration:
curl -X POST https://api.hatch.example.com/vms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
When no image_id is provided, Hatch uses the default image configured via HATCH_DEFAULT_KERNEL_PATH and HATCH_DEFAULT_ROOTFS_PATH environment variables.
2

Review the response

The API returns the created VM object:
{
  "id": "vm-abc123",
  "image_id": "img-default",
  "state": "running",
  "vcpu_count": 1,
  "mem_mib": 512,
  "guest_ip": "192.168.241.10",
  "guest_mac": "02:fc:00:00:00:01",
  "ssh_port": 2200,
  "enable_network": true,
  "created_at": "2026-03-06T10:30:00Z",
  "updated_at": "2026-03-06T10:30:00Z"
}
3

Verify the VM is running

Check the VM status using the returned ID:
curl https://api.hatch.example.com/vms/vm-abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Creating a Networked VM with Cloud-Init

For production workloads, you’ll typically want to customize the VM with cloud-init user data:
1

Prepare your cloud-init configuration

Create a cloud-init user data script. This example installs packages and sets up an SSH key:
#cloud-config
users:
  - name: ubuntu
    sudo: ALL=(ALL) NOPASSWD:ALL
    ssh_authorized_keys:
      - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... [email protected]

packages:
  - nginx
  - git

runcmd:
  - systemctl enable nginx
  - systemctl start nginx
2

Create the VM with user data

curl -X POST https://api.hatch.example.com/vms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vcpu_count": 2,
    "mem_mib": 2048,
    "user_data": "#cloud-config\nusers:\n  - name: ubuntu\n    sudo: ALL=(ALL) NOPASSWD:ALL\n    ssh_authorized_keys:\n      - ssh-ed25519 AAAAC3Nza...\npackages:\n  - nginx\n  - git\nruncmd:\n  - systemctl enable nginx\n  - systemctl start nginx"
  }'
Cloud-init user data is automatically injected into the VM’s rootfs as a NoCloud seed during creation. The VM will process this data on first boot.
3

Connect via SSH

Use the allocated SSH port from the response:
ssh [email protected] -p 2200

​
Custom Resource Allocation

You can specify CPU, memory, and network configuration: 
curl -X POST https://api.hatch.example.com/vms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vcpu_count": 4,
    "mem_mib": 4096,
    "guest_ip": "192.168.241.50",
    "guest_mac": "02:fc:00:00:00:32",
    "enable_network": true
  }'
Resource Limits
  • vcpu_count: 1-32 CPUs (defaults to 1)
  • mem_mib: 128-65536 MB (defaults to 512)
  • Custom IPs must be within the bridge CIDR range

​
Using Templates

Templates let you pre-configure VM settings for reuse: 
curl -X POST https://api.hatch.example.com/vms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "tpl-web-server"
  }'
When using a template, any explicit request values override the template defaults. Template values for image_id, vcpu_count, mem_mib, and user_data are used when not specified in the request.

​
Disabling Networking

For isolated workloads, you can disable networking: 
curl -X POST https://api.hatch.example.com/vms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enable_network": false,
    "vcpu_count": 1,
    "mem_mib": 512
  }'
VMs without networking will not have:
  • Guest IP allocation
  • TAP device
  • DHCP reservation
  • SSH port forwarding

​
Listing VMs

Retrieve all VMs in your account: 
curl https://api.hatch.example.com/vms \
  -H "Authorization: Bearer YOUR_API_KEY"
Response: 
[
  {
    "id": "vm-abc123",
    "state": "running",
    "vcpu_count": 2,
    "mem_mib": 2048,
    "guest_ip": "192.168.241.10",
    "ssh_port": 2200,
    "created_at": "2026-03-06T10:30:00Z"
  },
  {
    "id": "vm-def456",
    "state": "snapshotted",
    "vcpu_count": 1,
    "mem_mib": 512,
    "guest_ip": "192.168.241.11",
    "ssh_port": 2201,
    "created_at": "2026-03-06T09:15:00Z"
  }
]

​
Stopping VMs

Gracefully shut down a running VM: 
curl -X POST https://api.hatch.example.com/vms/vm-abc123/stop \
  -H "Authorization: Bearer YOUR_API_KEY"
1

VM receives shutdown signal

Firecracker sends a graceful shutdown signal to the guest OS.
2

State transitions to 'stopped'

The VM state changes from running → stopping → stopped.
3

Resources are cleaned up

SSH forwarding rules are removed, but IP allocation and work directory are retained.

​
Deleting VMs

Permanently remove a VM and all associated resources: 
curl -X DELETE https://api.hatch.example.com/vms/vm-abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
Deletion is permanent! This operation:
  • Stops the Firecracker process
  • Removes TAP device and iptables rules
  • Releases IP allocation and SSH port
  • Deletes the work directory (rootfs copy, logs)
  • Removes all proxy routes
  • Deletes all snapshots from S3 storage
Response: 
{
  "status": "deleted"
}

​
VM States

VMs transition through these states during their lifecycle:
StateDescription
startingVM is being created and Firecracker is launching
runningVM is active and responding
stoppingVM is shutting down gracefully
stoppedVM has been stopped but resources are retained
snapshottedVM has been paused and saved to S3 storage
errorVM encountered an error during operation
After a Hatch server restart, any VMs in transient states (starting, running, stopping) are automatically marked as error since their Firecracker processes no longer exist.

​
Common Request Parameters

ParameterTypeDefaultDescription
image_idstringdefault imageBase OS image to use
template_idstring-Template to inherit settings from
vcpu_countint1Number of virtual CPUs (1-32)
mem_mibint512Memory in MiB (128-65536)
boot_argsstringimage defaultCustom kernel boot arguments
enable_networkbooltrueEnable networking and SSH
guest_ipstringauto-assignedStatic IP within bridge CIDR
guest_macstringauto-generatedStatic MAC address
user_datastring-Cloud-init user data (YAML)

​
Next Steps

Network Setup

Configure networking, DNS, and internet access

Snapshots

Save and restore VM state with snapshots

Reverse Proxy

Expose VMs via subdomain routing

Idle Management

Auto-snapshot idle VMs to save resources

Build docs developers (and LLMs) love

Get started for freeTalk to us