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/guest-agent.md
View on GitHub# Guest Agent (qemu-ga)
In-guest daemon that provides host↔guest communication. Installed inside the VM.
## Architecture
```
Host (QEMU) ── virtio-serial / ISA serial / viosock ──► Guest Agent
```
The host sends QGA (QEMU Guest Agent Protocol) commands via a virtio-serial channel. The guest agent executes them and returns results.
## Enabling the Channel
1. Add a virtio-serial device to the VM:
```
-chardev socket,path=/tmp/qga.sock,server=on,wait=off,id=qga0
-device virtio-serial-pci
-device virtserialport,chardev=qga0,name=org.qemu.guest_agent.0
```
2. Install and start `qemu-guest-agent` inside the guest:
```bash
# apt install qemu-guest-agent # Debian/Ubuntu
# systemctl enable --now qemu-guest-agent
```
3. On the host, connect via `socat` or `qmp-shell`:
```
socat unix-connect:/tmp/qga.sock -
```
## Key QGA Commands
### Initialization
| Command | Description |
|---------|-------------|
| `guest-sync-delimited` | Sync stream with sentinel byte (0xFF) |
| `guest-sync` | Simple sync, returns echoed integer |
### System Information
| Command | Description |
|---------|-------------|
| `guest-info` | List supported commands |
| `guest-get-time` | Guest time (nanoseconds) |
| `guest-set-time` | Sync guest time (requires `-rtc base=utc`) |
| `guest-get-osinfo` | OS name, version, kernel |
| `guest-get-host-name` | Hostname |
| `guest-get-users` | Active user sessions |
| `guest-get-timezone` | Timezone info |
| `guest-get-vcpus` | VCPU information |
### Network
| Command | Description |
|---------|-------------|
| `guest-network-get-interfaces` | Interface name, MAC, IP addresses |
### Files and Execution
| Command | Description |
|---------|-------------|
| `guest-exec` | Execute command |
| `guest-exec-status` | Check exit status |
| `guest-file-open` | Open file (returns handle) |
| `guest-file-read` | Read from file handle |
| `guest-file-write` | Write to file handle |
| `guest-file-close` | Close file handle |
| `guest-file-seek` | Seek in file |
### FSFREEZE
| Command | Description |
|---------|-------------|
| `guest-fsfreeze-freeze` | Freeze filesystems |
| `guest-fsfreeze-thaw` | Thaw filesystems |
| `guest-fsfreeze-status` | Query freeze state |
### Shutdown and Reboot
| Command | Description |
|---------|-------------|
| `guest-shutdown` | `mode=powerdown|halt|reboot` |
| `guest-reboot` | Reboot guest |
### Disk and FS
| Command | Description |
|---------|-------------|
| `guest-get-disks` | List block devices |
| `guest-get-fsinfo` | Filesystem info |
| `guest-get-memory-block-info` | Memory block info |
| `guest-set-memory-blocks` | Online/offline memory blocks |
### SUSPEND
| Command | Description |
|---------|-------------|
| `guest-suspend-ram` | Suspend to RAM |
| `guest-suspend-disk` | Hibernate |
| `guest-suspend-hybrid` | Hybrid suspend |
## QGA Commands in QMP
Guest agent commands are accessed through the `guest-*` prefix via QMP, *not* directly:
```
{ "execute": "guest-exec", "arguments": { "path": "/bin/echo", "arg": ["hello"] } }
```
Or via `guest-agent-*` (depending on QEMU version):
```
{ "execute": "guest-agent-exec", "arguments": { "path": "/bin/echo", "arg": ["hello"] } }
```
## Security
- Guest agent runs as root inside the VM
- The host controls what commands are sent
- Use agent with `-device virtserialport,chardev=qga0,name=org.qemu.guest_agent.0` — the `name` must match what the agent expects
- Some commands can be restricted (e.g., `guest-exec`, `guest-file-open`)
- QEMU can be configured to only allow specific commands
## Use Cases
- **Backup integration**: `guest-fsfreeze-freeze` ensures consistent disk state before snapshot
- **Guest information**: Query IP address, OS version, uptime without guest network
- **Graceful shutdown**: `guest-shutdown` for clean VM shutdown without ACPI
- **File injection**: Transfer small files with `guest-file-open/write/close`
- **Orchestration**: Ansible, Terraform, libvirt use guest agent for provisioning
## See Also
- `qemu-ga-ref(7)` — complete QGA protocol reference
- `qemu-qmp-ref(7)` — QMP command reference (host side)
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: 323k | 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: 323k | 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: 323k | Updated | Claude CodeCodex | Verified | Install |