ASTROHACKER

TermSurf 0.2.0: A Real Browser Inside Your Terminal

August 16, 2026 · Ryan X. Charles

Astrohacker TermSurf 0.2.0 is a terminal for Apple silicon Macs that can run a real Chromium browser directly inside the terminal.

You open the browser from the shell:

ahweb example.com

The browser opens inside that same terminal pane.

This works like launching a full-screen TUI application, except the application is graphical. The terminal pane stops displaying the shell and becomes a live Chromium browser. When the graphical application exits, you return to the shell.

You can use this for normal websites or for local development. If your application is running on port 3456, run:

ahweb 3456

and the browser opens http://localhost:3456 inside the terminal.

This post describes what is included in TermSurf 0.2.0, how the browser integration works, and what is still unfinished.

What you are installing

TermSurf is installed with the Homebrew cask astrohacker.

The application is installed as Astrohacker TermSurf in /Applications.

TermSurf is based on a fork of Ghostty. It supports normal terminal features such as tabs, splits, and configuration.

You can run normal shells such as zsh. You do not need an Astrohacker account to use the terminal, and the terminal can work offline.

TermSurf also lets terminal programs open graphical applications inside their own terminal panes.

The main example is ahweb, which opens Chromium.

ahweb example.com

This is a real Chromium browser. It is not a screenshot, a text-mode browser, or a WebKit view.

The browser receives normal mouse and keyboard input and renders directly inside the terminal pane.

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 are saved to your Downloads folder.

TermSurf also includes ahsh, a shell in the Nushell family.

ahsh does not replace zsh. You can still run zsh or another shell normally.

There is no natural-language shell mode in 0.2.0.

Using English as the default shell interface is planned for later. It is not part of this release.

TermSurf also includes several other graphical terminal applications:

  • a calculator
  • a help application
  • a Nexus chat client
  • a KeyPears client

Like ahweb, these applications run inside a terminal pane. They are graphical applications controlled by terminal programs.

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

The name TermSurf refers to both the application and the protocol.

The application you install is Astrohacker TermSurf.

The TermSurf protocol is what terminal programs use to ask the terminal host to display graphical content. It uses sockets and protobuf.

You do not need to understand the protocol to use TermSurf.

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.

A browser is different. Chromium has a compositor, multiple processes, GPU rendering, input handling, networking, cookies, storage, and other systems that normally expect to run in a desktop window.

TermSurf connects those systems to a terminal pane.

When you run:

ahweb example.com

the shell starts ahweb.

ahweb tells TermSurf to turn the current terminal pane into a graphical surface and open the requested URL.

Chromium renders the page into that surface.

Mouse, keyboard, size, and other input from the terminal pane are forwarded to Chromium.

When the browser closes, the graphical surface goes away and the terminal pane returns to normal shell output.

We tested several ways to implement this.

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

We also found an important issue with Chromium profiles.

Two login profiles running inside one Chromium process caused JavaScript rendering to fall to about 2 fps.

Using one Chromium process per profile kept rendering at 60 fps.

Because of that, TermSurf 0.2.0 starts a separate Chromium helper process for each browser profile.

The terminal owns the terminal window and pane.

The Chromium 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 browser engines during development.

Chromium worked best with this architecture and is the only browser engine included in 0.2.0.

WebKit was difficult to use this way. The simple integration produced snapshots rather than a continuously updating browser surface. We got live compositing working, but the result was still not practical enough to ship.

Ladybird rendered a black surface in our implementation.

Gecko does not provide a practical desktop embedding API for this use case.

TermSurf 0.2.0 therefore ships with Chromium only.

The terminal itself is still based on the Ghostty fork written in Zig.

We also built a Rust implementation of the host and got its ABI working.

We decided not to continue with the Rust rewrite because it would require maintaining another implementation while continuing to follow changes in Ghostty.

Using the browser

To open a website, run:

ahweb example.com

The browser opens inside the terminal pane where you ran the command.

To open a local server on port 3456:

ahweb 3456

TermSurf opens:

http://localhost:3456

You can also enter:

3456

in the browser URL bar, and TermSurf treats it as http://localhost:3456.

The browser supports back, forward, refresh, and hard refresh.

Hard refresh is:

Cmd+Shift+R

Browser profiles have separate cookie stores.

You can use one profile for work accounts and another for personal accounts without sharing cookies between them.

Each profile gets its own Chromium helper process.

The Chromium helper does not appear as a separate application in the Dock.

The macOS application you launch is TermSurf.

The default theme is called Austin Night.

Its background color is:

#111219

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

TermSurf 0.2.0 is currently ad-hoc signed.

The command:

brew trust astrohackerlabs/astrohacker

trusts the Astrohacker Homebrew tap.

It does not mean the application has been notarized by Apple.

Known limitations

Browser drag behavior is still incomplete.

Dragging a link or image inside a webpage is currently cancelled because the native drag operation could freeze the graphical pane.

Dragging a downloaded file from TermSurf into Finder is not implemented yet.

The download bar also does not display progress correctly. It currently animates even when Chromium knows the total file size.

The connection between TermSurf and the Chromium helper is not authenticated yet.

A random local process should not be able to connect to a browser profile that contains your cookies.

That protection is planned, but it is not implemented in 0.2.0.

The Nexus client stores the last few hundred lines of chat history on disk.

It supports basic chat, but it does not include 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 remaining synchronization infrastructure are still being built.

It is not yet ready for general password synchronization.

What is planned for 1.0

Version 1.0 is still focused on macOS.

Linux and Windows are planned for 2.0.

The goal for 1.0 is to finish the current Mac implementation.

The main planned work is:

  • 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. This includes 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.

Other ideas are planned for later.

These include using natural language as the default shell interface, a model marketplace, and possibly adding WebKit again.

They are not part of TermSurf 0.2.0 or the 1.0 plan.

Install TermSurf 0.2.0

TermSurf 0.2.0 requires an Apple silicon Mac and Homebrew.

Install it with:

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

If you already have TermSurf installed:

brew update
brew upgrade --cask astrohacker

The current release is Astrohacker TermSurf 0.2.0.

Documentation: astrohacker.com/docs

Source: github.com/astrohackerlabs/termsurf

To try the browser, run:

ahweb example.com

To open a local development server:

ahweb 3456

The browser opens directly inside the terminal pane where you ran the command.

← Back to blog