appsandbox/tools/linux

tools/linux — Linux-side build of AppSandbox guest components

Everything in this tree compiles on a Linux box and produces artifacts that the Windows AppSandbox host needs in order to stage a Linux VM. The components:

Subdir	What it builds	Where it ends up in the guest
agent/	5 userspace daemons (ELF)	/usr/local/bin/appsandbox-{agent,audio,clipboard,display,input}
dxgkrnl/	Hyper-V GPU paravirt kernel module	/lib/modules/<kver>/updates/dxgkrnl.ko (or DKMS)
asb_drm/	Stub DRM driver for KMS capture	/lib/modules/<kver>/updates/asb_drm.ko (or DKMS)
wsl-mesa/	(optional) Mesa with d3d12 + dzn	tarball extracted to /opt/wsl-mesa/

wsl-deps/ (Microsoft's proprietary libd3d12.so etc.) is not built here — it's fetched by the Windows host from Microsoft's public NuGet feed into C:\ProgramData\AppSandbox\wsl-deps\. See tools/wsl-deps/README.md.

Build

Prereqs (Ubuntu 26.04+; package names may differ on other distros):

sudo apt-get install -y \
    build-essential dkms zstd \
    linux-headers-$(uname -r) \
    libdrm-dev libasound2-dev libxcb1-dev libxcb-xfixes0-dev

Then from this directory:

make

That builds the 5 daemons, both kernel modules against your running kernel, and installs them under tools/linux/dist/:

tools/linux/dist/
├── appsandbox-agent           ← strip'd ELF
├── appsandbox-audio
├── appsandbox-clipboard
├── appsandbox-display
├── appsandbox-input
└── modules/
    └── <uname-r>/
        ├── dxgkrnl.ko
        └── asb_drm.ko

dist/ is gitignored — it's only valid on this machine for this kernel.

Other targets:

Target	What it does
make compile	builds in place but doesn't copy to dist/
make agents	builds only the userspace daemons
make modules	builds only the kernel modules
make clean	removes *.o, *.ko, daemon ELFs from source dirs
make distclean	clean + removes dist/

Transfer to the Windows host

This step is manual on purpose — there's no assumption of network connectivity between your Linux build box and the Windows machine that runs AppSandbox.

After a successful build, get dist/'s contents over to your Windows host and place them at:

<appsandbox-repo>\release\resources\linux\

The simplest approach is a tarball:

tar -C dist -czf ~/asb-linux.tar.gz .

Then transfer asb-linux.tar.gz to the Windows host by whatever means you normally use to move files between these two systems (USB stick, shared filesystem, file-share VM, scp, manual upload — whatever works for your setup). On the Windows side, in your appsandbox checkout:

mkdir release\resources\linux
tar xzf C:\path\to\asb-linux.tar.gz -C release\resources\linux\

tar.exe ships with Windows 10+; if it isn't on your PATH the Git for Windows / 7-Zip / WinRAR equivalents all handle .tar.gz fine.

How the staged files reach a running VM

1. release/resources/linux/ is a committed staging dir on the Windows side — same model as the existing release/resources/appsandbox-*.exe files used for Windows guests.
2. AppSandbox.vcxproj's PostBuildEvent xcopies release/resources/ into bin/<cfg>/resources/ next to AppSandbox.exe and AppSandboxCore.dll. That happens on every build, so a rebuild after copying the new files makes them runtime-visible.
3. When you create a Linux VM, disk_util.c::iso_create_resources_ubuntu builds a cidata.iso with user-data (autoinstall) + an extras/ tree that includes everything from <exe_dir>/resources/linux/.
4. On first boot of the VM, autoinstall mounts the cidata ISO, copies extras/ into /opt/appsandbox/, then runs setup.sh via curtin in-target. setup.sh installs the agent ELFs into /usr/local/bin/, the kernel modules into /lib/modules/<kver>/updates/, wires up systemd units, and enables them.

Kernel module version skew

Kernel modules built here only load against an identical kernel version in the guest (uname -r must match exactly). If the guest is on a different kernel from your build machine, setup.sh automatically falls back to the DKMS build path — it copies the source from extras/dxgkrnl/src/ to /usr/src/dxgkrnl-<ver>/ and runs dkms install. DKMS handles future kernel upgrades automatically. The committed .ko is just a fast path.