Configuration Guide

Location: ~/.config/dumber/config.toml Formats: TOML (recommended), JSON, YAML

Database

History

Search Configuration

Example:

# Default search engine - used when no shortcut is specified
default_search_engine = "https://duckduckgo.com/?q=%s"

# Alternative search engines:
# default_search_engine = "https://www.google.com/search?q=%s"
# default_search_engine = "https://www.startpage.com/search?q=%s"
# default_search_engine = "https://search.brave.com/search?q=%s"

Default shortcuts (usage: !shortcut query):

# Examples:
#   !ddg golang      → DuckDuckGo search for "golang"
#   !g rust tutorial → Google search for "rust tutorial"
#   !gi cats         → Google Images search for "cats"
#   !gh opencode     → GitHub search for "opencode"
#   !yt music video  → YouTube search for "music video"

[search_shortcuts.ddg]
url = "https://duckduckgo.com/?q=%s"
description = "DuckDuckGo search"

[search_shortcuts.g]
url = "https://google.com/search?q=%s"
description = "Google Search"

[search_shortcuts.gi]
url = "https://google.com/search?tbm=isch&q=%s"
description = "Google Images"

[search_shortcuts.gh]
url = "https://github.com/search?q=%s"
description = "GitHub"

[search_shortcuts.yt]
url = "https://youtube.com/results?search_query=%s"
description = "YouTube"

Dmenu / Launcher

These settings control the dumber dmenu CLI command for rofi/fuzzel integration.

CLI Usage:

# Pipe mode (default) - outputs history for rofi/fuzzel with favicons
dumber dmenu | rofi -dmenu -show-icons -p "Browse: " | dumber dmenu --select
dumber dmenu | fuzzel --dmenu -p "Browse: " | dumber dmenu --select

# Interactive TUI mode
dumber dmenu --interactive

# Override history days via CLI flag (show last 7 days)
dumber dmenu --days 7

# Sort by most visited instead of recency
dumber dmenu --most-visited

# Combined: most visited from last 14 days
dumber dmenu --days 14 --most-visited

Omnibox

Example:

[omnibox]
initial_behavior = "recent"  # Show recent history when omnibox opens
most_visited_days = 30        # Days of history used for most_visited
auto_open_on_new_pane = false

# Alternative options:
# initial_behavior = "most_visited"  # Show most visited sites
# initial_behavior = "none"          # Show no initial suggestions

Logging

Appearance

Color Palettes

Light palette:

[appearance.light_palette]
background = "#fafafa"
surface = "#f4f4f5"
surface_variant = "#e4e4e7"
text = "#18181b"
muted = "#71717a"
accent = "#22c55e"
border = "#d4d4d8"

Dark palette:

[appearance.dark_palette]
background = "#0a0a0b"
surface = "#18181b"
surface_variant = "#27272a"
text = "#fafafa"
muted = "#a1a1aa"
accent = "#4ade80"
border = "#3f3f46"

External Theme: Noctalia

Dumber can integrate with Noctalia by reading the native Noctalia palette file directly. No user template is required for the default integration.

[appearance.external_theme]
enabled = true
provider = "noctalia"
format = "colors-json" # default
# Optional. Defaults to $XDG_CONFIG_HOME/noctalia/colors.json.
path = "~/.config/noctalia/colors.json"

The external file overrides palette colors only. Fonts, UI scale, pane-mode colors, and other appearance settings still come from Dumber config.

colors-json contract

colors-json reads Noctalia's active colors.json palette. Example file: docs/examples/noctalia-colors.json.

Dumber maps Noctalia roles like this:

Every mapped value must be a CSS-safe 6-digit hex color such as #aabbcc.

mShadow and mHover are optional nuance roles. When present, they are validated and used to preserve Dumber's background/surface/input contrast.

Because Noctalia's native file contains the active palette only, Dumber applies that mapped palette to both resolved light and dark palettes so the app follows the file immediately.

Advanced: dumber-json user template

dumber-json remains supported for an explicit Dumber-specific Noctalia user template:

[appearance.external_theme]
enabled = true
provider = "noctalia"
format = "dumber-json"
# Optional for dumber-json. Defaults to $XDG_CONFIG_HOME/dumber/noctalia-theme.json.
path = "~/.config/dumber/noctalia-theme.json"

The file must be JSON with root light and dark objects. Optional source, name, and mode metadata fields are accepted; name or source is used only as source metadata. Dumber chooses the active palette from appearance.color_scheme and the system color-scheme preference.

Supported palette fields are:

• background
• surface
• surface_variant
• text
• muted
• accent
• border

Each non-empty palette value must be a CSS-safe 6-digit hex color such as #AABBCC. Empty or omitted palette fields inherit from the configured Dumber palette for that mode.

Example rendered file: docs/examples/noctalia-dumber-theme.json. Example template: docs/examples/noctalia-dumber-theme.template.json.

When Noctalia rewrites the watched file, Dumber reapplies the same resolved theme path used by config reloads. A malformed or temporarily missing file keeps the last valid external palette when one exists; disabling appearance.external_theme.enabled clears that last-good external palette and returns to Dumber's configured palettes.

Debug Options

Privacy

Rendering, UI Scale & Zoom

CEF is the default browser engine. WebKitGTK remains available as a fallback via engine.type = "webkit"; engine.webkit.* settings only affect that fallback engine.

engine.cef.input.scroll_precise_multiplier controls touchpad/high-resolution wheel scroll speed, and engine.cef.input.scroll_vertical_multiplier applies an additional vertical-only scale. engine.cef.input.touchpad_navigation_max_vertical_ratio only filters horizontal back/forward swipe recognition; it does not tune vertical scroll speed.

engine.cef.input.touchpad_navigation_min_delta uses raw GTK touchpad surface units for back/forward gestures. The default 320.0 matches WebKit-style commit distance to reduce accidental navigation; raise or lower it in config.toml to tune gesture sensitivity.

Legacy key migration

Existing configs using older keys are migrated to the current engine shape. New configs should use the canonical keys above.

Workspace Configuration

General

Example:

[workspace]
new_pane_url = "dumb://history"

Pane Mode

Default pane mode actions:

[workspace.pane_mode.actions]
split-right = ["arrowright", "r"]
split-left = ["arrowleft", "l"]
split-up = ["arrowup", "u"]
split-down = ["arrowdown", "d"]
stack-pane = ["s"]
close-pane = ["x"]
move-pane-to-tab = ["m"]
move-pane-to-next-tab = ["M", "shift+m"]
eject-pane-to-window = ["w"]

# Consume-or-expel (niri-style) - very alpha
consume-or-expel-left = ["["]
consume-or-expel-right = ["]"]
consume-or-expel-up = ["{"]
consume-or-expel-down = ["}"]

focus-right = ["shift+arrowright", "shift+l"]
focus-left = ["shift+arrowleft", "shift+h"]
focus-up = ["shift+arrowup", "shift+k"]
focus-down = ["shift+arrowdown", "shift+j"]
confirm = ["enter"]
cancel = ["escape"]

Note: Actions are inverted to key→action map in memory for O(1) lookup performance during navigation.

Tab Mode

Default tab mode actions:

[workspace.tab_mode.actions]
new-tab = ["n", "c"]
close-tab = ["x"]
next-tab = ["l", "tab"]
previous-tab = ["h", "shift+tab"]
rename-tab = ["r"]
confirm = ["enter"]
cancel = ["escape"]

Note: Actions are inverted to key→action map in memory for O(1) lookup performance during navigation.

Vim Mode

Default vim mode actions:

[workspace.vim_mode.actions.vim-scroll-left]
keys = ["h"]
desc = "Scroll page left"

[workspace.vim_mode.actions.vim-scroll-down]
keys = ["j"]
desc = "Scroll page down"

[workspace.vim_mode.actions.vim-scroll-up]
keys = ["k"]
desc = "Scroll page up"

[workspace.vim_mode.actions.vim-scroll-right]
keys = ["l"]
desc = "Scroll page right"

[workspace.vim_mode.actions.vim-scroll-down-fast]
keys = ["shift+j"]
desc = "Scroll page down fast"

[workspace.vim_mode.actions.vim-scroll-up-fast]
keys = ["shift+k"]
desc = "Scroll page up fast"

[workspace.vim_mode.actions.focus-input]
keys = ["gi"]
desc = "Focus next page input"

[workspace.vim_mode.actions.heading-next]
keys = ["]]"]
desc = "Jump to next heading"

[workspace.vim_mode.actions.heading-prev]
keys = ["[["]
desc = "Jump to previous heading"

[workspace.vim_mode.actions.confirm]
keys = ["enter"]
desc = "Confirm action"

[workspace.vim_mode.actions.cancel]
keys = ["escape"]
desc = "Cancel/exit mode"

Notes:

• Vim Mode scrolls and navigates the active webpage inside the active pane only.
• gi focuses the next visible editable page input, starting at the first when no input is active and wrapping after the last.
• ]] and [[ move through visible h1–h6 headings and use the current Dumber theme accent for the selected-heading outline.
• The default timeout_ms = 0 means Vim Mode stays active until you exit it or focus moves into an editable/browser UI context. Ctrl+Y can still activate it when a page input is already focused.
• Arrow keys still use the browser engine's native page-navigation path while Vim Mode is active.
• Tab and Shift+Tab keep focus traversal inside the page while a page input is focused.
• Live input, heading, and page-focus navigation currently use the CEF engine path; WebKit fallback supports the Vim scroll commands while equivalent semantic navigation is pending.
• Other app-level shortcuts stay suspended until Vim Mode exits, except for the Vim Mode toggle itself.
• workspace.styling.pane_mode_color, workspace.styling.transition_duration, and workspace.styling.mode_indicator_toaster_enabled control the pane-local Vim Mode visuals.
• Scroll execution: CEF and WebKit both use the shared BuildPageScrollByJS resolver when the page is ready. Each step starts under the viewport center, walks up through ancestors that can move in the requested direction, and hands scrolling to the document when a nested container reaches its boundary. The application repeater owns held-key cadence; each engine executes one immediate scroll step per tick. Cross-origin frame contents remain best-effort. CEF may use native precision-wheel input only as a pre-frame fallback before the browser/main frame is ready.

Resize Mode

Default resize mode actions:

[workspace.resize_mode.actions]
resize-increase-left = ["h", "arrowleft"]
resize-increase-down = ["j", "arrowdown"]
resize-increase-up = ["k", "arrowup"]
resize-increase-right = ["l", "arrowright"]
resize-decrease-left = ["H"]
resize-decrease-down = ["J"]
resize-decrease-up = ["K"]
resize-decrease-right = ["L"]
resize-increase = ["+", "="]
resize-decrease = ["-"]
confirm = ["enter"]
cancel = ["escape"]

Notes:

• Directional actions (resize-increase-*/resize-decrease-*) move the split divider.
• Smart actions (resize-increase / resize-decrease) grow/shrink the active pane (best-effort) by picking a direction automatically.
• Timeout is refreshed on each resize keypress so you can keep adjusting without re-entering the mode.

Global Shortcuts

Global shortcuts are configured under workspace.shortcuts.actions using the same ActionBinding structure as modal keybindings:

Example:

[workspace.shortcuts.actions.close_pane]
  keys = ["ctrl+w"]
  desc = "Close active pane"

[workspace.shortcuts.actions.next_tab]
  keys = ["ctrl+tab", "alt+l"]
  desc = "Switch to next tab"

[workspace.shortcuts.actions.toggle_floating_pane]
  keys = ["alt+f"]
  desc = "Toggle floating pane"

Tip: Use dumb://config → Keybindings tab to edit shortcuts visually.

Note: New tab creation uses modal tab mode (Ctrl+T then n/c). This follows the Zellij-style modal keyboard interface.

Note: Consume-or-expel is experimental and may change behavior between releases.

Warning: Some Alt+<key> shortcuts may conflict with WebKit defaults, website handlers, or your desktop environment. If a binding does not fire, rebind it to a different key.

Floating Pane

The floating workspace pane is a persistent overlay session: hiding it does not destroy its web content.

• Default behavior includes exactly one floating shortcut: Alt+F (toggle_floating_pane).
• URL shortcuts (for example Alt+G) are user-defined via workspace.floating_pane.profiles and are empty by default.
• Alt+F toggles visibility only and preserves floating state.
• Ctrl+W on an active floating pane closes and releases that floating session for a fresh next open.
• Floating profile keybindings support modifier combos with ctrl, shift, and alt (for example ctrl+shift+y or ctrl+alt+m).

Example:

[workspace.shortcuts.actions.toggle_floating_pane]
keys = ["alt+f"]
desc = "Toggle floating pane"

[workspace.floating_pane]
width_pct = 0.82
height_pct = 0.72

[workspace.floating_pane.profiles]
# Empty by default. Add as many entries as needed.

[workspace.floating_pane.profiles.google]
keys = ["alt+g"]
url = "https://google.com"
desc = "Open floating pane on Google"

[workspace.floating_pane.profiles.github]
keys = ["alt+h"]
url = "https://github.com"
desc = "Open floating pane on GitHub"

Browsing Context Behavior

Workspace Styling

Example:

[workspace.styling]
border_width = 1
border_color = "@theme_selected_bg_color"
mode_border_width = 4
pane_mode_color = "#4A90E2"      # Blue for pane mode and Vim mode local accent
tab_mode_color = "#FFA500"       # Orange for tab mode
session_mode_color = "#9B59B6"   # Purple for session mode
resize_mode_color = "#00D4AA"    # Teal for resize mode
mode_indicator_toaster_enabled = true
transition_duration = 120

Session

Session Mode

Default session mode actions:

[session.session_mode.actions]
session-manager = ["s", "w"]
confirm = ["enter"]
cancel = ["escape"]

Example:

[session]
auto_restore = false              # Don't auto-restore on startup
snapshot_interval_ms = 5000       # Save state every 5 seconds (debounced)
max_exited_sessions = 50          # Keep last 50 exited sessions
max_exited_session_age_days = 7   # Delete sessions older than 7 days on startup

Media

WebKit fallback GStreamer tuning is configured under engine.webkit.force_vsync, engine.webkit.gl_rendering_mode, and engine.webkit.gstreamer_debug_level.

Hardware decoding modes:

• auto (recommended): Hardware preferred with software fallback - fixes Twitch Error #4000
• force: Hardware only - fails if unavailable
• disable: Software only - higher CPU usage

GPU auto-detection: Dumber automatically detects your GPU vendor (AMD/Intel/NVIDIA) and sets optimal VA-API driver settings:

• AMD: Uses radeonsi driver
• Intel: Uses iHD driver (modern, for Broadwell+)
• NVIDIA: Uses nvidia driver with EGL platform

Example:

[media]
hardware_decoding = "auto"    # HW preferred, SW fallback
prefer_av1 = false            # Let site choose codec
show_diagnostics = false      # Keep off for daily use

WebKit fallback GStreamer diagnostics:

[engine.webkit]
gstreamer_debug_level = 3

Set media.show_diagnostics = false and engine.webkit.gstreamer_debug_level = 0 to return to normal mode.

Diagnostics CLI:

# Check GStreamer plugins and VA-API status
dumber doctor --media

Runtime

engine.cef.cef_dir overrides CEF runtime discovery. For the WebKitGTK fallback, engine.webkit.prefix prepends prefix-derived paths to:

• PKG_CONFIG_PATH (for version checks)
• LD_LIBRARY_PATH (for runtime library loading)
• GI_TYPELIB_PATH (GObject introspection)
• XDG_DATA_DIRS (schemas/resources)

Example:

[engine.cef]
cef_dir = "/opt/cef"

[engine.webkit]
prefix = "/opt/webkitgtk"

Clipboard

When enabled, selecting text in a web page immediately copies it to the clipboard with a brief toast notification. Does not apply to text selection in input fields or textareas.

Example:

[clipboard]
auto_copy_on_selection = true  # Enabled by default

Content Filtering

Notes:

• Filter data is downloaded from bnema/ublock-webkit-filters GitHub releases.
• Domain whitelist is managed via the database (content_whitelist table), not the config file.

Update

Example:

[update]
enable_on_startup = true       # Check for updates on startup
auto_download = false          # Don't auto-download (prompt instead)
notify_on_new_settings = true  # Show toast when config migration available

CLI Commands:

# Check config status and available migrations
dumber config status

# Add missing settings with default values
dumber config migrate

# Skip confirmation prompt
dumber config migrate --yes

Performance Profiles

Performance profiles tune engine resource behavior. CEF is the default engine; the engine.webkit.* custom fields below apply only when using the WebKitGTK fallback.

Note: Performance settings are applied at browser startup. Changes require a restart to take effect.

Profiles

Example:

[engine]
profile = "default"
pool_prewarm_count = 4
zoom_cache_size = 256

WebKit fallback custom profile settings

When engine.profile = "custom" and engine.type = "webkit", you can configure individual WebKit tuning options:

Custom WebKit fallback example:

[engine]
type = "webkit"
profile = "custom"
pool_prewarm_count = 6
zoom_cache_size = 256

[engine.webkit]
skia_cpu_painting_threads = 4
skia_gpu_painting_threads = 2
web_process_memory_limit_mb = 1024
web_process_memory_conservative_threshold = 0.4
web_process_memory_strict_threshold = 0.6

Important: Individual engine.webkit.* tuning fields are ignored unless engine.profile = "custom".

Downloads

Downloads are saved to the configured directory with toast notifications for download started, completed, and failed events.

Example:

[downloads]
path = ""  # Use system default ($XDG_DOWNLOAD_DIR or ~/Downloads)

# Or specify a custom directory:
# path = "/home/user/my-downloads"

Environment Variables

All config values can be overridden via environment variables with the prefix DUMBER_:

# Database
DUMBER_DATABASE_PATH=/custom/path/db.sqlite

# Engine/rendering (examples)
DUMBER_ENGINE_TYPE=cef
# CEF defaults to the GPU-first Vulkan DMABUF stack.
# Use EGL/OpenGL for driver compatibility:
# DUMBER_ENGINE_CEF_RENDER_STACK=egl
# WebKit fallback rendering overrides:
# DUMBER_ENGINE_WEBKIT_DISABLE_DMABUF_RENDERER=true
# DUMBER_ENGINE_WEBKIT_GSK_RENDERER=opengl
DUMBER_DEFAULT_WEBPAGE_ZOOM=1.5

# Logging
DUMBER_LOG_LEVEL=debug
DUMBER_LOG_FORMAT=json