The TUI_
The whole cluster — or several — as one screen.
On this page
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.
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).
| Flag | Default | Description |
|---|---|---|
--connect-timeout | 10s | timeout 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:
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.
| Key | Action |
|---|---|
| ? | 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 |
| Tab | cycle to the next tab |
| 1–7 | jump to Stacks/Services / Volumes / Forwards / Networks / Secrets / Nodes / Configs |
| j k | move down / up (also ↓ ↑) |
| r | refresh the active tab and the cluster summary |
| y | copy the current list to the clipboard (OSC52) |
| m | toggle mouse capture (off = your terminal's own select/copy) |
| ` | open / close the live log viewer (see below) |
| Esc | leave 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 |
| q | quit |
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.
| Key | Action |
|---|---|
| c | focus the sidebar from any tab; c again or Esc gives the keyboard back |
| i | context details — endpoint and jump hosts, which the column itself has no room for |
| u / Enter | activate 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 |
| n | create 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 |
| X | remove 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:
| Key | Action |
|---|---|
| f | toggle follow |
| F | cycle log format (classic → json → logfmt → gelf → raw) |
| a | auto-detect the log format from the lines on screen — it says so when it cannot tell, and keeps watching |
| l | cycle minimum level filter (off → trace → … → fatal → off) |
| / | enter a grep regexp on the message (empty clears it) |
| m | toggle mouse capture (off = your terminal's own select/copy) |
| ↑ ↓ | scroll |
| Esc / q | close |
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.
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.
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.
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.