Generate a diagnostics bundle

Capture a single, secret-free .zip of your Ringleader install — local status, the daemon log, and every workstation — to share with the Ringleader team.

A diagnostics bundle is a self-contained .zip snapshot of a Ringleader install, meant to be mailed to the Ringleader team as-is. It gathers everything you’d otherwise collect by hand — local status, the daemon log, and per-workstation diagnostics — into one file, and it is built to contain no authentication tokens, refresh tokens, secret values, or private keys.

It’s the first thing we’ll ask for when you open a support conversation.

Make one

From the desktop app

The macOS native app and the Windows tray both have a Troubleshoot pane with a one-click Generate diagnostics bundle button.

  1. Open the app’s settings and go to the Troubleshoot pane.
  2. (Recommended) Raise Verbosity, reproduce the problem, so the log captures detail.
  3. Click Generate diagnostics bundle.

The app writes a timestamped .zip into your Ringleader data directory and reveals it for you — in Finder on macOS, in Explorer on Windows — so you can attach it to an email or a chat. If some items couldn’t be collected, the bundle is still written (and revealed); it just notes what was skipped.

The pane also shows the exact command it runs, so a CLI-comfortable user can copy and run it directly.

From the command line

rl troubleshoot --all --diagnostics

This is what the desktop button runs. It writes ./ringleader-diagnostics-<timestamp>.zip in the current directory and prints the absolute path it wrote.

CommandWhat it captures
rl troubleshoot --diagnosticsLocal diagnostics only (no workstation info).
rl troubleshoot --all --diagnosticsLocal diagnostics plus every workstation.
rl troubleshoot my-box --diagnosticsLocal diagnostics plus just my-box.
rl troubleshoot --diagnostics=out.zipWrite to an explicit path instead of the default.

--all dials every workstation over SSH, so a large fleet takes a little longer to capture.

Note

The bundle is built entirely in-process — it never shells out to a zip tool — so capturing diagnostics never depends on what’s installed on your machine.

What’s inside

README.md                     what this bundle is, how it was made, and the privacy guarantee
diagnostics/
    host.md                   OS, kernel, virtualization, CPU/cores, RAM, disk usage, architecture
    daemon.md                 the local daemon: running? since when? version, PID, heartbeat, last log line
    origins.md                per origin: name, URL, user, backend version, token validity (no tokens)
    versions.md               the rl CLI version and build
    daemon.log                the daemon log, trimmed to its most recent tail (across rotated backups)
    COLLECTION.md             every item the bundle tried to collect: OK / FAILED, with the error
workstations/
    <namespace>__<name>/
        troubleshoot.txt      the `rl troubleshoot <name>` output (controller view + probes + timeline)
        workstation.yaml      the Workstation object (spec + status + conditions)
        report.json           the raw in-VM provisioning ledger, when one was captured

The workstations/ folder is present only when you captured with --all or named a workstation. A *.error file next to an expected entry means that item failed to collect; its content is the error.

Collection is best-effort. Any single item can fail — a workstation that’s powered off, a probe that isn’t available — without aborting the rest. Every failure is recorded loudly: on your terminal, in diagnostics/COLLECTION.md inside the archive, and in the command’s exit code. A partial bundle is still useful, and is still written as long as the destination is writable.

This is also the “when everything is broken” command: if the control plane itself can’t start, the bundle still captures the host facts, the daemon status, and — most importantly — the daemon log, and records why the rest is missing.

How to read it

If you’re opening a bundle someone sent you, start at the top:

  1. diagnostics/COLLECTION.md — what was and wasn’t captured.
  2. diagnostics/host.md + diagnostics/daemon.md — is the environment sane and is the daemon alive?
  3. diagnostics/origins.md — is the user logged in, and is the token still valid?
  4. workstations/<…>/troubleshoot.txt — the per-workstation controller view, live probes, and provisioning timeline.

Privacy

The bundle is built to be safe to share:

  • No credentials. It carries no authentication tokens, refresh tokens, secret values, or private keys. The origins section reports token validity and expiry only, never the token bytes.
  • The daemon log is trimmed and lightly redacted. Only the most recent tail is included, and it’s passed through a redaction pass over obvious token-shaped values and private-key blocks.
  • Secret references stay references. A workstation’s YAML may contain ${secret:NAME} references — these are resolved only when they’re actually needed and never written into the bundle, so no secret value is present.

The redaction is defense-in-depth, not the guarantee: the guarantee is that Ringleader never writes a credential into the archive in the first place. Still, if your environment is known to log sensitive data, give the daemon log a glance before forwarding.

See also