RediWM Wiki

RediWM

RediWM is a wlroots compositor that draws its whole shell itself: taskbar, start menu, settings, lock and login screens, notifications, OSDs. One process, no waybar/greeter/launcher/notification daemon to wire up.

Pages

• Getting Started: build, install, recover a stuck session
• Using RediWM: keybinds, mouse, zoom, tabs, tiling
• Configuration: the config file, window rules, sandbox allowances
• IPC: the socket, the wire format, events, waiting, automation
• IPC Commands: every command, grouped
• rediwm-msg: the CLI, with copy-paste recipes
• Apps and Services: Files, Images, PDF, Editor, desktop, notifications, lock/login
• Protocols and Sandboxing: which Wayland protocols we speak and who gets what

The binaries

Other docs in the repo

• SECURITY.md: security model
• TESTING.md: how the tests run
• AGENTS.md: implementation notes for contributors

Getting Started

Install

scripts/install.sh installs the prebuilt release for your distro (Arch, Debian, Ubuntu and Fedora on x86_64, and their derivatives). It brings the exact wlroots 0.20 RediWM was tested with, installs the runtime libraries through your package manager, checks the download's checksum and adds a RediWM session entry. Nothing is compiled. Pass --build to compile from source instead; that is also the fallback for other distros and CPUs, or if the release's libraries don't match yours. REDIWM_VERSION=<tag> installs a specific release.

curl -fsSL https://rediwm.redios.org/install.sh | sh -s -- --dm   # --dm also installs rediwm-dm

Installing never replaces your login manager. SDDM, GDM and friends keep working. rediwm-dm is only installed with --dm, and even then it isn't enabled.

Optional: foot, brightnessctl, gio/xdg-open, git (for Files repo status), paplay (event sounds). For screen sharing you want xdg-desktop-portal, xdg-desktop-portal-wlr and xdg-desktop-portal-gtk; the installer adds all three.

Build and run

Building needs Zig 0.16 and wlroots 0.20 (scripts/install.sh --build builds it into a private prefix on Debian/Ubuntu; REDIWM_PRIVATE_WLROOTS=1 does the same on Arch and Fedora), plus dev files for Wayland, wayland-protocols, xkbcommon, pixman, FreeType, HarfBuzz, Fontconfig, librsvg/GdkPixbuf, PangoCairo, libinput, PAM, libpulse, libpipewire-0.3, Poppler GLib, libseccomp, libjpeg and libpng.

zig build run -- foot                     # nested in your current Wayland session
zig build -Doptimize=ReleaseSafe          # for daily use and measurements
sh scripts/install-session.sh             # install and restart the running session
sh scripts/install-session.sh --no-restart --dm   # install only, plus rediwm-dm

From a checkout, scripts/install.sh does deps, build, then install-session.sh with whatever args you pass.

Installing adds a RediWM entry to /usr/share/wayland-sessions.

Nested sessions

Running inside another Wayland session is handy for hacking, but:

• It's never sharper than the host. Use REDIWM_SCALE=1 to judge layout.
• The Wayland backend never sets buffer scale, so don't judge sharpness there.

Crashes and recovery

rediwm-session restarts the compositor after a crash, at most 5 times a minute. If the session was locked when it crashed, it comes back locked. Logs go to $XDG_STATE_HOME/rediwm/session.log.

Stuck? Switch VTs with Ctrl+Alt+F1..F12 (works while locked), or:

pkill -u "$(id -u)" -x rediwm

Restarting over IPC (restart_shell) disconnects every app.

Using RediWM

Keys

Everything lives under [keybinds] in the config. Set a binding to "noop" to turn it off.

Mouse

• Alt+drag moves a window, Alt+right-drag resizes.
• Super+Alt+mouse or a middle-button drag pans the desktop.
• Super+Alt+scroll zooms the desktop, Alt+scroll over a window zooms just that window. Scrolling on a titlebar does the same.
• Drag a window to a screen edge to tile or maximize it (snap_to_edges).

The canvas

The desktop is one big canvas, canvas_columns x canvas_rows screens (3x3 by default). You pan around it and zoom out to see everything. Desktop zoom scales all windows together around the pointer, up to 100%, and doesn't change their world positions. Desktop icons and the taskbar stay fixed on screen by default. The mini map shows where you are and hides itself after a moment.

The volume/brightness OSD also shows the desktop zoom percentage.

Window switching zoom

Settings > Appearance, or [compositor] focus_zoom. Controls what Alt+Tab, directional focus and taskbar clicks do to the camera.

Reveals ease over 320 ms. Animation speed and reduced motion apply. You can override the pan with [animations.camera_reveal].

Window tabs

Settings > Appearance > Window tabs lets you pick apps that get tabs, using RediWM chrome (XDG, KDE or X11 decorations). Open the app once and it shows up in the list.

• The + button opens another window as a tab in that frame. Normal launches stay separate.
• Each tab has its own close button. The outer close button closes the whole group and respects app confirmation dialogs.
• Arrow buttons or scrolling over the strip switch tabs. Alt+scroll still zooms the window.
• The app needs a desktop entry with a usable launch command. Launches that only activate an existing window don't make a tab.
• Saved in [compositor] window_tab_apps.

Settings

Start menu cog. It's a normal window covering display modes, scale, night light, input, audio, appearance, shortcuts and the desktop canvas. Changes are written to the config and your comments stay intact.

Locking

• The lock screen covers every output. Escape clears the field and never unlocks.
• Volume and brightness work behind the lock: the hardware keys, or the sliders at the bottom of the screen (click the speaker to mute). A slider appears only if there's a sound output or a backlight to control. The login screen has no sliders.
• It engages before the system sleeps and waits until it's on screen first (lock_on_suspend, on by default). loginctl lock-session works too.
• RediWM doesn't lock on idle by itself. Run swayidle from [[autostart]]: swayidle -w timeout 300 'swaylock -f'.
• Lock-screen UI can't be driven by virtual input.

Games, VMs, X11

• Games get pointer lock and relative motion.
• Xwayland starts on the first X11 connection. With native scaling, X11 apps render at ceil(max output scale) and stay sharp on HiDPI.
• Known limits from wlroots 0.20: X11 to Wayland drag and drop doesn't start, and X11 pointer input on a second output doesn't arrive.

Apps and Services

Files (rediwm-files)

The file manager. Space opens images, PDFs and text files.

• Git: detects repos, subfolders and linked worktrees. The sidebar shows the branch and ahead/behind from what's known locally. Badges: M modified, A added, D deleted, R renamed, U conflict, ? untracked. Click the repo name to jump to its root. It never fetches or changes anything, and never runs a repo's own programs. A repo whose config names filter or Git LFS commands (think archives and USB sticks) is shown as a plain folder.
• Archives: browse ZIP, TAR (gz, bz2, xz, zstd) and 7z like folders. They're read-only. Opening a member extracts just that file to private temp storage that's removed on exit. Context menu has Extract and Extract to.... Name clashes ask Skip/Rename/Cancel, nothing is overwritten, and paths outside the destination are rejected. No passworded archives, links or special files yet.
• Thumbnails: JPEG and PNG are decoded without GdkPixbuf (it's slow and goes through sandboxed loaders). Shared freedesktop cache in $XDG_CACHE_HOME/thumbnails. REDIWM_FILES_THUMBNAILS=0 turns them off.
• Devices: USB sticks and drives show up via UDisks2. Eject means unmount, the device stays listed, dimmed. REDIWM_FILES_DEVICES=0 disables it.
• Pins: drop a folder on the PLACES sidebar to pin it. Stored one path per line in $XDG_STATE_HOME/rediwm/files-places.
• Drag a file out and the window slides aside (dodge_file_drags).

Text editor (rediwm-editor [FILE ...])

Tabs, one window per display. UTF-8 files up to 4 GiB (they must fit in free memory), keeps BOM and line endings, asks before discarding changes. Only the lines on screen are ever laid out, so opening, scrolling and Find stay fast on huge files, and a single line of many megabytes is folded onto several rows. Editing near the start of a very large file moves the rest of the text, which costs a few milliseconds per 100 MB per keystroke.

Images (rediwm-images) and PDF (rediwm-pdf FILE)

Files, Images and the editor also run on other Wayland compositors.

The PDF viewer is sandboxed with Landlock (ABI 3 or newer) and needs a compositor with security-context-v1, which RediWM has. It refuses to parse a document if it can't isolate itself. Each PDF gets its own viewer. Web links copy their address instead of opening. Details in docs/pdf-security.md.

Desktop

Icons and wallpaper from ~/Desktop, on by default ([desktop] enabled). A .desktop launcher only runs if it's installed, owned by root and executable, or an exact copy of an installed entry. Anything else shows as a plain file until you pick Allow Launching in its menu. The wallpaper comes from wallpaper in the config, Settings, or set_wallpaper over IPC.

Notifications

RediWM is the notification daemon. Actions, images, do-not-disturb, history. Rules go in [[notification_rules]]. If you'd rather use dunst, set [notifications] daemon = "dunst" and restart. Inspect and drive them over IPC: notifications, set_dnd, dismiss_notification, invoke_notification_action.

Lock, login and polkit

• Lock: see Using RediWM. Locks never unlock because of a crash: after a crash while locked, rediwm-session locks again before the backend even starts.
• Greeter / rediwm-dm: the greeter is a lock that never unlocks, only rediwm-dm decides. It runs as an unprivileged user on its own VT. To use it: install with --dm, disable your current display manager, sudo systemctl enable rediwm-dm, reboot. Options in /etc/rediwm/dm.conf. It does no Xwayland, autostart, IPC, tray, portal or services.
• Polkit: RediWM is a polkit agent ([polkit] enable). Capture and screen sharing are refused during a prompt.
• Accounts: account management goes through rediwm-accounts-helper under pkexec. The compositor never runs as root.

Screen capture and sharing

wlr-screencopy and ext-image-copy-capture work (grim, wf-recorder, OBS, the portal). Any capture lights the taskbar Stop sharing indicator. It's refused while locked or during a polkit prompt. stop_all_capture over IPC ends everything. See docs/screen-sharing.md.

App scopes

On a real session each app you launch is moved into its own app-rediwm-<id>-<pid>.scope so systemd-oomd kills one runaway app and not your whole session. Off in nested and headless sessions unless REDIWM_APP_SCOPES=1.

Startup

The desktop renders before autostart runs, and audio and session environment setup never block frames or input. Autostart entries go in [[autostart]].

Configuration

The file is $XDG_CONFIG_HOME/rediwm/config.toml. REDIWM_CONFIG overrides the path. It's written with commented defaults on first run and reloads when you save. A parse error keeps the previous config. You can also reload with rediwm-msg reload, and check status with rediwm-msg config.

Sections

[theme], [input], [input_method], [compositor], [region], [animations.*], [idle], [night_light], [notifications], [desktop], [polkit], [ipc], [keybinds], [[outputs]], [[autostart]], [[window_rules]], [[notification_rules]], [[sandbox_allow]].

It's not full TOML

The parser reads a line-based subset. Don't run it through a generic TOML formatter. The rules:

• One key = value per line. Arrays on one line too.
• Strings use double quotes and are taken verbatim. No escape processing, so \n, \" and \u mean exactly those characters.
• No single-quoted strings, no multiline strings or arrays, no inline tables, no arbitrary dotted keys, no dates.
• # starts a comment outside double quotes.

app_id = ["firefox", "chromium"]   # fine

Theme

Colors, text sizes, corner radii and control styling belong in [theme]. See the complete theme reference for every supported key and its built-in default. Appearance preserves these overrides when it saves.

Region & Language

Settings → Region & Language lets you choose a personal language, regional formats and time zone. Empty choices inherit the login environment; system defaults are unchanged. RediWM's interface currently uses English.

Personal clock and calendar preferences apply immediately and are saved in [region]:

[region]
clock_24h = false
clock_show_seconds = false
clock_show_day = true
first_day_of_week = "sunday"

clock_24h applies to the taskbar, calendar and built-in lock screen. clock_show_seconds adds seconds to the taskbar time. clock_show_day shows the date line beneath it, using the selected regional format (formats, or the inherited locale). Both lines are centered; hiding the date centers the time vertically. These two options apply only to the taskbar clock. first_day_of_week accepts any lowercase weekday name, and changes both the weekday headings and date positions in the taskbar calendar. Existing configs keep 12-hour time and Sunday first until changed.

Handy [compositor] keys

Outputs

[[outputs]]
name = "DP-2"
x = -1920              # negative origin is only possible here
y = 0
scale = "auto"         # "auto" or 1 to 3
width = 1920           # optional mode
height = 1080
refresh_mhz = 60000    # omit for the highest at this size
enabled = true
primary = false
transform = "normal"   # normal, 90, 180, 270, flipped variants
night_light = false    # never tint this monitor
gamma = 1.0            # 0.5 to 2.0

Omit coordinates for automatic left-to-right placement. Scale and placement apply live. REDIWM_SCALE overrides every output. Changes from Settings, wlr-randr, kanshi or rediwm-msg output-config are all saved here.

Idle and night light

[idle]
blank_after_seconds = 600    # 0 disables
suspend_after_seconds = 0    # 0 disables

[night_light]
enabled = true
schedule = "always"          # "always", "fixed" or "sun"
temperature = 5000           # 1700 to 10000 K
# fixed: day_temperature, start, end, transition_minutes (0 to 180)
# sun:   latitude, longitude

Night light is on by default as a soft warm tint all day.

Window rules

Matched by glob. For each property the last matching rule wins.

[[window_rules]]
app_id = ["firefox", "chromium"]
title = "*Picture-in-Picture*"
opacity = 0.9
skip_taskbar = true
focus = false

• Matchers: app_id, title, tag, x11_class, x11_instance, backend, dialog, and exclude_* versions.
• Properties: output, x, y, center, width, height, maximized, fullscreen, focus, depth, opacity, decorations, skip_taskbar.

To debug a rule, ask the compositor:

rediwm-msg window-rules 12                       # what matched this window
rediwm-msg match-window-rules --app-id foo       # dry run

tag comes from the client (xdg-toplevel-tag), so it's metadata, not trusted identity.

[ipc]

[ipc]
automation = true   # synthetic input and screen capture. Restart required

Read once at startup. Details on IPC.

[polkit]

[polkit]
enable = true
helper_socket = "/run/polkit/agent-helper.socket"

[[autostart]]

[[autostart]]
cmd = "nm-applet"    # one entry per program

[[sandbox_allow]]

See Protocols and Sandboxing.

Theme reference

Put these keys in [theme] in $XDG_CONFIG_HOME/rediwm/config.toml. REDIWM_CONFIG selects another config file; REDIWM_THEME overlays another file's [theme] section. Omitted keys use the built-in defaults below. Appearance saves custom tokens along with its sliders and selectors. The bundled picker includes RediWM Dark, RediWM Light and Redi Blue. Redi Blue uses navy surfaces, cyan accents, 98% chrome opacity and a 30% selection tint. RediWM Light uses 75% window chrome opacity and teal selection accents. start_button_logo_color optionally tints the bundled R logo; Light uses a dark tint for contrast. Custom start-button icons retain their own colours.

Appearance also has a Taskbar theme picker under Theme, with the same presets plus "Same as theme". It gives the taskbar the preset's colours and leaves every other surface on the theme above. It is saved as a [taskbar_theme] section holding only these keys: taskbar_bg, taskbar_surface, taskbar_hover, taskbar_border, border_soft, surface_hover, window_fg, window_dim, danger, window_close_hover, start_button_hover, start_button_indicator, start_button_logo_color and the battery_* colours. Unlisted keys are ignored, so a whole theme file's body can be pasted under that header; keys it leaves out take the built-in defaults, not the main theme's. The section's presence selects the taskbar theme (an empty one is the built-in colours); without it the taskbar follows [theme]. Sizes, gaps and radii always come from [theme].

Colors accept "#rrggbb", "#rrggbbaa", or "rgba(r,g,b,a)" with RGB channels from 0 to 255 and alpha from 0 to 1. Numbers must be finite and nonnegative. Sizes are logical pixels. The tables describe appearance tokens; window placement, animation timing, cursor themes and sizes, blur, inactive opacity and frame radius also have settings in the other config sections.

[theme]
shell_accent = "#86bfff"
control_thumb = "#ffffff"
toggle_track = "rgba(120,140,170,0.25)"
slider_track_height = 6
app_text_size = 14
app_heading_size = 13
app_status_size = 12
desktop_selection = "rgba(80,140,220,0.2)"
desktop_selection_border = "#508cdc"
battery_full = "#40dca0"
image_checker_size = 16
pdf_search_match = "rgba(100,180,255,0.4)"

Palettes and reload

Shell surfaces use window_fg and window_dim. Their accent normally follows start_menu_selected_marker; shell_accent, shell_on_accent and shell_border_focus override that palette and its control/field focus rings. Settings uses settings_radius for controls. Text fields, carets and text selection have optional overrides that otherwise follow the accent of the surface displaying them.

Files' New, Sort and Filter buttons share the secondary-button palette: surface sets the background, surface_hover the hover fill, and border_soft the border. Their text and icons use window_fg. Active Filter and view-mode buttons use shell_accent (or start_menu_selected_marker when unset), tinted by button_selected_alpha. All of these values can be set in [theme]; Files follows edits while running.

Files' dialog bodies and context menus share app_toolbar as their background color. Changing it in [theme] updates both.

The compositor reloads the theme when the config changes. Files and Images follow saved colors and sizes; PDF and Editor load them when starting. The compositor's frame radius is the numeric [theme].radius_lg. The legacy [compositor].border_radius is used only when the theme omits radius_lg. Appearance's Radius presets write all numeric radius tokens: Default restores the current built-in radii, Sharp caps them at 4 px (the minimap's default), and Round uses 1.3 times the defaults. Individual theme radii remain editable. Cursor styling is [input].cursor_theme and [input].cursor_size; animation behavior belongs in [animations].

Set [theme].chrome_round_buttons = true for circular window controls and pill-shaped window tabs. Tab close, new-tab and overflow controls follow the same setting. It defaults to false, preserving the existing corner radii, and reloads live from the main config or the REDIWM_THEME file. Button sizes and hit targets stay the same; radius_lg still controls the window frame.

The lock's background always paints opaque, even if lock_bg supplies alpha; lock_wallpaper_opacity controls its wallpaper overlay. Actual image pixels, PDF paper/content, application-provided icons and fixed layout/hit-test geometry retain their content or structural dimensions.

Colors

accent_2, accent_3, glass_strong and border_focus are compatibility keys retained by the reader and saver; current painters use the specific surface and control tokens above. scrollbar_thumb_active now overrides the hover/drag color; omitted, it follows the surface accent.

Sizes and styling

Numeric tokens accept 0–4096 unless constrained below. Fractions ending in _alpha or _opacity, and dialog_glyph_lift, accept 0–1.

taskbar_height is an alias for taskbar_size. Layouts cap some dimensions to fit their available space. The scrollbar reserves room for its maximum width; slider_* keys control slider geometry while sharing the scrollbar feedback.

Strings

In Settings → Appearance → Start menu, Choose file… selects a PNG or SVG for the Start button logo and applies it immediately. Reset to default restores the bundled R logo. Both choices are saved with the theme.

IPC

RediWM has a JSON IPC over a Unix socket. Use it to script the compositor, inspect state, or drive it from tests. rediwm-msg is the friendly client, see rediwm-msg. Every command is in IPC Commands.

The socket

$XDG_RUNTIME_DIR/rediwm-<WAYLAND_DISPLAY>.sock, or whatever REDIWM_SOCKET says. It lives in a private directory (owned by you, no group/other access) and is created with umask 0177. If the directory isn't private the server refuses to start the IPC.

Wire format

UTF-8 JSON, one request per line, one response per line.

{"version":1,"id":1,"command":"windows"}
{"version":1,"id":2,"command":"move_cursor","params":{"x":100,"y":200}}

Anything else is rejected: extra envelope fields, duplicate JSON keys, bare strings, {"query":...} / {"action":...} envelopes, PascalCase names and CLI aliases. There's no separate "query" vs "action" on the wire, both are just command.

Responses:

{"id":1,"Ok":{"Windows":[]}}
{"id":1,"Err":"InvalidRequest"}

Response tags are case-sensitive and different from command names. Clients should ignore unknown response fields. New commands show up in capabilities, and a breaking change would mean a new protocol version.

Try it with no tools at all:

echo '{"version":1,"command":"version"}' | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/rediwm-wayland-1.sock

Discovering things

rediwm-msg capabilities    # canonical command names
rediwm-msg describe        # params, kinds, protocol version

describe_ipc is the source of truth for parameter schemas. The code reference is src/ipc/protocol.zig and src/ipc/commands.zig.

Queries vs actions

Queries read state. Actions change something. Both use the same envelope. The split only matters in rediwm-msg (rediwm-msg action focus-window ... for actions that don't have a top-level subcommand).

Events

event_stream turns the connection into a feed. You get an acknowledgement, then newline-delimited tagged events until you disconnect.

rediwm-msg event-stream
rediwm-msg event-stream --events window_opened,window_closed
rediwm-msg event-stream --window 12
rediwm-msg event-stream --output DP-1

Raw params: {"window_id"?: n, "output"?: "name", "events"?: ["..."]}.

Events you can filter on:

state_snapshot is always delivered, whatever you filter. A window_id filter only affects window events. Event subscriptions are re-checked against the lock state, so you get nothing while the session is locked.

Waiting instead of sleeping

If you're scripting, don't sleep. Use the wait commands.

rediwm-msg wait window_mapped --timeout 5000
rediwm-msg wait window_closed --id 12
rediwm-msg wait-frame --output DP-1

wait_for takes a condition and a timeout (default 5000 ms) and returns the condition, elapsed ms and state. Raw example:

{"version":1,"command":"wait_for","params":{"condition":{"window_mapped":{"app_id":"foot"}},"timeout_ms":5000}}

Conditions:

wait_for_frame blocks until the next frame commit on an output and returns the output, frame_seq and elapsed time. The CLI's wait takes a condition name plus --id/--output/--timeout. For conditions with richer params (app_id, title, path, ...), use --raw.

Automation (synthetic input and pixels)

Off by default. These commands are refused unless automation is on:

move_cursor, move_cursor_relative, pointer_button, click, scroll, key, key_press, type_text, drag, screenshot, dump_buffer, sample_pixels, pinch, swipe, click_widget, hover_widget.

Turn it on:

[ipc]
automation = true

or start with REDIWM_IPC_AUTOMATION=1. It's read once at startup, so you need a restart. When it's on, the compositor logs a warning, because any client of the socket can then type and take screenshots.

Security rules

• Everything is refused with SessionLocked while the session is locked.
• Sandboxed callers (Flatpak and friends, detected via SO_PEERPIDFD and .flatpak-info) need an explicit [[sandbox_allow]] with the ipc group. They fail closed, and the check is redone on config reload. Synthetic input and capture additionally need the automation group.
• The socket is only reachable by your uid.
• Virtual input never reaches the lock or auth UI.

Writing a client

Python is the easiest. This is basically what tests/ipc_client.py does:

import json, os, socket

path = f"{os.environ['XDG_RUNTIME_DIR']}/rediwm-{os.environ['WAYLAND_DISPLAY']}.sock"
s = socket.socket(socket.AF_UNIX)
s.connect(path)
f = s.makefile("rw")

def call(command, params=None, id=1):
    req = {"version": 1, "id": id, "command": command}
    if params is not None:
        req["params"] = params
    f.write(json.dumps(req) + "\n"); f.flush()
    resp = json.loads(f.readline())
    if "Err" in resp:
        raise RuntimeError(resp["Err"])
    return resp["Ok"]

print(call("windows"))
call("focus_window", {"id": 3})

For events, open a second connection, send event_stream, then keep calling readline().

Tips:

• Use get_state when you need windows, outputs, camera and shell to agree. Separate queries can race.
• Coordinates are layout coordinates, not per-output pixels.
• Set a socket timeout. wait_for can take up to its own timeout to answer.
• restart_shell drops your connection and every app. That's expected.

IPC Commands

Names are the wire names ("command": "..."). The CLI column is the rediwm-msg spelling. Run rediwm-msg describe for exact params. [auto] means it needs automation. "Action" in the CLI column means rediwm-msg action <name>.

Info

Windows

Outputs, camera, workspaces

output-config flags: --width --height --refresh-mhz --x --y, --scale <1..3|auto>, --position auto, --transform <normal|90|180|270|flipped|flipped_90|flipped_180|flipped_270>, --enabled/--disabled, --primary/--no-primary. auto clears the override.

Inspecting the shell and scene

Panels and menus

Input

Screenshots and pixels

Prefer screenshot and dump_buffer over host grim when debugging. Host tools show host scaling and any window covering yours.

Waiting

wait_for (wait) and wait_for_frame (wait-frame). See IPC for the condition list.

Audio

Volumes are clamped to 0..1.

Notifications

Night light and idle

Settings and appearance

These work without opening Settings.

set_wallpaper, set_accent_color and set_night_light save to the config by default. Pass "persist": false for a session-only change. If saving fails you get the error before anything changes live.

Service changes use systemd's interactive authorization and only return "accepted". Watch get_services.action_pending, raw state and status for the result.

Session

Examples

rediwm-msg --raw '{"version":1,"command":"get_theme"}'
rediwm-msg --raw '{"version":1,"command":"set_accent_color","params":{"color":"#e05a47"}}'
rediwm-msg --raw '{"version":1,"command":"set_night_light","params":{"enabled":true,"temperature":4000,"persist":false}}'

rediwm-msg

Command line client for the IPC. It turns friendly subcommands into v1 JSON, sends them, and pretty prints the reply.

rediwm-msg [options] <command>

rediwm-msg raw [JSON|-] does the same as --raw.

Two kinds of subcommand

Most queries and a few actions are top level: rediwm-msg windows, rediwm-msg maximize 12. The rest are under action: rediwm-msg action focus-window --id 12. --help shows which is which. Wire-name aliases like get-state, get-perf, list-panels also work.

doctor

rediwm-msg doctor

Checks the socket and the environment and tells you what's off. Run this first when nothing works. It runs even without a compositor to talk to.

Recipes

See what's open

rediwm-msg windows
rediwm-msg focused-window
rediwm-msg state --json | jq '.Ok'

Window management

rediwm-msg action focus-window --id 12
rediwm-msg action move-window-to --id 12 --x 200 --y 100
rediwm-msg action move-window-to --id 12 --output DP-2
rediwm-msg fullscreen 12
rediwm-msg set-zoom 12 80
rediwm-msg action close-window            # focused one

Launch things

rediwm-msg launch org.gnome.Nautilus.desktop
rediwm-msg action spawn -- foot -e htop

Displays

rediwm-msg outputs
rediwm-msg output-config DP-1 --scale 1.5
rediwm-msg output-config DP-1 --width 2560 --height 1440 --refresh-mhz 144000
rediwm-msg output-config DP-2 --x -1920 --y 0
rediwm-msg output-config DP-2 --disabled
rediwm-msg output-config DP-1 --scale auto --position auto

Debug a window rule

rediwm-msg window-rules 12
rediwm-msg match-window-rules --app-id firefox --title "Picture-in-Picture"

Watch events

rediwm-msg event-stream --events window_opened,window_focused

Scripted tests (needs automation on)

rediwm-msg action spawn -- foot
rediwm-msg wait window_mapped --timeout 5000
rediwm-msg action key-press --key ctrl+shift+t
rediwm-msg action type-text --text "hello"
rediwm-msg wait-frame
rediwm-msg action screenshot --save /tmp/shot.png
rediwm-msg sample-pixels 100 100 1 1

Poke at the UI

rediwm-msg action open-start-menu
rediwm-msg panels
rediwm-msg widget-tree start_menu
rediwm-msg dump-buffer taskbar
rediwm-msg close-panel start_menu

Audio and keyboard

rediwm-msg action set-master-volume --volume 0.4
rediwm-msg action toggle-mute
rediwm-msg switch-layout next

Anything without a subcommand

rediwm-msg --raw '{"version":1,"command":"get_theme"}'
echo '{"version":1,"command":"set_dnd","params":{"enabled":true}}' | rediwm-msg --raw

Exit behaviour

Bad arguments print an error and exit 1. A compositor Err is printed and the exit code is nonzero. With no socket it tells you to set REDIWM_SOCKET or XDG_RUNTIME_DIR and WAYLAND_DISPLAY.

Protocols and Sandboxing

Wayland protocols

On top of xdg-shell, layer-shell and Xwayland:

Things worth knowing

• Output changes from clients (wlr-randr, kanshi) are saved just like ones made in Settings.
• Workspace: the canvas is advertised as one workspace. You can't create, remove or switch workspaces through the protocol. Window IPC reports workspace_id = 1, plus tag, description and content_type when the client sets them. [[window_rules]] can match tag with the same globs as app_id.
• Content type hints (photo, video, game) don't change idle or focus policy.
• Colour: follows the renderer. Pixman gives colour feedback without parametric image creation, GPU renderers advertise what wlroots can convert. Output stays SDR. No HDR modes or ICC loading.
• Tearing: [compositor] allow_tearing = true honours async hints from focused fullscreen clients. If an output can't do it, that output falls back to synchronized presentation until it's recreated. Suppressed while locked.
• DRM leases: DRM backends only, physical non-desktop outputs only. Revoked on lock or auth. Private capture outputs are never offered.
• Session lock clients: a client ext-session-lock is treated as a real lock. If the client dies the session stays locked.
• Remote input: virtual pointer and keyboard can't touch the lock or auth UI.
• Pointer lock: active only when the client has both pointer and keyboard focus.
• Shortcut inhibit (VMs, remote desktops) blocks the switcher and screenshot shortcuts. Hardware keys, VT switching and open panels still win. Super+Escape takes shortcuts back.

Sandboxed apps

Clients connecting through wp_security_context_v1 (Flatpak etc.) only see the safe Wayland globals. Privileged ones are hidden, and guessing the name of a hidden global is a protocol error. Nested security contexts are fatal.

Grant access per app in the config:

[[sandbox_allow]]
app_id = "com.obsproject.Studio"   # exact match on the security-context app id
engine = "org.flatpak"             # optional, default matches any engine
allow  = ["capture"]

Groups:

On reload, Wayland grants apply to new connections only (already bound globals stay bound until the app reconnects). IPC grants apply immediately. The greeter hides all of these.