TermSurf logo TermSurf

About

TermSurf is a protocol for embedding web browsers inside terminal emulators. Type web example.com in a terminal pane and a real browser renders as a GPU overlay right there — no alt+tab, no context switch. You navigate the web with a small, keyboard-driven chrome (a URL bar and status line) drawn in the terminal itself.

The protocol is the product

TermSurf is a protocol, not just an app. The terminal (the GUI), each browser engine, and each terminal UI are separate processes that speak one protobuf/Unix-socket protocol. The GUI is the hub: terminal UIs and browser engines connect to it, and it composites browser content into the window as pixel-positioned overlays.

The design is multi-process by necessity — each browser engine process serves exactly one profile (one set of cookies, storage, and cache). That same separation is what lets the protocol stay engine-agnostic: the GUI does not care which engine renders a given pane. For the full process topology, IPC framing, and GPU-compositing details, see Architecture.

What ships in 1.0

TermSurf 1.0 runs on macOS. Three components make up the shipping stack:

  • Ghostboard — the GUI terminal emulator, a fork of Ghostty. It hosts the browser overlays and renders the terminal.

  • web

    — the terminal UI that provides the browser chrome (URL bar, modes, commands) in a pane.

  • Roamium

    — the browser engine binary, built on Chromium.

To install it and open your first page, see Getting Started. To tune the terminal, see the configuration guide. The underlying message protocol is documented in the protocol overview.

Relationship to Ghostty

Ghostboard is a fork of Ghostty, so TermSurf inherits Ghostty’s terminal behavior and its VT (terminal escape-sequence) support, then adds the browser-overlay protocol and terminal features built for it — such as split pane borders. The Terminal API reference documents the escape sequences TermSurf supports; that reference is adapted from Ghostty’s MIT-licensed documentation (see the repository NOTICE), with each page verified against the TermSurf fork.

Planned

These are not in 1.0 — they describe the project’s direction, at varying levels of commitment:

  • More browser engines. A WebKit engine (Surfari) is planned; Gecko (Waterwolf) and Ladybird (Girlbat) are researched — under consideration, not yet committed.

  • More terminal front-ends. Kitty, Alacritty, and iTerm2 are planned hosts in addition to Ghostboard.

  • More platforms. Linux and Windows are planned; iOS and Android may follow.

  • More browser features. Bookmarks, tabs, history, downloads, and PDF viewing are on the roadmap.