swarmexec

swarmexec › Docs › The TUI

The TUI_

The whole cluster — or several — as one screen.

ui — interactive TUI

A terminal UI over the swarm: stacks, services and their containers, volumes, port-forwards, networks, secrets, nodes and configs, one tab each, with exec, logs and port-forwarding built in — and several clusters in one session, through the context sidebar. Needs an interactive terminal. See The TUI for keys.

swarmexec ui [service]

With a service argument the UI opens with the Stacks/Services tree already filtered to it, as if you had typed it into the / search (swarmexec ui web).

FlagDefaultDescription
--connect-timeout10stimeout for connecting to an agent

The TUI

swarmexec ui has seven tabs — Stacks/Services (1), Volumes (2), Forwards (3), Networks (4), Secrets (5), Nodes (6), Configs (7) — a context sidebar down the right-hand side, and a two-line footer: the per-tab key hints on top, then a status line with the active docker context (ctx <name>, so it's always clear which cluster you're on), a live cluster summary (3 nodes · 3/3 agents — the agent count turns yellow when some nodes have no answering agent, and red with a — swarmexec init hint when none does), the forward count and — on the Volumes tab — how many volumes you have selected; at its far right it shows the client's own version — in yellow with the newer one beside it (v1.26.0 → v1.27.0) when a newer release is out, which a footer line also announces once at startup (ui.check_updates). On a terminal narrower than 100 columns the version gives way (the ? overlay's title still names it, and a newer release with it; the status line keeps a short ↑ v1.27.0), and if the line still does not fit the cluster summary shortens to 3n · 3/3 ag; anything beyond that is left out as a whole, never cut mid-value. These keys work on every tab:

Changed: the contexts used to be tab 6, and are now the sidebar (c). Nodes and Configs moved up to 6 and 7.

The tab bar is responsive: on a narrow terminal it switches to short labels — Stacks, Vol, Fwd, Net, Sec, Node, Cfg — so all seven tabs stay visible instead of the last ones being clipped. (Cfg is Configs.) The shortcut digits and the mouse hit-boxes are unaffected.

KeyAction
?open the keybindings overlay — the complete, live key reference (it is generated from your keymap, so remapped keys show correctly); the key-hint line of the footer only has room for the most used keys. It works in every overlay too — a detail view, a list editor, the prune dialog, a log view — and opens there on that overlay's own keys, read off its footer, before everything else. On a tab it opens on that tab's section, then the other tabs, with Global last; the box grows with the terminal, and long descriptions wrap under themselves, so the key column stays readable. Where you are typing (an input field, the vim editors, a shell) ? is just a character; the vim editors' ? opens their own editor help
Tabcycle to the next tab
1–7jump to Stacks/Services / Volumes / Forwards / Networks / Secrets / Nodes / Configs
j kmove down / up (also ↓ ↑)
rrefresh the active tab and the cluster summary
ycopy the current list to the clipboard (OSC52)
mtoggle mouse capture (off = your terminal's own select/copy)
`open / close the live log viewer (see below)
Escleave the open overlay — back from a detail view, cancel a form or editor, close a log stream. It is always the first key in an overlay's footer, so a narrow terminal clips the other hints before the way out
qquit

An overlay never gives r or m a different meaning: in a detail view they do nothing (both log viewers toggle the mouse with m, like the tabs — with whatever key toggle_mouse is bound to, which their footers name). The detail actions that used to sit on them moved to capitals — R rotates in the secret detail, M measures in the node detail. The vim editors are the exception, as for every letter.

Context sidebar

The clusters live in a column down the right-hand side, not in a tab. Switching cluster is something you do from wherever you are — and the list of clusters is what tells you where that is, so it belongs on screen rather than on a page you have to travel to.

c gives it the keyboard from any tab; c again or Esc hands it back to the tab you were on. The cursor starts on the active cluster, marked ▶ — the same name the footer shows — so c Enter only says “already on” and never switches by accident. A cluster you have already visited this session is marked · in green: it is still connected, so switching to it is instant. One that refused a connection is marked ✗ in red. The built-in default context is protected.

The sidebar sizes itself to the longest context name and steps aside on a narrow terminal: below roughly 92 columns it hides rather than clip the tree, and reappears for as long as c holds it. While it is hidden, the right end of the status line says so: c contexts. Endpoints are not shown in the column — there is no room for them there, and i shows the full detail.

Switching cluster keeps your session. The UI does not rebuild itself: where the cursor stood, which stacks and services were unfolded and the / filter are remembered per cluster, so going back puts you exactly where you left off. Port forwards keep running across a switch — the Forwards tab gains a CLUSTER column so you can see at a glance which ones belong to the cluster you are looking at and which do not.

Only the cluster you are looking at is polled: switching away stops the other one's refresh, and its ssh connection expires on its own shortly after. The first switch to a cluster takes as long as connecting to it does, because the connection is made before anything on screen changes — if it fails, you are told which cluster and stay on the one that works. Every later switch back is immediate.

A write is not abandoned by a switch. A stack removal, a deploy, a scale, a prune or a secret rotation that is still running when you switch cluster keeps going, and you are told how it ended: a notice names the cluster and says whether it finished or failed (with the error). Reads — lists, inspect, diffs — are cancelled by the switch as before. q while a write is still running asks Quit anyway first, because quitting stops it midway.

KeyAction
cfocus the sidebar from any tab; c again or Esc gives the keyboard back
icontext details — endpoint and jump hosts, which the column itself has no room for
u / Enteractivate the selected context — switches the UI to that cluster, keeping your position, your filters and your port-forwards. The switch is the TUI's only: docker's stored current context, and with it docker in your other terminals, stays where it was (the flash says TUI only). Set ui.sync_docker_context: true in the config to have the shell follow (the flash then says docker context is now X (shell too)), and contexts.<name>.confirm_switch: true to be asked before switching to that context
ncreate a context — a guided form. A checkbox “Connect to Docker over SSH” decides the endpoint: when on, you fill in SSH user / host / port and a second checkbox “Use a jump host” reveals a jump host(s) field (comma-separated, multi-hop ProxyJump) — swarmexec stores them on the context and injects -J into both the Docker-API and the agent-tunnel ssh connections, so bastions work without editing ~/.ssh/config. When off, you enter a plain tcp:// / unix:// host. The form assembles the docker host for you, and Test pings the assembled endpoint before you save. Also on the CLI: swarmexec context create <name> --docker-host ssh://ops@mgr --ssh-jump bastion1,bastion2
Xremove the selected context (behind a confirm); removing the current one resets the selection to default

Embedded shell & logs

In an embedded shell, Ctrl-] detaches (without ending the process). The logs view — a single container or a service's aggregated logs — supports the same format-aware parsing and filtering as the logs command:

KeyAction
ftoggle follow
Fcycle log format (classic → json → logfmt → gelf → raw)
aauto-detect the log format from the lines on screen — it says so when it cannot tell, and keeps watching
lcycle minimum level filter (off → trace → … → fatal → off)
/enter a grep regexp on the message (empty clears it)
mtoggle mouse capture (off = your terminal's own select/copy)
↑ ↓scroll
Esc / qclose

The view re-renders the buffered lines live when you change format, level or grep, and the title bar shows the active fmt:… lvl:… grep:… status.

When following, the log view reconnects across container replacement the same way the logs command does — for both a single container's logs and a service's aggregated logs (each replica followed by slot). Reconnect notices appear inline in the log view.

L on a service with no running container opens its last logs: the newest exited container of each slot, headed by a line that says how it ended, and still following, so a crash loop's next attempt appears as a reconnect. When no task ever got a container, a dialog shows the newest task's error instead.

Activity: what changed in the cluster

Press e from any tab for the activity overlay: what the manager reported about this cluster, newest first — a service updated or scaled, a node drained, a secret, config or network created or removed. Each line says how long ago, the kind of object, what happened to it and its name, plus the one detail the Engine defines for that kind (a rolling update's state, a node's new availability). Esc, q or e close it.

The TUI has subscribed to the manager's event stream since it started refreshing the tree reactively; this is the same stream, kept instead of discarded. Nothing here asks the manager for anything, so opening it costs nothing.

It is not a log. The last 500 events are kept in memory, per cluster, for this session: the list starts when the TUI connects to a cluster and is empty again after a restart. A gap in it means “nobody was watching”, not “nothing happened” — and when the event stream is not connected (an older daemon, a blocked endpoint) the overlay says so rather than showing an honest-looking empty list. For a record that outlives a session, keep the stack files in git and use stack diff.

Only fields whose meaning the Engine defines are shown. A service event carries every label its deployer wrote, and those are arbitrary strings; they are dropped rather than rendered, for the same reason the container event stream takes only typed fields. A network's connect and disconnect are dropped too: every container joining or leaving a network emits one, which is the cluster working rather than changing, and on a busy node they would push everything else out of the list.

Log viewer

Press ` (backtick) from any tab to toggle a live log overlay. It shows the most recent records from the in-memory ring buffer — newest at the bottom — refreshing while open and colour-coded by level (red = error, yellow = warn, gray = debug). Long lines wrap, so the cause at the end of an error stays readable; w turns wrapping off and on. ↑/↓ scroll; m toggles the mouse, as on the tabs, so your terminal can select a line to paste into a bug report; Esc, q or ` close it. It floats over the tab like every other overlay, so the footer with these keys stays visible. This is the TUI's window onto the same logs that go to the log file, since the terminal itself can't show them while the UI is drawing.

Responsiveness. The container list refreshes off the UI thread (its two manager API calls used to run inline and could briefly freeze the TUI), and a background watchdog logs a warning when the event loop stalls — handy for diagnosing sluggishness from the log viewer.

Custom keys

The shortcut keys are remappable in ~/.config/swarmexec/keys.yaml (next to config.yaml; override the path with $SWARMEXEC_KEYS). Each value is a single key, or the word space. The structural keys — Enter, Esc, Tab, the arrows, the tab-number keys 1–9 and the vim aliases j/k/g/G — are fixed. The footer always shows your actual keys, and the ? overlay lists all of them.

# ~/.config/swarmexec/keys.yaml — omit any line to keep its default quit: q refresh: r copy: y toggle_mouse: m activity: e search: / fold: h unfold: l forward: p container_inspect: i logs: L security_risks: "!" # "!" must be quoted — YAML stack_group: s stack_file: E service_remove: X volume_select: space volume_select_all: a volume_delete: X volume_prune: P volume_used_by: i volume_attach: A volume_sort: s volume_sort_reverse: S volume_new: n network_attached: i network_new: n network_all: a context_focus: c context_use: u context_new: n context_delete: X node_edit_labels: l node_availability: a node_prune: P node_prune_schedule: S secret_delete: X secret_new: n config_new: n forward_stop: X forward_copy_url: o

The destructive keys — service_remove (a service or a whole stack, from the tree), volume_delete, secret_delete, context_delete and forward_stop — default to capital X, and the footer and the ? overlay draw them in red, whatever key you bind them to. The fixed d that detaches a network or secret from a service (members view, secret detail) is red too: it reads like bookkeeping and is a rolling update. The four delete keys used to default to d; if your fingers want it back, bind it in keys.yaml — volume_delete: d and the others still work.

Loading never fails: an invalid or reserved key, an unknown action, or two actions bound to the same key on one tab each fall back to the default, and the UI shows the warnings once on startup. The same goes for an action bound to a key a detail view that also answers to it keeps for itself — node_prune: M would prune from the Nodes tab but measure in the node detail, so it is refused (the node detail's M, l and i; the i that closes the context and forward details).

quit and copy also apply inside every dialog — the inspect overlay, the detail views, the log viewer — so a remapped key closes and copies there too. For the same reason they cannot take a key a dialog uses for itself, such as t, d or i: that remap keeps the default, with a warning. The env editor is the exception: there every letter is a vim command or text, so it leaves with Esc / :q and copies with yy whatever quit and copy are bound to.