Configuration

TermSurf uses Ghostboard’s Ghostty-based configuration system. This page covers the current config file location and settings relevant to TermSurf.

Config File

TermSurf looks for config at:

1. ~/.config/termsurf/config

Minimal config example:

# ~/.config/termsurf/config
font-size = 14
theme = TokyoNight
window-decoration = false

TermSurf-Relevant Settings

window-decoration

Controls the window title bar and frame. Default is true (standard macOS title bar).

# No title bar
window-decoration = false

With false, 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

Ghostty-compatible color themes 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

Ghostboard listens on a PID-scoped socket:

$TMPDIR/termsurf/termsurf-ghostboard-<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

Ghostty Documentation

For the upstream terminal configuration model, see the Ghostty configuration docs.