[GH-ISSUE #357] Custom Proton (proton-cachyos) placed in compatibilitytools.d never registered by containerized Steam client (steam:edge) #102

New issue

Open

opened 2026-10-15 12:49:01 +00:00 by bsakaguchi · 3 comments

bsakaguchi commented

2026-10-15 12:49:01 +00:00

Owner

Originally created by @Moustik2002 on GitHub (Aug 16, 2026).
Original GitHub issue: https://github.com/games-on-whales/gow/issues/357

Environment

Wolf / Games on Whales, Steam container image: ghcr.io/games-on-whales/steam:edge
Host: Unraid NAS, RTX 3070
Wolf Den's "Compatibility Tools" page (Ubuntu tab) used to upload the archive

What I tried

Downloaded proton-cachyos-11.0-20260703-slr-x86_64.tar.xz and proton-cachyos-10.0-20260425-slr-x86_64.tar.xz from CachyOS's official releases.
Manually extracted into compatibilitytools.d inside the persistent Steam profile folder, with correct ownership (99:100). Not detected.
Uploaded the same archive (repacked as .zip) via Wolf Den's built-in "Compatibility Tools" page (Ubuntu tab) — confirmed successful deployment (2.45 GiB).
Added an explicit mount in config.toml for the WolfSteam app profile:
mounts = ['/mnt/cache_nvme/appdata/gow/compatibilitytools.d/ubuntu:/home/retro/.steam/steam/compatibilitytools.d']

Confirmed via docker inspect that the mount is active, and via docker exec ... ls that the tool's files (including compatibilitytool.vdf and toolmanifest.vdf) are present and readable inside the container at the expected path.

Restarted the wolf container, fully removed/recreated the WolfSteam container, toggled Steam Play settings, and cleared appcache/appinfo.vdf — none of this caused Steam to pick up the tool.

Result

The custom Proton build never appears in the per-game Compatibility dropdown (tested on a native Steam game). grep -rli "compatibilitytools\|cachyos" logs/ inside the container returns nothing — the Steam client apparently never even attempts to scan compatibilitytools.d for custom tools, despite valid file structure and correct permissions.

As a side note, for non-Steam (shortcut) games, many more "Steam Linux Runtime" compat tools (1.0–4.0, Legacy) do show up in the dropdown, which suggests some difference in how compat tool lists are built for native vs. non-Steam titles — possibly relevant here.

Question

Is compatibilitytools.d scanning expected to work out of the box in the steam:edge image, or does it require something else (e.g. a specific Steam client flag, first-run-only detection, or a different mount target) to be picked up? Any pointers appreciated.

Originally created by @Moustik2002 on GitHub (Aug 16, 2026). Original GitHub issue: https://github.com/games-on-whales/gow/issues/357 ## Environment - Wolf / Games on Whales, Steam container image: `ghcr.io/games-on-whales/steam:edge` - Host: Unraid NAS, RTX 3070 - Wolf Den's "Compatibility Tools" page (Ubuntu tab) used to upload the archive ## What I tried 1. Downloaded `proton-cachyos-11.0-20260703-slr-x86_64.tar.xz` and `proton-cachyos-10.0-20260425-slr-x86_64.tar.xz` from CachyOS's official releases. 2. Manually extracted into `compatibilitytools.d` inside the persistent Steam profile folder, with correct ownership (99:100). Not detected. 3. Uploaded the same archive (repacked as `.zip`) via Wolf Den's built-in "Compatibility Tools" page (Ubuntu tab) — confirmed successful deployment (2.45 GiB). 4. Added an explicit mount in `config.toml` for the `WolfSteam` app profile: mounts = ['/mnt/cache_nvme/appdata/gow/compatibilitytools.d/ubuntu:/home/retro/.steam/steam/compatibilitytools.d'] Confirmed via `docker inspect` that the mount is active, and via `docker exec ... ls` that the tool's files (including `compatibilitytool.vdf` and `toolmanifest.vdf`) are present and readable inside the container at the expected path. 5. Restarted the `wolf` container, fully removed/recreated the `WolfSteam` container, toggled Steam Play settings, and cleared `appcache/appinfo.vdf` — none of this caused Steam to pick up the tool. ## Result The custom Proton build never appears in the per-game Compatibility dropdown (tested on a native Steam game). `grep -rli "compatibilitytools\|cachyos" logs/` inside the container returns nothing — the Steam client apparently never even attempts to scan `compatibilitytools.d` for custom tools, despite valid file structure and correct permissions. As a side note, for non-Steam (shortcut) games, many more "Steam Linux Runtime" compat tools (1.0–4.0, Legacy) do show up in the dropdown, which suggests some difference in how compat tool lists are built for native vs. non-Steam titles — possibly relevant here. ## Question Is `compatibilitytools.d` scanning expected to work out of the box in the `steam:edge` image, or does it require something else (e.g. a specific Steam client flag, first-run-only detection, or a different mount target) to be picked up? Any pointers appreciated.

bsakaguchi commented

2026-10-15 12:49:02 +00:00

Author

Owner

@Skerga commented on GitHub (Aug 16, 2026):

From me scanning your description I caught a small error, the mount for ubuntu based images should be: mounts = ['/mnt/cache_nvme/appdata/gow/compatibilitytools.d/ubuntu:/home/retro/.steam/debian-installation/compatibilitytools.d'].

Could you try again with this path and report back if that fixed it, please.

@Skerga commented on GitHub (Aug 16, 2026): From me scanning your description I caught a small error, the mount for ubuntu based images should be: mounts = ['/mnt/cache_nvme/appdata/gow/compatibilitytools.d/ubuntu:/home/retro/.steam/**debian-installation**/compatibilitytools.d']. Could you try again with this path and report back if that fixed it, please.

bsakaguchi commented

2026-10-15 12:49:02 +00:00

Author

Owner

@Moustik2002 commented on GitHub (Aug 17, 2026):

Thanks for the suggestion — tested it, but it doesn't seem to apply to this image. /home/retro/.steam/debian-installation/ doesn't exist at all in steam:edge (checked via find /home/retro -iname "compatibilitytools"); the only real path is /home/retro/.steam/steam/compatibilitytools.d, which is what my original mount already pointed to. So I reverted to that path and kept digging.

Confirmed the mount/permissions aren't the issue. From inside the container as the retro user:

Directory and files fully readable (0755, world-readable)
compatibilitytool.vdf and toolmanifest.vdf both present and well-formed
Mount confirmed active via docker inspect

Ruled out a premature-shutdown theory. Initially suspected the Wolf startup script (startup-app.sh/Sway) was killing Steam before it finished scanning tools on boot — the container's normal launch path does show Steam dying silently a few seconds after ExecCommandLine, no crash dump (-nominidumps -nobreakpad are set), no dmesg/OOM entry. But launching Steam manually in the foreground (/usr/games/steam -bigpicture -console) keeps it alive and fully usable for 30+ minutes. Even with a long-lived, stable session, proton-cachyos never appears in compat_log.txt — no Loaded manifest line, no scan attempt logged at all. Only the officially registered tools (by AppID via Steam's own appinfo) ever get mapped.

Tried forcing it via config instead of relying on the scan. Edited config.vdf's CompatToolMapping section directly to map a native AppID (Forza Horizon 6, 2483190) to "proton-cachyos-10.0-20260425-slr-x86_64" with Steam closed, then relaunched. The game did launch and got through shader processing — but the resulting steam-2483190.log shows it actually ran under Proton Experimental (base_dir: S:\steamapps\common\Proton - Experimental...), not CachyOS. So Steam silently ignores a manually forced mapping to an unregistered tool and falls back to its own default, rather than honoring the forced value or erroring out.

Takeaway: this points to the tool needing to pass through Steam's own registration/scan step before it can be referenced at all — even bypassing the picker UI doesn't help. Since the scan itself never runs on compatibilitytools.d in this image (confirmed with a stable, long-running session, so it's not a timing/race issue), this looks like a genuine limitation/bug in steam:edge's handling of custom compat tools rather than anything fixable from the Wolf config side.

Happy to test any specific env var / flag / rebuild if anyone has a lead — right now I don't see a user-side workaround.

@Moustik2002 commented on GitHub (Aug 17, 2026): Thanks for the suggestion — tested it, but it doesn't seem to apply to this image. /home/retro/.steam/debian-installation/ doesn't exist at all in steam:edge (checked via find /home/retro -iname "*compatibilitytools*"); the only real path is /home/retro/.steam/steam/compatibilitytools.d, which is what my original mount already pointed to. So I reverted to that path and kept digging. Confirmed the mount/permissions aren't the issue. From inside the container as the retro user: Directory and files fully readable (0755, world-readable) compatibilitytool.vdf and toolmanifest.vdf both present and well-formed Mount confirmed active via docker inspect Ruled out a premature-shutdown theory. Initially suspected the Wolf startup script (startup-app.sh/Sway) was killing Steam before it finished scanning tools on boot — the container's normal launch path does show Steam dying silently a few seconds after ExecCommandLine, no crash dump (-nominidumps -nobreakpad are set), no dmesg/OOM entry. But launching Steam manually in the foreground (/usr/games/steam -bigpicture -console) keeps it alive and fully usable for 30+ minutes. Even with a long-lived, stable session, proton-cachyos never appears in compat_log.txt — no Loaded manifest line, no scan attempt logged at all. Only the officially registered tools (by AppID via Steam's own appinfo) ever get mapped. Tried forcing it via config instead of relying on the scan. Edited config.vdf's CompatToolMapping section directly to map a native AppID (Forza Horizon 6, 2483190) to "proton-cachyos-10.0-20260425-slr-x86_64" with Steam closed, then relaunched. The game did launch and got through shader processing — but the resulting steam-2483190.log shows it actually ran under Proton Experimental (base_dir: S:\steamapps\common\Proton - Experimental\...), not CachyOS. So Steam silently ignores a manually forced mapping to an unregistered tool and falls back to its own default, rather than honoring the forced value or erroring out. Takeaway: this points to the tool needing to pass through Steam's own registration/scan step before it can be referenced at all — even bypassing the picker UI doesn't help. Since the scan itself never runs on compatibilitytools.d in this image (confirmed with a stable, long-running session, so it's not a timing/race issue), this looks like a genuine limitation/bug in steam:edge's handling of custom compat tools rather than anything fixable from the Wolf config side. Happy to test any specific env var / flag / rebuild if anyone has a lead — right now I don't see a user-side workaround.

bsakaguchi commented

2026-10-15 12:49:02 +00:00

Author

Owner

@Skerga commented on GitHub (Aug 17, 2026):

Since it looks like it's a problem with the steam image directly, I'll move this issue over to the gow repo. Maybe this way we get the attention of someone that is up-to-date with the steam image and knows what is happening.

@Skerga commented on GitHub (Aug 17, 2026): Since it looks like it's a problem with the steam image directly, I'll move this issue over to the gow repo. Maybe this way we get the attention of someone that is up-to-date with the steam image and knows what is happening.

bsakaguchi referenced this issue

2026-10-15 12:49:48 +00:00

[PR #144] [CLOSED] udev #185