Gamescope session-aware operations

Scope

Gamescope is a micro-compositor with two distinct roles: SteamOS Gaming Mode's embedded display session and an optional nested window on a normal Wayland/X11 desktop. This page does not modify the SteamOS compositor service.

Session matrix

ContextOwner and output pathSafe first control
Gaming Mode
SteamOS embedded session to display
SteamOS per-game display profile
Desktop nested
Gamescope window inside desktop session
One explicit Steam launch option
Flatpak application
Sandbox plus host compositor boundaries
Verify package/runtime visibility

Trust boundary

Gamescope owns presentation, resolution mapping, frame limiting, focus/input routing, screenshots, HDR/VRR negotiation, and capture paths. A nested session can change latency, color, cursor, input, and window behavior.

Supported installation

Do not reinstall or remove the Gamescope supplied by SteamOS. On another Linux desktop, use the distribution's maintained package. Check the installed build's actual options before copying an upstream example:

A bounded nested desktop example is a launch option, not a Gaming Mode repair:

Verification

Record session type, internal/output resolution, refresh, cap, HDR/VRR, GPU/driver, display path, and game build. Confirm the game renders, input focus works, frame pacing is stable, and exiting returns cleanly to the owning desktop or Steam session.

Update

SteamOS updates its embedded Gamescope as part of the OS. Other distributions update their package. Do not mix a manually built binary into the SteamOS session; test changed CLI behavior on a nested desktop first.

Uninstall

In SteamOS, remove only the per-game launch option or custom profile. On another distribution, uninstall through the same package manager used for the nested desktop package; preserve unrelated SteamOS session files.

Rollback

Remove the full Gamescope launch option, restore the original in-game resolution/cap and SteamOS per-game profile, restart the game, and verify direct launch before changing another variable.

Recommended use

Use nested Gamescope on desktop Linux for a specific resolution, scaling, isolation, or frame-limit experiment. Use SteamOS's native controls inside Gaming Mode.

Frequently asked questions

Should I start another Gamescope inside Gaming Mode?
Should I start another Gamescope inside Gaming Mode?
Not as a general fix. Gaming Mode already uses an embedded Gamescope session; nesting adds another compositor boundary and different failure modes.
Does an option in upstream --help mean SteamOS UI supports it?
Does an option in upstream --help mean SteamOS UI supports it?
No. Upstream CLI availability does not prove the current Gaming Mode UI exposes, persists, or safely combines that option.

Sources

Version history

  • 2026-07-15: Phase 6 embedded, nested, package, and rollback boundary review.