PHPackages coquibot/coqui-toolkit-libvirt - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. coquibot/coqui-toolkit-libvirt ActiveLibrary[Utility & Helpers](/categories/utility) coquibot/coqui-toolkit-libvirt ============================== Libvirt virtualization toolkit for Coqui — manage VMs, networks, snapshots, and GPU passthrough via virsh/virt-install v0.1.0(2mo ago)00MITPHPPHP ^8.4CI failing Since Apr 9Pushed 2mo agoCompare [ Source](https://github.com/carmelosantana/coqui-toolkit-libvirt)[ Packagist](https://packagist.org/packages/coquibot/coqui-toolkit-libvirt)[ RSS](/packages/coquibot-coqui-toolkit-libvirt/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (3)Versions (2)Used By (0) Coqui Libvirt Toolkit ===================== [](#coqui-libvirt-toolkit) Libvirt/KVM virtualization toolkit for [Coqui](https://github.com/AgentCoqui/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 ------------ [](#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) [](#installing-dependencies-debianubuntu) ``` # Core sudo apt install libvirt-daemon-system qemu-kvm virtinst qemu-utils # Web console (optional) pip3 install websockify sudo apt install novnc ``` Installation ------------ [](#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 ----------- [](#credentials) KeyDescription`LIBVIRT_URI`Libvirt connection URI (default: `qemu:///system`). Set to `qemu:///session` for unprivileged access or `qemu+ssh://user@host/system` for remote hosts.Set via the Coqui `credentials` tool or in your workspace `.env`: ``` LIBVIRT_URI=qemu:///system ``` Tools Provided -------------- [](#tools-provided) ### `vm_lifecycle` [](#vm_lifecycle) Manage VM lifecycle — create, start, stop, reboot, destroy, delete, snapshot, restore. ParameterTypeRequiredDescription`action`enumYes`create`, `start`, `stop`, `force_stop`, `destroy`, `reboot`, `delete`, `suspend`, `resume`, `snapshot`, `restore`, `delete_snapshot`, `check_deps``name`string\*VM name. Required for all actions except `check_deps`.`memory`integerNoRAM in MiB (default: 2048). Used with `create`.`vcpus`integerNoVirtual CPUs (default: 2). Used with `create`.`disk_path`stringNoPath to existing disk image. Used with `create`.`disk_size`stringNoDisk size (e.g. `20G`). Used with `create` when `disk_path` is not given.`iso`stringNoPath to ISO for CD-ROM. Used with `create` for OS installation.`network`stringNoNetwork name (default: `default`). Used with `create`.`os_variant`stringNoOS variant hint (e.g. `ubuntu22.04`, `win11`). Used with `create`.`pci_devices`arrayNoPCI addresses for GPU passthrough (e.g. `["0000:06:00.0"]`). Used with `create`.`shared_folders`arrayNoShared folders: `[{"host_path": "...", "mount_tag": "...", "driver": "9p"}]`. Used with `create`.`boot_dev`enumNoBoot device: `hd` (default) or `cdrom`. Used with `create`.`snapshot_name`stringNoSnapshot name. Used with `snapshot`, `restore`, `delete_snapshot`.`snapshot_description`stringNoSnapshot description. Used with `snapshot`.`remove_storage`booleanNoRemove disk images when deleting. Used with `delete`.### `vm_info` [](#vm_info) Query VM and host information. ParameterTypeRequiredDescription`action`enumYes`info`, `list`, `domxml`, `hardware`, `snapshots``name`string\*VM name. Required for `info`, `domxml`, `snapshots`.`all`booleanNoInclude all VM states. Default: true. Used with `list`.### `vm_console` [](#vm_console) Manage web console access to VMs via noVNC + websockify. ParameterTypeRequiredDescription`action`enumYes`open`, `close`, `status``name`stringYesVM name.`ws_port`integerNoWebSocket port (auto-detected from 6080 if omitted). Used with `open`.### `vm_network` [](#vm_network) Manage libvirt virtual networks. ParameterTypeRequiredDescription`action`enumYes`create`, `start`, `stop`, `destroy`, `list`, `info``name`string\*Network name. Required for all actions except `list`.`type`enumNo`nat` (default), `isolated`, `bridged`. Used with `create`.`subnet`stringNoCIDR subnet (e.g. `192.168.100.0/24`). Used with `create`.`bridge`stringNoBridge interface name. Required when type is `bridged`.`dhcp`booleanNoEnable DHCP. Default: true. Used with `create`.`autostart`booleanNoAuto-start on host boot. Default: true. Used with `create`.### `vm_storage` [](#vm_storage) Manage disk images, shared folders, and GPU passthrough. ParameterTypeRequiredDescription`action`enumYes`create_disk`, `disk_info`, `resize_disk`, `attach_disk`, `shared_folder`, `gpu_passthrough``path`stringNoDisk image path. Used with `create_disk`, `disk_info`, `resize_disk`, `attach_disk`.`size`stringNoDisk size (e.g. `20G`, `+10G`). Used with `create_disk`, `resize_disk`.`format`enumNo`qcow2` (default), `raw`, `vmdk`, `vdi`. Used with `create_disk`.`name`stringNoVM name. Used with `attach_disk`, `shared_folder`.`target`stringNoTarget device (e.g. `vdb`). Used with `attach_disk`.`host_path`stringNoHost directory to share. Used with `shared_folder`.`mount_tag`stringNoMount tag for shared filesystem. Used with `shared_folder`.`driver`enumNo`9p` (default, wider compat) or `virtiofs` (faster). Used with `shared_folder`.`sub_action`enumNo`list_gpus`, `check_iommu`, `iommu_group`. Used with `gpu_passthrough`.`pci_address`stringNoPCI address (e.g. `0000:06:00.0`). Used with `iommu_group` sub-action.Agent Workflow -------------- [](#agent-workflow) ### Creating a VM [](#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) [](#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 [](#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 [](#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 ---------------- [](#standalone-usage) ```