wire / wire-format / firecracker-api

Firecracker microVM REST API (over Unix socket)

Firecracker is a VMM (Virtual Machine Monitor) for microVMs, written in Rust, used by AWS Lambda and Fargate. Its control API is a REST API over a Unix domain socket. Endpoints: PUT /machine-config, PUT /boot-source, PUT /drives/{id}, PUT /network-interfaces/{id}, PUT /vsock, PUT /actions (InstanceStart, SendCtrlAltDel, Pause, Resume, CreateSnapshot, LoadSnapshot, ...), GET /vm, GET /mmds, ... .

wire-format kind wire-format status standard verification verified tier B wire-format@1

aka: Firecracker microVM REST API (over Unix socket)

wire format

spec: Firecracker (firecracker-microvm.github.io)

Firecracker is a VMM (Virtual Machine Monitor) for microVMs, written in Rust, used by AWS Lambda and Fargate. Its control API is a REST API over a Unix domain socket. Endpoints: PUT /machine-config, PUT /boot-source, PUT /drives/{id}, PUT /network-interfaces/{id}, PUT /vsock, PUT /actions (InstanceStart, SendCtrlAltDel, Pause, Resume, CreateSnapshot, LoadSnapshot, ...), GET /vm, GET /mmds, ... .

fieldsizemeaning
TransportUnix domain socketAPI listens on a Unix socket (path given by --api-sock). No TCP port.
Machine configJSONPUT /machine-config: {"vcpu_count": N, "mem_size_mib": M, "smt": bool, "track_dirty_pages": bool}.
Boot sourceJSONPUT /boot-source: {"kernel_image_path": "...", "boot_args": "...", "initrd_path": "..."}.
DriveJSONPUT /drives/{id}: {"drive_id": "...", "path_on_host": "...", "is_root_device": bool, "is_read_only": bool, "partuuid": "..."}.
Network interfaceJSONPUT /network-interfaces/{id}: {"iface_id": "...", "guest_mac": "...", "host_dev_name": "..."}.
VSOCKJSONPUT /vsock: {"guest_cid": N, "uds_path": "...", "vsock_id": "..."}.
ActionJSONPUT /actions: {"action_type": "InstanceStart" | "SendCtrlAltDel" | "Pause" | "Resume" | "CreateSnapshot" | "LoadSnapshot" | "FlushMetrics"}.
MMDSJSONMicroVM Metadata Service: GET/PUT /mmds (IMDSv2-like metadata for the guest, fetched via 169.254.169.254 inside the guest).

example:

7b 22 61 63 74 69 6f 6e 5f 74 79 70 65 22 3a 22 49 6e 73 74 61 6e 63 65 53 74 61 72 74 22 7d

JSON: {"action_type":"InstanceStart"}


provenance

agent: curl -H 'accept: application/json' wire.phall.io/wire-format/firecracker-api or /wire-format/firecracker-api.json