TUI

yoink tui

Heavily inspired by k9s and lazydocker, but pointed at remote hosts you deploy to instead of just the local docker daemon. Keyboard-driven, real-time, and aware of yoink-specific concepts (services, drift, sealed secrets, deploy history) on top of the everyday docker introspection an operator wants when something is on fire.

What it shows

Top-level navigation

Operator gestures from the dashboard

Container detail (i from any list view)

The detail pane renders four kinds of information for a single container:

1. Header card: image, state (colored), command, restart count, started/finished/exit-code timestamps. The right column has live CPU / MEM gauges and a NET ↓rx ↑tx cumulative-bytes line ("how much has this thing transferred since start").
2. 5-minute history charts: three side-by-side panels, each with the latest sampled value baked into its title so it's readable without squinting at the rightmost edge:
   • CPU % (cyan): own y-axis scaled to peak CPU
   • Mem (magenta): own y-axis. % when memory is capped, MB when uncapped
   • net tx / rx (yellow / green): btop-style mirrored: tx (outgoing) plots above the zero line, rx (incoming) mirrored below. The two series can never overlap. Title shows current rates: ↑1.2MB/s ↓340KB/s. Y-axis labels carry the direction arrow on each side.
3. Runtime + security blocks: published ports, mounts, attached networks, then cap_drop / cap_add / security_opt / read_only / pids_limit / effective user so you can see at a glance whether this container is hardened.
4. Env + labels: sorted KEY=value with secret-ish keys (*TOKEN*, *SECRET*, *PASSWORD*, *API_KEY*, *PRIVATE_KEY*, *DSN*) auto-redacted; full label table including the yoink.* set.

Plus, at the bottom of the pane, a rolling tail of the container's logs.

History is collected for every container, all the time. A background poller samples docker stats for every running container across every configured host every 2 seconds, regardless of which view you're currently on. When you drill into a container's detail pane, the chart is already populated with up to 5 minutes of context instead of starting from zero. Stale entries (containers that stopped and aged out) are GC'd automatically.

If your image is distroless or otherwise has no shell, ! will fail. Fall back to B: the debug sidecar attaches an alpine container sharing the target's PID and network namespaces, so you can run ps, ss, cat /proc/<pid>/... against the target without modifying the production image. The sidecar auto-removes when you exit / Ctrl-D.

Drift detail (~)

When the dashboard / host detail / service detail / container detail view shows ⚠ on a row, press ~ to open a modal that explains what drifted, the same per-field diff yoink up --plan produces on the CLI side:

 drift: api on host-a (esc to close)
   image  ghcr.io/me/api  (unchanged)
   spec   a1b2c3d → e5f6a7b
    tag   v1.2.4
env:
  + DATABASE_POOL_SIZE
  ~ LOG_LEVEL
labels:
  - yoink.caddy.tls

Color-coded so the markers read at a glance: + green (added in desired), - red (removed from running), ~ yellow (changed). The hash and image columns highlight the running → desired transition in cyan when they differ; the line dims to (unchanged) when they match.

The fetch reuses diff::compute under the hood, so the modal's content is identical to yoink up --plan --service <name> against the same host. For services without a tag: pinned in config (typical for image: ghcr.io/you/api where CI provides the tag), the modal falls back to the running replica's tag so the diff isolates the env/label change instead of erroring on a missing tag, useful for "what changed since deploy?" without leaving the TUI.

Esc closes the modal. The underlying view stays put.

Hosts pane (h)

Per-host summary table:

Enter drills into HostDetail, which shows every running container on the host (whether yoink manages it or not), with the same live CPU/mem cells, drift indicator, and per-container actions:

The events panel at the bottom of HostDetail collects live docker events for that host (start / stop / die / health-status / kill / oom / restart). Each row is a one-line summary timestamped with relative time. The ring keeps the last 200 events per host, long enough that an operator returning to the pane after a reconcile sees the full sequence of swaps, not just the final state.

Services pane (s)

Services lists every service in yoink.yaml with its current replica count and configured image. Enter opens ServiceDetail: one row per running replica across every host, with the same per-row container actions. H opens ServiceHistory: every yoink-managed container with yoink.service=<name> (running and exited), sorted newest-first by yoink.deployed-at. Pressing r on a row triggers a rollback confirmation pinned to that row's tag (same flow as yoink rollback --tag <value>).

Resources pane (R)

Three sub-tabs covering the introspection lazydocker users expect, fanned out across every configured host:

Tab / Shift-Tab cycles between the three sub-tabs (only inside Resources, not the top-level modes). / filters across host/name/tag substrings; partial fetch errors per host appear as a red footer ribbon rather than blanking the whole table. Dangling images sort to the top so they're trivial to prune.

There's intentionally no volume file browsing. Drop into the container with ! (or, for distroless containers, B for the debug sidecar) and use the shell. That's strictly more capable than the half-baked file UI lazydocker has, and it's what most operators reach for anyway.

Secrets pane (e)

View / add / edit / remove individual sealed secrets without leaving the TUI. Reuses the same on-disk format as yoink secrets edit and respects per-environment secrets.file: paths; the title bar shows which file is active.

When provider: command is configured the pane is read-only; rotation happens in whichever external tool the configured CLI talks to. When no age identity is available, the pane shows the failed-load reason + a remediation pointer. For bulk multi-line edits, drop to the CLI: yoink secrets edit.

Logs pane (l)

The multiplexed Logs view aggregates a live tail from every yoink-managed container across every host into one scrollable buffer. Each line is prefixed with the container name; lines from different hosts and services interleave in real time. Useful for "something just happened on prod, what was it?" when you don't yet know which service.

The buffer is bounded at 5,000 lines; older lines fall off as new ones arrive. Filter doesn't shrink the buffer, only the rendered view.

ContainerLogs (single container)

Reached via Enter from any list view. Same shape as the multiplexed Logs pane, scoped to one container. Same keybindings; Esc returns to the parent. ! and B are also bound here for quick "tail logs → drop into shell" pivots.

Audit pane (a)

Merged operator + per-host JSONL audit log: every state-changing run yoink performed (deploy, rollback, prune, secrets rotate). Same data path as yoink audit log, with stable selection on event_id so a refresh keeps you on the row you were looking at.

The first column tags each row with operator (purple) or host (cyan) so you can tell at a glance which side of the merge a line came from.

Shell / debug sidecar (!, B)

Both gestures put you on a PTY inside the host's docker daemon with no SSH on top; yoink uses the Docker exec API and the TUI streams bytes both ways through a terminal-emulator parser.

! runs bash (falls back to sh) inside the existing container, equivalent to yoink shell <service> but staying in the TUI. Useful when the image has a shell and you want quick access to the running process's filesystem, env, etc.

B spins up an ephemeral alpine debug sidecar sharing the target container's PID and network namespaces. The fallback for distroless / scratch / shell-less images: you get ps, ss, cat /proc/<pid>/..., tcpdump, apk add whatever you need, without modifying the production image. The sidecar is --rm and force-removed when you exit / Ctrl-D, even if the TUI crashes.

Window resizing flows through automatically; the panel size is sent to the daemon on every render so top / vim / etc. re-flow.

Progress modals

Long-running operations (reconcile-one, reconcile-all, prune) render a centred modal that streams the deploy event log live. The border colour reflects state: cyan while running, green on success, red on failure. The modal eats every key while the operation is in flight (so a stray j can't drive the underlying view); y yanks the modal's text to the clipboard at any time. Once finished, Esc / Enter dismisses.

reconcile-all (A from Dashboard) gets a richer status table at the top of the modal: one row per service, colour-coded by current state (waiting → pulling → healthcheck → swapping → done / failed), so when the wave-parallel deploy is mid-flight you can see all six services' progress at a glance instead of hunting through interleaved log lines.

Filter conventions

Every list/table pane has a consistent filter:

• / enters input mode; type freeform, Backspace deletes, Enter applies, Esc cancels (drops back to whatever filter was already active)
• Active filter is shown in cyan in the footer (filter: foo); editable filter buffer is yellow
• Esc with no input mode and an active filter clears it

Filter is case-insensitive substring across multiple fields per pane (host + service + container name + state + version + networks for the dashboard; analogous sets elsewhere). Empty filter shows everything.

Help overlay (?)

Toggles a centred per-view modal listing every key binding active in the current view. Press ? again or Esc to close. The contents are scoped; Dashboard's overlay shows only Dashboard keys, Resources' shows only Resources keys, etc., so you don't have to scan irrelevant bindings.

The overlay is available in every view including inside the embedded shell (which otherwise forwards every key to the PTY).

CLI launch flags

yoink tui                       # Dashboard view by default
yoink tui --mode hosts          # start on a specific top-level pane
yoink tui --mouse               # enable mouse capture (scroll wheel + selection)

--mode accepts dashboard / hosts / services / logs / resources / secrets / audit. --mouse is opt-in because mouse capture disables your terminal's native text-selection; if you don't actively use mouse scroll inside the TUI, leave it off.

YOINK_NO_HL=1 in the environment skips the hl auto-detection (the logs pane will use raw output even if hl is on PATH). Useful when troubleshooting hl itself.

Pretty logs

Structured log lines (JSON, logfmt, etc.) are hard to scan as raw text. The TUI's logs pane auto-detects hl (brew install pamburus/tap/hl) on the operator's PATH and transparently pipes every container's log stream through it before rendering; JSON keys are colored, timestamps are dim, levels are highlighted, and stack traces stay readable. Falls back to raw output when hl isn't installed; no config knob to toggle.

The yoink logs <svc> -f CLI doesn't auto-pipe (the operator decides their own shell pipeline), but yoink logs api -f | hl works the same way.

Keybinding cheat sheet

A consistent set of letters has the same meaning everywhere they appear:

Letters are case-sensitive; capital letters generally mean "destructive or expensive" (kill, restart, reconcile-all, prune-all-images, …) and require a y/Enter confirmation when state-changing, while lowercase letters are read-only navigation / refreshes.

See also

• CLI reference — the same commands the TUI binds to keys, in scriptable form.
• Driving yoink from an AI agent — the CLI surface the TUI mirrors, suitable for non-interactive driving.
• Troubleshooting — when the TUI shows something surprising.