Skip to content

Instantly share code, notes, and snippets.

@Rishikant181
Last active September 10, 2026 05:18
Show Gist options
  • Select an option

  • Save Rishikant181/e26fb23d4c57db74bddaa0a57b26cd26 to your computer and use it in GitHub Desktop.

Select an option

Save Rishikant181/e26fb23d4c57db74bddaa0a57b26cd26 to your computer and use it in GitHub Desktop.
Create a Steam Gamescope Session, allowing you to seamlessly switch between your Desktop Environment and Gamemode.

Steam Gamescope Session

Instructions

1. Install Gamescope

Install the gamescope using your package manager.

2. Setup Steam inside Gamescope

  • Run the following command to launch Steam within a Gamescope instance from the terminal:

    gamescope -e -- steam -steamdeck

3. Run through Steam Deck set up

  • Run through the set up process by:
    • Selecting the language of your choice
    • Setting the timezome
  • You will then be presented with the home screen (like Big Picture mode).
  • Close the window to exit from Steam.

4. Creating a script to launch Steam inside Gamescope

  • Using a code editor, create a new file called gamescope-session, add the following lines to the file and then save the file

    #!/bin/bash
    
    STEAM_GAMESCOPE_VRR_SUPPORTED=1 STEAM_MULTIPLE_XWAYLANDS=1 gamescope --mangoapp -W <resolution_width> -H <resolution_height> -r <refresh_rate> -O <output_display> -e --xwayland-count 2 -- steam -steamdeck -steamos3
    
    • Replace <resolution_width> and <resolution_height> with the width and height of your primary dispaly's resolution, <refresh_rate> with the refresh rate of your primary display, and <output_display> with whatever display you wan't to use as the primary. You can get the <output_display> value for your primary display using wayland-info command and looking for the name field of your primary display.

      As an example, for me, the command looks like this:

      STEAM_GAMESCOPE_VRR_SUPPORTED=1 STEAM_MULTIPLE_XWAYLANDS=1 gamescope --mangoapp -W 1920 -H 1080 -r 165 -O DP-1 -e --xwayland-count 2 -- steam -steamdeck -steamos3
      
    • The --mangoapp flag enables controlling of MangoHud overlay from within Steam.

    • The STEAM_GAMESCOPE_VRR_SUPPORTED=1 flag is required to fix a VRR issue.

    • The STEAM_MULTIPLE_XWAYLANDS=1 flag combined with --xwayland-count 2 option is required when you want to be able to use keyboard and mouse properly inside Gamemode.

  • Set the file permissions and copy it to the ~/.local/bin directory using the commands:

    chmod +x gamescope-session
    cp gamescope-session ~/.local/bin
    

5. Creating a script to switch back to 'desktop mode' (close steam)

  • Create a new file named steamos-session-select, add the following lines to the file and save it:

    #!/bin/bash
    
    steam -shutdown
    
  • Set the file permissions and copy it into ~/.local/bin directory using the commands:

    chmod +x steamos-session-select  
    cp steamos-session-select ~/.local/bin
    

6. Applying fixes for software updates

  • Create a new file named steamos-select-branch, add the following lines to the file and then save it:

    #!/bin/bash
    
    echo "Not applicable for this OS"
    
  • Set the file permissions and copy it to the ~/.local/bin directory using the commands:

    chmod +x steamos-select-branch  
    cp steamos-select-branch ~/.local/bin
    
  • Create a new file named steamos-update, add the following lines to the file and then save it:

    #!/bin/bash
    
    exit 7;
    
  • Set the file permissions and copy it to the ~/.local/bin directory using the commands:

    chmod +x steamos-update  
    cp steamos-update ~/.local/bin
    
  • Create a new file named jupiter-biosupdate, add the following lines to the file and then save it:

    #!/bin/bash
    
    exit 0;
    
  • Set the file permissions and copy it to the ~/.local/bin directory using the commands:

    chmod +x jupiter-biosupdate
    cp jupiter-biosupdate ~/.local/bin
    

7. Understaing TTYs

Before proceeding to the next step, let's recap some info about TTY.

  • TTYs are essentially terminal sessions which can run in parallel.
  • You can switch between terminal sessions using the keyboard combination Ctrl+Alt+[F1-F6], where Ctrl+Alt+F1 will switch to TTY1, Ctr+Alt+F2 will switch to TTY2 and so on, upto TTY6.
  • On GNOME (I don't know about other desktop environments), TTY1 corresponds to GDM, the login manager and TTY2 corresponds to the GNOME session itself, while TTY3-TTY6 are available for use. For the sake of an example, let's choose TTY3 as our Gamescope session target.

8. Setting up autologin on target TTY

  • Open a terminal and execute the following command: sudo systemctl edit getty@tty3. Replace tty3 with any other tty which you want to use.

  • Insert the folling text where the cursor is pointed by default:

    [Service]
    ExecStart=
    ExecStart=-/sbin/agetty -o '-p -f -- \\u' --noclear --autologin <username> %I TERM
    Restart=no
    

    Replace <username> with you user account's username.

  • Save the file and reboot your system.

9. Setting up command to start and exit the session

  • Edit the ~/.bashrc file and insert the following text at the end:

    alias gsteam="gamescope-session; chvt 2; exit"
    

    Here, I'm using chvt 2 since GNOME runs on TTY2. If you know for sure that your desktop environment runs on a different TTY instance, replace 2 with whatever instance number you desktop environment runs.

  • Save the file and exit.

  • Edit your ~/.bash_profile file and insert the following text at the end:

    if [[ $(tty) == "/dev/tty3" ]]; then
        gsteam
    fi
    

    Here I'm using /dev/tty3. If your selected target TTY was anything else, replace tty3 with your selected target i.e, if you want to use tty5 for the Gamemode, replace /dev/tty3 with /dev/tty5.

  • Save the file and exit.

10. Testing things out

  • Log out and login again and test it out by switching to the selected TTY using the keyboard shortcut. Here, since I used TTY3, I can test it by pressing Ctrl+Alt+F3, which should open Steam Gamemode.
  • You can exit it by going into the menu and selecting Switch to Desktop, which should switch you back to your usual Desktop Environment and terminate the Steam Gamemode.
  • To switch between the TTY sessions (including the one where your desktop environment is running), you can just use the keyboard shortcuts, and both the desktop environment and Steam Gamemode will run in parallel.
  • Steam Gamemode will only terminate if you click Switch to Desktop in Steam.

Credits

Shoutout to shahnawazshahin for the Gamescope Session guide and u/felix_ribeiro for the fix for Keyboard and Mouse input.

@chenxiex

chenxiex commented Jan 27, 2026

Copy link
Copy Markdown

I tried this and found some issues and workarounds:

  1. Under this setup, Steam will use its own MangoHud configuration and ignore the user’s configuration. You can force an override of the MangoHud configuration by setting the MANGOHUD_CONFIG environment variable in the gamescope-session script. For example, to add a time display, use:
MANGOHUD_CONFIG="time" STEAM_GAMESCOPE_VRR_SUPPORTED=1 STEAM_MULTIPLE_XWAYLANDS=1 gamescope --mangoapp -W <resolution_width> -H <resolution_height> -r <refresh_rate> -O <output_display> -e --xwayland-count 2 -- steam -steamdeck -steamos3

Don't use MANGOHUD_CONFIGFILE= environment variable, Steam will overwrite the file.

Edit: Steam will read presets 1-4 in ~/.config/MangoHud/presets.conf, and you can choose one presets in the quick access menu. The quick access menu can be triggered by start+A on an Xbox controller.

  1. Some games may read an incorrect screen resolution, even if the -W and -H parameters are set correctly. To resolve this issue, set a resolution limit in the game's properties inside Steam.

@Rishikant181

Rishikant181 commented Jan 27, 2026

Copy link
Copy Markdown
Author

@chenxiex For MangoHud, I personally customize Steam's MangoHud config by using my custom presets in ~/.config/MangoHud/presets.conf. In that file, I define the 4 presets preset 1, preset 2, preset 3, preset 4. Then in ~/.config/MangoHud/MangoHud.conf, I select which presets to enable using preset=1,2,3,4. That way, Steam's MangoHud levels are my own custom configurations, which are shared with the desktop mode as well.

These are my config files:

  • ~/.config/MangoHud/presets.conf:
[preset 1]
legacy_layout=false
fps_only
round_corners=10
background_alpha=0.5
fps_limit_method=early
toggle_fps_limit=Shift_L+F1
fps_limit=160,55,33

[preset 2]
legacy_layout=false
fps
fps_metrics=avg,0.01,0.001
background_alpha=0.0
round_corners=10
position=top-left
gpu_color=2e9762
cpu_color=2e97cb
fps_color=cc0000,ffaa7f,92e79a
gpu_load_color=92e79a,ffaa7f,cc0000
cpu_load_color=92e79a,ffaa7f,cc0000
background_color=000000
background_alpha=0.5
frametime_color=00ff00
vram_color=ad64c1
ram_color=c26693
wine_color=eb5b5b
engine_color=eb5b5b
text_color=ffffff
media_player_color=ffffff
network_color=e07b85
battery_color=92e79a
media_player_format={title};{artist};{album}
fps_limit_method=early
toggle_fps_limit=Shift_L+F1
fps_limit=160,55,33

[preset 3]
legacy_layout=false
gpu_stats
vram
gpu_core_clock
gpu_mem_clock
gpu_temp
gpu_power
cpu_stats
cpu_mhz
cpu_temp
cpu_power
ram
fps
fps_metrics=avg,0.01,0.001
frame_timing
round_corners=10
background_alpha=0.5
position=top-left
gpu_color=2e9762
cpu_color=2e97cb
fps_value=30,60
fps_color=ff0000,fdfd09,ffffff
gpu_load_value=30,60
gpu_load_color=ffffff,ffaa7f,cc0000
cpu_load_value=30,60
cpu_load_color=ffffff,ffaa7f,cc0000
background_color=000000
frametime_color=00ff00
vram_color=ad64c1
ram_color=c26693
wine_color=eb4b4b
engine_color=eb5b5b
text_color=ffffff
media_player_color=ffffff
network_color=e07b85
battery_color=92e79a
media_player_format={title};{artist};{album}
fps_limit_method=early
toggle_fps_limit=Shift_L+F1
fps_limit=160,55,33

[preset 4]
legacy_layout=false
gpu_stats
vram
gpu_core_clock
gpu_mem_clock
gpu_temp
gpu_mem_temp
gpu_power
cpu_stats
core_load
cpu_mhz
cpu_temp
cpu_power
ram
fps
fps_metrics=avg,0.01,0.001
frame_timing
frame_timing_detailed
round_corners=10
background_alpha=0.5
position=top-left
gpu_color=2e9762
cpu_color=2e97cb
fps_value=80,140
fps_color=ff0000,fdfd09,ffffff
gpu_load_value=30,60
gpu_load_color=ffffff,ffaa7f,cc0000
cpu_load_value=30,60
cpu_load_color=ffffff,ffaa7f,cc0000
background_color=000000
frametime_color=00ff00
vram_color=ad64c1
ram_color=c26693
wine_color=eb4b4b
engine_color=eb5b5b
text_color=ffffff
media_player_color=ffffff
network_color=e07b85
battery_color=92e79a
media_player_format={title};{artist};{album}
fps_limit_method=early
toggle_fps_limit=Shift_L+F1
fps_limit=160,55,33
  • ~/.config/MangoHud/MangoHud.conf:
preset=1,2,3,4

@chenxiex

Copy link
Copy Markdown

@Rishikant181 Unluckily, this doesn't work for me. I try to create presets.conf and MangoHud.conf, but mangohud just doesn't show at all. There are some outputs in the terminal like:

[MANGOHUD] [error] [overlay_params.cpp:739] Unknown option 'nis_steam_sharpness'

But I don't set nis_steam_sharpness option.
If I force mangohud to use the config file by setting the MANGOHUD_CONFIGFILE and MANGOHUD_PRESETSFILE env, my config file will be overwritten with the following content:

control=mangohud
fsr_steam_sharpness=5
nis_steam_sharpness=10
no_display

@chenxiex

Copy link
Copy Markdown

I found what's wrong. I don't use a steam gamepad, so I didn't notice the quick access menu. The quick access menu can be accessed by pressing start+A on a xbox controller. After adjusting the configuration in the quick access menu, the mangohud showed. In this case, ~/.config/MangoHud/MangoHud.conf is ignored, but presets 1-4 in ~/.config/MangoHud/presets.conf is read. Thanks for your reply and patience!

@Star-veil

Copy link
Copy Markdown

Is there anyway to fix the ui while using the -steamos3 flag? I get forced in a grainy 16:9 resolution with no way to change it, only removing that flag fixes the issue, but then i dont get the functionality of all the other scripts

@Rishikant181

Copy link
Copy Markdown
Author

@Star-veil I don't that's possible currently, when using the -steamos flag.

@Star-veil

Copy link
Copy Markdown

@Star-veil I don't that's possible currently, when using the -steamos flag.

Gotcha, Yeah I haven't found a way around it.
My current fix is adding a bash script as a Non-Steam game to the library that does steam -shutdown, if I find anything more elegant I'll share it here

@karelion-s

Copy link
Copy Markdown

A couple of things to be aware
first there's a typo in the tty conf , is:
ExecStart=-/sbin/agetty` -o '-p -f -- \\u' --noclear --autologin <username> %I $TERM
TERM without the $ breaks the tty
Second, in ubuntu there's not .bash_profile everything goes to .profile if you create .bash_profile youre overriding .profile which is a VERY bad thing for bash... because it breaks lots of things of the terminal.. and the PATH
third, in Ubuntu at least there is not .local/bin/ by default so it is better to be sure that it exist because your commands just overwrite ./local/bin all over in every step. better to use cp whatever .local/bin/ so the terminal returns "theres no local/bin"
Then, the graphics are scrambled.. this could be a nvidia thing but if I launch it through GDM dedicated session it works normally so I'm not sure whats happening but maybe is related to the existing session.

@hosean90

Copy link
Copy Markdown

@Star-veil I don't that's possible currently, when using the -steamos flag.

Gotcha, Yeah I haven't found a way around it. My current fix is adding a bash script as a Non-Steam game to the library that does steam -shutdown, if I find anything more elegant I'll share it here

I don't know if anything have changed in the past updates, but currently, both -steamos3 and -steamdeck enables script desktop switch, and either can be used instead of the other

Just remove -steamos3 and leave -steamdeck and it will work

@Rishikant181

Copy link
Copy Markdown
Author

@Star-veil I don't that's possible currently, when using the -steamos flag.

Gotcha, Yeah I haven't found a way around it. My current fix is adding a bash script as a Non-Steam game to the library that does steam -shutdown, if I find anything more elegant I'll share it here

I don't know if anything have changed in the past updates, but currently, both -steamos3 and -steamdeck enables script desktop switch, and either can be used instead of the other

Just remove -steamos3 and leave -steamdeck and it will work

Let me test that out

@Rishikant181

Rishikant181 commented Aug 31, 2026

Copy link
Copy Markdown
Author

A couple of things to be aware first there's a typo in the tty conf , is: ExecStart=-/sbin/agetty` -o '-p -f -- \\u' --noclear --autologin <username> %I $TERM TERM without the $ breaks the tty Second, in ubuntu there's not .bash_profile everything goes to .profile if you create .bash_profile youre overriding .profile which is a VERY bad thing for bash... because it breaks lots of things of the terminal.. and the PATH third, in Ubuntu at least there is not .local/bin/ by default so it is better to be sure that it exist because your commands just overwrite ./local/bin all over in every step. better to use cp whatever .local/bin/ so the terminal returns "theres no local/bin" Then, the graphics are scrambled.. this could be a nvidia thing but if I launch it through GDM dedicated session it works normally so I'm not sure whats happening but maybe is related to the existing session.

Strange, for the ExecStart..., I have it without $, i.e, just TERM and it's working fine.
As for the scrambled graphics, might be Nvidia, or might be something else. I'm not really an expert on that matter lol.

@Rishikant181

Copy link
Copy Markdown
Author

@Star-veil I don't that's possible currently, when using the -steamos flag.

Gotcha, Yeah I haven't found a way around it. My current fix is adding a bash script as a Non-Steam game to the library that does steam -shutdown, if I find anything more elegant I'll share it here

I don't know if anything have changed in the past updates, but currently, both -steamos3 and -steamdeck enables script desktop switch, and either can be used instead of the other

Just remove -steamos3 and leave -steamdeck and it will work

Okay just tried this, but it unfortunately disabled the per-game resolution selection. So I can't do super-sampling with it.

@akashidom

Copy link
Copy Markdown

is there a way to use custom proton compactibility tool? i feel like it switch my proton-cachyos to proton-11 only in this gamescope session because proton 11 were suddenly being downloaded.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment