TermSurf logo TermSurf

Getting Started

TermSurf embeds web browsers inside your terminal. Type web localhost:3000 and see your work without leaving the shell.

Install with Homebrew

The fastest way to install on macOS:

brew tap termsurf/termsurf
brew install --cask termsurf

This installs the Wezboard app to /Applications/, the web and wezboard CLIs to /opt/homebrew/bin/, and Roamium (Chromium engine) to /opt/homebrew/opt/termsurf-roamium/.

To upgrade to a new version: 

brew update && brew upgrade --cask termsurf

Build from Source

For development or if you want to build from source. Requires macOS, the Rust toolchain, and a Chromium build (~100 GB disk space).

Clone

git clone https://github.com/termsurf/termsurf.git
cd termsurf

Build

Build all components (Chromium, Roamium, Wezboard, and the web TUI) with: 

scripts/build.sh all --release

Or build components individually:

scripts/build.sh chromium --release   # Chromium + libtermsurf_chromium
scripts/build.sh roamium --release    # Roamium (Chromium engine binary)
scripts/build.sh wezboard --release   # Wezboard GUI + CLI
scripts/build.sh webtui --release     # web TUI

Install

sudo scripts/install.sh all

This installs:

  • Wezboard to /Applications/TermSurf Wezboard.app
  • Wezboard CLI to /usr/local/bin/wezboard
  • Roamium + Chromium dylibs to /usr/local/roamium/
  • web TUI to /usr/local/bin/web

Usage

Launch Wezboard:

open "/Applications/TermSurf Wezboard.app"

In any Wezboard pane, open a browser:

web ryanxcharles.com

The browser renders inline, in the same pane. Use Esc to switch from Browse mode to Control mode. Use Enter to switch back. See Web TUI for the full keybinding reference.

After macOS Updates

After a macOS update, rebuild Chromium. The Seatbelt sandbox APIs are tied to the macOS SDK version — a stale build will crash child processes. 

scripts/build.sh chromium --clean
scripts/build.sh all --release
sudo scripts/install.sh all