README

Libvirt/KVM virtualization toolkit for Coqui. Wraps virsh, virt-install, and qemu-img to give agents full VM management capabilities including lifecycle control, disk management, virtual networking, GPU passthrough, shared folders, snapshots, and browser-based console access via noVNC.

Requirements

• PHP 8.4+
• libvirt (virsh, virt-install, virt-xml-validate)
• QEMU/KVM (qemu-system-x86_64, qemu-img)
• KVM kernel modules loaded (/dev/kvm accessible)
• websockify (optional — for web console)
• noVNC (optional — for browser-based console UI)

Installing Dependencies (Debian/Ubuntu)

# Core
sudo apt install libvirt-daemon-system qemu-kvm virtinst qemu-utils

# Web console (optional)
pip3 install websockify
sudo apt install novnc

Installation

composer require coquibot/coqui-toolkit-libvirt

When installed alongside Coqui, the toolkit is auto-discovered via Composer's extra.php-agents.toolkits — no manual registration needed.

Credentials

Set via the Coqui credentials tool or in your workspace .env:

LIBVIRT_URI=qemu:///system

Tools Provided

vm_lifecycle

Manage VM lifecycle — create, start, stop, reboot, destroy, delete, snapshot, restore.

vm_info

Query VM and host information.

vm_console

Manage web console access to VMs via noVNC + websockify.

vm_network

Manage libvirt virtual networks.

vm_storage

Manage disk images, shared folders, and GPU passthrough.

Agent Workflow

Creating a VM

1. vm_lifecycle  action: check_deps          → verify system requirements
2. vm_storage    action: create_disk          → create a qcow2 disk image
3. vm_network    action: create               → create a virtual network (or use "default")
4. vm_lifecycle  action: create               → define the VM with CPU, RAM, disk, network, ISO
5. vm_lifecycle  action: start                → boot the VM
6. vm_console    action: open                 → get a noVNC URL for browser-based console

Shared Folders (9p)

Mount a host directory inside the guest:

vm_storage  action: shared_folder  name: my-vm  host_path: /data/shared  mount_tag: hostshare

Inside the guest:

mount -t 9p -o trans=virtio hostshare /mnt/shared

GPU Passthrough

1. vm_storage  action: gpu_passthrough  sub_action: check_iommu    → verify IOMMU/VFIO
2. vm_storage  action: gpu_passthrough  sub_action: list_gpus      → find GPU PCI addresses
3. vm_storage  action: gpu_passthrough  sub_action: iommu_group    → check IOMMU group isolation
4. vm_lifecycle action: create ... pci_devices: ["0000:06:00.0"]   → create VM with GPU attached

Prerequisites: IOMMU enabled in BIOS + kernel (intel_iommu=on or amd_iommu=on), GPU bound to vfio-pci driver.

Snapshots

vm_lifecycle  action: snapshot         name: my-vm  snapshot_name: before-update
vm_lifecycle  action: restore          name: my-vm  snapshot_name: before-update
vm_lifecycle  action: delete_snapshot  name: my-vm  snapshot_name: before-update
vm_info       action: snapshots        name: my-vm

Standalone Usage

<?php

declare(strict_types=1);

use CoquiBot\Toolkits\Libvirt\LibvirtToolkit;

require __DIR__ . '/vendor/autoload.php';

$toolkit = LibvirtToolkit::fromEnv();

foreach ($toolkit->tools() as $tool) {
    echo $tool->name() . ': ' . $tool->description() . PHP_EOL;
}

// Check system dependencies
$lifecycle = $toolkit->tools()[0];
$result = $lifecycle->execute(['action' => 'check_deps']);
echo $result->content;

Architecture

The toolkit wraps CLI tools rather than using PHP libvirt bindings (which are abandoned/minimal):

Development

git clone https://github.com/AgentCoqui/coqui-toolkit-libvirt.git
cd coqui-toolkit-libvirt
composer install

Run tests

./vendor/bin/pest

Static analysis

./vendor/bin/phpstan analyse

License

MIT