Docker / Podman

On this page

• Docker / Podman
  • Pull the Image
  • Run the Container
    • Recommended: host networking
    • No GPU (CPU / Pixman renderer)
    • AMD or Intel GPU passthrough
    • NVIDIA GPU passthrough (CDI)
    • Gamepad / joystick passthrough
    • Port mapping (alternative to host networking)
  • Port Reference
  • Remote Access
  • Environment Variables
  • SELinux / AppArmor Note
  • What’s Inside the Image
    • labwc image (DESKTOP=labwc, default)
    • KDE image (DESKTOP=kde)

The Lumen container image bundles a complete desktop environment — labwc or KDE Plasma, XWayland, and Firefox — on top of Ubuntu. It’s the fastest way to try Lumen without installing anything on your host system.

The instructions below use podman. docker works as a drop-in replacement for every command.

---

Pull the Image

Pre-built images are available on the GitHub Container Registry. Choose the desktop environment you want:

# labwc (lightweight Wayland compositor) — default
podman pull ghcr.io/swedishborgie/lumen:latest-labwc

# KDE Plasma 6
podman pull ghcr.io/swedishborgie/lumen:latest-kde

Image tag	Desktop	Terminal
latest-labwc (recommended)	labwc — lightweight wlroots compositor	foot
latest-kde	KDE Plasma 6 (kwin_wayland + plasmashell)	Konsole

---

Run the Container

Recommended: host networking

Podman’s default NAT networking can interfere with WebRTC UDP flows even when ports are mapped. Using --network host bypasses NAT entirely and is the recommended approach:

podman run --rm -it --device /dev/dri --network host ghcr.io/swedishborgie/lumen:latest-labwc

Open http://localhost:8080 in a browser and click Connect.

No GPU (CPU / Pixman renderer)

Works on any Linux machine without a GPU:

podman run --rm -it --network host ghcr.io/swedishborgie/lumen:latest-labwc

AMD or Intel GPU passthrough

Pass the DRI device group to enable VA-API hardware encoding:

podman run --rm -it \
    --device /dev/dri \
    --security-opt label=disable \
    --network host \
    ghcr.io/swedishborgie/lumen:latest-labwc

NVIDIA GPU passthrough (CDI)

Requires the NVIDIA Container Toolkit (CDI) on the host:

podman run --rm -it \
    --device nvidia.com/gpu=all \
    --security-opt label=disable \
    --network host \
    ghcr.io/swedishborgie/lumen:latest-labwc

Gamepad / joystick passthrough

Lumen can forward browser gamepad input to virtual Linux input devices via uinput. Pass /dev/uinput and add the input group to enable this:

podman run --rm -it \
    --device /dev/uinput \
    --group-add input \
    --network host \
    ghcr.io/swedishborgie/lumen:latest-labwc

The uinput kernel module must be loaded on the host (lsmod | grep uinput). Load it with sudo modprobe uinput if not. The input group is granted write access to /dev/uinput by the udev rule installed with the package (pkgs/70-lumen-uinput.rules). If /dev/uinput is not passed, Lumen starts normally and gamepad support is simply disabled.

You can combine --device /dev/uinput --group-add input with GPU passthrough flags as needed.

Port mapping (alternative to host networking)

If you prefer explicit port mapping instead of --network host:

podman run --rm -it \
    --device /dev/dri \
    --security-opt label=disable \
    -p 8080:8080 \
    -p 3478:3478/udp \
    -p 50000-50010:50000-50010/udp \
    ghcr.io/swedishborgie/lumen:latest-labwc

---

Port Reference

Port	Protocol	Purpose
8080	TCP	HTTP server + WebSocket signaling
3478	UDP	TURN server (NAT traversal control)
50000–50010	UDP	TURN relay data channels

The embedded TURN server handles NAT traversal automatically. The browser receives TURN credentials via /api/config — no manual configuration is required.

To disable the TURN server:

podman run ... -e LUMEN_TURN_PORT=0 ghcr.io/swedishborgie/lumen:latest-labwc

---

Remote Access

To allow WebRTC connections from other machines on your network, set LUMEN_TURN_EXTERNAL_IP to the host’s reachable IP address:

podman run --rm -it \
    --device /dev/dri \
    --security-opt label=disable \
    --network host \
    -e LUMEN_TURN_EXTERNAL_IP=192.168.1.100 \
    ghcr.io/swedishborgie/lumen:latest-labwc

---

Environment Variables

Variable	Default	Description
LUMEN_BIND	0.0.0.0:8080	HTTP server bind address
LUMEN_DRI_NODE	(auto-detected)	Override the DRI render node (e.g. /dev/dri/renderD128)
LUMEN_TURN_PORT	3478	TURN server UDP port. Set to 0 to disable.
LUMEN_TURN_EXTERNAL_IP	127.0.0.1	IP advertised as the TURN relay address
LUMEN_TURN_USERNAME	(auto-generated)	TURN credential username
LUMEN_TURN_PASSWORD	(auto-generated)	TURN credential password
LUMEN_TURN_MIN_PORT	50000	Start of TURN relay UDP port range
LUMEN_TURN_MAX_PORT	50010	End of TURN relay UDP port range
LUMEN_WIDTH	1920	Output width in pixels
LUMEN_HEIGHT	1080	Output height in pixels
LUMEN_FPS	30.0	Target frames per second
LUMEN_VIDEO_BITRATE_KBPS	4000	Video encoder target bitrate (kbps)

---

SELinux / AppArmor Note

On hosts with SELinux or AppArmor enforcement, GPU device passthrough may require additional flags:

--security-opt label=disable        # SELinux
--security-opt apparmor=unconfined  # AppArmor

---

What’s Inside the Image

labwc image (DESKTOP=labwc, default)

Component	Purpose
lumen	The compositor/streamer binary
labwc	Inner Wayland compositor (the desktop you stream)
xwayland	XWayland bridge for X11 apps
firefox	Browser — auto-started by labwc on launch
foot	Terminal emulator (available in the labwc right-click menu)
pipewire	Audio server for audio capture

KDE image (DESKTOP=kde)

Component	Purpose
lumen	The compositor/streamer binary
kwin_wayland	KDE window manager / inner Wayland compositor
plasmashell	KDE Plasma desktop shell
xwayland	XWayland bridge for X11 apps
firefox	Browser — auto-started on launch
konsole	KDE terminal emulator
pipewire	Audio server for audio capture