Preserving the Legacy: The SPICE vd_agent Community Fork

"I refuse to let SPICE die."

This project serves as a community-driven lifeline for the abandoned legacy vd_agent originally hosted by freedesktop.org. It ensures that Windows guests—particularly Windows 11 running on Linux hosts—remain fully functional.

🛠️ Core Functionalities

The agent enables several critical guest-to-host integrations:

• Mouse Integration: Client mouse mode that operates without needing to grab the pointer.
• Dynamic Display: Automatic matching of the desktop resolution to the client window.
• Shared Clipboard: Seamless transfer of text and images.
• File Transfer: Ability to move files from the host into the guest environment.
• Background Service: A dedicated Windows service (spice-agent) responsible for launching vdagent.exe within every user session.

Key Improvements

The current codebase incorporates a vital fix for multi-GPU setups (sourced from commit d7405ee in vdagent/desktop_layout.cpp). This prevents the agent from losing track of mouse movements when a physical GPU is passed through alongside the virtual SPICE display.

---

📦 Technical Specifications

Submodule Dependencies

To maintain stability, the following submodules are pinned. Caution: Do not update these without a specific reason.

Installer & Packaging Nuances

• Identity: The MSI maintains the historical WiX UpgradeCode: 7eb9b146-db04-42d7-a8ba-71fc8ced7eed.
• Component Handling: To prevent shared components from being deleted during an update, related products are purged after InstallValidate but before the transaction begins.
• Version Sync: Since wixl ignores PE version resources, the RC_FILEVERSION in the File table must be manually kept identical to the VS_VERSION_INFO fields.
• Deployment: The x64 installer deploys vdagent.exe and vdservice.exe to C:\Program Files\SPICE agent\bin.

---

🏗️ Build Instructions

Getting the Code

# Clone the repository including submodules
git clone --recursive https://github.com/nefarius/vd_agent.git
cd vd_agent

# If you forgot submodules during clone:
git submodule update --init --recursive

# Access the original freedesktop source
git fetch upstream

Local Build: MSYS2 (UCRT64)

The primary method for generating the official installer is via Autotools + MinGW-w64 UCRT64.

Prerequisites:

• MSYS2 installation.
• An UCRT64 shell (via C:\msys64\ucrt64.exe or setting MSYSTEM=UCRT64).

Build Sequence:

• Initialize environment: bash msys2/install.sh (Installs autotools, autoconf-archive, msitools, and ImageMagick).
• Generate build files: autoreconf -i
• Compile binaries: bash msys2/build.sh builducrt64
• Create MSI package: bash msys2/package.sh builducrt64

Note: PNG clipboard support relies on the Windows Imaging Component (WIC) available in Windows Vista and newer.

Local Build: MSVC (Development Only)

For those preferring Visual Studio, a CMake path is available, though it cannot produce an MSI.

git submodule update --init --recursive
cmake -S . -B build64 -A x64
cmake --build build64 --config Release
cmake --build build64 --config Release --target check

---

🔢 Versioning Logic

Version strings are generated via build-aux/git-version-gen using git describe.

1. Tagged Releases: Must follow the v0.11.0 format for correct display in "Programs and Features."
2. Development Builds: Append the commit count since the last tag (e.g., 0.11.0.83-hash).

Collision Warning: The configuration will fail if the commit count $C$ plus the build ID $B$ exceeds the micro-version limit: $\text{If } (C + B) \ge 256 \rightarrow \text{Configuration Failure}$

---

🚀 CI/CD Pipeline

The project utilizes GitHub Actions (.github/workflows/build.yml) on windows-2022 to automate the x64 UCRT64 MSI production.

Security & Environment

To ensure the signing certificate is never exposed to the runner, SignRelay is used (pinned to commit 39ccbe0). The runner requires .NET 10 (actions/setup-dotnet with 10.0.x).

Required Repository Secrets: