# bee-tui 1.0 — a terminal cockpit for Bee operators

*Draft, 2026-05-07. Polish before publishing on the chosen blog
platform (personal site / dev.to / Hashnode / a guest spot on
ethswarm.org).*

---

I've been running a Bee node since 2024 and the same loop keeps
playing out: something feels off, I `curl /health`, the gates
look fine, then I `curl /stamps`, then `/topology`, then
`/redistributionstate`, until forty minutes later I find the
real problem — bin 4 is starving, or the worst bucket on my
primary stamp is at 98 % even though `utilization` reads 14 %,
or AutoNAT has been flickering between `Public` and `Private`
for the last hour and I've been unreachable half the time.

Bee gives operators every byte of state they need. The problem
is the shape: 50+ endpoints returning JSON, with the
"is this normal?" calibration buried in the bee-go source.
There was no operator dashboard worth running.

So I built one. **bee-tui 1.0 is shipping today** — a k9s-style
terminal cockpit that surfaces the state Bee's API hides:
bucket collisions, redistribution skip reasons, bin starvation,
NAT reality, and a live HTTP request tail so you trust what
you see.

```sh
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/ethswarm-tools/bee-tui/releases/latest/download/bee-tui-installer.sh \
  | sh
```

That fetches a 2.1 MiB stripped binary for your platform —
Linux arm64/x86_64, macOS arm64/x86_64, Windows x86_64. No
Rust toolchain required.

---

## Nine screens, one truth anchor

The cockpit has nine operator-facing screens, each answering
a real question I (or someone in `#node-operators` Discord)
asked at 2 AM:

| Screen | Question |
|---|---|
| **S1 Health** | Why is my node unhealthy? |
| **S2 Stamps** | Which batch is about to fail uploads? |
| **S3 SWAP** | How much chequebook headroom is left? |
| **S4 Lottery** | Why am I not earning rewards? |
| **S5 Warmup** | What's Bee doing during the 25–60 minute cold start? |
| **S6 Peers** | Which kademlia bin is starving? |
| **S7 Network** | Why am I unreachable? |
| **S8 API** | Is the Bee API itself slow / erroring? |
| **S9 Tags** | Where is my upload stuck? |

Plus a tenth pane that's always on: **S10 Command log**, a
lazygit-style append-only tail of every Bee API call bee-tui
makes. The trust anchor — operators learn the API by
watching it.

The headline screens have a *drill*: hit `↵` on a row and
bee-tui fans out to the relevant endpoints. On S2, that's
`/stamps/<id>/buckets`, rendered as a fill-percentage
histogram (six bins from 0 % to 100 %) plus the top-10 worst
buckets by collision count. Two batches with the same
headline `utilization` can fail uploads under wildly
different conditions; the drill answers *how concentrated*
the load is.

On S6, the drill is a four-way parallel fetch — peer balance,
last cheque, settlement totals, ping RTT — rendered inline.
Each field fails independently, so a 404 on
`/chequebook/cheque/<peer>` (peers we've never exchanged
cheques with) shows `error: 404` for that one field instead
of blanking the drill.

## The bin starvation surface no other tool has

The single highest-leverage thing bee-tui surfaces is **per-bin
starvation**. Bee returns `connectedPeers` per kademlia bin in
`/topology`, but the threshold for "starving" lives in the
bee-go source as constants:

```go
// pkg/topology/kademlia/kademlia.go:54-55
SaturationPeers     = 8
OverSaturationPeers = 18
```

A bin at or below the kademlia depth with fewer than 8
connected peers is starving — uploads to that bin's chunks
will struggle to find replicas. Above 18 is over-saturated
(not harmful, just unusual). bee-tui's S6 strip computes
this directly from `/topology` and labels each bin
Empty / Starving / Healthy / Over.

That single piece of derived signal — "bin 4 is starving,
manually `connect` more peers or wait" — has saved me hours
already. As far as I know, no other tool in the Bee
ecosystem derives it.

## Hidden bee-rs bug found along the way

While building the `:set-logger` command (which lets
operators bump a Bee subsystem to `debug` verbosity from
inside the cockpit without curl), I discovered that bee-rs's
`set_logger_verbosity` had been **broken since 1.0**.

Bee's actual route is `PUT /loggers/{base64url(exp)}/{verbosity}`
— two path components, verbosity mandatory. bee-rs was
emitting `PUT /loggers/{exp}` with the verbosity nowhere.
Every call against a real Bee returned 404; only mock-based
tests with the wrong path ever "passed".

This is now fixed in [bee-rs 1.6](https://crates.io/crates/bee-rs/1.6.0).
A nice example of why building application-level tools
against your library catches bugs that unit tests can't.

## Architecture, briefly

- **Rust + Ratatui 0.30 + Tokio.** Single static binary, ~2
  MiB stripped.
- **k9s-style watch / informer hub.** Each Bee endpoint group
  has a poller spawned under a hierarchical
  `tokio_util::CancellationToken`. Cancel the root and every
  task tears down cleanly. Snapshots flow to screens via
  `tokio::sync::watch`.
- **Pure `view_for(snapshot) → View` per screen.** All
  rendering logic is a pure function from snapshot to
  data-shape, so insta snapshot tests pin every gate / status
  ladder / drill view shape — 107 lib + ~75 insta tests in
  v1.0.
- **Slot-based theme + glyph systems.** Components ask
  `theme::active().glyphs.pass` for the "pass" glyph rather
  than hardcoding `✓`. `--ascii` flips every screen at once
  for terminals with poor Unicode support; `NO_COLOR` env
  honoured per [no-color.org](https://no-color.org).

## What's next

- **Operator beta.** I'd love to hear from anyone running a
  Bee node in production: install bee-tui 1.0, run it for a
  while, [open an issue](https://github.com/ethswarm-tools/bee-tui/issues)
  with anything that surprises you. Yellow items in the
  [R3 audit report](https://github.com/ethswarm-tools/bee-tui/blob/main/docs/R3-observations.md)
  are pre-staged candidates if you'd like to start there.
- **mdBook handbook.** Per-screen explainers, operator FAQ
  ("why is bin 4 starving"), and the architecture pages.
  Scaffolded today at `docs/book/`; content fills in as
  beta feedback selects priorities.
- **VHS demos.** Animated terminal recordings for the
  README and follow-up posts. Tape templates ready at
  `docs/tapes/`.
- **bee-rs 1.7+.** Continued parity tracking with bee-go.

If you operate a Bee node, give it a spin:

```sh
bee-tui   # talks to http://localhost:1633 by default
```

The `?` key opens a per-screen help overlay so you don't have
to memorise anything.

---

*bee-tui is dual-licensed Apache-2.0 OR MIT. Source code at
[ethswarm-tools/bee-tui](https://github.com/ethswarm-tools/bee-tui),
crate at [crates.io/crates/bee-tui](https://crates.io/crates/bee-tui).
Built on top of [bee-rs](https://crates.io/crates/bee-rs) — the
Rust client library — which has its own semver track and is
also at 1.6 today.*
