TermSurf 0.2.0 Runs a Real Chromium Browser in a Terminal Pane

TermSurf 0.2.0 runs a real Chromium browser in a terminal pane. Running ahweb example.com turns the current pane into a live browser. The browser does not open a new window and does not put a Chromium icon in the Dock. The same split that was a shell becomes a real Chromium instance, not a screenshot, a text-mode browser, or a WebKit view.

TermSurf is a terminal for Apple silicon Macs, based on a fork of Ghostty. Chromium takes normal mouse and keyboard input and renders inside the pane. Closing the browser returns the pane to a shell.

What 0.2.0 Includes

The application is Astrohacker TermSurf in /Applications. TermSurf is still a terminal. Tabs, splits, and configuration work. You can run zsh. You do not need an Astrohacker account, and the terminal works offline.

A terminal program can now ask the host to turn its own pane into a graphical surface. The main example is ahweb, which opens Chromium.

ahweb example.com

PDFs open in the browser. Video playback works, including H.264 and HLS. Trackpad scrolling works. File selection works. Folder upload works. You can drag files from Finder into the browser. Same-origin downloads go to your Downloads folder.

TermSurf also ships ahsh, a shell in the Nushell family. ahsh does not replace zsh. You can keep using zsh or any other shell. There is no natural-language shell mode in 0.2.0. Using English as the default shell interface is planned for later and is not in this release.

TermSurf also ships a calculator, a help application, a Nexus chat client, and a KeyPears client. Those applications work the same way as ahweb. A terminal program starts each one, and each one runs as a graphical application inside a pane.

The Nexus client can connect to our BBS at nexus.astrohacker.com.

The name TermSurf refers to both the application and the protocol. The protocol is how a terminal program asks the host to display graphical content. The protocol uses sockets and protobuf. You do not need to know the protocol to use the terminal. If you want to build your own TermSurf applications, the implementer docs are public.

How the Browser Works

A normal terminal application draws characters into a grid of cells. Chromium does not draw that way. Chromium has a compositor, multiple processes, GPU rendering, input handling, networking, cookies, and storage. Those systems expect a desktop window.

TermSurf connects Chromium to a pane. When you run ahweb example.com, the shell starts ahweb. ahweb tells TermSurf to turn the current pane into a graphical surface and open the URL. Chromium renders into that surface. Mouse, keyboard, size, and other input from the pane go to Chromium. When the browser closes, the surface goes away and the pane is a shell again.

We tried other approaches first. Off-screen rendering with systems such as CEF or Electron caused problems with frame timing, focus, vsync, and CPU usage.

Chromium profiles were a worse surprise. Two login profiles inside one Chromium process dropped JavaScript rendering to about 2 fps. One process per profile stayed at 60 fps.

So 0.2.0 starts a separate Chromium helper process for each browser profile. The terminal owns the window and the pane. The helper owns the browser engine, page state, cookies, and cache for that profile.

flowchart LR
  shell[Shell]
  app["ahweb example.com"]
  host["TermSurf terminal pane"]
  helper["Chromium helper"]
  profile["Profile cookies and cache"]

  shell --> app
  app -->|open graphical surface| host
  app -->|open URL| helper
  host -->|mouse, keys, size| helper
  helper -->|render browser| host
  helper --> profile

We tested four engines. Chromium worked with this architecture. Chromium is the only engine in 0.2.0.

WebKit was difficult. The simple WebKit integration produced snapshots instead of a continuously updating surface. We got live compositing working in WebKit, but WebKit was still not practical enough to ship. Ladybird rendered a black surface. Gecko does not provide a practical desktop embedding API for this use case.

The terminal itself is still the Ghostty fork, written in Zig. We also built a Rust implementation of the host and got the ABI working. We stopped the Rust host because maintaining a second implementation while tracking Ghostty was not worth it.

Using ahweb

To open a website:

ahweb example.com

The browser opens in the pane where you ran the command.

To open a local server on port 3456:

ahweb 3456

ahweb 3456 opens http://localhost:3456. Typing 3456 in the URL bar also opens http://localhost:3456.

Back, forward, refresh, and hard refresh work. Hard refresh is Cmd+Shift+R.

Profiles have separate cookie stores. You can keep work accounts in one profile and personal accounts in another. Each profile gets its own Chromium helper. The helper does not show up as a separate application in the Dock. The application you launched is TermSurf.

The default theme is Austin Night. The background is #111219.

The first browser launch can be slow because TermSurf has to start Chromium.

TermSurf 0.2.0 is currently ad-hoc signed. Ad-hoc signing is not Apple notarization.

Known Limitations

Browser drag is incomplete. Dragging a link or image inside a page is cancelled, because the native drag operation could freeze the graphical pane. Dragging a downloaded file from TermSurf into Finder is not implemented.

The download bar does not show progress correctly. The download bar animates even when Chromium knows the total file size.

The connection between TermSurf and the Chromium helper is not authenticated. A random local process should not be able to attach to a profile that holds your cookies. Authentication for that connection is planned and is not in 0.2.0.

The Nexus client stores the last few hundred lines of chat history on disk. The Nexus client does basic chat. The Nexus client does not have every feature of the upstream desktop client.

The KeyPears client can create accounts, manage an encrypted vault, and use the messaging system we have tested in the lab. The hosted KeyPears node and the rest of the synchronization infrastructure are still being built. KeyPears is not ready for general password synchronization.

Planned for 1.0

1.0 is still macOS. Linux and Windows are planned for 2.0. The point of 1.0 is to finish the Mac implementation.

The work we are planning:

Password and bookmark sync through KeyPears. The browser and terminal will use KeyPears for this data instead of separate local JSON files.
TypeScript and Rust libraries. Developers will be able to build their own graphical applications that run inside TermSurf panes. The calculator, help, Nexus, and KeyPears clients are the current internal examples.
More complete browser support. Popups, permissions, printing, download progress, drag-and-drop, and authentication between TermSurf and Chromium.
A stable TermSurf protocol. The protocol will be frozen, so applications and libraries do not need to change every month.

Natural language as the default shell, a model marketplace, and possibly WebKit again are later ideas. Those ideas are not in 0.2.0, and they are not on the 1.0 plan.

When you close the browser, the pane is a shell again.

Install TermSurf 0.2.0

Install TermSurf 0.2.0 with Homebrew on an Apple silicon Mac.

brew tap astrohackerlabs/termsurf
brew trust astrohackerlabs/termsurf
brew install --cask termsurf

brew trust trusts the tap. brew trust is not Apple notarization. The app is still ad-hoc signed.

If TermSurf is already installed:

brew update
brew upgrade --cask termsurf

The cask installs Astrohacker TermSurf in /Applications. The current release is 0.2.0.

Docs: termsurf.com/docs

Source: github.com/astrohackerlabs/termsurf

Then open a website:

ahweb example.com

Or open a local server on port 3456:

ahweb 3456

The browser opens in the pane where you ran the command.