wire / wire-format / firecracker-api
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, ... .
aka: Firecracker microVM REST API (over Unix socket)
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, ... .
| field | size | meaning |
|---|---|---|
| Transport | Unix domain socket | API listens on a Unix socket (path given by --api-sock). No TCP port. |
| Machine config | JSON | PUT /machine-config: {"vcpu_count": N, "mem_size_mib": M, "smt": bool, "track_dirty_pages": bool}. |
| Boot source | JSON | PUT /boot-source: {"kernel_image_path": "...", "boot_args": "...", "initrd_path": "..."}. |
| Drive | JSON | PUT /drives/{id}: {"drive_id": "...", "path_on_host": "...", "is_root_device": bool, "is_read_only": bool, "partuuid": "..."}. |
| Network interface | JSON | PUT /network-interfaces/{id}: {"iface_id": "...", "guest_mac": "...", "host_dev_name": "..."}. |
| VSOCK | JSON | PUT /vsock: {"guest_cid": N, "uds_path": "...", "vsock_id": "..."}. |
| Action | JSON | PUT /actions: {"action_type": "InstanceStart" | "SendCtrlAltDel" | "Pause" | "Resume" | "CreateSnapshot" | "LoadSnapshot" | "FlushMetrics"}. |
| MMDS | JSON | MicroVM 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"}
agent: curl -H 'accept: application/json' wire.phall.io/wire-format/firecracker-api
or /wire-format/firecracker-api.json