Troubleshooting

Diagnose a Ringleader install: local status, a stuck workstation, the daemon logs, and the sendable diagnostics bundle you share with the Ringleader team.

When something is wrong — the daemon won’t start, a workstation never reaches Ready, rl shell can’t connect — Ringleader gives you a layered way to see what happened, and a one-command way to package all of it up and send it to us.

Work from the outside in:

  1. Local status — is the daemon alive, are you logged in, is the host sane?
  2. A specific workstation — what does the control plane think, and what do live probes on the workstation say?
  3. The logs — raise the detail, reproduce the problem, read what the daemon recorded.
  4. The diagnostics bundle — capture everything above as a single, secret-free .zip to share with the Ringleader team.

Local status

Run rl troubleshoot with no arguments to print a snapshot of this machine:

rl troubleshoot

It reports, all from local state (no network calls, no tokens):

  • Version — the rl CLI version and build.
  • Host / system — OS, kernel, architecture, CPU/RAM, virtualization, and disk usage for the data directory and /.
  • Daemon — whether the local daemon is running, its PID, version, uptime, and last log line. If the daemon is a different build from your CLI, it says so and tells you to run rl daemon restart.
  • SSH config include — whether your ~/.ssh/config pulls in the Ringleader- managed config, so plain ssh <workstation> resolves. If it’s missing or mis-ordered it points you at rl ssh-config install.
  • Origins / auth — each origin you’re logged in to, its URL and user, the backend version, and whether your token is still valid (validity only — never the token itself).

This is the fastest first look, and it works even when the control-plane store can’t be opened: the sections that don’t need it still render, and the missing part is named rather than hidden.

A stuck workstation

Point rl troubleshoot at a workstation to diagnose it:

rl troubleshoot my-box

You get three views stitched together:

  • Controller view — the phase, conditions, and last processing pass the control plane recorded (what Ringleader thinks is true).
  • Live probes — Ringleader connects to the workstation and checks the real thing: OS, the agent, Docker, disk, the login user.
  • Provisioning timeline — the in-VM agent’s step-by-step ledger of everything it installed and configured, with the outcome of each step.

Narrow the timeline when a workstation is busy:

rl troubleshoot my-box --failed              # only steps that failed
rl troubleshoot my-box --kind devtool --since 1h
rl troubleshoot my-box --reconcile latest    # only the most recent configuration pass
rl troubleshoot my-box --report-only         # just the in-VM ledger
rl troubleshoot my-box --json                # machine-readable ledger

The full flag list is on the workstation lifecycle & access page.

Logs and verbosity

The daemon keeps a rotating log in your data directory. The support flow is three steps, in this order:

  1. Raise the verbosity so the next run records more detail.
  2. Reproduce the problem.
  3. Capture the log (on its own, or inside a diagnostics bundle).

Raising the level first matters: at the default level the line that explains a failure may never be written. The macOS native app and the Windows tray both carry a Verbosity control on their Troubleshoot pane — raise it, reproduce, then generate a bundle. From the CLI, rl logs and the daemon’s log file cover the same ground.

The diagnostics bundle

When you want to hand the whole picture to us, generate a diagnostics bundle: a single .zip containing local status, the daemon log, and every workstation’s diagnostics — with no tokens, secrets, or private keys. It’s the one file the Ringleader team asks for.

rl troubleshoot --all --diagnostics

See Generate a diagnostics bundle for exactly what’s inside, how to make one from the CLI or the desktop apps, and the privacy guarantees.

Getting help

Stuck after all of the above? Generate a bundle and reach out — include the .zip so we can see your install without a back-and-forth. Start at ringleader.dev.