Configuration reference

Configuration reference

This is the complete configuration surface read by hyprbaric. Every table and field is optional: an omitted value keeps its built-in default. The settings window writes the same user config.toml for the controls it manages. TOML additionally exposes runtime policy.

Configuration surfaces

Top-level table	Purpose	Managed in Settings
[appearance]	Bar placement and visual treatment.	Appearance
[global_menu]	Where the global menu's compositor plugin comes from.	Global menu
[modules.*]	Which modules are shown on the bar.	Modules
[workspaces]	Workspace indicator presentation and interaction.	Workspaces
[night_light]	Desired night light state and temperature.	Display
[schedules.night_light]	Daily night light time window.	Display
[shortcuts.*]	Built-in global action bindings.	Keybinds
[audio]	Volume shortcut adjustment policy.	No
[network]	NetworkManager and traffic refresh cadence.	No
[brightness]	Backlight polling and DDC discovery/write policy.	No
[power]	Battery and power-profile refresh cadence.	No
[system]	CPU, memory, and disk occupancy refresh cadence.	No
[setup]	First-run setup-guide persistence and startup policy.	Setup guide

Nothing outside these thirteen tables is read from config.toml. An unknown table or key is ignored. A known key with an invalid value stops startup and is logged with the offending path.

For file locations, precedence, and when changes are applied, see Configuration. For the environment variables, capture destinations, and host capabilities that are configured outside TOML, see Environment and files and Dependencies and capabilities.

Appearance

The Appearance tab applies changes live and can restore these values to their defaults.

config.toml

[appearance]
position = "top"
monitor = "primary"
opacity = 77
corner_radius = 12
accent_hue = 275

Key	Values	Default	Effect
position	"top", "bottom"	"top"	Edge where hyprbaric reserves space and renders.
monitor	"primary", "all", or a monitor name offered by the Appearance tab	"primary"	Displays that receive a bar. A missing named monitor temporarily falls back to the primary display.
opacity	Integer 20..=100	77	Bar background opacity in percent.
corner_radius	Integer 0..=32	12	Radius of the bar’s outer corners, in pixels.
accent_hue	Integer 0..=359	275	Hue used for highlights and active states.

Modules

The Modules tab controls which modules appear on the bar. Hiding one does not stop its backing service, as Settings window describes.

config.toml

[modules.active_window_title]
enabled = true

[modules.system_tray]
enabled = true

[modules.notifications]
enabled = true

[modules.audio_display]
enabled = true

[modules.system_occupancy]
enabled = true

Table	Key	Default	Effect
[modules.active_window_title]	enabled	true	Shows the focused app and document title.
[modules.system_tray]	enabled	true	Shows StatusNotifier tray items.
[modules.notifications]	enabled	true	Shows the notification indicator and center entry point.
[modules.audio_display]	enabled	true	Shows the Audio & Display popup anchor.
[modules.system_occupancy]	enabled	true	Shows the CPU and memory occupancy chip.

Global menu

Global menus remain opt-in while the companion protocol is maturing. Enable it to have Hyprbaric load the plugin carried in its Linux bundle before the bar starts reading focused applications:

config.toml

[global_menu]
enabled = true

Key	Values	Default	Effect
plugin_path	Absolute or relative shared-library path	Unset	Replaces the plugin bundled at lib/hyprbaric-appmenu.so; useful for a locally built companion.
repository	Git URL	Hyprbaric's repository	Where hyprpm builds the companion from when the bundled one no longer fits Hyprland.

Whether the menu appears is a module, not a key here:

[modules.global_menu]
enabled = true

It is the one module that is off by default. Failure to obtain the companion is reported on the Modules settings row and in the setup guide, but it does not stop the bar. Applications that export no menu still render the ordinary focused window title.

Which applications export a menu, and which ones still need Firefox prefs, a GTK module, or a Java agent, is covered in Global menu. The rest of this section is the configuration surface and what owning the registrar name does.

How the companion is obtained

The companion is a compositor plugin, compiled against Hyprland's internals, so it only loads into the version it was built for. Hyprbaric tries three sources in the order that costs least:

1. The bundled plugin, carried in the release at lib/hyprbaric-appmenu.so. Loading it needs no privileges, no toolchain and no network, and this is what almost every launch uses.
2. A local cmake rebuild, from data/hyprland-appmenu in the bundle or from the hyprland-appmenu tree a Flutter checkout already has. Output goes to the user cache. This is the answer to a compositor-library SONAME bump that leaves the bundled .so behind: relink against the installed hyprland.pc without hyprpm's privileged store.
3. hyprpm, Hyprland's own plugin manager, which rebuilds the companion from this repository's hyprpm.toml against the headers of the installed compositor. Hyprbaric falls back to it automatically, in the background, when the bundled plugin and the local rebuild both fail.

hyprpm keeps its store in /var/cache/hyprpm, which it creates with a privileged command on first use. A desktop session has no terminal to answer that prompt on, so Hyprbaric does not raise it behind your back. If every automatic path is exhausted before hyprpm has run at all, Modules settings asks you to run this once:

hyprpm add https://github.com/asaphaaning/hyprbaric

What enabling this changes in your applications

Enabling global menus moves menu bars out of application windows. Qt asks whether com.canonical.AppMenu.Registrar is owned on the session bus to decide whether the desktop displays its menus for it, so Hyprbaric owns that name while the feature is on. Qt applications started afterwards stop drawing their own menu bar and export it instead.

That is why the feature is opt-in and why both halves share one switch. Owning the name without rendering the menus would leave those applications with no menu bar at all. Turning the setting off and restarting Hyprbaric releases the name, and applications started after that draw their own menu bars again.

Applications already running when the setting changes keep whichever menu bar they started with, so restart them to see the change. Firefox, traditional GTK menubars, Swing, JetBrains on native Wayland, and apps without a menubar at all need extra steps or will never export; see Global menu.

Workspaces

The Workspaces tab manages all workspace-indicator settings.

config.toml

[workspaces]
indicator_style = "roman"
clickable = true
visible_range = "medium"

Key	Values	Default	Effect
indicator_style	"roman", "numeric"	"roman"	Renders workspace IDs as Roman numerals or digits.
clickable	Boolean	true	Allows direct clicks on an indicator to switch workspace. Previous/next controls stay available.
visible_range	"small" (5), "medium" (7), "large" (9)	"medium"	Number of workspace indicators kept visible around the active workspace.

Display: Night light and schedule

The Display tab manages night light and its local-time schedule. hyprsunset must be available for the filter to be applied.

config.toml

[night_light]
enabled = false
temperature = 3500

[schedules.night_light]
enabled = false
start_hour = 21
stop_hour = 7

Table	Key	Values	Default	Effect
[night_light]	enabled	Boolean	false	Restores the configured filter state at launch.
[night_light]	temperature	Non-zero Kelvin integer	3500	Color temperature passed to hyprsunset.
[schedules.night_light]	enabled	Boolean	false	Enables the daily time window.
[schedules.night_light]	start_hour	Integer 0..=23	21	Local hour at which the filter becomes active.
[schedules.night_light]	stop_hour	Integer 0..=23	7	Local hour at which the filter becomes inactive.

The start hour is included and the stop hour is excluded. A window that crosses midnight works normally (21 to 7), and equal start and stop hours mean all day.

The filter is applied at the hour boundary itself rather than on a polling delay. If applying it fails, for example because hyprsunset is not running yet, hyprbaric retries within five minutes. A disabled schedule costs nothing at runtime.

Runtime policy

These tables are TOML-only. Audio uses a bounded percentage step; polling and command policies use non-zero, human-readable durations such as "300ms", "1s", or "60s". Every key except ddc_discovery_interval has a default, so omitting it keeps that default.

config.toml

[audio]
volume_step = 5

[network]
traffic_refresh_interval = "1s"
full_refresh_interval = "8s"

[brightness]
backlight_refresh_interval = "1s"
ddc_discovery_delay = "1s"
# Optional. Omitted, DDC discovery runs once and is never repeated.
# ddc_discovery_interval = "15m"
ddc_write_debounce = "300ms"
ddc_command_timeout = "1200ms"
write_timeout = "5s"

[power]
refresh_interval = "15s"

[system]
refresh_interval = "1s"

Table	Key	Default	Effect
[audio]	volume_step	5	Percentage points added or removed by volume-up/down shortcuts. Values outside 0..=100 are clamped.
[network]	traffic_refresh_interval	"1s"	Refreshes inexpensive /proc/net/dev traffic counters.
[network]	full_refresh_interval	"8s"	Refreshes NetworkManager state, access points, and interfaces, and measures latency.
[brightness]	backlight_refresh_interval	"1s"	Polls Linux backlight devices.
[brightness]	ddc_discovery_delay	"1s"	Waits after startup before the first DDC monitor scan.
[brightness]	ddc_discovery_interval	Unset	Repeats DDC monitor discovery. Left unset, discovery runs once after ddc_discovery_delay and never again. Set it only if you hot-plug displays.
[brightness]	ddc_write_debounce	"300ms"	Coalesces rapid DDC brightness changes into at most one write per window. A change that arrives mid-window replaces the pending value without extending the deadline.
[brightness]	ddc_command_timeout	"1200ms"	Bounds one DDC command before it is treated as failed.
[brightness]	write_timeout	"5s"	Backstop for a brightness write that never returns. Without it a stalled backend would silently swallow every later change for that display.
[power]	refresh_interval	"15s"	Refreshes UPower battery and power-profiles-daemon status.
[system]	refresh_interval	"1s"	Refreshes CPU, memory, disk, uptime, temperature, and process occupancy.

The latency reading in the network panel is a TCP connection to 1.1.1.1:53 with a 350 ms timeout, made once per full_refresh_interval. It is not currently configurable, so raise full_refresh_interval if you want it to happen less often.

Shortcuts

Each built-in action has one nested table inside [shortcuts]. The Keybinds tab edits these mappings interactively, and TOML can also choose a binding or disable it.

config.toml

[shortcuts.controls]
modifiers = ["logo", "shift"]
key = "O"
phase = "press"

[shortcuts.toggle_caffeine]
state = "disabled"

Binding key	Values	Default	Notes
modifiers	Array of "logo", "ctrl", "shift", "alt", "num"	Action-specific	"super"/"meta" alias "logo". "control" aliases "ctrl".
key	Non-empty key name without ,, +, <, or >	Action-specific	Ordinary keys are uppercased. PrintScreen becomes Print. XF86… names retain their spelling.
phase	"press", "release"	"press"	Controls whether activation happens on key press or release.
state	"disabled"	Bound	The only explicit mapping state. It skips portal registration and Hyprland bind reconciliation.

The full list of all 18 actions, default chords, phases, behavior, and TOML table names is on Shortcuts. The Keybinds tab’s Record, Disable, and Reset buttons write exactly the keys above.

Validation

Every value is checked while the file loads, not when it is first used. The table below is the complete set of constraints. Anything not listed here accepts any value of its type.

Enumerations

Spelling is exact and lowercase. A value outside the accepted set is rejected.

Keys	Accepted	Rejected
position	"top", "bottom"	"left", "Top"
indicator_style	"roman", "numeric"	"arabic", "Roman"
visible_range	"small", "medium", "large"	"7", "huge"
phase	"press", "release"	"hold"
state	"disabled"	"enabled", "off"
modifiers entries	"logo", "ctrl", "shift", "alt", "num"	"cmd", "win"

modifiers also accepts "super" and "meta" for "logo", and "control" for "ctrl".

Bounded integers

Bounds are inclusive on both ends.

audio.volume_step is the exception to rejection: values below 0 become 0, and values above 100 become 100.

Keys	Accepted	Rejected
opacity	20 to 100	0, 19, 101
corner_radius	0 to 32	33, -1
accent_hue	0 to 359	360, -1
start_hour, stop_hour	0 to 23	24
temperature	Any integer above 0	0

rejected

[appearance]
opacity = 15        # below the 20 floor
accent_hue = 360    # hue wraps at 359

[schedules.night_light]
start_hour = 24     # hours are 0..=23

Durations

The runtime-policy duration keys take a human-readable duration string. Zero is rejected in every case, because each one drives a timer that must advance.

Accepted	Rejected
"300ms", "1s", "2m", "1s 500ms"	"0s", "0", 1 (a bare integer, not a string), "soon"

rejected

[network]
traffic_refresh_interval = "0s"   # a cadence cannot be zero
full_refresh_interval = 8         # must be a quoted duration, not a number

Shortcut keys

Rule	Accepted	Rejected
Non-empty after trimming	"S", "F12", "Print", "XF86AudioMute"	"", " "
No bind separators	as above	"Super+S", "A,B", "<S>"

A chord is expressed as modifiers plus a single key, so writing the whole chord into key is the common mistake. Ordinary key names are uppercased on load, PrintScreen normalizes to Print, and XF86… names keep their exact spelling.

What a failure does

A file that parses as TOML but fails any check above stops startup. The failing path is logged, and hyprbaric does not fall back to defaults for a file it found but could not read, so check the log when a change appears to have been ignored. An unknown table or key is the one exception: it is ignored rather than rejected.

Not configurable in TOML

For completeness, these are deliberately outside the configuration file:

Behavior	Where it lives instead
Do-not-disturb, caffeine, active recording	Session-only runtime state, reset when hyprbaric restarts.
Volume, mute, brightness levels	PipeWire and the kernel backlight or DDC display.
Wi-Fi credentials and connection profiles	NetworkManager.
Screenshot and recording destinations	XDG user directories. See Environment and files.
Log verbosity and format	RUST_LOG, HYPRBARIC_LOG, RUST_LOG_STYLE.
Terminal used for terminal desktop entries	$TERMINAL, with a built-in fallback list.
Click-to-focus for the global menu	Hyprland follow_mouse and float_switch_override_focus. See Click to focus.
Classic GTK menubars on the global menu	Hyprland GTK_MODULES and UBUNTU_MENUPROXY. See GTK AppMenu module.
Swing menubars on the global menu	Per-JVM JAyatana agent on X11. See Java / JAyatana.
Which features are available at all	Installed backends. See Dependencies and capabilities.