TermSurf 0.2.0: Graphical Apps Inside the Terminal
Astrohacker TermSurf 0.2.0 is a macOS terminal that can run graphical applications directly inside terminal panes.
The main application today is a real Chromium browser.
From the shell:
ahweb example.com
The current pane becomes a browser. It is still the same terminal pane, but instead of rendering a grid of cells, TermSurf gives the pane to Chromium. Close the browser and you are back at the shell.
For local development, you can also give ahweb a port:
ahweb 3456
That opens http://localhost:3456.
This is the basic idea behind TermSurf: a terminal application does not have to be limited to text. A program can temporarily take over its pane and use it as a graphical surface.
The browser is inside the terminal
TermSurf is based on Ghostty, so it works like a normal terminal when you are running normal terminal programs.
The difference is that TermSurf applications can ask the terminal to display graphical content.
ahweb does this with Chromium.
You launch it from the shell just like you would launch vim, htop, or
another full-screen terminal program:
ahweb example.com
But instead of drawing a TUI into the terminal grid, ahweb opens a real
browser in that pane.
Chromium handles the page itself. Mouse input, keyboard input, scrolling, video, PDFs, file uploads, downloads, cookies, and normal browser rendering all work through the graphical pane.
The Chromium helper does not appear as another application in the Dock. From the user’s point of view, the browser is part of TermSurf.
TermSurf is more than ahweb
The browser is the most useful TermSurf application right now, but the same system also supports other graphical applications.
Version 0.2.0 includes:
- a calculator
- a help application
- a Nexus chat client
- a KeyPears client
These applications use the same basic model as ahweb: launch a command from
the shell and use the current terminal pane as a graphical application surface.
TermSurf 0.2.0 also includes ahsh, a shell in the Nushell family.
You do not have to use it. zsh and other normal shells still work.
Natural language as the default shell interface is something I want to explore later, but it is not part of 0.2.0.
The TermSurf protocol
TermSurf is also the name of the protocol behind these applications.
A TermSurf application is still a normal process. It communicates with the terminal host over sockets using protobuf messages.
The protocol lets an application create a graphical surface in its terminal pane and communicate with the component that renders it.
For ahweb, that renderer is Chromium.
This separation is important because TermSurf is not intended to be a collection of graphical features hard-coded into one terminal. The long-term goal is for other developers to be able to build graphical terminal applications using the same interface.
The protocol documentation is already public:
The protocol is still changing, however. Public TypeScript and Rust libraries are planned for 1.0.
Chromium is the browser engine
TermSurf currently ships with Chromium only.
I previously experimented with four browser engines: Chromium, WebKit, Ladybird, and Gecko.
Chromium is the one that worked well enough to ship.
WebKit could be made to render inside TermSurf, but the integration was not good enough to maintain as a production browser engine.
Ladybird rendered a black surface in the implementation I tested.
Gecko does not provide a practical desktop embedding interface for this architecture.
So 0.2.0 keeps things simple: ahweb uses Chromium.
There is also a separate Chromium helper process for each browser profile.
I originally tried using multiple profiles inside one Chromium process. With two logged-in profiles, JavaScript rendering dropped to about 2 fps. Separate Chromium processes stayed at 60 fps.
Each profile therefore gets its own helper process and its own cookies and cache.
This also means you can keep separate work and personal browser profiles without sharing their cookie stores.
What is still unfinished
TermSurf 0.2.0 is usable, but there are still parts of the Mac implementation that need work.
Browser drag-and-drop is incomplete. Dragging a link or image inside a page is currently disabled because the native drag operation could freeze the pane.
Dragging a downloaded file from TermSurf into Finder is not implemented yet.
The download bar does not show progress correctly yet.
The connection between TermSurf and the Chromium helper also needs authentication. A random local process should not be able to connect to a Chromium helper that has access to one of your browser profiles.
The application is currently ad-hoc signed rather than notarized by Apple.
The Nexus client stores the last few hundred lines of chat locally and does not yet implement every feature of the upstream client.
The KeyPears client supports accounts, an encrypted vault, and the messaging system we have tested so far. The hosted node and full synchronization system are still under development.
These are some of the main things I want finished before calling TermSurf 1.0.
About the version number
There is one confusing part of the release history.
In June, I published a post called TermSurf 1.0.
I numbered it too aggressively.
At that point, the important technical idea worked: a real browser could run inside a terminal pane. But the implementation, protocol, packaging, commands, and browser architecture were all still changing quickly.
After that post I shipped more than a hundred 0.1.x releases while continuing to change the architecture. I also removed the experimental WebKit, Gecko, and Ladybird engines from the shipped product.
So I reset the public version number to match the actual maturity of the software.
The current release is 0.2.0.
I am leaving the old post online because it documents that stage of the project, but its version number should not be treated as the current version history.
The Astrohacker name
The product is now called Astrohacker TermSurf.
I introduced Astrohacker in April and wrote more about the naming in It’s Astrohacker Now and Keep the Names.
Astrohacker TermSurf is the application.
TermSurf is the protocol.
Older posts often use TermSurf as the name of the whole product. I am not rewriting those posts, but new releases use the Astrohacker name.
Version 0.2.0 is the first release packaged this way.
What 1.0 means
Version 1.0 will still be a Mac release.
Linux and Windows are planned for 2.0.
Before 1.0, I want the Mac application and the TermSurf protocol to be stable enough that developers can rely on them.
The main work includes:
- public TypeScript and Rust libraries for building TermSurf applications
- a stable TermSurf protocol
- authentication between TermSurf and the Chromium helper
- finished browser drag-and-drop and download behavior
- password and bookmark synchronization through KeyPears
- normal Apple signing and notarization
The exact list may change as the software develops, but that is the general standard for 1.0.
Install TermSurf 0.2.0
TermSurf currently supports Apple silicon Macs.
Install it with Homebrew:
brew tap astrohackerlabs/astrohacker
brew trust astrohackerlabs/astrohacker
brew install --cask astrohacker
If you already have it installed:
brew update
brew upgrade --cask astrohacker
Then try:
ahweb example.com
or, if you have a local server running:
ahweb 3456
The application installed in /Applications is Astrohacker TermSurf.
Docs: astrohacker.com/docs