Installation

📦 Installation

NixOS user? You have a nicer path — see NixOS. Not sure your distro, kernel or setup is supported? Check Prerequisites first.

🚀 Quick start

1. Download the latest OpenDS5-Companion-Setup-<version>.AppImage from Releases and make it executable:

   chmod +x OpenDS5-Companion-Setup-*.AppImage
   ./OpenDS5-Companion-Setup-*.AppImage

2. The setup wizard opens on first launch. It shows the exact plan for your distribution and asks for your password once (polkit). It installs:
   • the vds_hcd kernel module via DKMS (so it rebuilds automatically on every kernel update),
   • the vdsd daemon + vdsctl CLI to /usr/local/bin,
   • the systemd service, udev rules, and controller-audio (wireplumber) config,
   • the vds group (your user is added — log out and back in for it to take effect),
   • a launcher: the AppImage is copied to ~/Applications/OpenDS5.AppImage with a desktop entry, so it appears in your app menu.
   • a bluetoothd override (--noplugin=input) so vds can claim the controller — see the note in Getting Started.
3. Pair your DualSense over Bluetooth. Done.

Prefer the terminal? ./OpenDS5.AppImage --install-system runs the same installer. Useful flags: --dry-run (print the plan and exact commands, change nothing), --yes (skip the confirmation).

🐧 What happens per distribution

Distro	Mechanism
Fedora	dnf installs dkms + kernel-devel (or the matching COPR devel package on CachyOS/fsync kernels)
Arch / CachyOS	pacman installs dkms + headers matched to your kernel flavor (linux-cachyos-bore-headers, linux-zen-headers, …); Clang/LTO kernels are detected and built with LLVM automatically
Debian / Ubuntu	apt installs dkms + linux-headers-$(uname -r)
openSUSE	zypper installs dkms + the devel package matching your kernel flavor (kernel-default-devel, kernel-rt-devel, …)
Bazzite / Silverblue	rpm-ostree install dkms kernel-devel layers the packages; one reboot, then re-run the wizard
NixOS	Declarative — see NixOS
Anything else	Clean "unsupported" message; see docs/PORTING.md for manual steps

🔐 Secure Boot

Fully supported. The module is signed with DKMS's own MOK key (/var/lib/dkms/mok.key). If your system already enrolled that key for any other DKMS module (NVIDIA, VirtualBox, …), nothing extra happens. If not, the wizard runs mokutil --import:

1. You choose a one-time password during install.
2. On the next reboot, the blue MOK Manager screen appears — choose Enroll MOK, enter that password.
3. The module loads from then on.

Until that reboot the module is built and installed but can't load (the installer exits with code 6 to signal this).

✅ Verifying an install

lsmod | grep vds_hcd        # module loaded
ls /dev/vds*                # device nodes exist
systemctl status vdsd       # daemon running

📜 Logs & exit codes

Path	Contents
/var/log/opends5/install.log	Every privileged command with full output
~/.local/state/opends5/install.log	The plan and run header

Exit code	Meaning
0	Success (or dry run)
2	Usage error
3	Unsupported distribution
4	A step failed; partial DKMS registration was rolled back
5	Module loaded but /dev/vds* missing
6	Built and signed; reboot to finish MOK enrollment

The wizard's failure screen shows the log path and can copy a diagnostics bundle for bug reports. The installer is additive only (never edits existing host config), asks for authentication exactly once, needs no network, and rolls back on the first failing step.