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 trust termsurf/termsurf
brew install —cask termsurf

The Homebrew cask currently installs TermSurf 1.0.0. It puts the TermSurf app at /Applications/TermSurf.app, the web CLI at /opt/homebrew/bin/web, and Roamium (Chromium engine) under /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, Ghostboard, 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 ghostboard —release # TermSurf GUI
scripts/build.sh webtui —release     # web TUI

Install

sudo scripts/install.sh all

This installs:

TermSurf to /Applications/TermSurf.app
Roamium + Chromium dylibs to /opt/homebrew/opt/termsurf-roamium/
web TUI to /usr/local/bin/web for source installs

Usage

Launch TermSurf:

open “/Applications/TermSurf.app”

In any TermSurf 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