Skip to content

carapace-sh/carapace-bin / skills/qemu

Use 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".

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)
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 323kUpdated Claude CodeCodexVerifiedInstall