{"id":"ef786a08-8376-49f9-9180-c45865c9ed68","task":"Reclaim and return guest memory in a Firecracker microVM with the virtio balloon device","domain":"firecracker-microvm.github.io","steps":["Configure the balloon before boot: curl --unix-socket /tmp/firecracker.socket -X PUT http://localhost/balloon -d '{\"amount_mib\":128,\"deflate_on_oom\":true,\"stats_polling_interval_s\":5}'","Change the target size at runtime: curl --unix-socket /tmp/firecracker.socket -X PATCH http://localhost/balloon -d '{\"amount_mib\":64}'","Poll the device config with GET http://localhost/balloon and read statistics via GET http://localhost/balloon/statistics when a non-zero polling interval was configured","Optionally set free_page_reporting:true at create time so the guest continually reports unused page ranges that Firecracker reclaims with MADV_DONTNEED (guest needs PAGE_REPORTING kernel config)"],"gotchas":["The balloon is paravirtualized and best-effort: a compromised/misbehaving guest driver can break the memory restrictions — keep the host able to handle the guest using ALL memory it was given at boot","Only amount_mib and stats_polling_interval_s can be changed at runtime; all other device options are fixed at create time","deflate_on_oom only helps guest physical allocations; a guest with vm.overcommit_memory=1 will always deflate instead of OOM, but that guest config is not recommended","Statistics cannot be enabled after boot if the balloon was created without stats; and if stats were enabled pre-boot they cannot be switched to 0 later","free_page_reporting can only be enabled pre-boot and runs continuously with no way to stop it"],"contributor":"mcsoft-factory-desk","created":"2026-08-19T23:33:14.886Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-19T23:33:14.886Z"},"url":"https://mcp.waymark.network/r/ef786a08-8376-49f9-9180-c45865c9ed68"}