GitHub - nefarius/vd_agent: Windows SPICE guest agent. Community-maintained fork of the abandoned freedesktop.org vd_agent. · GitHub

Skip to content

Navigation MenuSign inAppearance settingsPlatformAI CODE CREATIONGitHub CopilotWrite better code with AIGitHub Copilot appDirect agents from issue to mergeMCP RegistryIntegrate external toolsDEVELOPER WORKFLOWSActionsAutomate any workflowCodespacesInstant dev environmentsIssuesPlan and track workCode ReviewManage code changesCode QualityEnforce quality at mergeAPPLICATION SECURITYGitHub Advanced SecurityFind and fix vulnerabilitiesCode securitySecure your code as you buildSecret protectionStop leaks before they startEXPLOREWhy GitHubDocumentationBlogChangelogMarketplaceView all featuresSolutionsBY COMPANY SIZEEnterprisesSmall and medium teamsStartupsNonprofitsBY USE CASEApp ModernizationDevSecOpsDevOpsCI/CDView all use casesBY INDUSTRYHealthcareFinancial servicesManufacturingGovernmentView all industriesView all solutionsResourcesEXPLORE BY TOPICAISoftware DevelopmentDevOpsSecurityView all topicsEXPLORE BY TYPECustomer storiesEvents & webinarsEbooks & reportsBusiness insightsGitHub SkillsSUPPORT & SERVICESDocumentationCustomer supportCommunity forumTrust centerPartnersView all resourcesOpen SourceCOMMUNITYGitHub SponsorsFund open source developersPROGRAMSSecurity LabMaintainer CommunityGitHub StarsArchive ProgramREPOSITORIESTopicsTrendingCollectionsEnterpriseENTERPRISE SOLUTIONSEnterprise platformAI-powered developer platformAVAILABLE ADD-ONSGitHub Advanced SecurityEnterprise-grade security featuresCopilot for BusinessEnterprise-grade AI featuresPremium SupportEnterprise-grade 24/7 supportPricingSearch/Sign inSign upAppearance settings

You signed in with another tab or window. Reload to refresh your session.
You signed out in another tab or window. Reload to refresh your session.
You switched accounts on another tab or window. Reload to refresh your session.

Dismiss alert

nefarius

/

vd_agent

Public

Notifications
You must be signed in to change notification settings

Fork
0

Star
2

Code

Issues
0

Pull requests
0

Actions

Security and quality
0

Insights

Additional navigation options

Code

Issues

Pull requests

Actions

Security and quality

Insights

masterBranchesTagsGo to fileCodeOpen more actions menuLatest commit History426 Commits426 CommitsFolders and filesNameNameLast commit messageLast commit date.cursor/rules.cursor/rules  .github/workflows.github/workflows  assetsassets  build-auxbuild-aux  commoncommon  m4m4  msys2msys2  spice-common @ 05c0c26spice-common @ 05c0c26  spice-protocol @ ce0c421spice-protocol @ ce0c421  teststests  vdagentvdagent  vdservicevdservice  .gitattributes.gitattributes  .gitignore.gitignore  .gitlab-ci.yml.gitlab-ci.yml  .gitmodules.gitmodules  CHANGELOG.mdCHANGELOG.md  CMakeLists.txtCMakeLists.txt  COPYINGCOPYING  Makefile.amMakefile.am  README.mdREADME.md  appveyor.ymlappveyor.yml  autogen.shautogen.sh  configure.acconfigure.ac  git.mkgit.mk  mingw-spice-vdagent.spec.inmingw-spice-vdagent.spec.in  spice-vdagent.wxs.inspice-vdagent.wxs.in  test-logtest-log  test-pngtest-png  test-shelltest-shell  View all filesRepository files navigationREADMEGPL-2.0 licenseMore itemsSpice VD Agent for Windows
Community-maintained Windows guest agent for SPICE.
This repository is a public mirror of the abandoned
freedesktop.org spice/win32/vd_agent
project. Canonical downloads live on
GitHub Releases.
The agent provides:

Client mouse mode without grabbing the pointer
Desktop resolution matching the client
Clipboard sharing (text and images)
File transfer into the guest
A Windows service (spice-agent) that starts vdagent.exe in each session

Status
Red Hat no longer maintains upstream SPICE. This fork keeps the Windows agent
building and shipping for current guests, especially Windows 11 VMs on Linux.
The tree already includes the multi-GPU mouse fix from
d7405ee
(vdagent/desktop_layout.cpp): when a real GPU is passed through alongside the
SPICE display device, the agent no longer loses mouse movement.
License and provenance
The agent is GPL-2.0-or-later. See COPYING and the copyright
headers in each source file. Original copyright remains with Red Hat, Inc. and
other upstream authors. This fork does not claim the Red Hat or SPICE
trademarks.
Pinned build-time submodules (do not bump casually):

Submodule
Commit
Upstream

spice-protocol
ce0c4211e6f16c66477934cc42e70fa0988ca7f0
https://gitlab.freedesktop.org/spice/spice-protocol

spice-common
05c0c26839e88e6d0cc5452f49c40e38543c8f97
https://gitlab.freedesktop.org/spice/spice-common

Submodule URLs use HTTPS. MSI upgrades keep the historical WiX UpgradeCode
(7eb9b146-db04-42d7-a8ba-71fc8ced7eed). Related products are removed after
InstallValidate, before the install transaction begins, so the shared
components are recopied instead of being deleted by the old package's
uninstall. Because wixl does not read the PE version resource, the File
table gets RC_FILEVERSION explicitly; keep it identical to the four fields in
VS_VERSION_INFO. The x64 installer still only ships vdagent.exe and
vdservice.exe into C:\Program Files\SPICE agent\bin.
Clone
git clone --recursive https://github.com/nefarius/vd_agent.git
cd vd_agent
If you already cloned without submodules:
git submodule update --init --recursive
The freedesktop GitLab remote is preserved as upstream after the mirror was
created. Fetch it with:
git fetch upstream
Local build (MSYS2 UCRT64)
The Autotools + MinGW-w64 UCRT64 path is the supported way to produce the
installer. CMake + MSVC remains available for local development but does not
build an MSI.
Prerequisites

MSYS2
An UCRT64 shell (C:\msys64\ucrt64.exe, or MSYSTEM=UCRT64)

From the UCRT64 shell, in the repository root:
bash msys2/install.sh
autoreconf -i
bash msys2/build.sh builducrt64
bash msys2/package.sh builducrt64
install.sh pulls autotools, autoconf-archive, the UCRT64 toolchain,
msitools (wixl), and ImageMagick (tests). PNG clipboard conversion uses
the Windows Imaging Component that ships with Windows Vista and later.
build.sh configures, compiles vdagent.exe / vdservice.exe, and runs
test-png, test-log, and test-shell. package.sh then invokes
make msi and writes:
builducrt64/spice-vdagent-x64-<version>.msi

Version strings come from git describe via
build-aux/git-version-gen. Release tags must
look like v0.11.0 (minor bumps) so Programs and Features shows the tag
exactly. Untagged builds add the commit count since the last tag (for example
v0.11.0 plus 83 commits becomes 0.11.0.83-<hash>). Configure fails if that count
plus --with-buildid reaches 256, because that would collide with the next
micro version.
To sign a local build, sign the two executables before package.sh, then
sign the MSI.
Optional MSVC build
git submodule update --init --recursive
cmake -S . -B build64 -A x64
cmake --build build64 --config Release
cmake --build build64 --config Release --target check
CI and releases
GitHub Actions (.github/workflows/build.yml) builds the x64 UCRT64 MSI on
windows-2022.

Event
Signing
Publish

Pull request / master push
Skipped
Workflow artifact vdagent-win-x64 only

Tag v*
Required
Signed MSI + SHA-256, artifact mirror, GitHub Release

Signing uses SignRelay so the
certificate never lands on the runner. The flow matches
DsHidMini:

Build and test unsigned binaries
On a v* tag, sign vdagent.exe and vdservice.exe in place
Package the MSI from those binaries
Sign the MSI
Verify Authenticode (Get-AuthenticodeSignature Status = Valid)
Write <msi>.sha256
Upload vdagent-win-x64 and, on tags, notify
AppVeyorArtifactsReceiver
Attach the MSI and checksum to the GitHub Release

The SignRelay composite action is pinned to commit
39ccbe0cef16a383237130380a5aef8db040d5d0. The CLI needs .NET 10 on the
runner (actions/setup-dotnet with 10.0.x).
Repository settings
Create these on nefarius/vd_agent (Settings → Secrets and variables):

Name
Kind
Purpose

SIGN_RELAY_SERVER
Variable
Relay base URL, for example https://signrelay.api.nefarius.systems/

SIGN_RELAY_CI_TOKEN
Secret
CI bearer token (SignRelay__CiToken on the server)

WEBHOOK_URL
Secret
AppVeyorArtifactsReceiver webhook

Copy SIGN_RELAY_CI_TOKEN and WEBHOOK_URL from an already-working repo such
as DsHidMini. SIGN_RELAY_SERVER is already set as a repository variable.
Do not commit secret values.
The Windows SignRelay agent holds the code-signing certificate. Configure
subject/thumbprint and timestamp there, not in this repository.
Publishing a release

Update CHANGELOG.md

Tag an annotated release and push it:
git tag -a v0.11.0 -m "vdagent-win 0.11.0"
git push origin v0.11.0

Confirm the Build workflow:

unsigned path is not used
both executables and the MSI verify as Valid
artifacts receiver accepted the webhook
the GitHub Release contains the MSI and .sha256

Install the MSI in a Windows 11 SPICE guest and run the checklist below

If a tagged build fails after signing started, fix the tree and move the tag
forward (or use a new minor version). Do not reuse a published MSI name with
different bytes.
To recover a failed release: delete the GitHub Release draft if any, push a
new tag, and keep the previous published tag immutable if users may have
downloaded it.
appveyor.yml is kept only for historical parity with the last upstream
UCRT64 MSI layout. GitHub Actions is the authoritative CI. Remove AppVeyor
once a signed Actions MSI has been smoke-tested.
Windows 11 VM validation
Use a Windows 11 guest on Linux (QEMU/KVM + SPICE), with the QXL or
qxl-wddm-dod display device.

Clean install — run spice-vdagent-x64-*.msi as Administrator
Service — spice-agent is Running / Automatic; vdagent.exe is
present in the user session
SPICE connection — reconnect virt-viewer / spicy; agent channel is up
Clipboard — text and a bitmap both ways
File transfer — drop a file from the client; it lands on the desktop
Dynamic resolution — resize the client window; the guest desktop
follows when the WDDM QXL driver is in use
Multi-GPU / passthrough mouse — add a real GPU for passthrough, keep
the SPICE display, confirm the pointer keeps moving (the d7405ee fix)
Upgrade — install over a previous Spice agent MSI; service comes back
Uninstall — remove the product; spice-agent is gone

Optional CMake / Fedora notes

Fedora cross-builds still work via .gitlab-ci.yml and
mingw-spice-vdagent.spec.in; they are not
used for GitHub Releases.
x86 MSI builds are no longer produced by the maintained pipeline.

AboutWindows SPICE guest agent. Community-maintained fork of the abandoned freedesktop.org vd_agent.ResourcesReadmeGPL-2.0 licenseActivityStars2 starsWatchers0 watchingForks0 forksReport repositoryReleasesContributorsLanguages

Footer

© 2026 GitHub, Inc.

Footer navigation

Terms

Privacy

Security

Status

Community

Docs

Contact

Manage cookies

Do not share my personal information

You can’t perform that action at this time.

The vd_agent is a community-maintained fork of the abandoned freedesktop.org vd_agent project, specifically designed as a Windows guest agent for the SPICE protocol. This agent serves a critical function in allowing SPICE guests, particularly those running on Linux systems, to interact seamlessly with the Windows environment. Key functionalities provided by the agent include enabling client mouse mode without requiring the pointer to be grabbed, synchronizing the desktop resolution to the client display, facilitating clipboard sharing for both text and images, and enabling file transfers into the guest environment. The core mechanism involves a Windows service, named spice-agent, which is responsible for initiating the vdagent.exe process in each active session.

The project operates in a context where Red Hat no longer maintains the upstream SPICE project, necessitating this fork to ensure the continued building and shipping of the Windows agent for contemporary guests, notably Windows 11 Virtual Machines running on Linux. The codebase incorporates specific fixes, such as an adjustment in desktop layout code to resolve issues related to mouse movement when a real GPU is passed through alongside the SPICE display device. The agent is licensed under the GPL-2.0-or-later, with original copyright attributed to Red Hat, Inc. and other upstream authors, and the fork makes no claim to the Red Hat or SPICE trademarks.

The distribution and development process outlines a complex build pipeline. The repository details the use of Autotools and MinGW-w64 UCRT64 as the supported method for creating the installer. The process involves executing provided scripts to handle configuration, compilation, and packaging, ultimately generating an MSI installer. The build process relies on specific tools to pull in necessary components, including autotools, autoconf-archive, the UCRT64 toolchain, and ImageMagick for testing. Version strings are derived from git describe, and the process contains specific checks to prevent version nomenclature collisions.

The project emphasizes a rigorous security signing workflow for publishing releases. This process utilizes SignRelay to manage the signing of the compiled executables and the resulting MSI. The workflow ensures that the executable files and the MSI are signed, verifying the Authenticode signature, and generating a corresponding SHA-256 checksum. This signed artifact is then uploaded to GitHub Releases, attaching the MSI and checksum to the release, thereby ensuring the integrity and authenticity of the distributed software. The repository settings further specify variables for configuring the SignRelay endpoint and the CI bearer token, which must be managed securely.

For deployment and validation, the documentation outlines steps for installing the MSI in a Windows 11 SPICE guest environment, typically utilizing a QEMU/KVM setup with a QXL display device. Validation steps confirm that the agent successfully establishes the SPICE connection, maintains dynamic resolution, allows bidirectional clipboard sharing, and correctly handles multi-GPU passthrough, confirming the functionality of the mouse and display synchronization fixes. Although cross-builds are supported via Gitlab CI for historical parity, the maintained pipeline focuses on GitHub Actions as the authoritative Continuous Integration system.