SSS/GNU system - Manual & Documentation

Find the divine sayings, and the destined computer configurations, all my Guix, Scheme, Hyprland, and Emacs Lisp and more configurations here for learning you a fully Lisp machine with GNU/Linux for a great good.

⚠️ Warning: parts of the code and settings might default to the Dutch language ( nl_NL.UTF-8 ).

I refer to SSS lovingly as the modern Lisp machine. With this one obtains a computing style and programming environment that can be referred to as Lisp user space. This is a modern iteration of the Lisp machines of yore.

You can be aware of all the code that is running on your machine, which puts free GNU systems among the most secure operating systems on Earth.

Learning Lisps is really going down a rabbit hole, but trust me, you will come out with a better understanding of programming as a whole out the other end.

Lisp user space provides an introspective, hackable, and transactionable operating system that can be modified live in a REPL.

⭐ The lines between data and code fade, allowing insane flexibility and power.

In some ways this is a laboratory of experimentation for my computing environment. What I do with any other program that forms part of SSS is only meant to work for me. As such, I will try to maintain backwards compatibility and consistency, but I may introduce breaking changes without prior notice.

This configuration is somewhat biased towards containing a joe user who also acts as administrator for most of the time. This is trivial to change and should be easy to adapt to your needs. Your mileage may vary (YMMV).

I have a bias towards Emacs-style behaviors and keyboard shortcuts, so most of my preferences in software settings get reflected on SSS, while I do try to make it all configurable.

Some commands in the Makefile are more geared towards joe since we assume a device is most frequently only tended to by one system administration most of the time. Some examples are make fr or make jr. Feel free to change this or contribute improvements to make this modular.

The system and home folders of users are managed independently of each other, in quite a loosely coupled manner.

GNU Guix is a package management tool for and distribution of the GNU system. Guix makes reproducibility easy and allows users to install, upgrade, or remove software packages, to roll back to a previous package set, to build packages from source, and generally assists with the creation and maintenance of software environments.

While you can install GNU Guix on top of an existing GNU/Linux system where it complements the available tools without interference, I encourage the use of Guix system, as standalone operating system distro, on top of which I have built the Supreme Sexp System (SSS).

I highly recommend refering to and studying the Guix reference manual, it's a super valuable source of knowledge: https://guix.gnu.org/manual/en/html_node/.

SSS attempts to stay as libre as possible, while also respecting your convenience.

This means, among other things that SSS:

• includes the OG Linux kernel (with proprietary blobs) so as to be more compatible with modern hardware
• includes non-guix software channel by default, so as to allow installation of convenient software to which few/no libre alternatives exist.

When keybindings (shortcurts) are defined, the following legend applies (a la Emacs):

This manual is written by hand with care and attention for detail.

I write my documents in Org format from Emacs and export them for your convenience to several other formats. A usual release of the manual happens as follows:

• Edit the SSS manual
• Run C-c # m from Emacs, which runs lib/sss-manual.el, exporting the Org document to several other formats (LaTEX, PDF, HTML, Markdown, etc.)

SSS supports several user customizations via the per-host.scm file and others.

I took inspiration from many sources, including several color palettes, inspired by the great `ef-themes` by Protesilaos Stavrou (https://github.com/protesilaos/ef-themes).

There are more palettes though, see per-host section for more.

Note: Screenshots below might be outdated and no longer representative of the current, ever-changing state of SSS.

Some tutorials, conversations and videos have been made about SSS, some more up to date than others:

<2025-03-06 do>

SSS/GNU - Supreme Sexp System Installation Demo - How to install Joe's riced up Guix system @ virtual machine

https://youtu.be/wZUes_10US8

It is REQUIRED to include a per-host.scm in the root of this project, which is excluded from Git, and will determine certain settings for your own machine. Find here a reference configuration with what is required.

  (use-modules (gnu)
               (gnu packages))

  ;; system language
  (define sss-lang "en_US")

  ;; system timezone
  (define sss-timezone "Europe/Amsterdam")

  ;; system keyboard layout
  (define sss-keyboard-layout "us")

  ;; caps to control enabled
  (define sss-caps-to-ctrl
    #t)

  ;; system hostname
  (define sss-hostname "gnusystem")

  ;; disk partitioning
  (define sss-filesystems
    (list (file-system
           (device "/dev/nvme0n1p3")
           (mount-point "/")
           (type "ext4"))
          (file-system
           (device "/dev/nvme0n1p1")
           (mount-point "/boot/efi")
           (type "vfat"))))

;; bootloader configuration
(define sss-bootloader-configuration
  (bootloader-configuration
    (bootloader grub-efi-bootloader)
    (targets '("/boot/efi"))))

  ;; packages that should only be installed in the current host
  ;; or (define sss-per-host-packages '())
  (define sss-per-host-packages '(
                                  ;; AMD non-free drivers
                                  "amd-microcode" "amdgpu-firmware"
                                  ;; Games
                                  "prismlauncher" "steam")
    )

  ;; location where you cloned SSS Git repository
  (define sss-clone-dir
    "$HOME/Ontwikkeling/Persoonlijk/sss")

  ;;
  ;; Define the active palette for all users accounts
  ;; You should reconfigure and ideally restart the system
  ;; for all changes to take effect
  ;;
  ;; Note: You could choose on a per-user basis to set a fixed palette
  ;; and not follow system wide, by just redefining this value
  ;;
  ;; Possible values are:
  ;;   - sss-palette-ef-bio
  ;;   - sss-palette-ef-cyprus
  ;;   - sss-palette-ef-dream
  ;;   - sss-palette-heavy-metal
  ;;   - sss-palette-solarized-light
  ;;   - sss-palette-ef-autumn
  ;;   - sss-palette-everforest-dark
  ;;   - sss-palette-everforest-light
  ;;
  (define-public sss-palette
    'sss-palette-ef-dream)

  ;; Nix packages to install
  (define-public sss-nixpkgs
    '("yaml-language-server" "bash-language-server"
      "monaspace"
      "jdt-language-server"
      "nil"
      "black"
      "pyright"
      "marksman"
      "_1password-gui"
      "_1password-cli"
      "stack"
      "sbt"
      "scala_2_13"
      "thunderbird"
      "postman"
      "vscode-langservers-extracted"
      "nwg-look"
      "krew"
      "mermaid-cli"
      "jetbrains.idea-community"))

  ;; Flatpak remotes to add to the user
  (define sss-flatpak-user-remotes '((flathub . "https://dl.flathub.org/repo/flathub.flatpakrepo")))

  ;; Flatpak packages to install
  (define sss-flatpak-pkgs '("app.drey.Warp" "com.usebottles.bottles"))

  ;; Additional Labwc startup commands on per-host basis, byt default '() , see example:
  (define sss-labwc-extra-startups
  '("wlr-randr --output eDP-1 --scale 1.5  >/dev/null 2>&1 &"))

  ;; Hyprland monitor configurations as a list of strings (lines)
  ;;
  ;; you can have a sensible default like "monitor = , preferred, auto, 1"
  ;; or more detailed config like "monitor=DP-1,1920x1080@144,0x0,1"
  ;; see https://wiki.hyprland.org/hyprland-wiki/pages/Configuring/Monitors/
  ;;
  (define sss-hyprland-monitors
  '("monitor = , preferred, auto, 1"))

  ;; Additional Hyprland startup commands on per-host basis, by default '() , see example:
  (define sss-hyprland-extra-startups
  '("sudo warp-svc" "sudo mkdir -p /usr/share/warp/images"
    "sleep 1 && warp-taskbar"))

It's possible you need to some manual installations, and temporary workarounds, in order to install sss on a brand-new Guix installation.

Some aspects will be dependent on the manner of installation and hardware. Below follows a simple startup guide.

On Hardware Requirements:

While SSS is designed to be lightweight and efficient, certain hardware configurations will provide a smoother experience. The following are recommended minimums:

• CPU: A modern x86-64 processor (Intel or AMD) is preferred. ARM64 is supported but may require additional configuration.
• RAM: 4GB of RAM is the absolute minimum. 8GB or more is highly recommended for a comfortable experience, especially if you plan to run memory-intensive applications or virtual machines.
• Disk Space: 30GB of disk space is a good starting point. Consider more if you plan to install a large number of packages, store many files, or use virtual machines extensively. SSDs are strongly recommended for optimal performance.
• Graphics: SSS leverages Wayland and Hyprland. Most modern graphics cards should work well. If you encounter issues, consult the Hyprland documentation for compatibility information.

Download and the Guix GNU/Linux distribution from the official Guix page: https://guix.gnu.org/download/ and make a bootable installation medium convenient for your use case.

If you are not familiar with the dd command which is present in all GNU/Linux distributions and in macOS, you can always feel free to use something like Rufus on Windows, or balenaEtcher, to flash this image into a USB, with which you can then boot your computer.

It is highly recommended to first become familiar with SSS and Guix via a throw-away virtual machine where you can experiment and do mistakes. After familiarity is acquired then a bare metal installation is the best.

SSS strives to be completely cross-architecture and should work well everywhere. That being said, as of the latest manual, x86-64 is the preferred architecture.

If your system doesn't boot due to lack of drivers, it can be useful to add the nomodeset option after quiet in the GRUB menu, by editing the boot "command" of the latest entry.

If you are on aarch64/arm64, or other more niche architectures, then you might need to put in some more work to get an installer image, and to get it working, likely having to generate an ISO image yourself to install Guix or a qcow2 virtual machine.

The following articles may be of help: https://jointhefreeworld.org/blog/articles/gnu-linux/gnu-guix-virtual-machine-image-aarch64/

If things really aren't working with your hardware, you can build your own ISO with the right drivers, or use the one from nonguix: https://gitlab.com/nonguix/nonguix/-/releases

It is highly recommended to connect your device to Internet via an Ethernet cable or some other form of wired connection, specially since Guix by default will only come with free software drivers, and as such, might not immediately support your WiFi card. After installing SSS drivers will be there and you can use WiFi.

When installing Guix, make sure you take note of the Scheme code that gets generated by it, specially for the disk partitioning. You will see this at the last install step. This code can also be found after installing, at /etc/config.scm by default. Parts of this code will later need to be added to the per-host.scm.

After having installed things using the guided Guix installer, or via the command line for advanced users, boot into your new system.

I would recommend to then use a web browser and visit the web version of this manual: https://codeberg.org/jjba23/sss/src/branch/trunk/docs/Manual.

Once you have a working Guix base installation on your machine, you are ready to go about installing SSS.

Nixpkgs contains a lot of software which we can leverage and manage from Guix.

SSS will automatically install and provide the Nix package manager for you.

SSS also provides some facilities to manage Nix from the comfort of your Guile Scheme.

You might need to activate and link the profile in order to be able to use, for the first time.

Assuming joe as user in question.

/nix/var/nix/profiles/per-user/ should be:

joe@guixvm ~ λ  ll /nix/var/nix/profiles/per-user/

drwxr-xr-x 2 joe  users  16K 29 dec 23:09 joe/
drwxr-xr-x 2 root root  4,0K 22 nov 13:23 root/

For this, make the directory an link it to your home.

sudo mkdir -p /nix/var/nix/profiles/per-user/joe
sudo chown -R joe:users /nix/var/nix/profiles/per-user/joe
ln -sfv /nix/var/nix/profiles/per-user/joe/profile $HOME/.nix-profile

It's possible you might need to logout and log back in to re-activate the profile.

You can switch your install to use nixpkgs-unstable with:

nix-channel --add https://nixos.org/channels/nixpkgs-unstable
nix-channel --update

You can install Nix packages by running:

nix -L profile install --impure nixpkgs#package-name

You can keep your Nix packages updated by running:

NIXPGS_ALLOW_UNFREE=1 nix profile upgrade --impure '.*'

The installed software will be available, for example at: $HOME/.nix-profile/bin/

SSS provides some scripts that allow you to maintain your Nix configuration and installed packages programatically with Lisp.

You can find these scripts and the list file at system/scripts in this repo and in the Makefile.

Installing all wanted Nix packages can be done with make npi for example and updating them with make npu.

SSS takes care of flatpak origins and installing and maintaining your flatpaks up to date, all programatically and with Lisp.

You can find these scripts and the list file at system/scripts in this repo and in the Makefile.

Installing all wanted Flatpak packages can be done with make fpi for example and updating them with make fpu.

Contributing to free software is a uniquely beautiful act because it embodies principles of generosity, collaboration, and empowerment.

We welcome everyone to feel invited to the SSS Project, and feel free to contribute, improve it and/or suggest improvements, brainstorm with me, make it more modular/flexible.

Find the backlog and project management of SSS here.

SSS favors modern technologies and thus makes use of Pipewire for all your GNU/Linux audio needs.

In practice this means that any user account in your system that wants to make use of audio, should have the (service home-dbus-service-type) and (service home-pipewire-service-type) services enabled for their account (yes per-user basis).

You will also want to set the RTC_USE_PIPEWIRE variable to true. This is already the case by default in SSS.

SSS automatically loads at startup a matching wallpaper for the currently enabled theme.

This uses swww and thus can load animated images as well and do fancy transitions. If you have bugs loading wallpaper at startup, try reloading the wallpaper with s-S-b.

TODO: allow more dynamics and often changing of wallpapers, also random wallpaper script (but within theme)

Nyxt is a fantastic web browser, infinitely extensible, and in Emacs-spirit. It is a great fit for SSS.

Find more about Nyxt here: https://nyxt.atlas.engineer/

Before you start Nyxt, you need to perform a one-time action so as to allow the SSS Nyxt config to work properly.

What we need is Quicklisp (refer to https://quicklisp.org for more details).

You only need to load quicklisp.lisp once to install Quicklisp.

Here's an example installation session on SBCL:

curl -O https://beta.quicklisp.org/quicklisp.lisp
sbcl --load quicklisp.lisp

You will then, if all went well, be inside a Common Lisp REPL. Here, all you need to do is type the following commands, each followed by ENTER:

(quicklisp-quickstart:install)
(quit)

You are then ready to start the Nyxt browser, all configuration should work well from then on.

Joe's account is automatically configured with a multi-user Git setup. See lib/git.scm. Currently this works on a per-directory basis, and is configured by default to my preferred settings. TODO: make this more configurable.

My settings are:

• $HOME/Ontwikkeling/Persoonlijk is where I keep my personal development projects. These are uploaded to Codeberg, and use their own gitconfig, email address, default git message, GPG key, and SSH keys.
• $HOME/Ontwikkeling/Werk is where I keep my work projects. These are uploaded to Github, and use their own gitconfig, email address, default git message, GPG key, and SSH keys.

Reproducibility and isolation of builds naturally leads to a little more disk usage than other systems. This is not a problem nowadays, with cheap storage.

That being said, here follow some useful reminders, every now and then clean:

• Guix generations
• Guix store
• Nix store
• Unused Steam games

You could run something like this:

sudo guix system delete-generations 1d
sudo guix gc
nix-store --gc

If you'd like to find the largest files in your disk, here’s an example command:

du -ah / | sort -rh | head -n 20

The real best way to manage your bluetooth is using the bluetoothctl shell. That being said SSS comes with a GUI graphical interface to manage Bluetooth. You can also go low-level, and programatically connect to your devices, setup shortcuts for "favourite" connections, and much more with bluetoothctl.

SSS comes equipped with libvirt and libvirt-manager (the GUI).

I'd recommend for most cases to simply use the GUI to create a new NAT network, and have your VMs be able to connect to the Internet.

If you want two-way traffic, and your machine is connected wirelessly to the network, you won’t be able to use a true network bridge.

In this case, the next best option is to use a virtual bridge with static routing and to configure a libvirt-powered virtual machine to use it (via the virt-manager GUI for example).

SSS supports specifying default applications to use for certain files, and also xdg-open, and customize allowed options, all in comfortable Scheme code.

Refer to the sss mime module at lib/ and the sss-mimeapps-list-file function to understand more how it works.

(define-public sss-mime-default-applications
'((application/pdf org.gnome.Evince icecat)
  (text/html icecat emacsclient)))

The XDG MIME Applications specification builds upon the shared MIME database and desktop entries to provide default applications.

Added Associations indicates that the applications support opening that MIME type. For example: bar.desktop and baz.desktop can open JPEG images. This might affect the application list you see when right-clicking a file in a file browser.

Removed Associations indicates that the applications do not support that MIME type. For example, baz.desktop cannot open H.264 video.

Default Applications indicates that the applications should be the default choice for opening that MIME type. For example, JPEG images should be opened with foo.desktop. This implicitly adds an association between the application and the MIME type. If there are multiple applications, they are tried in order.

At ~/.config/mimeapps.list you get this:

[Default Applications]
application/pdf=evince.desktop;icecat.desktop
text/html=icecat.desktop;emacsclient.desktop

Q: I ran out of disk space, and have too much garbage in the system!

A: Check the Makefile of SSS and run a make full-gc followed by a make sr

Q: Grub install fails due to missing disk space / input-output error!

A: It's recommended to delete some old generations of the system (perhaps also a make full-gc) and to clean the dump file at: /sys/firmware/efi/efivars/dump*

Q: I have a strange error, where guix system reconfigure or guix home reconfigure fails, and some error about expected string ~`Derive String(['! This is also not consistently reproducible and happens in some machines, others not!

A: Sorry, your guix store is partially corrupted. There is some things you can do luckily. First of all backup your important data. Then try to identify the culprit, i.e. the file in the store which is being read and not successfully parsed.

You could first try to do a sudo guix gc --verify=repair,contents, but that may not help. If it does then great you are done! Otherwise try to find a way to disable the dependency on this in your config if possible. Proceed to delete all Guix home generations (except current), after which you should delete all system generations (except current) and do an intensive garbage collection (make full-gc).

You can optionally do a guix pull now to see if maybe a new version of things comes along and helps. In any case try to reconfigure (make jr / make sr) again and it should work, after which you can turn the "offender" back on.

Q: I am unable to generate a GPG key! I get errors about pin-item or pinentry!

A: Try with gpg --pinentry-mode loopback --full-gen-key. Otherwise try other options and check you have the right pinentry programs installed.

Find here the Hyprland keybindings. I usually use these bindings in other WMs too. Labwc session has a a more windows-like style of bindings.

Contributing to free software is a uniquely beautiful act because it embodies principles of generosity, collaboration, and empowerment.

We welcome everyone to feel invited to the SSS Project, and encourage active contribution in all forms, to improve it and/or suggest improvements, brainstorm with me, make it more modular/flexible, etc, feel free to contact me <jjbigorra@gmail.com> to chat, discuss or report feedback.

Find here the Backlog and Kanban boards for SSS: https://lucidplan.jointhefreeworld.org/tickets/sss

• GNU/Linux: A free and open-source operating system combining the GNU system and the Linux kernel.
• Lisp Machine: A type of computer optimized for running Lisp, a family of programming languages.
• GNU Guix: A functional package management tool and standalone distribution of the GNU system.
• REPL (Read Eval Print Loop): An interactive programming environment for evaluating code and seeing immediate results.
• TTY (TeleTYpewriter): A text terminal for interacting with a computer system.
• Scheme: A Lisp dialect often used for scripting in GNU Guix.
• Wayland: A protocol for a display server, often used as a modern alternative to X11.
• Hyprland: A Wayland compositor with great and smooth graphics.
• PipeWire: A modern multimedia framework for managing audio and video streams.
• Elpaca: A package manager for Emacs that supports advanced configuration options.
• Libre: Free and open-source software that respects user freedom.

• SSS: Supreme Sexp System
• GNU: GNU's Not Unix
• OS: Operating System
• REPL: Read Eval Print Loop
• TTY: TeleTYpewriter
• X11: The X Window System
• DBus: Desktop Bus (inter-process communication system)
• RTC: Real-Time Communication

While we may not like thinking about these situations, life has an expiry date for us all, and as such we should prepare for a day when we are no more.

Instructions are crucial in this case because the computer systems we posess might hold valuable or sentimental information.

Without guidance, it could be difficult to figure out how to access these computers, specially a somewhat niche setup like SSS.

Our loved ones can hopefully thanks to this section of the manual understand how to use the computer, retrieve important files, or preserve their work.

Firstly, get a hold of as many passwords as you can and account information, before turning on the device.

Proceed to turn on the device. If immediately a password prompt appears, this is likely a system-wide BIOS password, which you will need to unlock to even use the computer.

Choose the boot option for Guix/GNU/Linux if the choice is presented. If multiple options are shown, just press ENTER to choose the default option or use the arrow keys to move around the GRUB boot menu. If the machine struggles to boot, something like Universal Rescue Disk could come in handy.

Once you boot into SSS (Guix + GNU + Linux), you will see a fast succession of letters in a black screen, wait a bit until you see appear something like:

This is the GNU system! login:

At this point you should type the username of the session you want to log into (generally this is short and all lowercase letters), followed by ENTER.

Then you will get a password prompt. Type the password and press ENTER. Don't worry if you don't see any * characters for the password, your typing worked, this is just a security measure.

If the details were not correct, you will get prompted to login again.

If they were correct, then you will enter the user's shell, at which point you could type gui followed by ENTER to start a graphical user interface. If it doesn't work, try hyprland or labwc.

You should have then booted into a more familiar environment. If the user you logged into has the Hyprland session, the keyboard bindings are documented in sections above. You could for example use Super+/ to open the fuzzy application finder (Super is often the "Windows" or "command" key).

Good luck!