node-qemu

QEMU management library for Node.js

Typed QMP client, process lifecycle manager, and qemu-img wrappers - all in pure TypeScript with no native bindings.

Features

• QMP client - typed JSON-RPC over Unix socket or TCP, full capability negotiation, sequential command dispatch, typed async events
• 60+ typed QMP commands - VM control, block/storage, device hotplug, migration, CPU/memory, display, introspection, QOM
• Process manager - spawn, monitor, and gracefully stop QEMU processes; PID files; stdout/stderr streams
• CLI argument builder - convert a typed QemuConfig into a validated string[] argv
• Image tools - typed wrappers around qemu-img: create, resize, convert, info, check, snapshots
• AsyncDisposable - await using support on QMPClient and QemuProcess
• Automatic reconnect - exponential backoff on unexpected disconnect (opt-in)
• Dual ESM + CJS output, TypeScript source maps, full .d.ts declarations

Installation

npm install node-qemu

Requires Node.js ≥ 18 and qemu-system-* / qemu-img binaries on the host.

Quick Start

QMP Client

import { QMPClient } from "node-qemu";

await using client = new QMPClient({ socketPath: "/run/qemu/vm1.sock" });
await client.connect();

// Typed command
const status = await client.queryStatus();
console.log(status.status); // "running" | "paused" | ...

// Typed events
client.on("SHUTDOWN", (e) => console.log("Guest shut down:", e.reason));
client.on("BLOCK_JOB_COMPLETED", (e) => console.log("Backup done:", e.device));
client.on("MIGRATION", (e) => console.log("Migration:", e.status));

// Pause and resume
await client.stop();
await client.cont();

// Graceful shutdown
await client.systemPowerdown();

Process Manager

import { QemuProcess, QMPClient } from "node-qemu";

const proc = new QemuProcess({
  binary: "/usr/bin/qemu-system-x86_64",
  config: {
    machine: { type: "q35", accel: "kvm" },
    cpu: "host",
    memory: { size: 2048 },
    drives: [{ file: "/var/lib/qemu/vm1.qcow2", format: "qcow2", virtio: true }],
    net: [{ type: "tap", ifname: "tap0", script: "no", vhost: true }],
    qmp: { socketPath: "/run/qemu/vm1.sock" },
    vnc: { display: "0" },
    enableKvm: true,
    noReboot: true,
    pidfile: "/run/qemu/vm1.pid",
  },
});

await proc.start();
console.log("QEMU PID:", proc.pid);

proc.on("stderr", (line) => console.error("[qemu]", line));
proc.on("exit", (code, signal) => console.log("Exited", { code, signal }));

// Connect QMP after process starts
await using client = new QMPClient({ socketPath: proc.socketPath! });
await client.connect();

// Graceful stop - SIGTERM with 5s SIGKILL fallback
await proc.stop();

Image Tools

import { QemuImg } from "node-qemu";

// Create a thin-provisioned overlay over a base image
await QemuImg.create({
  filename: "/var/lib/qemu/vm1.qcow2",
  format: "qcow2",
  size: "20G",
  backingFile: "/var/lib/qemu/base.qcow2",
});

// Resize in place
await QemuImg.resize({ filename: "/var/lib/qemu/vm1.qcow2", size: "+10G" });

// Convert raw → qcow2 with compression
await QemuImg.convert({
  src: "/var/lib/qemu/vm1.raw",
  dst: "/var/lib/qemu/vm1.qcow2",
  format: "qcow2",
  compress: true,
});

// Inspect
const info = await QemuImg.info({ filename: "/var/lib/qemu/vm1.qcow2" });
console.log(info.format, info.virtualSize, info.backingFile);

// Internal qcow2 snapshots
await QemuImg.snapshotCreate({ filename: "/var/lib/qemu/vm1.qcow2", tag: "clean" });
const snaps = await QemuImg.snapshotList({ filename: "/var/lib/qemu/vm1.qcow2" });
await QemuImg.snapshotApply({ filename: "/var/lib/qemu/vm1.qcow2", tag: "clean" });
await QemuImg.snapshotDelete({ filename: "/var/lib/qemu/vm1.qcow2", tag: "clean" });

TCP Connection

const client = new QMPClient({ host: "192.168.1.10", port: 4444 });
await client.connect();

Automatic Reconnect

const client = new QMPClient({
  socketPath: "/run/qemu/vm1.sock",
  reconnect: true,
  reconnectDelay: 1000,    // initial delay ms (doubles on each attempt)
  reconnectMaxDelay: 30_000,
});

client.on("disconnected", () => console.log("Lost connection, retrying..."));
client.on("connected", () => console.log("Reconnected"));

Incremental Backup with Dirty Bitmaps

// Track changed blocks since last backup
await client.blockDirtyBitmapAdd({ node: "hd0", name: "inc-backup" });

// ... time passes, guest writes data ...

// Incremental backup using the bitmap
await client.blockdevBackup({
  device: "hd0",
  target: "backup-target",
  sync: "incremental",
  bitmap: "inc-backup",
});

// Monitor completion
client.once("BLOCK_JOB_COMPLETED", async (e) => {
  console.log("Backup complete:", e.device);
  await client.blockDirtyBitmapClear({ node: "hd0", name: "inc-backup" });
});

Live Migration

await client.migrateSetCapabilities([
  { capability: "xbzrle", state: true },
  { capability: "zero-blocks", state: true },
]);

await client.migrate({ uri: "tcp:192.168.1.2:4444" });

client.on("MIGRATION", (e) => {
  if (e.status === "completed") console.log("Migration done");
  if (e.status === "failed")    console.error("Migration failed");
});

Error Handling

import { QmpError, QmpCommandError } from "node-qemu";

try {
  await client.blockdevBackup({ device: "hd0", target: "missing", sync: "full" });
} catch (err) {
  if (err instanceof QmpCommandError) {
    console.error(err.qmpClass, err.description); // "DeviceNotFound" "..."
  } else if (err instanceof QmpError) {
    console.error(err.code); // "CONNECTION_CLOSED" | "CLIENT_CLOSED" | ...
  }
}

Events

QMPClient extends EventEmitter with fully typed payloads:

| Event | Payload | Description | |---|---|---| | SHUTDOWN | ShutdownEvent | Guest or host-initiated shutdown | | RESET | ResetEvent | System reset | | STOP | - | VM execution paused | | RESUME | - | VM execution resumed | | GUEST_PANICKED | GuestPanicEvent | Guest kernel panic | | WATCHDOG | WatchdogEvent | Watchdog timer fired | | BLOCK_IO_ERROR | BlockIoErrorEvent | Block device I/O error | | BLOCK_JOB_COMPLETED | BlockJobEvent | Backup/mirror/stream finished | | BLOCK_JOB_CANCELLED | BlockJobEvent | Block job cancelled | | BLOCK_JOB_ERROR | BlockJobErrorEvent | Block job I/O error | | BLOCK_JOB_READY | BlockJobEvent | Mirror ready to pivot | | JOB_STATUS_CHANGE | JobStatusChangeEvent | Generic job status changed | | DEVICE_ADDED | DeviceEvent | Hotplug device added | | DEVICE_DELETED | DeviceEvent | Hotplug device removed | | MIGRATION | MigrationEvent | Migration status update | | MIGRATION_PASS | MigrationPassEvent | Migration pass counter | | NIC_RX_FILTER_CHANGED | NicRxFilterEvent | NIC RX filter updated | | VNC_CONNECTED | VncEvent | VNC client connected | | VNC_DISCONNECTED | VncEvent | VNC client disconnected | | MEMORY_FAILURE | MemoryFailureEvent | Hardware memory failure | | SUSPEND | - | Guest suspended | | WAKEUP | - | Guest woke up | | connected | - | QMP handshake complete | | disconnected | - | Socket closed | | error | Error | Transport error |

API Reference

Full API documentation is available at sourceregistry.github.io/node-qemu.

For the underlying QMP wire protocol, see the QEMU QMP Reference and qemu-img manual.

Related Libraries

| Library | Role | |---|---| | node-lxc | LXC container lifecycle | | node-ovsdb | Open vSwitch / OVSDB networking | | node-qemu | QEMU VM lifecycle (this library) |

License

Apache-2.0