Skip to content

Add a terminal dashboard for pools and runners - #26

Merged
clroot merged 1 commit into
mainfrom
feature/tui
Nov 16, 2026
Merged

clroot merged 1 commit into
mainfrom
feature/tui

Conversation

@clroot

@clroot clroot commented Nov 16, 2026

Copy link
Copy Markdown
Owner

Problem

Watching pools means rerunning runnerctl status, and acting on what you see means typing a separate command with the pool name. A desktop GUI would not help much: most Docker hosts are servers reached over SSH.

Change

runnerctl tui opens a terminal dashboard (ratatui).

  • A pool table with the same columns as status, and the selected pool's scope, image, labels, group, error, and runners with drain notes. Refreshes every second.
  • Keys: s start, x stop (drain), X force stop (both confirmed), +/- scale, l/Enter runner logs (follows output, stays in place when scrolled up), d doctor, r refresh, ? help, q quit.
  • It sends the same control requests as the CLI. Periodic refreshes only talk to a running manager, so the dashboard never holds the manager lock while the manager starts. Saved state is read only when the dashboard opens, on r, and after a change, and the header says when the manager is stopped.
  • One change is in flight at a time, so offline changes do not collide on the lock.
  • Runner logs are stripped of escape sequences and control characters before drawing.
  • Without a terminal it exits with an error pointing to runnerctl status.
  • ratatui = "0.29" keeps rust-version = "1.85"; 0.30.x needs 1.86 or later. crossterm comes through ratatui's re-export.
  • README: one paragraph under Daily commands.

Verification

  • cargo fmt --check, cargo clippy --all-targets --locked -- -D warnings, cargo test --locked: pass. Adds 8 unit tests (key handling, refresh behavior, log scrolling, escape stripping, rendering with TestBackend) and a CLI test for the non-terminal error.
  • Drove the built binary in a pty on WSL2 against a temporary home with two pools: with the manager stopped (saved state, stop with confirmation, scale, doctor, help) and with runnerctl manager running (live status over the socket).
  • Not checked: a pool with live runners and their logs against real GitHub and Docker, Windows and macOS terminals, and a Rust 1.85 build (only stable was installed).

🤖 Generated with Claude Code

runnerctl tui shows every pool with its runner counts and the selected
pool's configuration and runners, refreshing every second. From it you
can start, stop (drain or force, both confirmed), and scale the selected
pool, follow a runner's logs, and run doctor checks. It works over SSH,
where most Docker hosts are managed.

The dashboard is another control-channel client and sends the same
requests as the CLI. Periodic refreshes only talk to a running manager,
so the dashboard never holds the manager lock while the manager starts;
saved state is read only when the dashboard opens, on r, and after a
change. Runner log output is stripped of escape sequences and control
characters before it is drawn.

ratatui 0.29 keeps the crate's Rust 1.85 minimum; 0.30.x needs 1.86 or
later.
@clroot
clroot merged commit 241e4f1 into main Nov 16, 2026
3 checks passed
@clroot
clroot deleted the feature/tui branch November 16, 2026 01:24
@clroot clroot mentioned this pull request Nov 16, 2026
clroot added a commit that referenced this pull request Nov 16, 2026
Publishes the runnerctl tui terminal dashboard (#26).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant