{"id":28804767,"url":"https://github.com/gechandesu/qga","last_synced_at":"2026-02-24T00:45:31.398Z","repository":{"id":298190347,"uuid":"999169922","full_name":"gechandesu/qga","owner":"gechandesu","description":"QEMU Guest Agent Protocol client","archived":false,"fork":false,"pushed_at":"2025-06-11T16:32:48.000Z","size":26,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-18T09:48:55.881Z","etag":null,"topics":["qemu","qemu-ga","qemu-guest-agent","virtualization","vlang","vlang-module","vlang-package"],"latest_commit_sha":null,"homepage":"https://gechandesu.github.io/qga/","language":"V","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gechandesu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-09T21:04:50.000Z","updated_at":"2025-06-11T16:32:51.000Z","dependencies_parsed_at":"2025-06-09T22:22:58.118Z","dependency_job_id":"08753f8a-2d84-4583-8c34-f804b6000329","html_url":"https://github.com/gechandesu/qga","commit_stats":null,"previous_names":["gechandesu/qga"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/gechandesu/qga","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gechandesu%2Fqga","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gechandesu%2Fqga/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gechandesu%2Fqga/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gechandesu%2Fqga/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gechandesu","download_url":"https://codeload.github.com/gechandesu/qga/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gechandesu%2Fqga/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262714471,"owners_count":23352462,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["qemu","qemu-ga","qemu-guest-agent","virtualization","vlang","vlang-module","vlang-package"],"created_at":"2025-06-18T09:31:11.508Z","updated_at":"2025-10-30T14:32:49.262Z","avatar_url":"https://github.com/gechandesu.png","language":"V","funding_links":[],"categories":[],"sub_categories":[],"readme":"# QEMU Guest Agent Protocol client for V\n\n`qga` is full featured QGA client for interacting with guest operating systems\nin QEMU-powered virtual machine from virtualisation host.\n\nSee also:\n\n- Guest Agent in QEMU Wiki: https://wiki.qemu.org/Features/GuestAgent\n- QEMU Guest Agent Protocol Reference: https://qemu-project.gitlab.io/qemu/interop/qemu-ga-ref.html\n\n## Usage\n\nRun the virtual machine. In this example `disk.qcow2` contains Debian 12 Bookworm\nwith `qemu-guest-agent` package installed.\n\n```\n/usr/bin/qemu-system-x86_64 \\\n    -name testvm \\\n    -accel kvm \\\n    -cpu host \\\n    -smp 1 \\\n    -m 1024M \\\n    -drive file=disk.qcow2,media=disk,if=virtio \\\n    -chardev socket,path=/tmp/qga.sock,server=on,wait=off,id=qga0 \\\n    -device virtio-serial \\\n    -device virtserialport,chardev=qga0,name=org.qemu.guest_agent.0\n```\n\nThen connect to a guest agent server socket `/tmp/gqa.sock`:\n\n```v\nimport qga\n\nfn main() {\n  mut ga := qga.Client.new('/tmp/qga.sock')!\n  agent_version := ga.info()!.version\n  println('everything is fine! guest agent version is ${agent_version}')\n}\n```\n\n## Error handling\n\n`GuestAgentError` contains extended error information. See the description of\nthe structure fields.\n\nThe error can be returned either directly by the guest agent or when trying to\ncommunicating it. `GuestAgentError` has an explicit flag to distinguish such\nerrors. If for some reason the guest agent could not be reached, `is_unreachable`\nwill be true. The error information will be in the underlying error stored in the\n`err` field and in the error text itself.\n\n```v\nmodule main\n\nimport qga\n\nfn main() {\n\tmut ga := qga.Client.new('/tmp/qga.sock')!\n\tga.get_devices() or {\n\t\tif err is qga.GuestAgentError {\n\t\t\tif err.is_unreachable {\n\t\t\t\tprintln('agent is unreachable')\n\t\t\t\treturn\n\t\t\t} else {\n\t\t\t\tprintln('error info from guest agent: class=${err.class} desc=${err.desc}')\n\t\t\t\treturn\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\nPrints this (so `guest-get-devices` is disabled on Debian):\n\n```\nerror info from guest agent: class=CommandNotFound desc=Command guest-get-devices has been disabled\n```\n\nIn addition, `qga` module provides a small set of specific error codes.\nThey can be checked in this way without `err` smartcasting:\n\n```v ignore\nga.ping() or {\n  match err.code() {\n    qga.err_no_connect { panic('socket connection error') }\n    qga.err_timed_out { panic('timeout reached') }\n    qga.err_from_agent { panic('error ocurred in guest agent') }\n    else { panic(err) }\n  }\n}\n```\n\n## License\n\n`LGPL-3.0-or-later`\n\nSee [COPYING](COPYING) and [COPYING.LESSER](COPYING.LESSER) for information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgechandesu%2Fqga","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgechandesu%2Fqga","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgechandesu%2Fqga/lists"}