Hikari

Hikari is a Wayland compositor/window manager heavily inspired by cwm window manager. It may be considered minimalist by some, installing at 1140 KiB as of July 2025 with no launchbar/taskbar/status bar by default. Supported protocols:-

wlroots0.15, including layer-shell, screencopy and gamma control.

EWMH/NetWM and ICCCM standards, in large part, may be reflected while not explicitly stated; for what it's worth, artificial intelligence may quickly be consulted, say, specifically for ten traits of each of these protocols that are demonstrated in Hikari (for example, as per a notable listing by Gab AI chat). On the other hand, however, there are shortcomings: the latest wlroots is not supported; wlr-randr reports as of July 2025 that the "compositor doesn't support wlr-output-management-unstable-v1"; etc.

This page may act as a quick start only: enough to launch, navigate windows, edit principal configurations, and to demonstrate how to quit Hikari or reload its configuration.

Todo: * How to configure for bars, including launch bar and task bar; employing rofi here.

Elaborate on views, groups, layouts and marks.

Contributions welcome.

Installation

Install Wayland

Wayland is a new display protocol that aims to replace X11. Wayland requires a seat manager to work.

The setup-wayland-base script installs and enables elogind as seat manager besides enabling community repository and eudev.

Compositors

Display servers that implement the Wayland display server protocol are also called Wayland compositors because they additionally perform the task of a compositing window manager.

Multiple compositor implementations exist, including Sway, Mutter (GNOME's compositor) and Kwin (KDE's compositor). The following compositors are available in Alpine Linux.

XDG_RUNTIME_DIR

As per the protocol spec, Wayland compositors require the XDG_RUNTIME_DIR variable to be set.

With elogind

When using elogind as a seat manager, it exports XDG_RUNTIME_DIR and other XDG environment variables automatically for each session. No further configuration is required.

With pam_rundir

pam_rundir is a PAM module that provides the runtime directory variable. Installing the package pam-rundir takes care of dependencies and no further configuration is required.

Note: XDG_RUNTIME_DIR variable MUST be initialised before the Wayland compositor, and also before the D-Bus session instance is started in your startup script/file for both the methods listed below.

With mkrundir

mkrundir is an executable that can be used to initialise the runtime directory explicitly by each user. To use mkrundir, install the package mkrundir available in testing repository. In your shell init script (e.g.: ~/.profile include an entry as follows at the top of the file

Contents of ~.profile

...
export XDG_RUNTIME_DIR=$(mkrundir)
...

As per mkrundir website, this might have issues inside containers, due to privilege escalation.

Creating and exporting XDG_RUNTIME_DIR manually

Generally, care should be taken when configuring the XDG_* variables manually as this configuration may have errors or conflict with other utilities that do this automatically. Use this only on a system that's not using elogind and other solutions outlined above cannot handle this.

The XDG_RUNTIME_DIR can be initialised manually by adding below snippet to shell init scripts (e.g.: ~/.profile):

Contents of ~/.profile

if [ -z "$XDG_RUNTIME_DIR" ]; then
	XDG_RUNTIME_DIR="/tmp/$(id -u)-runtime-dir"

	mkdir -pm 0700 "$XDG_RUNTIME_DIR"
	export XDG_RUNTIME_DIR
fi

Configuration

To configure Hikari for a given user, one would simply create a hikari.conf file in a hikari folder within the user's $XDG_CONFIG_HOME folder. XDG_CONFIG_HOME is an environment variable, and it is typically set during Wayland configuration to be the /home/<yourusername>/.config folder. Check, as follows:-

$ echo $XDG_CONFIG_HOME

If a blank is returned, one could add the following line to ~/.profile file anywhere before any window manager launch lines/code appear towards the end of the file:

export XDG_CONFIG_HOME=$HOME/.config

Create the Hikari configuration folder and copy over the default configuration file to be customised:

 mkdir $XDG_CONFIG_HOME/hikari
 doas cp /etc/hikari/hikari.conf $XDG_CONFIG_HOME/hikari/

Give the user ($USER) ownership of the file:

$ doas chown $USER:$USER $XDG_CONFIG_HOME/hikari/hikari.conf

Assign only read and write permissions for the user; zero permissions are required for the group and for other users:

$ chmod 600 $XDG_CONFIG_HOME/hikari.conf

Configuration file

As a quick start, provided that one is okay with Hikari launching with the default/primary display and input settings, then one may not require familiarising oneself nor adding or modifying any of the following stanzas of the configuration file (hikari.conf):-

ui
inputs (not currently mentioned in default configuration, anyway)
outputs (other than changing the background wallpaper path default, if desired)
layouts
views

Various 'actions' —such as launching a given application or switching to another window a.k.a. 'view'— will be specified first, so that their shortcuts/'keybindings' could be assigned next.

Specify actions to launch terminal(s)

Option 1: Specify default terminal

The default hikari.conf configuration expects one's default terminal emulator to be specified with the TERMINAL environment variable:

actions {
  terminal = "$TERMINAL"
}

To check whether your default terminal is specified:-

$ echo $TERMINAL

If this returns a blank, or if you prefer a different terminal than the one displayed, you can set yours in your .profile file. You may choose one that is optimised for Wayland. In this example, we had installed qterminal, so in the .profile file, before the last line(s), insert:-

export TERMINAL=qterminal

Option 2: Specify terminal package(s) in hikari.conf

Edit the actions section, mentioned under Option 1, by changing the predefined terminal action so as to call it, if one wishes, the qterminal action. One could also mention additional terminals, such as foot, as additional actions that could be launched each with their own keybindings, also known as 'shortcuts'. For example:-

actions {
  qterminal   = "/usr/bin/qterminal"
  foot        = "/usr/bin/foot"
        }

You may choose to specify the package's path, as shown, in case that this could enhance security.

Specify other actions

One could further instruct Hikari what other essential actions one would want to launch with keybindings/shortcuts that will be soon specified. For example, continue the above passage as follows:-

actions {
  qterminal   = "/usr/bin/qterminal"
  foot        = "/usr/bin/foot"
  libreoffice = "/usr/bin/libreoffice"
  chromium    = "/usr/bin/chromium"
  thunar      = "/usr/bin/thunar"
  rofi        = "/usr/bin/rofi -combi-modi run,drun,filebrowser -show combi -sort"

        }

Tip: The rofi arguments proposed above will offer a useful "combination" of modes: the default rofi view that would appear with those arguments is the combi-mode that will search for any command in your $PATH as you type it into rofi, and it will simultaneously also search for that command among the $XDG_DATA_HOME/applications as well as files with .desktop file extensions in $XDG_DATA_DIRS/applications. Furthermore, with those rofi specified command switches, one could alternatively hit <Ctr>+<Tab> to toggle between the run or drun modes only; or toggle into its filebrowser, from where one could navigate to any file and then hit <Return> to open the file with its assigned mime application. Rofi may therefore replace a launch bar.

Add other commands to that actions stanza that one would want to make application shortcuts/'keybindings' for.

Specify custom keybindings

Now, continuing in hikari.conf, navigate just below that actions stanza to the bindings stanza, and put your cursor at the action-terminal keybinding.

Note that Hikari syntax requires for each of the aforementioned actions to be referred to in this keybindings stanza with the action- prefix; for example, the terminal action is to being referred to here as action-terminal.

bindings {
  keyboard {

[...]

    "L+Return" = action-terminal

[...]

  }

Note what the available key codes are, from the Hikari man page:-

L = <Logo>
S = <Shift>
C = <Control>
A = <Alt>
5 = <AltGR>

Therefore, the default keybinding/shortcut to launch the original terminal (action-terminal) defined above is: <Logo>+<Return> .

One might want to replace the <Logo>+<Return> keybinding with perhaps the more familiar <Ctr>+<Alt>+<Return> binding, say.

Tip: It is important to check that one's chosen keybinding combination has not already been assigned in hikari.conf.

<Ctr>+<Alt>+<key> is not bound to anything by default in Hikari as of July 2025. Add your chosen <key> combination for each of the shortcuts for the actions that you defined earlier. say, <Ctr>+<Alt>+<Return> could be used to launch the action-qterminal, as opposed to the original and default action-terminal action. Continue assigning keybindings for the other actions also:

bindings {
  keyboard {

[...]
    "CA+Return" =  action-qterminal
    "CA+f" =  action-foot
    "CA+l" =  action-libreoffice
    "CA+c" =  action-chromium
    "CA+t" =  action-thunar
    "CA+r" =  action-rofi
[...]

         }

The [...] here only represent unrelated passages from that stanza.

Change any other keybindings, if so wished. One may even assign additional (albeit redundant) shortcuts in that stanza for the same aforementioned actions, as long as the chosen keybinding hasn't already been assigned for a different action, of course, which would create a confusion for that keybinding. Say, for rofi, the action-rofi launch instruction could alternatively be executed through the following additional action-rofi keybinding line that is the same as, say, the shortcut <Logo>+<d> used in cwm:

    "L+d" =  action-rofi

Bindings to toggle between windows/views

The view-cycle-next keybinding (and view-cycle-prev) is another essential binding to make note of in order to navigate between any view/window that one may launch:

bindings {
  keyboard {

[...]
    "LS+n" = view-cycle-next
    "LS+p" = view-cycle-prev

[...]

  }

One may choose to change these to something such as the following.

bindings {
  keyboard {

[...]
    "L+Tab" = view-cycle-next
    "LS+Tab"= view-cycle-prev
[...]

  }

Tip: Be advised that the view-cycle-prev action may need to involve the <Shift> key plus the same key(s) as with view-cycle-next, as opposed to trying unrelated keys; your mileage may vary.

Bindings to toggle between ttys

In case Hikari is launched from the default tty1 login and one's configuration does not work as expected and then hopes to edit the configuration file by logging in from a different tty (a.k.a. virtual terminal or vt), be aware that the common <Ctr>+<Alt>+<Fn> combination shortcut, e.g. <Ctr>+<Alt>+<F2> for tty2, does not work in the default configuration. Instead, <Alt>+<Fn> changes to different ttys e.g. <Alt>+<F2> for tty2, as per the default bindings:-

bindings {
  keyboard {

[...]

    "A+F1" = vt-switch-to-1
    "A+F2" = vt-switch-to-2
[...]


           }

One might decide to change that hikari.conf keybinding passage (for vt-switch-to-1 through vt-switch-to-9) to the <Ctr>+<Alt>+<Fn> bindings that one may be used to; the following binding choices are not assigned elsewhere in Hikari as of July 2025:

   "CA+F1" = vt-switch-to-1
   "CA+F2" = vt-switch-to-2
   "CA+F3" = vt-switch-to-3
   "CA+F4" = vt-switch-to-4
   "CA+F5" = vt-switch-to-5
   "CA+F6" = vt-switch-to-6
   "CA+F7" = vt-switch-to-7
   "CA+F8" = vt-switch-to-8
   "CA+F9" = vt-switch-to-9

Specify session keybindings

Be mindful to make note of these further important keybindings and/or to edit them to suit your preferences:-

Lock your screen (<Logo>+<Space>+<Backspace>).
Quit your Hikari session (<Logo>+<Control>+<LeftAlt>+<q>); which will either (a) drop one into a tty virtual terminal; or (b) if there is no display manager, it may log one out.
Reload your Hikari configuration (<Logo>+<Control>+<LeftAlt>+<r>), in case one wants to attempt applying any recent edits in hikari.conf during that same session.

bindings {
  keyboard {

[...]

    "LS+Backspace" = lock
    "LCA+q"        = quit
    "LCA+r"        = reload

[...]

Specify mouse bindings

The default hikari.conf only specifies the following mouse bindings at the time of creation of this wiki:

  mouse {
    "L+left"  = mode-enter-move
    "L+right" = mode-enter-resize
        }

As per Hikari's man page, available mouse button actions are: ""right", "middle", "left", "side", "extra", "forward", "back" and "task"."

One may prefer to carry over, say, certain cwm mouse bindings instead, if these were more familiar, including:

  mouse {
    "A+left"  = mode-enter-move
    # For the following, apply keys and drag the lower right corner of the window
    "A+middle"= mode-enter-resize		
        }

Autostarting session applications

All applications or instructions that one would like to start automatically during a particular user's session can be specified in the autostart file that could be created in Hikari's configuration folder for the user; only read, write and execution permissions for the user are required:

 touch $XDG_CONFIG_HOME/hikari/autostart
 chmod 700 $XDG_CONFIG_HOME/hikari/autostart

In that autostart file, there is no need for a shebang line (#!, #!/bin/sh, etc) anywhere. Place BusyBox/ash commands on each line in that file, placing ampersands (&) at the end of each command line (similarly to X11's .xinitrc file). In a text editor, enter, for example:-

/usr/bin/qterminal &
/usr/bin/libreoffice &
/usr/bin/rofi -combi-modi run,drun,filebrowser -show combi -sort &

Theming / Ricing

The following will model theming to Breeze Dark.

$ doas apk add gsettings-desktop-schemas breeze-gtk breeze-icons qt6ct

GTK applications

LXAppearance method - Install lxappearance (may only be in edge's @testing repository) and set 'Breeze-Dark' under Widgets; and 'Breeze Dark' under Icons theme.

Gsettings method - In a shell:

 gsettings set org.gnome.desktop.interface gtk-theme 'Breeze-Dark'
 gsettings set org.gnome.desktop.interface icon-theme 'breeze-dark'

Qt applications

Qt applications may be themed in part with the GTK applications instruction above. One application could be suggested for installation: qt6ct (may only be in edge's @testing repository), although other approaches exist. One may also need to add the following in ~/.profile before any wm/compositor launch line or code:-

export QT_QPA_PLATFORMTHEME=qt6ct

Launch qt6ct. Under the Appearance tab, select 'Breeze-Dark'.

Launch Hikari

Tip: Before launching Hikari, make a hard copy of all essential keybindings —especially those addressed in the Configuration section above— to have a listing of the shortcuts needed to launch and navigate through your applications, seeing how there are no out-of-the-box launchbars or taskbars.

From a display manager

Consult how to configure your 'dm' from among Alpine Linux's display managers.

From a tty/virtual terminal

In layman's terms, if on startup you do not have a graphical interface login, known as a display manager, but rather a 'teletype' login, you could simply enter the following.

Option 1 - Note: Do not do so when running as root, for security reasons.

$ exec /usr/bin/dbus-run-session /usr/bin/hikari

Option 2 - A useful launch alternative is to have Hikari automatically log configuration errors and various other session errors/warnings into a log file, say, into ~/hikariandsessionerrors.log. This could help in troubleshooting, say, from a different tty; the log will be overwritten for each session:

$ exec /usr/bin/dbus-run-session /usr/bin/hikari 2> ~/hikariandsessionerrors.log

Option 3 - If you prefer to keep the error log files of each session, consider adding date and time stamps instead:

$ exec /usr/bin/dbus-run-session /usr/bin/hikari 2> ~/hikariandsessionerrors-$(date +'%d.%m.%Y_at_%Hh.%Mmns').log

Autostarting without a graphical display manager

Three options:-

You could add the above instruction to the bottom of your /home/<yourusername>/.profile, but before any other window manager launcher instruction there. However, the following option could be preferable.

In case you would only want to launch Hikari from the default tty1 so as to be able to use any other available tty (tty2-tty6) to edit your Hikari configuration if that session is hanging/crashing, then consider using the following code instead:

 if [ "$(tty)" = "/dev/tty1" ]; then
    exec /usr/bin/dbus-run-session /usr/bin/hikari  2> ~/hikariandsessionerrors.log }}
 fi

Alternatively, at the end of .profile, edit code, if any, that determines, depending on any user input, what compositor/window manager to launch: consider employing the code or launch line from any of the options above.

Navigating a Hikari session

Launch applications:-

from your defined action keybinding/shortcuts; or
from your terminal, launched from your autostart file, or launched from your keybinding; or
from rofi or any other application launcher that you may have installed and launched using its keybinding/shortcut; or
from a launchbar that you may install and configure.

Indicator bars

When you focus a view (or program 'window', so to speak) and then click on the <Logo> key (a.k.a. the 'Super'/'Window'/'Command' key), then 'indicator bars' will light up in yellow, pink, etc. on the top left of the view; the colors can be programmed to indicate the state of each view (see colorscheme in Hikari's man page).

Consider Example (a):
- The first bar displays the title of the window e.g. 'New Tab - Chromium'
- The second bar, below it, may look like: 0 - HDMI-A-1;
  - The first number, the 0, refers to the sheet number,
  - The second part of the ID reports the display output, indicating in this case that it is connected via "HDMI". See how this corresponds to the monitor's display name as reported, say, by xrandr or arandr, although more Wayland-specific applications could be used, preferably. That indicator bar would also display any 'mark' that you may have given for the view.
- The third bar displays the name of the package's title or, if any is assigned, the name of its group. Group names can be given for each application by developing the 'views' stanzas in hikari.conf: browser, editor, etc.

Consider Example (b):

Depending on your configuration, the second indicator bar may state, for example, 0 @ 1 - HDMI-A-1 instead. In this case, a second number appears after an @ symbol, such as @ 1, which indicates 'output number 1'. Output numbers can be assigned for specific packages in your hikari.conf file.

Note that, according to Hikari's man page, "Views that are a member of sheet 0 will always be visible but stacked below the views of the selected sheet." This may not be necessarily noticeable, but if this is not desired, one could, for example, create a stanza for each affected package under the views section and specify for those packages to be launched under sheet = 1 instead. Concurrently, if desired, one could also specify a group name for the package. For example:

views {
  chromium = {                                                                                            
                sheet = 1
                group = browser                                                                                     
             }                                                                                                   
  
  [...]

}