linux/docs/display-managers/matchbox‑wm.md

matchbox‑wm

matchbox‑wm is a minimal, single‑window X11 window manager originally designed for embedded systems, kiosks, and low‑resource devices. Unlike traditional window managers, it enforces a strict one‑window‑only model, making it ideal for fullscreen kiosk applications such as Chromium dashboards.

Key characteristics:

• Single‑window design: Only one application window is shown at a time, always fullscreen.

• No desktop components: No panels, menus, compositors, notifications, or session daemons.

• Deterministic behavior: Eliminates window management complexity, ideal for locked‑down kiosk workflows.

• Runs on Xorg: Works as a tiny layer on top of the X11 display server.

• Perfect for kiosks: Commonly paired with Chromium in kiosk mode for dashboards and appliances.

Install

apt update
apt install matchbox-window-manager xorg 

Setup

Example to start matchbox-window-manager, auto login user xxx and start chromium kiosk mode.

1. Auto login

mkdir -p /etc/systemd/system/getty@tty1.service.d

#/etc/systemd/system/getty@tty1.service.d/autologin.conf
[Service]
ExecStart=
ExecStart=-/sbin/agetty --autologin xxx --noclear %I $TERM

sudo systemctl daemon-reload

2. Setup user to startx

# /home/xxx/.bash_profile
if [ -z "$DISPLAY" ] && [ "$(tty)" = "/dev/tty1" ]; then
    startx
fi

3. Setup scripts

# /home/xxx/.xinitrc
                             
eval $(dbus-launch --exit-with-session)
export SSL_CERT_DIR=/etc/ssl/certs
export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt

matchbox-window-manager &
chromium \
  --kiosk \
  --noerrdialogs \
  --disable-infobars \
  https://yoursite

chmod +x /home/xxx/.xinitrc

misc

Stop auto tty session and kill sessions:

sudo systemctl stop getty@tty1

if stuck in a kiosk loop, the system boots straight into:

• matchbox-window-manager
• Chromium kiosk and cannot switch TTY, cannot access a terminal, and cannot fix the script.

Interrupt GRUB and boot into console mode.

Steps:

1. Reboot the machine

2. When it starts, force the GRUB menu to appear:

3. When GRUB appears, highlight your Linux entry

4. Press e to edit

5. Find the line starting with: linux /boot/vmlinuz...

6. At the end of that line, add: systemd.unit=multi-user.target