Configuration

Wezboard uses WezTerm's Lua configuration system. All WezTerm config options are supported. This page covers the config file location and settings relevant to TermSurf.

Config File

Wezboard looks for config in this order:

1. $XDG_CONFIG_HOME/termsurf/wezboard/wezboard.lua
2. ~/.config/termsurf/wezboard/wezboard.lua

Minimal config example:

-- ~/.config/termsurf/wezboard/wezboard.lua
local config = 

config.font_size = 14.0
config.window_decorations = "RESIZE"
config.color_scheme = "Tokyo Night"

return config

TermSurf-Relevant Settings

window_decorations

Controls the window title bar and frame. Default is "TITLE | RESIZE" (standard macOS title bar).

-- No title bar, just resize handles
config.window_decorations = "RESIZE"

With "RESIZE", the title bar is hidden and the content view fills the entire window. Browser overlays align correctly in both modes.

font_size

Font size affects cell dimensions, which determine the pixel size and position of browser overlays. Changing the font size resizes all overlays.

color_scheme

WezTerm's built-in color schemes apply to terminal panes. Browser content uses its own color scheme, controlled via the :dark command in the Web TUI.

Browser Profiles

Browser profiles are stored at:

~/.local/share/termsurf/chromium-profiles/<profile-name>/

Each profile gets its own Chromium user data directory with separate cookies, storage, and cache. Profiles are specified per-pane when launching the web TUI.

Data Directories

Socket Paths

Wezboard listens on a PID-scoped socket:

$TMPDIR/termsurf/wezboard-<pid>.sock

This path is exposed to child processes via the TERMSURF_SOCKET environment variable. Each browser engine process also listens on its own socket:

$TMPDIR/termsurf/roamium-<hash>-<gui-pid>-<profile>.sock

WezTerm Documentation

For the full configuration reference (fonts, colors, keybindings, Lua API, multiplexer, SSH, etc.), see the WezTerm configuration docs.