Configuration

bmux is configured via a bmux.toml file. If no config file exists, bmux uses sensible defaults for all options.

Config File Location

bmux resolves bmux.toml from the configured config directory candidate chain. Use the path/env override table below to pin exact locations.

Path & Env Overrides

VariableScopeBehavior
BMUX_CONFIGconfigMerges an additional config file after discovered config (lower precedence than –config).
BMUX_CONFIG_DIRconfigOverrides the config directory root and disables fallback candidate chaining.
BMUX_RUNTIME_DIRruntimeOverrides the runtime root used for sockets and temp runtime artifacts.
BMUX_RUNTIME_NAMEruntimeSelects the runtime instance name; non-default values use runtime subdirectories.
BMUX_DATA_DIRdataOverrides the persistent data directory (plugins and runtime identity files).
BMUX_STATE_DIRstateOverrides the persistent state directory (recordings, traces, and runtime layout state); when BMUX_LOG_DIR is unset, logs default to $BMUX_STATE_DIR/logs.
BMUX_LOG_DIRlogsOverrides the log directory used by bmux file logging.
BMUX_RECORDINGS_DIRrecordingsOverrides recording storage root for recording CLI/runtime resolution.
BMUX_SLOT_NAMEslotForces the active bmux slot. Overrides argv[0] parsing. When unset, the binary’s basename (bmux-) is used.
BMUX_SLOTS_MANIFESTslotPath to the slot manifest (slots.toml). - means read from stdin. Defaults to <config_dir>/slots.toml.
BMUX_SLOTS_ROOTslotRoot directory under which per-slot default dirs are materialized. Defaults to the platform data dir.
BMUX_SLOTS_BIN_DIRslotDirectory containing the bmux- binaries. Defaults to ~/.local/bin.
BMUX_NO_BASE_CONFIGconfigWhen set to a truthy value, disables merging the shared ~/.config/bmux/base.toml layer for this invocation.
BMUX_MANIFEST_READ_ONLY_PREFIXESslotColon-separated path prefixes that, when a manifest file lives under one of them, make write-side helpers refuse to modify the file.

[general]

Core session defaults: shell, scrollback depth, and server connection settings
OptionTypeDefaultDescription
default_modestringNORMALDefault interaction mode when starting bmux Valid values: normal, insert, visual, command.
mouse_supportbooltrueEnable mouse support for clicking to focus panes, scrolling through output, and dragging to resize pane borders
default_shellstring (optional)—Default shell to launch in new panes. When unset, uses the SHELL environment variable or falls back to /bin/sh.
scrollback_limitinteger10000Maximum number of scrollback lines retained per pane. Must be at least 1.
server_timeoutinteger5000Server socket timeout in milliseconds. Must be at least 1.

[appearance]

Visual styling: pane borders, status bar placement, and window titles
OptionTypeDefaultDescription
status_positionstringBOTTOMWhere to render the status bar. TOP places it above panes, BOTTOM below panes, and OFF hides it entirely. Valid values: TOP, BOTTOM, OFF.
pane_border_stylestringSINGLEDrawing style for pane borders. NONE hides borders entirely, giving panes the full terminal width. Valid values: SINGLE, DOUBLE, ROUNDED, THICK, NONE.
show_pane_titlesboolfalseDisplay a title label in each pane’s border showing the running process name
window_title_formatstring``Format string for the outer terminal’s title bar. Empty string leaves the title unset.

[behavior]

Runtime behavior toggles for terminal protocol handling, layout persistence, and build compatibility
OptionTypeDefaultDescription
aggressive_resizeboolfalseImmediately resize panes to the largest remaining client when a client disconnects, rather than keeping the previous dimensions
visual_activityboolfalseHighlight panes in the status bar when they produce output while unfocused, so you can tell which panes have new activity
bell_actionstringANYHow to handle terminal bell signals from panes. NONE ignores bells entirely. ANY notifies on bells from any pane. CURRENT only notifies from the focused pane. OTHER only notifies from unfocused panes. Valid values: NONE, ANY, CURRENT, OTHER.
automatic_renameboolfalseAutomatically rename windows based on the currently running command in the focused pane
exit_emptyboolfalseExit bmux when no sessions remain
restore_last_layoutbooltrueRestore and persist the last local CLI runtime layout across sessions, so reattaching resumes where you left off
confirm_quit_destroybooltruePrompt for confirmation before a destructive quit that clears persisted local runtime state
pane_termstringbmux-256colorTerminal type exposed to pane processes via the TERM environment variable. Common values: bmux-256color, xterm-256color, screen-256color.
pane_shell_integrationbooltrueEnable per-shell runtime integration hooks that emit verbatim pane command and prompt metadata for resurrection. When disabled, bmux does not inject shell wrapper config/rc files and falls back to best-effort process inspection for command/cwd restore.
protocol_trace_enabledboolfalseEnable protocol query/reply tracing in the runtime. Useful for debugging terminal protocol behavior with CSI/OSC/DCS sequences.
protocol_trace_capacityinteger200Maximum number of in-memory protocol trace events to retain. Must be at least 1.
terminfo_auto_installstringneverWhat to do when the bmux terminfo entry is missing from the system. ask prompts before installing. always installs silently. never skips installation, which may degrade terminal rendering. Valid values: ask, always, never.
terminfo_prompt_cooldown_daysinteger7Number of days to wait before prompting again after the user declines terminfo installation
stale_build_actionstringignoreWhat to do when the running server was built from a different version than the current CLI binary. ignore skips stale-build checks. warn connects with a warning message. error refuses to connect until the server is restarted. Valid values: ignore, warn, error.
kitty_keyboardbooltrueEnable the Kitty keyboard protocol for enhanced key reporting. When true, bmux negotiates enhanced keyboard mode with the outer terminal, allowing modified special keys like Ctrl+Enter to be correctly forwarded to pane programs.
pane_restore_methodstringsnapshotHow to restore pane content when hidden panes become visible again (e.g. after exiting zoom). SNAPSHOT re-fetches from the server for guaranteed accuracy. RETAIN keeps parsers in memory for instant restore. Valid values: snapshot, retain.
mouse.enabledbooltrueMaster toggle for mouse handling in attach mode.
mouse.focus_on_clickbooltrueFocus pane when clicking inside it.
mouse.click_propagationstringfocus_and_forwardHow pane-area mouse clicks are routed between bmux and pane TUIs. Valid values: focus_only, forward_only, focus_and_forward.
mouse.focus_on_hoverboolfalseFocus pane when hovering over it.
mouse.hover_delay_msinteger0Hover dwell time before focus is applied.
mouse.scroll_scrollbackbooltrueRoute wheel scrolling to focused pane scrollback.
mouse.wheel_propagationstringautoHow wheel events are routed between pane TUIs and bmux scrollback. Valid values: auto, forward_only, scrollback_only, forward_and_scrollback.
mouse.scroll_lines_per_tickinteger3Number of scrollback lines per mouse wheel tick.
mouse.exit_scrollback_on_bottombooltrueExit scrollback mode automatically when wheel scrolling reaches bottom.
mouse.alternate_screen_wheelstringignoreHow wheel events behave in alternate-screen panes that have not requested mouse tracking. Valid values: ignore, forward_only, scrollback_only.
mouse.selection_releasestringselectWhat to do when a bmux-managed mouse selection drag is released. Valid values: select, copy, copy_and_exit.
mouse.resize_bordersbooltrueResize panes by dragging shared pane borders.
mouse.resize_drag_throttle_msinteger32Minimum interval in milliseconds between resize requests while dragging pane borders. Set to 0 to apply every drag event. Mouse release always applies the final position.
mouse.gesture_actionstable``Optional mouse gesture overrides mapped to action names. Supported keys in the current core runtime are click_left, hover_focus, scroll_up, and scroll_down. Values use the same action naming format as keybindings, including built-in action names and plugin:<id>:<command>.
damage.max_rectsinteger64Maximum damaged rectangles to track per surface before falling back to a full-surface repaint.
damage.max_area_percentinteger60Damaged cell-area percentage that triggers a full-surface repaint fallback. Must be 1 through 100.
damage.visualizeboolfalseDraw a colored debug overlay around regions repainted by attach damage tracking.
event_coalescing.max_events_per_frameinteger64Maximum ready server events to drain before rendering one attach frame.
images.enabledbooltrueMaster switch for Sixel, Kitty graphics, and iTerm2 inline image support. When false, image escape sequences are passed through to the host terminal without interception or registry tracking.
images.decode_modestringpassthroughHow image decoding is distributed between server and client. PASSTHROUGH forwards raw protocol bytes with coordinate translation (fastest, requires same protocol support on the host terminal). SERVER decodes images to pixel buffers on the server side. CLIENT sends raw bytes for the client to decode and re-encode. Valid values: server, client, passthrough.
images.max_image_bytesinteger10485760Maximum image payload size in bytes per image. Images exceeding this limit are silently discarded to prevent memory exhaustion.
images.max_images_per_paneinteger100Maximum number of images kept in the registry per pane. When this limit is reached, the oldest images are evicted (FIFO).
compression.enabledbooltrueMaster switch for all compression. When false, image payloads are sent uncompressed and remote connections are not wrapped in streaming compression.
compression.imagesstringautoCompress image payloads (Sixel, Kitty graphics, iTerm2) before IPC transport. Typical reduction: 5-15x for sixel text, 3-20x for kitty raw pixels. Pre-compressed formats (e.g. kitty PNG) are automatically detected and skipped. auto selects zstd when available. Valid values: none, auto, zstd, lz4.
compression.remotestringautoCompress remote connections (TLS gateway, Iroh P2P) with streaming compression. Local Unix socket connections are never compressed. Both the client and the server gateway must use the same setting; a mismatch will cause the connection to fail. If SSH is already compressing the tunnel, set this to none to avoid double work. Valid values: none, auto, zstd, lz4.
compression.levelinteger3Zstd compression level for image payloads (1-19, ignored for lz4). Level 1 is fastest (~500 MB/s), level 3 (default) balances speed and ratio, level 9+ gives diminishing returns. Remote streaming always uses level 1 internally for low latency regardless of this setting.

[multi_client]

Settings for multiple clients attached to the same session
OptionTypeDefaultDescription
allow_independent_viewsboolfalseAllow clients to have independent views of the same session, with separate focused panes and scroll positions
default_follow_modeboolfalseWhen true, new clients automatically track the leader client’s focused pane and scroll position. When false, clients start with an independent view.
max_clients_per_sessioninteger0Maximum number of clients that can attach to a single session. Set to 0 for unlimited.
sync_client_modesboolfalseWhen true, switching interaction modes (e.g. Normal to Insert) on one client applies to all attached clients in the same session

[keybindings]

Keyboard shortcuts organized by scope and interaction mode
OptionTypeDefaultDescription
initial_modestringnormalInitial interaction mode id. Mode ids are matched case-insensitively.
modestable[insert]<br>label = "INSERT"<br>passthrough = true<br><br>[insert.bindings]<br>"ctrl+a escape" = "enter_mode normal"<br><br>[normal]<br>label = "NORMAL"<br>passthrough = false<br><br>[normal.bindings]<br>'"' = "plugin:bmux.windows:split-pane --direction horizontal"<br>"%" = "plugin:bmux.windows:split-pane --direction vertical"<br>"(" = "plugin:bmux.windows:prev-window"<br>")" = "plugin:bmux.windows:next-window"<br>"?" = "show_help"<br>"[" = "enter_scroll_mode"<br>"]" = "exit_scroll_mode"<br>"^" = "plugin:bmux.windows:last-window"<br>arrow_down = "plugin:bmux.windows:focus-pane-in-direction --direction down"<br>arrow_left = "plugin:bmux.windows:focus-pane-in-direction --direction left"<br>arrow_right = "plugin:bmux.windows:focus-pane-in-direction --direction right"<br>arrow_up = "plugin:bmux.windows:focus-pane-in-direction --direction up"<br>c = "plugin:bmux.windows:new-window"<br>"ctrl+e" = "scroll_down_line"<br>"ctrl+y" = "scroll_up_line"<br>d = "detach"<br>g = "scroll_top"<br>h = "plugin:bmux.windows:focus-pane-in-direction --direction left"<br>i = "enter_mode insert"<br>j = "plugin:bmux.windows:focus-pane-in-direction --direction down"<br>k = "plugin:bmux.windows:focus-pane-in-direction --direction up"<br>l = "plugin:bmux.windows:focus-pane-in-direction --direction right"<br>minus = "plugin:bmux.windows:resize-pane --direction decrease"<br>o = "plugin:bmux.windows:focus-pane-in-direction --direction next"<br>page_down = "scroll_down_page"<br>page_up = "scroll_up_page"<br>plus = "plugin:bmux.windows:resize-pane --direction increase"<br>q = "quit"<br>r = "plugin:bmux.windows:restart-pane"<br>"shift+arrow_down" = "plugin:bmux.windows:resize-pane --direction down"<br>"shift+arrow_left" = "plugin:bmux.windows:resize-pane --direction left"<br>"shift+arrow_right" = "plugin:bmux.windows:resize-pane --direction right"<br>"shift+arrow_up" = "plugin:bmux.windows:resize-pane --direction up"<br>"shift+c" = "plugin:bmux.sessions:new-session"<br>"shift+g" = "scroll_bottom"<br>"shift+h" = "plugin:bmux.windows:resize-pane --direction left"<br>"shift+j" = "plugin:bmux.windows:resize-pane --direction down"<br>"shift+k" = "plugin:bmux.windows:resize-pane --direction up"<br>"shift+l" = "plugin:bmux.windows:resize-pane --direction right"<br>v = "begin_selection"<br>x = "plugin:bmux.windows:close-active-pane"<br>z = "plugin:bmux.windows:zoom-pane"First-class modal keymap definitions keyed by mode id.
prefixstringctrl+aPrefix key for runtime key chords (e.g. “ctrl+a”). All runtime bindings require pressing this key first. Legacy path only.
timeout_msinteger (optional)—Exact timeout in milliseconds for multi-stroke chord resolution. Takes precedence over timeout_profile. Valid range: 50-5000.
timeout_profilestring (optional)—Named timeout profile for multi-stroke chord resolution. Built-in profiles: fast (200ms), traditional (400ms), slow (800ms). Ignored when timeout_ms is set.
timeout_profilestable``Override values for built-in timeout profiles or define custom ones. Keys are profile names, values are timeout in milliseconds.
runtimetable'"' = "plugin:bmux.windows:split-pane --direction horizontal"<br>"%" = "plugin:bmux.windows:split-pane --direction vertical"<br>"(" = "plugin:bmux.windows:prev-window"<br>")" = "plugin:bmux.windows:next-window"<br>"?" = "show_help"<br>"[" = "enter_scroll_mode"<br>"]" = "exit_scroll_mode"<br>"^" = "plugin:bmux.windows:last-window"<br>arrow_down = "plugin:bmux.windows:focus-pane-in-direction --direction down"<br>arrow_left = "plugin:bmux.windows:focus-pane-in-direction --direction left"<br>arrow_right = "plugin:bmux.windows:focus-pane-in-direction --direction right"<br>arrow_up = "plugin:bmux.windows:focus-pane-in-direction --direction up"<br>"ctrl+e" = "scroll_down_line"<br>"ctrl+y" = "scroll_up_line"<br>d = "detach"<br>g = "scroll_top"<br>h = "plugin:bmux.windows:focus-pane-in-direction --direction left"<br>j = "plugin:bmux.windows:focus-pane-in-direction --direction down"<br>k = "plugin:bmux.windows:focus-pane-in-direction --direction up"<br>l = "plugin:bmux.windows:focus-pane-in-direction --direction right"<br>minus = "plugin:bmux.windows:resize-pane --direction decrease"<br>o = "plugin:bmux.windows:focus-pane-in-direction --direction next"<br>page_down = "scroll_down_page"<br>page_up = "scroll_up_page"<br>plus = "plugin:bmux.windows:resize-pane --direction increase"<br>q = "quit"<br>r = "plugin:bmux.windows:restart-pane"<br>"shift+arrow_down" = "plugin:bmux.windows:resize-pane --direction down"<br>"shift+arrow_left" = "plugin:bmux.windows:resize-pane --direction left"<br>"shift+arrow_right" = "plugin:bmux.windows:resize-pane --direction right"<br>"shift+arrow_up" = "plugin:bmux.windows:resize-pane --direction up"<br>"shift+c" = "plugin:bmux.sessions:new-session"<br>"shift+g" = "scroll_bottom"<br>"shift+h" = "plugin:bmux.windows:resize-pane --direction left"<br>"shift+j" = "plugin:bmux.windows:resize-pane --direction down"<br>"shift+k" = "plugin:bmux.windows:resize-pane --direction up"<br>"shift+l" = "plugin:bmux.windows:resize-pane --direction right"<br>v = "begin_selection"<br>x = "plugin:bmux.windows:close-active-pane"<br>z = "plugin:bmux.windows:zoom-pane"Key bindings triggered after pressing the prefix key. Maps key chords to runtime action names.
globaltable"alt+0" = "plugin:bmux.windows:goto-window 10"<br>"alt+1" = "plugin:bmux.windows:goto-window 1"<br>"alt+2" = "plugin:bmux.windows:goto-window 2"<br>"alt+3" = "plugin:bmux.windows:goto-window 3"<br>"alt+4" = "plugin:bmux.windows:goto-window 4"<br>"alt+5" = "plugin:bmux.windows:goto-window 5"<br>"alt+6" = "plugin:bmux.windows:goto-window 6"<br>"alt+7" = "plugin:bmux.windows:goto-window 7"<br>"alt+8" = "plugin:bmux.windows:goto-window 8"<br>"alt+9" = "plugin:bmux.windows:goto-window 9"<br>"alt+=" = "plugin:bmux.windows:resize-pane --direction increase"<br>"alt+down" = "plugin:bmux.windows:focus-pane-in-direction --direction down"<br>"alt+h" = "plugin:bmux.windows:focus-pane-in-direction --direction left"<br>"alt+j" = "plugin:bmux.windows:focus-pane-in-direction --direction down"<br>"alt+k" = "plugin:bmux.windows:focus-pane-in-direction --direction up"<br>"alt+left" = "plugin:bmux.windows:focus-pane-in-direction --direction left"<br>"alt+minus" = "plugin:bmux.windows:resize-pane --direction decrease"<br>"alt+n" = "plugin:bmux.windows:split-pane --direction horizontal"<br>"alt+plus" = "plugin:bmux.windows:resize-pane --direction increase"<br>"alt+right" = "plugin:bmux.windows:focus-pane-in-direction --direction right"<br>"alt+t" = "plugin:bmux.windows:focus-pane-in-direction --direction next"<br>"alt+up" = "plugin:bmux.windows:focus-pane-in-direction --direction up"<br>"ctrl+alt+t" = "plugin:bmux.theme:pick-theme"<br>"ctrl+h" = "plugin:bmux.windows:prev-window"<br>"ctrl+j" = "plugin:bmux.windows:prev-window"<br>"ctrl+k" = "plugin:bmux.windows:focus-pane-in-direction --direction prev"<br>"ctrl+l" = "plugin:bmux.windows:last-window"<br>"ctrl+left" = "plugin:bmux.windows:prev-window"<br>"ctrl+o" = "plugin:bmux.windows:last-window"<br>"ctrl+right" = "plugin:bmux.windows:next-window"<br>"ctrl+s" = "plugin:bmux.windows:next-window"<br>"ctrl+t" = "plugin:bmux.windows:focus-pane-in-direction --direction prev"Key bindings that trigger without the prefix key. Use sparingly to avoid conflicts with pane input.
scrolltablearrow_down = "move_cursor_down"<br>arrow_left = "move_cursor_left"<br>arrow_right = "move_cursor_right"<br>arrow_up = "move_cursor_up"<br>"ctrl+a ]" = "exit_scroll_mode"<br>"ctrl+b" = "scroll_up_page"<br>"ctrl+c" = "exit_scroll_mode"<br>"ctrl+e" = "scroll_down_line"<br>"ctrl+y" = "scroll_up_line"<br>enter = "confirm_scrollback"<br>escape = "exit_scroll_mode"<br>g = "scroll_top"<br>h = "move_cursor_left"<br>j = "move_cursor_down"<br>k = "move_cursor_up"<br>l = "move_cursor_right"<br>page_down = "scroll_down_page"<br>page_up = "scroll_up_page"<br>"shift+g" = "scroll_bottom"<br>v = "begin_selection"<br>y = "copy_scrollback"Key bindings active in scrollback/copy mode. No prefix required unless the chord explicitly includes it.

[plugins]

Plugin discovery, enablement, and per-plugin settings
OptionTypeDefaultDescription
enabledlist of strings``Plugin IDs to enable in addition to the bundled defaults. Bundled plugins like bmux.windows and bmux.permissions are enabled automatically without being listed here.
disabledlist of strings``Plugin IDs to explicitly disable, including bundled ones. Overrides both bundled defaults and the enabled list.
search_pathslist of paths``Additional directories to scan for plugin binaries beyond the default plugin search path. Supports ~, $VAR, and ${VAR} interpolation.
settingstable``Per-plugin settings keyed by plugin ID. Each plugin defines its own accepted keys and values.
native_service.initial_response_bytesinteger4096Initial response buffer size, in bytes, for native service calls.
native_service.max_response_bytesinteger67108864Maximum response buffer size, in bytes, for native service calls.
native_service.buffer_resize_attemptsinteger8Maximum number of buffer-too-small retries before failing the service call. Set to 0 to disable retries beyond the initial buffer.
routing.conflict_modestringfail_startupConflict behavior when multiple plugins claim overlapping command ownership. Valid values: fail_startup.
routing.required_namespaces.<index>.namespacestring``Namespace segment that must be owned by a plugin.
routing.required_namespaces.<index>.ownerstring (optional)—Optional owner plugin ID; when omitted, any plugin may own the namespace.
routing.required_paths.<index>.pathlist of strings``Command path that must be owned by a plugin.
routing.required_paths.<index>.ownerstring (optional)—Optional owner plugin ID; when omitted, any plugin may own the path.

[connections]

Local and remote connection target profiles
OptionTypeDefaultDescription
hosted_modestringp2pHosted mode strategy. p2p avoids control-plane dependencies by default. Valid values: p2p, control_plane.
default_targetstring (optional)—Default command target when --target is not passed.
control_plane_urlstring (optional)—Optional control-plane base URL for hosted auth/share resolution.
targets.<name>.transportstringlocalTransport backend for this target. Valid values: local, ssh, tls, iroh.
targets.<name>.hoststring (optional)—SSH host for transport = "ssh".
targets.<name>.userstring (optional)—SSH username override.
targets.<name>.portinteger (optional)—SSH port override.
targets.<name>.identity_filepath (optional)—Private key file path. Supports ~, $VAR, and ${VAR} interpolation.
targets.<name>.known_hosts_filepath (optional)—Known hosts file path. Supports ~, $VAR, and ${VAR} interpolation.
targets.<name>.ca_filepath (optional)—Optional CA certificate bundle used for TLS transport. Supports ~, $VAR, and ${VAR} interpolation.
targets.<name>.server_namestring (optional)—Optional TLS server name override (defaults to host).
targets.<name>.endpoint_idstring (optional)—Iroh endpoint id for hosted transport.
targets.<name>.relay_urlstring (optional)—Optional Iroh relay URL for hosted transport.
targets.<name>.iroh_ssh_authboolfalseRequire SSH auth handshake when connecting to this iroh target.
targets.<name>.strict_host_key_checkingbooltrueRequire strict host key checking.
targets.<name>.jumpstring (optional)—SSH jump host (ProxyJump) value.
targets.<name>.remote_bmux_pathstringbmuxRemote bmux executable path.
targets.<name>.connect_timeout_msinteger8000Connection timeout in milliseconds.
targets.<name>.server_start_modestringautoRemote server startup behavior. Valid values: auto, require_running.
targets.<name>.default_sessionstring (optional)—Default session name used by clients.
recent_targetslist of strings``Most recently used targets (newest first).
recent_sessionstable``Most recently used sessions per target (newest first).
share_linkstable``User-defined share links (bmux:// -> target reference)
tls_trust.modestringpromptTrust mode for TLS gateways without CA validation or a known pin. Valid values: prompt, require_known, trust_new.
tls_trust.known_gateways.<host:port>.fingerprint_sha256string``Pinned SHA-256 fingerprint of the gateway leaf certificate.
tls_trust.known_gateways.<host:port>.server_namestring (optional)—Expected TLS server name for display/auditing.
tls_trust.known_gateways.<host:port>.labelstring (optional)—Human-readable target label.
iroh_ssh_access.enabledboolfalseRequire SSH challenge authentication on iroh connections.
iroh_ssh_access.allowlist.<fingerprint>.public_keystring``Public key in OpenSSH one-line format.
iroh_ssh_access.allowlist.<fingerprint>.labelstring (optional)—Optional descriptive label (for display and management UX).
iroh_ssh_access.allowlist.<fingerprint>.added_at_unixinteger (optional)—Unix timestamp of when the key was added.

[clipboard]

Clipboard integration and remote sync behavior
OptionTypeDefaultDescription
remote_sync.enabledbooltrueEnable client-to-remote clipboard sync.
remote_sync.modestringfocus_lazySync trigger mode. Valid values: off, manual, focus_lazy, paste_lazy, eager.
remote_sync.textbooltrueSync text clipboard payloads.
remote_sync.imagesbooltrueSync PNG/image clipboard payloads.
remote_sync.max_text_bytesinteger1048576Maximum text clipboard bytes to sync.
remote_sync.max_image_bytesinteger10485760Maximum image clipboard bytes to sync.
remote_sync.max_total_bytesinteger10485760Maximum total clipboard payload bytes to sync.
remote_sync.min_interval_msinteger1000Minimum milliseconds between sync attempts per client process.
remote_sync.debounce_msinteger250Debounce milliseconds for focus/activity-triggered syncs.
remote_sync.idle_after_msinteger2000Idle milliseconds before first-input fallback triggers sync.
remote_sync.request_timeout_msinteger500Clipboard request timeout in milliseconds.

[status_bar]

Content and layout of the status bar displayed at the top or bottom of the terminal
OptionTypeDefaultDescription
enabledbooltrueEnable status bar rendering in attach UI.
presetstringtab_railHigh-level status bar visual preset. Valid values: tab_rail, minimal, classic.
layout.densitystringcozySpacing density for tabs and right modules. Valid values: compact, cozy.
layout.left_paddinginteger1Left padding before first tab.
layout.right_paddinginteger1Right padding after final segment.
layout.tab_gapinteger1Number of spaces between tabs.
layout.module_gapinteger1Number of spaces between right-side modules.
layout.overflow_stylestringarrowsOverflow indicator style when tabs are hidden. Valid values: count, arrows.
layout.align_activestringkeep_visibleBehavior used to keep the active tab visible. Valid values: keep_visible, focus_bias.
style.separator_setstringangled_segmentsSeparator character set for tabs and modules. Valid values: angled_segments, plain, ascii.
style.prefer_unicodebooltruePrefer Unicode separators when available.
style.force_asciiboolfalseForce ASCII separators even when Unicode is enabled.
style.dim_inactivebooltrueDim inactive tabs for stronger active emphasis.
style.bold_activebooltrueBold active tabs for stronger active emphasis.
style.underline_activeboolfalseUnderline active tabs.
colors.bar_bgstring (optional)—Bar background color (hex #RRGGBB).
colors.bar_fgstring (optional)—Bar foreground color (hex #RRGGBB).
colors.tab_active_bgstring (optional)—Active tab background color (hex #RRGGBB).
colors.tab_active_fgstring (optional)—Active tab foreground color (hex #RRGGBB).
colors.tab_inactive_bgstring (optional)—Inactive tab background color (hex #RRGGBB).
colors.tab_inactive_fgstring (optional)—Inactive tab foreground color (hex #RRGGBB).
colors.module_bgstring (optional)—Right-side module background color (hex #RRGGBB).
colors.module_fgstring (optional)—Right-side module foreground color (hex #RRGGBB).
colors.overflow_bgstring (optional)—Overflow marker background color (hex #RRGGBB).
colors.overflow_fgstring (optional)—Overflow marker foreground color (hex #RRGGBB).
max_tabsinteger12Maximum number of tabs shown in the tab strip before overflow is collapsed.
tab_label_max_widthinteger20Maximum display width for each tab label.
show_tab_indexbooltrueDisplay 1-based tab indexes before labels.
tab_scopestringall_contextsWhich context set to render as tabs. Valid values: all_contexts, session_contexts, mru.
tab_orderstringstableHow tab entries are ordered when rendered. Valid values: stable, mru.
show_session_nameboolfalseDisplay the active session name in the status bar.
show_context_nameboolfalseDisplay the current context label in the status bar.
show_modebooltrueDisplay the current interaction mode (Normal, Scroll, Help, etc.).
show_rolebooltrueDisplay the current attach role (write/read-only).
show_followbooltrueDisplay follow target details when following another client.
show_hintbooltrueDisplay runtime hints on the right side.
hint_policystringscroll_onlyHint visibility policy. Valid values: always, scroll_only, never.

Status Bar Preset Examples

Tab Rail (recommended)

[status_bar] enabled = true preset = "tab_rail" tab_scope = "all_contexts" tab_order = "stable" max_tabs = 14 tab_label_max_width = 22 show_tab_index = true show_mode = true show_role = true show_follow = true show_hint = true hint_policy = "scroll_only" [status_bar.layout] density = "cozy" left_padding = 1 right_padding = 1 tab_gap = 1 module_gap = 1 overflow_style = "arrows" align_active = "keep_visible" [status_bar.style] separator_set = "angled_segments" prefer_unicode = true force_ascii = false dim_inactive = true bold_active = true underline_active = false

Minimal

[status_bar] enabled = true preset = "minimal" tab_scope = "all_contexts" tab_order = "stable" show_tab_index = false show_follow = false show_hint = true hint_policy = "scroll_only" [status_bar.layout] density = "compact" tab_gap = 1 module_gap = 1 overflow_style = "count" align_active = "keep_visible" [status_bar.style] separator_set = "plain" prefer_unicode = false force_ascii = true dim_inactive = true bold_active = false underline_active = false

Status Color Override (partial)

[status_bar.colors] # Unset fields inherit from the runtime appearance defaults tab_active_bg = "#7aa2f7" tab_active_fg = "#1a1b26" tab_inactive_bg = "#2a2f45" module_bg = "#343a55"

[recording]

Session recording for terminal replay, debugging, and playbook generation
OptionTypeDefaultDescription
dirpath (optional)—Root directory for recording data. Supports ~, $VAR, and ${VAR} interpolation. Relative paths are resolved against the directory containing bmux.toml.
enabledbooltrueEnable hidden rolling recording by default when the server starts. Manual recordings (bmux recording start/stop) remain available even when this is false.
capture_inputbooltrueCapture pane input bytes (keystrokes sent to pane processes)
capture_outputbooltrueCapture pane output bytes (terminal output from pane processes)
capture_eventsbooltrueCapture lifecycle and server events (pane creation, resize, close, etc.)
rolling_capture_inputbool (optional)—Override rolling capture of pane input bytes. None falls back to recording.capture_input.
rolling_capture_outputbool (optional)—Override rolling capture of pane output bytes. None falls back to recording.capture_output.
rolling_capture_eventsbool (optional)—Override rolling capture of lifecycle/request/custom events. None falls back to recording.capture_events.
rolling_capture_protocol_repliesbool (optional)—Enable rolling capture of protocol reply bytes. None defaults to false.
rolling_capture_imagesbool (optional)—Enable rolling capture of extracted pane image payloads. None defaults to false.
rolling_event_kindslist of strings``Explicit rolling event-kind allowlist. When non-empty, this takes precedence over rolling capture category booleans. Valid values: pane_input_raw, pane_output_raw, protocol_reply_raw, pane_image, server_event, request_start, request_done, request_error, custom.
segment_mbinteger64Rotate recording segments at approximately this size in MB
retention_daysinteger30Retention period for completed recordings in days. Set to 0 to disable automatic pruning and keep recordings indefinitely.
rolling_window_secsinteger0Enable hidden always-on rolling capture and retain at most this many seconds of recent events. Set to 0 to disable rolling capture.
auto_exportboolfalseAutomatically export stopped/cut user-initiated recordings as GIF.
auto_export_dirpath (optional)—Directory for auto-exported GIFs. Supports ~, $VAR, and ${VAR} interpolation. Relative paths are resolved against the directory containing bmux.toml. When unset, GIFs are written next to the recording directory.
export.fpsinteger24Target frames per second default for GIF exports.
export.cursorstringautoCursor rendering default for recording export. Valid values: auto, on, off.
export.cursor_shapestringautoCursor shape default for recording export. Valid values: auto, block, bar, underline.
export.cursor_blinkstringautoCursor blink default for recording export. Valid values: auto, on, off.
export.cursor_blink_period_msinteger500Cursor blink period default for recording export.
export.cursor_colorstringautoCursor color default for recording export (auto or #RRGGBB).
export.cursor_profilestringautoCursor behavior profile default for recording export. Valid values: auto, ghostty, generic.
export.cursor_solid_after_activity_msinteger (optional)—Keep cursor solid after activity for this duration in milliseconds. None lets terminal profiles choose an emulator-specific default.
export.cursor_solid_after_input_msinteger (optional)—Keep cursor solid after input activity for this duration in milliseconds.
export.cursor_solid_after_output_msinteger (optional)—Keep cursor solid after output activity for this duration in milliseconds.
export.cursor_solid_after_cursor_msinteger (optional)—Keep cursor solid after cursor movement activity for this duration in milliseconds.
export.cursor_paint_modestringautoCursor paint mode default for recording export. Valid values: auto, invert, fill, outline.
export.cursor_text_modestringautoCursor text mode default for recording export. Valid values: auto, swap_fg_bg, force_contrast.
export.cursor_bar_width_pctinteger16Cursor bar width default as a percent of cell width.
export.cursor_underline_height_pctinteger12Cursor underline height default as a percent of cell height.
export.palette_sourcestringautoPalette source default for recording export. Valid values: auto, recording, terminal, xterm.
export.palette_foregroundstring (optional)—Default foreground override for recording export palette resolution. Accepts auto/empty to keep source-derived defaults, or a color value.
export.palette_backgroundstring (optional)—Default background override for recording export palette resolution. Accepts auto/empty to keep source-derived defaults, or a color value.
export.palette_colorslist of strings``Default indexed color overrides for recording export. Entries must be INDEX=COLOR (for example 5=#bb78d9).

[performance]

Performance diagnostics capture controls and telemetry safety limits
OptionTypeDefaultDescription
recording_levelstringoffCapture verbosity for performance telemetry written into recording custom events. Valid values: off, basic, detailed, trace.
window_msinteger1000Aggregation window for periodic performance telemetry, in milliseconds.
max_events_per_secinteger32Maximum number of performance custom events emitted per second by a client/runtime.
max_payload_bytes_per_secinteger65536Maximum serialized performance payload bytes emitted per second by a client/runtime.

[logs]

Runtime diagnostic log rotation, retention, and sink selection
OptionTypeDefaultDescription
retention_daysinteger14Default completed-log retention for sinks that do not override it.
max_total_mbinteger1024Default maximum total disk usage in MiB for sinks that do not override it.
prune_interval_secsinteger3600Background prune cadence in seconds for long-running processes.
server.modestringsegmentedSink mode: segmented, unified, or off. Valid values: segmented, unified, off.
server.segment_mbinteger16Segment rotation size in MiB.
server.retention_daysinteger14Completed-run retention in days.
server.max_total_mbinteger512Maximum total disk usage in MiB.
client.modestringsegmentedSink mode: segmented, unified, or off. Valid values: segmented, unified, off.
client.diagnostic_levelstringbasicDiagnostic event verbosity. Valid values: basic, detailed, trace.
client.segment_mbinteger8Segment rotation size in MiB.
client.retention_daysinteger7Completed-run retention in days.
client.max_total_mbinteger256Maximum total disk usage in MiB.
client.slow_frame_msinteger50Slow frame warning threshold in milliseconds.
client.slow_terminal_write_msinteger25Slow terminal write warning threshold in milliseconds.
client.metrics_window_msinteger1000Metrics summary window in milliseconds.

[diagnostics]

Structured operational diagnostics captured from tracing events
OptionTypeDefaultDescription
enabledbooltrueEnable the operational diagnostics event sink.
persistbooltruePersist selected diagnostics to $BMUX_STATE_DIR/diagnostics/events.jsonl.
min_levelstringwarnMinimum event level captured when no component override applies. Valid values: error, warn, info, debug, trace.
max_eventsinteger1000Maximum persisted JSONL events retained after pruning.
components.<component>.min_levelstring (optional)—Minimum event level captured for this component.
targets.<target-prefix>.componentstring``Semantic component name assigned to matching tracing targets.
targets.<target-prefix>.min_levelstring (optional)—Optional minimum event level captured for this target rule.

[kiosk]

Kiosk profiles and SSH/bootstrap settings for locked-down access flows
OptionTypeDefaultDescription
defaults.enabledboolfalseEnable kiosk features and commands.
defaults.ssh_userstringbmux-kioskDefault SSH user when profiles do not override it.
defaults.rolestringobserverDefault role assigned to issued kiosk tokens. Valid values: observer, writer.
defaults.allow_detachboolfalseAllow detach in kiosk attach mode.
defaults.token_ttl_secsinteger900Default issued token TTL in seconds.
defaults.one_shotbooltrueRequire one-time token usage by default.
defaults.sandboxstringautoSandbox mode preference. Valid values: auto, none, container, native.
profiles.<name>.sessionstring (optional)—Optional session name to attach when token omits a session override.
profiles.<name>.targetstring (optional)—Optional target name for attach routing.
profiles.<name>.rolestring (optional)—Override role for this profile.
profiles.<name>.ssh_userstring (optional)—Override SSH user for this profile.
profiles.<name>.allow_detachbool (optional)—Override detach policy for this profile.
profiles.<name>.token_ttl_secsinteger (optional)—Override token TTL in seconds for this profile.
profiles.<name>.one_shotbool (optional)—Override one-shot token behavior for this profile.
profiles.<name>.sandboxstring (optional)—Override sandbox mode for this profile.
files.sshd_include_pathpath (optional)—Destination path for generated sshd include content.
files.wrapper_dirpath (optional)—Destination directory for generated wrapper scripts.

[sandbox]

Sandbox workflow defaults for cleanup and isolation operations
OptionTypeDefaultDescription
cleanup.failed_onlyboolfalseWhen true, cleanup removes only failed/aborted sandboxes.
cleanup.older_than_secsinteger300Minimum age in seconds before sandbox is eligible for cleanup.
cleanup.sourcestringallDefault cleanup source scope. Valid values: sandbox_cli, playbook, recording_verify, all.