Virtual Machines

Create VM

Create and start a new Firecracker microVM.

Request Body

image_id

string

The ID of the image to use. If not provided, uses the default image configured via HATCH_DEFAULT_KERNEL_PATH and HATCH_DEFAULT_ROOTFS_PATH.

template_id

string

Optional template ID to use for default values. Template values are overridden by explicit request parameters.

vcpu_count

integer

Number of virtual CPUs. Defaults to HATCH_DEFAULT_VCPU (default: 1).

mem_mib

integer

Memory size in MiB. Defaults to HATCH_DEFAULT_MEM_MIB (default: 512).

boot_args

string

Kernel boot arguments. Defaults to the configured default boot args.

enable_network

boolean

Whether to enable networking. Defaults to true.

guest_ip

string

Specific guest IP address to assign. If not provided, an IP is automatically allocated from the bridge CIDR.

guest_mac

string

Specific guest MAC address. If not provided, a MAC is automatically generated.

user_data

string

Cloud-init user data to configure the VM on first boot.

Response

string

Unique VM identifier (e.g., vm_abc123).

image_id

string

The image ID used for this VM.

template_id

string

The template ID used (if any).

state

string

Current VM state. One of: starting, running, stopping, stopped, snapshotted, error.

vcpu_count

integer

Number of virtual CPUs.

mem_mib

integer

Memory size in MiB.

guest_ip

string

The guest IP address assigned to the VM.

guest_mac

string

The guest MAC address.

tap_name

string

The TAP network interface name.

ssh_port

integer

The host port forwarded to the VM’s SSH port (22).

socket_path

string

Path to the Firecracker API socket (used for internal VM communication).

user_data

string

The cloud-init user data.

enable_network

boolean

Whether networking is enabled.

created_at

string

ISO 8601 timestamp when the VM was created.

updated_at

string

ISO 8601 timestamp when the VM was last updated.

Example Request

curl -X POST http://localhost:8080/vms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vcpu_count": 2,
    "mem_mib": 1024,
    "enable_network": true,
    "user_data": "#!/bin/bash\necho 'Hello from Hatch'"
  }'

Example Response

{
  "id": "vm_abc123def456",
  "image_id": "img_default",
  "state": "running",
  "vcpu_count": 2,
  "mem_mib": 1024,
  "guest_ip": "172.16.0.10",
  "guest_mac": "02:FC:00:00:00:0A",
  "tap_name": "tap0",
  "ssh_port": 16001,
  "user_data": "#!/bin/bash\necho 'Hello from Hatch'",
  "enable_network": true,
  "created_at": "2026-03-06T12:00:00Z",
  "updated_at": "2026-03-06T12:00:00Z"
}

List VMs

Retrieve a list of all VMs.

Response

Returns an array of VM objects. See the VM response schema above for field descriptions.

Example Request

curl http://localhost:8080/vms \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

[
  {
    "id": "vm_abc123def456",
    "image_id": "img_default",
    "state": "running",
    "vcpu_count": 2,
    "mem_mib": 1024,
    "guest_ip": "172.16.0.10",
    "ssh_port": 16001,
    "enable_network": true,
    "created_at": "2026-03-06T12:00:00Z",
    "updated_at": "2026-03-06T12:00:00Z"
  },
  {
    "id": "vm_xyz789ghi012",
    "image_id": "img_default",
    "state": "stopped",
    "vcpu_count": 1,
    "mem_mib": 512,
    "enable_network": false,
    "created_at": "2026-03-06T11:30:00Z",
    "updated_at": "2026-03-06T11:45:00Z"
  }
]

Get VM

Retrieve details of a specific VM.

Path Parameters

string

required

The VM ID.

Response

Returns a VM object. See the VM response schema in the Create VM section.

Example Request

curl http://localhost:8080/vms/vm_abc123def456 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "id": "vm_abc123def456",
  "image_id": "img_default",
  "state": "running",
  "vcpu_count": 2,
  "mem_mib": 1024,
  "guest_ip": "172.16.0.10",
  "guest_mac": "02:FC:00:00:00:0A",
  "tap_name": "tap0",
  "ssh_port": 16001,
  "enable_network": true,
  "created_at": "2026-03-06T12:00:00Z",
  "updated_at": "2026-03-06T12:00:00Z"
}

Delete VM

Stop and delete a VM. This removes the VM, cleans up its resources, and deletes the database record.

Path Parameters

string

required

The VM ID.

Response

status

string

Returns deleted on success.

Example Request

curl -X DELETE http://localhost:8080/vms/vm_abc123def456 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "status": "deleted"
}

Stop VM

Gracefully stop a running VM.

Path Parameters

string

required

The VM ID.

Response

Returns the updated VM object with state set to stopped.

Example Request

curl -X POST http://localhost:8080/vms/vm_abc123def456/stop \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "id": "vm_abc123def456",
  "image_id": "img_default",
  "state": "stopped",
  "vcpu_count": 2,
  "mem_mib": 1024,
  "guest_ip": "172.16.0.10",
  "enable_network": true,
  "created_at": "2026-03-06T12:00:00Z",
  "updated_at": "2026-03-06T12:15:00Z"
}

API

​Create VM

​Request Body

​Response

​Example Request

​Example Response

​List VMs

​Response

​Example Request

​Example Response

​Get VM

​Path Parameters

​Response

​Example Request

​Example Response

​Delete VM

​Path Parameters

​Response

​Example Request

​Example Response

​Stop VM

​Path Parameters

​Response

​Example Request

​Example Response

Build docs developers (and LLMs) love

Create VM

Request Body

Response

Example Request

Example Response

List VMs

Response

Example Request

Example Response

Get VM

Path Parameters

Response

Example Request

Example Response

Delete VM

Path Parameters

Response

Example Request

Example Response

Stop VM

Path Parameters

Response

Example Request

Example Response