carapace-sh/carapace-bin / skills/qemu
qemu
UnverifiedUse when working with QEMU — qemu-system-*, qemu-img, qemu-nbd, qemu-storage-daemon, qemu-pr-helper, block drivers, machine types, CPU models, device emulation, networking, display options, QMP protocol, and guest agent. Triggers on: "qemu", "qemu-system", "qemu-img", "qemu-nbd", "qemu-kvm", "QEMU", "qcow2", "qcow", "qed", "virtio", "virgl", "vhost-user", "VirtIO", "block driver", "machine type", "SEV", "SEV-SNP", "TDX", "snapshot", "backing file", "NBD", "Network Block Device", "QMP", "QEMU Monitor Protocol", "guest agent", "qemu-ga", "cpu model", "host passthrough", "SPICE", "VNC".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.5 KB |
| references/block-devices.md | markdown | 4.1 KB |
| references/block-drivers.md | markdown | 4.6 KB |
| references/cpu-models.md | markdown | 4.8 KB |
| references/devices.md | markdown | 5.1 KB |
| references/display.md | markdown | 4.2 KB |
| references/guest-agent.md | markdown | 4.0 KB |
| references/machine.md | markdown | 3.2 KB |
| references/man-docs.md | markdown | 2.9 KB |
| references/networking.md | markdown | 5.2 KB |
| references/overview.md | markdown | 3.8 KB |
| references/qemu-img.md | markdown | 6.5 KB |
| references/qemu-nbd.md | markdown | 3.3 KB |
| references/qemu-pr-helper.md | markdown | 2.0 KB |
| references/qemu-storage-daemon.md | markdown | 3.7 KB |
| references/qemu-system.md | markdown | 5.2 KB |
| references/qmp.md | markdown | 5.8 KB |
references/qmp.md
View on GitHub# QMP — QEMU Monitor Protocol
JSON-based protocol for controlling QEMU programmatically. The primary management interface for QEMU.
## Enabling QMP
```
-qmp tcp:localhost:4444,server,nowait # TCP
-qmp unix:/tmp/qmp.sock,server,nowait # UNIX socket
```
Also via `-chardev` + `-mon`:
```
-chardev socket,id=qmp0,path=/tmp/qmp.sock,server=on,wait=off
-mon chardev=qmp0,mode=control
```
## HMP (Human Monitor Protocol)
Legacy text-based monitor:
```
-hmp tcp:localhost:4445,server,nowait
-hmp unix:/tmp/hmp.sock,server,nowait
```
Can also be accessed from QMP with the `human-monitor-command` command.
## Protocol Basics
QMP is JSON-over-TCP. Messages are newline-delimited JSON objects.
### Handshake
```
← {"QMP": {"version": {"qemu": {"major": 11, "minor": 0, "micro": 1}, "package": ""}, "capabilities": []}}
→ { "execute": "qmp_capabilities" }
← { "return": {} }
```
### Command Structure
```
{ "execute": "COMMAND", "arguments": { ... }, "id": "TAG" }
```
- `execute` — command name (required)
- `arguments` — command arguments (optional)
- `id` — request identifier, echoed in response (optional)
### Response Structure
Success:
```
{ "return": VALUE, "id": "TAG" }
```
Error:
```
{ "error": { "class": "ERROR_CLASS", "desc": "Human-readable description" }, "id": "TAG" }
```
Events (asynchronous):
```
{ "event": "EVENT_NAME", "data": { ... }, "timestamp": { "seconds": N, "microseconds": N } }
```
## Key Commands
### VM Lifecycle
| Command | Description |
|---------|-------------|
| `stop` | Pause VM |
| `cont` | Resume VM |
| `system_powerdown` | ACPI power button |
| `system_reset` | Reset VM |
| `system_wakeup` | Wake from S3 |
| `quit` | Shut down QEMU |
| `human-monitor-command` | Execute HMP command |
### State Queries
| Command | Description |
|---------|-------------|
| `query-kvm` | KVM status |
| `query-status` | VM run state |
| `query-name` | VM name |
| `query-uuid` | VM UUID |
| `query-machines` | List machine types |
| `query-cpus-fast` | CPU information |
| `query-block` | Block device info |
| `query-blockstats` | Block I/O statistics |
| `query-netdev` | Netdev info |
| `query-migrate` | Migration status |
| `query-commands` | All available commands |
| `qom-list` | QOM object tree |
| `qom-get` | QOM property value |
### Block Operations
| Command | Description |
|---------|-------------|
| `blockdev-snapshot-sync` | Create snapshot (legacy) |
| `blockdev-snapshot` | Take snapshot (new API) |
| `blockdev-backup` | Backup job |
| `blockdev-mirror` | Mirror job |
| `block-commit` | Commit overlay chain |
| `block-stream` | Stream data from backing file |
| `block-job-cancel` | Cancel active job |
| `block-job-pause` / `block-job-resume` | Job control |
| `blockdev-add` / `blockdev-del` | Dynamic block node add/remove |
| `blockdev-create` | Create image via QMP |
| `transaction` | Atomic batch of block operations |
| `x-blockdev-amend` | Modify image format options |
| `query-jobs` | List active jobs |
| `nbd-server-start` | Start NBD server |
| `nbd-server-add` / `nbd-server-remove` | Dynamic NBD export management |
| `nbd-server-stop` | Stop NBD server |
### Migration
| Command | Description |
|---------|-------------|
| `migrate` | Start migration (`uri` argument) |
| `migrate_cancel` | Cancel migration |
| `migrate-incoming` | Set migration target for incoming (`-incoming defer`) |
| `migrate-set-parameters` | Set migration tuning |
| `migrate-start-postcopy` | Switch to post-copy |
| `migrate-continue` | Continue after pause |
| `query-migrate` | Migration status |
| `query-migrate-parameters` | Migration parameters |
### Device Hotplug
| Command | Description |
|---------|-------------|
| `device_add` | Add device (QOM path, id, properties) |
| `device_del` | Remove device by ID |
| `netdev_add` / `netdev_del` | Network backend hotplug |
| `chardev-add` / `chardev-remove` | Character device hotplug |
| `object-add` / `object-del` | QOM object lifecycle |
### QOM (QEMU Object Model)
```
qom-list path=/machine/peripheral
qom-get path=/machine/peripheral/virtio0,property=drive
qom-set path=/machine/peripheral/virtio0,property=drive,value=disk0
```
### Dump and Snapshot
```
dump-guest-memory paging=false protocol=file:/tmp/dump
pmemsave val=... size=... filename=...
```
### Set Password
```
{ "execute": "set_password", "arguments": { "protocol": "vnc", "password": "mypass" } }
{ "execute": "expire_password", "arguments": { "protocol": "vnc", "time": "+10m" } }
```
## Key Events
QMP events the management layer subscribes to:
| Event | Trigger |
|-------|---------|
| `SHUTDOWN` | Guest shutdown |
| `RESET` | Guest reset |
| `STOP` | VM paused |
| `RESUME` | VM resumed |
| `SUSPEND` | Guest suspended |
| `RTC_CHANGE` | RTC time changed |
| `WATCHDOG` | Watchdog fired |
| `BLOCK_IO_ERROR` | Block I/O error |
| `BLOCK_JOB_COMPLETED` | Block job finished |
| `BLOCK_JOB_READY` | Block job ready (ready bit) |
| `BLOCK_JOB_PENDING` | Block job pending |
| `DEVICE_DELETED` | Device removed |
| `NIC_RX_FILTER_CHANGED` | Guest changed MAC |
| `MIGRATION` | Migration state change |
| `MIGRATION_PASS` | Migration pass |
| `VSERPORT_CHANGE` | virtio-serial port change |
| `NVDIMM_REPLACEMENT` | NVDIMM replaced |
| `MEMORY_DEVICE_SIZE_CHANGE` | Memory device size changed |
| `SUSPEND_DISK` | Guest hibernate |
## Tools
**qmp-shell** (in QEMU source tree):
```
python3 scripts/qmp/qmp-shell /tmp/qmp.sock
```
**qmp-proxy** and **qemu-vm** for programmatic Python use via `qemu.qmp` package:
```python
from qemu.qmp import QMPClient
qmp = QMPClient()
await qmp.connect("/tmp/qmp.sock")
await qmp.execute("query-status")
await qmp.disconnect()
```
## JSON Formatting
For constructing QMP commands and parsing responses programmatically, use `jq`. See the `jq` skill (`skills/jq/`).
## See Also
- `qemu-qmp-ref(7)` — complete command and event reference
- `qemu-storage-daemon-qmp-ref(7)` — storage daemon QMP subset
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |