Notes on building a Clear SteamOS appliance

Hi everyone, I figured I’d start posting things I use clear for to encourage people to start posting. I’ve been messing around with this for a few months on and on, and created a video, but now I’ve rebuilt this a few times and have a better understanding of what I need to do and I’ve been getting feedback from random redditors so I figured I should start writing this down:

Ok so first things first, I’m using a Hades Canyon NUC for this, but have had success with prebuilt systems, and even all-AMD Ryzen/Vega systems. Generally speaking if it has open drivers this should work.

Install Clear Linux

We’re building some things so you might want to grab desktop-dev. If you’re on an older installation make sure you switch over to network-manager as you need this for Steam’s wireless manager to work when you’re in big picture mode.

Install Steam

I used to do this via the flatpak via flathub (in the video), but I was having problems with controller permissions, controlling shutdown/reboot via the client, not getting sound in the session and even occasional game(!) problems. So I just installed Steam via a tarball that Valve provides. This solved like 90% of the problems I was having in the video!

Before you need to run steam at least once so it downloads/updates itself, and then log in, perhaps play some games to make sure it’s working right.

Install the compositor

I set up steamcompmgr, when we run this in a dedicated session it will ensure games launch fullscreen and give us that slick console-like experience.

Grab the latest tarball from this directory, and you’re going to go in there and do the usual ./configure, make, make install. Depending on what you have installed you might need to install some devpkg’s from clear, I still need to make a list of what to install, but generally speaking if you have desktop-dev installed this should work.

I then copied the steamcompmgr binary into /usr/bin and the session files that came with it. On my system they were in ~/steamos-compositor-1.35/usr/bin.

Now you have the compositor and /usr/bin/steamos-session. At the bottom of this file it just launches a steam binary, which you probably don’t have installed in a pathable place, so for me the last line of that file looks like: /home/jorge/steam/steam -tenfoot -steamos -enableremotecontrol


You need to install uinput, and then I made /etc/modules-load.d/modules.conf and then added a uinput line in the file, and that was it. (Either manually modprobe uinput after that or reboot.)

I use a steam controller so I copied this file, into /etc/udev/rules.d and this allows me to connect and use the controller . Valve’s steamos includes support for all controllers, so that you can just add any Xbox or PS4 controller from steam and it all just works, I haven’t investigated other controllers though, and I think it would be real useful to figure that out for people who want to use those controllers. Like I think we’d need to load the xpad module for xbox controllers?

Custom Session bits

This will make it so that there is a Steam option in GDM so you can log into steam directly instead of loading up your desktop. Make a /usr/share/xsessions/steamos.desktop and put this in there:

[Desktop Entry]

Then just try it, boot up the machine, select that from the menu, and steam should fire up, go into the settings, add your controller, etc.

Autologin into the session

If you intend to use the machine also as a desktop, you can just ignore this part, adding the steam session to GDM will give you the console experience if you need it, and then if you want to do desktop stuff you can just select the normal GNOME session in the gdm gear menu thing and use your computer normally.

However, since my NUC is a dedicated gaming machine I do the last step to get a clean boot right into steam big picture mode, make a /etc/gdm/custom.conf and then:


This will just autologin my user to whatever session I was in last, which by now is the steam session.


So, this was kind of convoluted, but, the nice thing is there’s no maintenance. I’ve been running this on my hades canyon for a few months now, the steam client bits and games auto-update themselves, and swupd does it’s thing in the background, all I do is use the machine and it’s continuously keeping itself up to date in the background. Since I get fresh kernels and mesa the gaming toolchain is always up to date, which is really nice.

From an end user experience they don’t see any linux at all. When I show it to people I hit the power button, they see the uefi logo, and a few seconds later steam fires up and we’re playing.

Updating on Demand

Steam has a little button in big picture mode that let’s you explictly update the OS in the “System” section called “Check for SteamOS updates”:

Ends up this calls a /usr/bin/steamos-update file, which I found online.

Lots of this is debian specific, so I trimmed mine down to this. Steam expects an /etc/lsb-release in the UI, which doesn’t exist in clear, so I read /etc/os-release and generate a partial one:

#! /bin/sh
echo $$ > /tmp/
/usr/bin/swupd update
version=`printf '%b\n' "$(cat /etc/os-release | grep VERSION_ID)"| sed 's/[^0-9]*//g'`
if [ -f "$destdir" ]
   echo "DISTRIB_DESCRIPTION=\"Clear Linux $version\"" > "$destdir"
rm /tmp/

Don’t forget to chmod +x the file. The file location seems hardcoded in steam. Then in /etc/sudoers:

ALL ALL=NOPASSWD: /usr/bin/steamos-update

This will allow the updater to run when you click on that button. (Thanks to u/wesbl for that tip!)

I think if I figure out how to ask clr-service-restart if I need to reboot I can replicate refreshing the steam inbox, or just keep that stanza in the file and touch a /var/run/reboot-required?


It is exactly the type of contributions we are looking for in our community. Thank you @castrojo! I moved that to Tutorials and Guides categories.


This is a really cool use case of Clear and I would love if it either could be set up as a specific bundle that you just download and have all set up or/also available as a spin ISO like Fedora and their different desktops. Just think of the possibilities of installing clear Linux and having a gaming computer that updates by itself and is as fast as it can be, all without needing much to be done by the users…


It sounds like a good idea. Let’s move it to github issues as a feature request, so Clear Linux engineers can discuss its priority. Thanks!


I watched your video and I really like it. I do several similar things with clearlinux myself and have a few things I’d like to add to this thread.

  1. columbiad. A long time ago I built a HTPC PC and needed a simple ‘app chooser’ that could work with a controller or cheapo remote control. Together with a colleague (who did all the code pretty much) we made a simple full screen application chooser that is far more comfortable than any standard desktop. It’s much like a tablet chooser or a smart TV. I’ll add this to clearlinux because this is a great way to do many things like this - not just launch steam, but also a fullscreen browser, KODI, mythtv or even Linux games like tuxracer, all from a NUC tucked behind a TV screen.

  2. Aside that I’d like to see if we can make this use lightdm instead of gdm/gnome, it’ll make a smaller system that will take less to download and update. lightdm isn’t working well at the moment and I’ll need to brush it up, but it should be gigabytes smaller than the full GNOME desktop.

  3. When you’re adding local modifications to apps, try and use local areas for configuration files. So please make sure you put xsession files in /usr/local/share/xsessions and desktop files in /usr/local/share/applications and not in /usr/share/xsessions. The reason is obvious: Clearlinux might overwrite the files in /usr/share/xsessions. Another good reason is that you might want to run sudo swupd verify --fix --picky at some point, and this will absolutely remove those files. Of course, another great location to put stuff is ~/.config./ and other user-specific XDG locations.


Yeah! That sounds good. Should I do that? If so, in what repository?

Yeah, on top of that I had to install some dev packages to build the compositor so I ended up with a much larger system than I needed. I see a columbiad bundle in clear, I’ll install it and follow along, looks like it would be a useful kiosk system too!

Ah yes of course, I’ll do that the next time I’m in there.

If their compositor is open source, we should just make a bundle out of it.

Filed here:


Add also Gamemode could be interesting.


I’ve added some new things to the original post, mostly I got the update button working in steam big picture mode. I can also confirm that this guy’s steamcompmgr fork works:

This replaced the steamcompmgr I built with his fork, which removed a weird green/blue box flashing thing when running Proton games in steam, which resulted in a cleaner presentation. I’m sure at some point upstream steamcompmgr will incorporate these fixes or fix them on their own so I’ve left it out for now but am mentioning it here.


Update from the last few nights.

I was hoping to find a way to see the Clear Linux version without having to ssh in or go to a terminal. Steam grabs a field from /etc/lsb-release to populate it’s version field in big picture mode. This file doesn’t exist in Clear so I write one by parsing the line in /etc/os-release to get the version, this gives me this:

So now at least when I hit the “check for updates” button I can get the Clear Linux version in the UI. the “Unknown” field is a mystery. I see in the system journal that Steam is trying to call dpkg and then throwing an error, I suspect on SteamOS it’s doing the equivalent of dpkg -s <packagename> | grep '^Version: to populate this field, which maybe we can just alias in the update file so it ends up reading “Clear Linux update 29690”.

Also as a nice bonus Steam is smart enough to refresh this when the file is written, so if I do an update and swupd updates the number changes in real time on the spot, which is nice!


I have accomplished this before on ubuntu:

If you need any help debugging, just let me know. I never did get it to restart and/or switch to desktop mode to work for steamos mode.

1 Like

I haven’t had time to automate this (hah, the irony), but a script or mixer thing is probably the way to go. I’d chip in a steam gift card or game to someone who wants to take a stab at it. :smiley:

I started to work on this project but I haven’t been able to test it yet. Please review code before you run anything, please and thank you. This is simply a modification of the before mentioned set of scripts. A lot of work still needs to be done before it will be ready for general use. I am not even sure it works yet. :confused: I should be testing this evening if everything goes to plan.

Awesome! Won’t be able to get to this until later in the week but a quick scan looks ok so far. This part gave me a chuckle:

		echo "The latest Intel drivers are installed!"

I resolved most of the installation issues with this script. It still needs more testing especially from a clean install. Only 1 pre-req is not currently being installed and I am waiting till later so I can check to see if I can find a smaller bundle than desktop-dev. Major issues still include: no sakura, no nvidia installation, no readme.

1 Like

The script seems to work on a clean install. It is using desktop-dev which is massive in size, and NVIDIA users must restart to rerun the nvidia_install script to get it to work. SteamOS session isn’t set to default but it also must be updated before SteamOS session works. Going to have to setup some boot scripts to solve these issues.

1 Like

I just installed Clear Linux over the weekend and got Steam up and running. So far the experience is awesome. I’m planning on setting it up as a dedicated gaming box, so looking forward to trying some recommendations you’ve all posted.