TermSurf logo TermSurf

How TermSurf Works

TermSurf puts a real web browser inside a terminal pane. You type web example.com and the page renders right where you’re working — no alt+tab, no switching to a separate browser app, no losing your place. You drive it from the keyboard with a small chrome (a URL bar and status line) and a couple of modes.

What happens when you run web example.com

  1. The web TUI starts in the pane and connects to the GUI (Ghostboard) over a Unix socket (it finds the socket via the TERMSURF_SOCKET environment variable the GUI sets).

  2. The GUI launches — or reuses — a browser engine process for your profile. There is one engine process per profile, so each profile keeps its own cookies, storage, and cache.

  3. The engine renders the page, and the GUI composites it as a zero-copy GPU overlay positioned exactly over your pane (on macOS, via CALayerHost). The web content is drawn by the GPU, not painted as terminal cells.

  4. The TUI draws the chrome (URL bar, status) in the terminal and forwards your input. You switch between Control mode (terminal/TUI keys) and Browse mode (keyboard and mouse go to the page).

The browser lives in the pane alongside your shells and editors — resize it, split it, or close it like any other pane. To move between editing the URL and using the page, you change modes rather than switching apps; see the Web TUI reference for the modes, keybindings, and commands.

Why it’s built this way

TermSurf is a protocol, not just an app: the terminal (GUI), each browser engine, and each TUI are separate processes speaking one protobuf/Unix-socket protocol. That separation is what makes the engine swappable and the overlay model possible. The full process topology, the IPC wire format, and the GPU-compositing mechanics are documented in Architecture; the message types are in the protocol overview.

Today the shipping engine is Roamium (Chromium) on macOS. Because the GUI talks to engines only through the protocol, additional engines are a planned extension rather than a rewrite — see the engine table in Architecture.

Ready to try it? Start with Getting Started.