Dashboard

/rl:dashboard — serve the training dashboard here

Gets webui/ running on this machine, whatever its paths look like. The dashboard is a stdlib-only Python server plus a prebuilt static bundle, so the work is never "install things" — it is deciding which logs to show, on which port, and whether the bundle is current.

/rl:dashboard [log-dir]
   │
   ├─ 1. lib/dashboard_probe.sh ..... layout · running instances · tunnels · ports
   │                                  · toolchain · dist freshness · log dirs
   ├─ 2. judgement ................. reuse or start? which log dir? rebuild?
   ├─ 3. plan + confirm ............. one block, explicit yes (a tunnel is public)
   └─ 4. start in background + report the URLs

Deterministic facts come from the probe; this skill only decides. It never kills a process it did not start.

Step 0 — Orient

Repo root is the checkout containing webui/server.py and scripts/lib/dashboard_probe.sh. If the user invoked this from elsewhere, locate it. An argument, if given, is the log directory to serve.

Step 1 — Probe

bash scripts/lib/dashboard_probe.sh 2>&1

Read it as-is. Everything below is a judgement over these lines; never re-probe a fact the script already reported.

Step 2 — The four decisions

2a — Is one already serving?

Two servers on two ports is fine and common. Two servers on the same log dir is just confusion. Never kill an existing instance to take its port — the probe cannot tell you whose it is, and on a shared box it is usually not yours.

<!-- A `server.py` sometimes shows as two pids (parent + thread); same port and
same log-dir means it is one instance, not two. -->

2b — Which log directory?

This is the decision that actually moves between machines, and the one to get right before anything else: a board serving the wrong directory looks perfectly healthy and shows nothing.

Rank the logdir:* lines by evidence, not by name:

1. an explicit argument or LOG_DIR from the user — always wins;
2. logdir:* with the most run logs and the freshest newest-write;
3. logdir:default (<repo>/logs) when nothing else has logs.

INFO logdir:… exists but holds no .log/.out means serving it yields an empty board — say so rather than starting it. If two candidates both look live (a sibling checkout is the usual case), ask which one; do not merge them silently. When the user wants several at once, that is what --extra-log-dir is for — the primary stays the one with the runs they care about.

<repo>/logs is NOT where the runner writes any more

Since the config/template refactor, scripts/templates/verl/common.env:126 derives

TRAIN_LOG=${HARBOR_LOG_DIR}/${TRAINER_EXPERIMENT_NAME}.log

and a real config overrides HARBOR_LOG_DIR to a per-experiment directory under the shared trials root (<trials-root>/<project>/<exp>/logs). Only the template default falls back to <repo>/logs, which is why serving <repo>/logs alone can look correct and still show nothing.

server.py globs one level, no recursion (webui/server.py:133), so a board on <repo>/logs shows nothing for those runs while training is perfectly healthy.

The probe reports this directly — act on these lines, never assume:

Two fixes, both fine; pick by how many runs and whether the board is already up:

• --extra-log-dir <exp>/logs per run dir — explicit, but needs a restart, and you add a flag for every new exp;
• ln -s <exp>/logs/<exp>.log <served-dir>/<readable-name>.log — no restart (run discovery re-globs per request), and the name becomes the run's id in the UI. The trials/exp-dir mapping for the analysis panels is parsed out of the log contents, not the filename, so any readable name works.

Never move a run log to make it visible — the runner is holding it open through tee, and a stale symlink left under a log dir is its own outage (webui/server.py:141).

Say which directories you scanned

Whatever you decide, the plan and the final report must name the directories being served and account for any logdir:offrepo line — including the ones you chose to leave out. "The board is up" while a live run is invisible is the exact failure this skill exists to prevent, and the user cannot see the probe output.

2c — Does the frontend need rebuilding?

Rebuilding needs OK node (>= 20). On WARN node, activate nvm in the same shell rather than declaring it impossible:

export NVM_DIR="$HOME/.nvm"; . "$NVM_DIR/nvm.sh"; nvm use 22

If no Node >= 20 exists at all and dist:absent, stop and say the frontend cannot be built here — serving is impossible without a bundle. If dist:stale and Node is unavailable, serving the stale bundle is a legitimate fallback; just say it is stale.

2d — Port, and whether to expose it

Take OK port:free. Honour an explicit PORT= from the user even if the probe warns it is busy — but then say who holds it.

The deliverable is a URL the user can actually open. They are usually not on this box, so http://127.0.0.1:<P> alone is not an answer — default to proposing a tunnel, and only skip it if they say local-only.

It is still an outward-facing action: a quick tunnel makes the board reachable by anyone with the URL, so it goes in the plan and waits for the yes like everything else. Never open one silently.

Before opening a new one, check the WARN tunnel lines: if one already targets the port you are about to serve, reuse it — that URL is the answer, and a second tunnel to the same port just creates a second URL to keep track of.

A quick tunnel needs no Cloudflare account, no login, and no token. cloudflared tunnel --url http://127.0.0.1:<P> gets a random *.trycloudflare.com hostname anonymously. Never ask the user for credentials for this, and never tell them to run cloudflared tunnel login — it is not required and does not make a quick tunnel any more stable.

What can actually stop you, in the order it bites on a new machine:

INFO cf:account is informational only: it reports whether a login happens to exist, never a requirement.

If the user asks for a stable URL, be straight about the three options and their real costs — none of them is "the same thing but permanent":

• quick tunnel (what this skill opens): no account, new URL on every restart.
• named tunnel: needs a Cloudflare account and a domain on it, plus cloudflared tunnel login or an API token. Gives a hostname you control. This skill does not set one up; say what it takes and let the user decide.
• Cloudflare Pages (webui/functions/): a fixed *.pages.dev URL, but it reads wandb, not local log files — so it shows different data than the board you just started. Do not offer it as a drop-in replacement.