v0.8.1 · MIT · self-hosted

Topophany — self-hosted network monitoring in the terminal

From where, via which path, reaching what — and on what evidence.

Self-hosted network and service monitoring, read in the terminal. One Go binary, no dependencies, and nothing turns green until a check passes.

Install GitHub
go install github.com/WhitenWhiten/topophany/cmd/topo@latest

01 The terminal UI

Is anything wrong, and where?

A recording of topo preview: the real TUI, on synthetic evidence.

~ topo preview replay · 140×42
A recording of the Topophany terminal UI in preview mode, in chapters that can be chosen below.

An outage arrives

Press x and home loses the line to the transit host in Los Angeles. Only confirmed failures turn red.

1–9 chapters space pause. Or run topo preview yourself.

02 Semantics

Evidence, not colors

Nothing turns green without a passing check. What nobody monitors stays unknown.

Nothing is green by default

serviceevidencestate
●Main siteCloudflare ⇢ Oracle New Yorkhttp 200 · 4s agoanswered by Cloudflare FRA · cache DYNAMIC
○Home panelnotes onlyregistered, not monitoredno check configuredunknown
✖VLESS+Reality entryBandwagonHost · Los Angelestcp timeout · 6s agofrom Seattle MacBook · 3 of 3 samplesDOWN

Healthy rows stay quiet. No check means unknown, never up.

Vantage points are explicit

tcp timeout ×3 http 200 · 182 ms Seattleworker · MacBook Los AngelesBandwagonHost entry New Yorkworker · Oracle verdict fault on the path from Seattle · server up

A failure seen from one place is a fault on that path, not a server outage.

The edge answered

visitors
Cloudflare · FRA● HTTP 521 · edge up
New York origin▲ affected

An answer from the CDN proves the edge. Only a response it says it fetched proves the origin.

A guess is labeled a guess

✖ INCIDENTVLESS+Reality entryBandwagonHost · Los Angeles

Failed checks
✖ m-exit-transit-a
Other-observer response evidence
● w-exit-aux-b
Hypothesis (not a finding)
source/path-specific interference, filtering or routing fault is possible; blocking authority and untested protocols are not established

Incidents show their evidence. Anything more is marked as a hypothesis.

03 Architecture

One binary, three roles

topo is the client, the collector and the observer. No CGO, no database, no external modules.

  • binaryclient, collector and worker
  • external Go modulesstandard library only
  • release buildsLinux, macOS, Windows · amd64, arm64
  • tabsmouse included

Two collectors, no consensus theatre

Workers send to both and buffer while one is away.

Read-only by design

No remote config API, no remote shell. Topology is local JSON you review.

Bounded, and says so

When a quota fills, probing stops with an error rather than dropping evidence.

04 Probes

What it measures

Native probes, proxy chains, and read-only adapters for tools you already run.

Native probes

L7
  • HTTPstatus, body, headers, egress IP
  • SSHbanner
  • DNSA, AAAA
L6
  • TLScertificate validation
L4
  • TCPconnect
  • UDPecho, random nonce
L3
  • ICMPIPv4

Proxy chains

  • HTTP CONNECT
  • HTTPS CONNECT
  • SOCKS5remote DNS
  • OpenSSH -Wverified hosts

Read-only adapters

  • Mihomo
  • Tailscale
  • WireGuard

Edges and platforms

  • CloudflareWorkers, Pages
  • Vercel
  • Supabase

05 Install

Up in a minute

Prebuilt archives, or one go install.

go install github.com/WhitenWhiten/topophany/cmd/topo@latest

Needs Go 1.26.9 or newer.

  1. Look around

    A built-in demo. Press x to break something.

    topo preview

  2. Start a collector

    Serves a demo on 127.0.0.1:7447.

    topo init --dir ./demo topo serve --config ./demo/topology.json \ --auth ./demo/auth.json \ --data ./demo/collector-data \ --observer demo

  3. Open the TUI

    In another terminal.

    topo --credentials ./demo/credentials.json