v1.7.0 · MIT · セルフホスト

Topophany — ターミナルで読むセルフホスト型ネットワーク監視

どこから、どの経路で、何に届いたのか — そして、何を根拠に。

ネットワーク全体をひとつの画面に。どの経路がどこから通じているか、どのサービスが応答しているか、それぞれの状態の根拠まで。セルフホストで、Go のバイナリ 1 つ、ターミナルで読めます。

ライブデモ Web 版
go install github.com/WhitenWhiten/topophany/cmd/topo@latest
Newtopophany-bar で Topophany を macOS のメニューバーに

01 ターミナル UI

どこかおかしい？ それはどこ？

topo preview の録画です。本物の TUI に、合成の根拠を流しています。 ブラウザーで試す →

~ topo preview 再生中 · 200×50
プレビューモードの Topophany ターミナル UI の録画。下のチャプターから選べます。

障害が起きる

x を押すと、自宅からロサンゼルスの中継回線への接続が遮断されます。確定した失敗だけが赤くなります。

1–9 チャプター space 一時停止。topo preview で自分でも試せます。

02 セマンティクス

色ではなく根拠を

通過したチェックなしに緑になるものはありません。誰も監視していないものは unknown のままです。

初めから緑のものはない

サービス根拠状態
●メインサイトCloudflare ⇢ Oracle ニューヨークhttp 200 · 4 秒前Cloudflare FRA が応答 · キャッシュ DYNAMIC
○自宅ダッシュボードノートのみ登録済み・未監視チェックが未設定unknown
✖VLESS+Reality 入口BandwagonHost · ロサンゼルスtcp タイムアウト · 6 秒前大阪 MacBook から · 3 サンプル中 3DOWN

正常な行は静かなまま。チェックがなければ稼働中ではなく unknown です。

観測点を明示する

tcp タイムアウト ×3 http 200 · 182 ms 大阪worker · MacBook ロサンゼルスBandwagonHost 入口 ニューヨークworker · Oracle 判定 大阪からの経路の障害 · サーバーは稼働中

ある場所から見えた失敗は、その経路の障害であって、サーバーの停止ではありません。

エッジが応答した

判定 障害はエッジの奥 · オリジンは未証明

CDN からの応答が証明するのは、何を名乗ろうとエッジだけ。オリジンを証明するのは、エッジを通らないオリジン自身のチェックだけです。

推測は推測と明記する

✖ INCIDENTVLESS+Reality 入口BandwagonHost · ロサンゼルス

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

インシデントは根拠を示し、それ以上は仮説と明記します。

03 構成

1 つのバイナリ、3 つの役割

topo はクライアントであり、コレクターであり、観測点です。CGO も、データベースも、外部モジュールも不要。

  • バイナリクライアント、コレクター、ワーカー
  • 外部 Go モジュール標準ライブラリのみ
  • リリースビルドLinux、macOS、Windows · amd64、arm64
  • タブマウス対応

2 つのコレクター、合意ごっこはなし

ワーカーは両方に送り、片方が落ちている間はバッファします。

最初から読み取り専用

リモートの設定 API もシェルもありません。トポロジーはレビューするローカル JSON です。

上限はあり、隠さない

上限に達すると、根拠を捨てずにエラーで計測を止めます。

04 プローブ

計測できるもの

ネイティブのプローブ、プロキシチェーン、そして既存ツール向けの読み取り専用アダプター。

ネイティブプローブ

  • L7
    • http200 · 182 ms期待したステータス・本文・ヘッダー・出口 IP
    • ssh-bannerSSH-2.0 · 38 msSSH バナー。ログインではない
    • dnsA 192.0.2.10 · 9 ms期待した A / AAAA レコード
  • L6
    • tlsTLS 1.3 · verified · 41 ms検証済みの証明書チェーンと名前
  • L4
    • tcpconnected · 23 ms接続できたこと。その先は問わない
    • udp-echononce echoed · 27 msランダムな nonce が返ってきたこと
  • L3
    • icmpecho reply · 31 msエコー応答（IPv4 のみ）

プロキシチェーン

  1. 観測点
  2. OpenSSH -W先頭ホップ。ホスト鍵を検証
  3. HTTP CONNECT
  4. HTTPS CONNECTプロキシの TLS を検証
  5. SOCKS5リモート DNS
  6. ターゲット

最大 12 ホップ。HTTP、TCP、TLS、SSH のチェックは、そのすべてを順に通ります。

読み取り専用アダプター

  • MihomoGET /proxiesコアが報告するモード、チェーン、選択中のノード
  • Tailscaletailscale status --jsonピアのオンライン状態、直結かリレーか
  • WireGuardwg show wg0 dump最後のハンドシェイクと転送量。鍵は保持しない
  • cloudflaredGET /readyコネクターが報告するトンネルセッションと colo

ツールの報告は報告として示し、エンドツーエンドの合格とはみなしません。

エッジとプラットフォーム

  • CloudflareedgeWorkers と Pages。応答した POP も
  • VerceledgeFunctions。エッジと関数のリージョンも
  • Supabaseplatformリージョンにあるマネージドサービス

応答は送ったエッジのものとして記録し、その奥のオリジンのものにはしません。

05 エージェントと

地図はエージェントに描かせる

監視でいちばん手間がかかるのはネットワークを書き起こすことで、それは普段使っているコーディングエージェントの得意分野です。マシンが既に持っている情報を読んでトポロジーを書き、何かを動かす前に topo validate で確かめます。

頼み方

私のネットワークを Topophany のトポロジーとして topology.json に書いてください。形式は `topo preview --print-topology` の出力と、github.com/WhitenWhiten/topophany の docs/REFERENCE.md を参考にしてください。SSH の設定、`tailscale status`、見つかる Compose ファイルとリバースプロキシの設定を読み、各マシンについて場所、動いているサービス、サービスが属するアプリケーション、待ち受けているアドレスを宣言し、ワーカーを動かす予定のマシンからのチェックを加え、分かったことはそれぞれのマシンの notes に書いてください。秘密情報はファイルに書かないでください。`topo validate --config topology.json` が通るまで直し、最後に、確かめたことと推測したことを分けて教えてください。

Claude Code、Codex、Gemini CLI、Cursor など、コマンドを実行できるエージェントなら何でも。秘密情報はファイルに入りません。形式に書くのは環境変数名と鍵ファイルのパスだけで、その中身ではありません。

そのあとも

  • ネットワークのメモとしてtopology.json何がどこで動き、各マシンにどう届くのかを、ノートや手順書と一緒にレビュー済みのファイル 1 つに。エージェントは手を動かす前にこれを読み、あなたはその変更を差分で確かめます。
  • すぐ引ける窓口としてtopo status · show · historyコマンド 1 つで、文字でも JSON でも、あなたにもエージェントにも答えます。いま何かおかしいか、あのサーバーで何が動いているか、あのチェックが夜のあいだどうだったか。
  • 動かす前にtopo preview --configプレビューなら、合成の根拠で自分のネットワークを描けます。ワーカーを 1 台も動かす前に、エージェントと一緒に見直せます。

06 Mac で

ネットワークをメニューバーに

topophany-bar は Topophany の macOS 用コンパニオンです。topo を通してコレクターを読み、状態はメニューバーに、問題がどこから見えているかはパネルに、サーバーとサービスはデスクトップのウィジェットに表示します。

macOS のデスクトップ。メニューバーには白夜のアイコンがあり、部分月食の月の横に 2 の数字。その下に開いたパネルには、警告 2 件で低下したネットワーク、それを見ているオブザーバー、地図が表示され、デスクトップにはステータス、サーバー、タイムゾーン、サービス、地図のウィジェットが並ぶ
警告が 2 件あるデモネットワーク。合成データを使い、アプリ自身のビューで描いています。

topophany-bar

macOS 26 以降 · プレリリース、ソースからビルド

GitHub の topophany-bar
  • ひと目でアイコン、件数、短い言葉で状態を示します。組み込みのディザの夜空「白夜」では月が状態です。すべて正常なら満月、何かが低下すれば部分月食、何かが停止すれば赤い月。
  • どこから見えているかインシデント、影響を受けるアプリケーション、問題を報告しているオブザーバーをひとつのパネルに。どれもターミナル UI で開いて根拠を確かめられます。
  • Beszel と Komari を直接Beszel Hub や Komari サーバーからサーバーを選び、CPU、メモリー、ディスクを見守れます。コレクターは要りません。
  • ウィジェットとテーマステータス、サーバー、サービス、地図、タイムゾーンのウィジェット。テーマは macOS 標準から紙に刷ったターミナル UI まで 6 種類です。

07 iPhone Duo のための設計

地図はヒンジの上に

iPhone アプリはまだありません。あるのは、そのための TUI の設計です。--device は TUI を iPhone、iPad、そして姿勢ごとの iPhone Duo の画面に合わせてレイアウトし、その画面をターミナルの中でシミュレートします。開いた Duo では、見るものと触るものが折り目の両側に分かれます。

ターミナルのシミュレーターが描いた、縦に持った iPhone Duo 向けの TUI。ヒンジの上にネットワークの地図と琥珀色の影響ルート、下に 5 件のインシデントを示すステータスカード、オブザーバー、要対応の一覧、下端のタブ
ターミナルのシミュレーターで、縦に開いてノートパソコンのように半分折った状態：topo preview --device duo-laptop。
  • 見るのは上、触るのは下ノートパソコンの姿勢では、立てた半分（画面）に地図を、指を置く寝かせた半分にイベントとすべての操作を置きます。
  • 折っても描き直さない平らに開いた時点で折り目を空けているので、折ってもセルは 1 つも動きません。シミュレーターの中で折っても、開いても、向きを変えても、タブ、選択、開いた根拠はそのままです。
  • システムの領域を避ける折り目の上、時計やカメラの下、セーフエリアの外には操作を置かず、どのタップ領域も指 1 本分の高さにします。テストがすべてのデバイスのすべてのタブを確かめます。

ターミナルで試す

go install github.com/WhitenWhiten/topophany/cmd/topo@main topo preview --device duo-laptop

[ と ] で姿勢を切り替え、\ で次のデバイスへ。マウスが指の代わりになります。ターミナルは 99×70 セルほど必要です。次のリリースまで、--device は main にあります。

GitHub でスターを付ける デバイスごとのレイアウト
ターミナルのシミュレーターが描いた、5 つの姿勢の iPhone Duo 向け TUI、どれも同じ瞬間。閉じてカバーディスプレイに（タブは時計の下の列）、横に開いて（左に地図、右に一覧）、本のように半分折って、縦に開いて（ヒンジの上に地図）、ノートパソコンのように半分折って
シミュレーターが描く、どの姿勢でも同じ瞬間。閉じるとタブは時計の下の列に入り、横に開くと見開きの左右がそれぞれの役目を持ち、縦にすると地図はヒンジの上に来ます。

08 インストール

1 分で動く

ビルド済みアーカイブ、または go install ひとつで。

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

Go 1.26.11 以降が必要です。

  1. 見て回る

    組み込みのデモ。x で何かを壊してみてください。

    topo preview

  2. コレクターを起動する

    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. TUI を開く

    別のターミナルで。

    topo --credentials ./demo/credentials.json