Troubleshooting

When something is wrong, whether Ringleader will not start on your machine, a workstation never reaches Ready, or rl shell cannot connect, there are four places to look, and one command that packages all of them up to send 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 reads only what is already on this machine, so it works offline and touches no credentials. It reports:

• 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. If the daemon cannot write its log, a log failure line says why. On Windows, an elevated line says when the daemon runs as an administrator.
• SSH config include. Whether your ~/.ssh/config pulls in the Ringleader-managed config, so plain ssh <workstation> resolves. If it is missing or in the wrong place, it points you at rl ssh-config install.
• Origins / auth. Each Ringleader server (origin) you are logged in to, its URL and your user there, its version, and whether your login is still valid. It never prints the login token itself.

This is the fastest first look, and it still works when Ringleader’s own database on this machine cannot be opened: the parts that do not need it are printed, and the part that does is named as missing rather than left out.

When this computer cannot run local workstations

The desktop app may say Local workstations aren’t available, or rl local-runtime create may stop with no local provider can run a workstation on this computer. Either way, Ringleader found no local provider it can use on this machine. Cloud workstations still work. To see why, run:

rl status

Under Local providers, each provider gets one row in one of these states:

An unavailable row lists the checks that failed in brackets, then the reason, as in vz unavailable [helper]: .... The row the daemon picked ends with default for new workstations that name no provider. Fix what the reason names, then run rl daemon restart, because the daemon picks its default when it starts. Providers lists what each local provider needs.

When docker pull fails after you removed Docker Desktop

On a Mac or a Windows PC, every docker pull may fail with an error like error getting credentials - err: exec: "docker-credential-desktop": executable file not found in $PATH. Your Docker config still names Docker Desktop’s sign-in helper, and the helper went with the app. docker compose and docker buildx can go missing the same way.

Run rl local-runtime repair-docker to fix both. After removing Docker Desktop says what it changes, and how to undo it.

A stuck workstation

Point rl troubleshoot at a workstation to diagnose it:

rl troubleshoot my-box

You get these views, in this order:

• Controller view. What Ringleader believes about the workstation: its phase, its conditions, and what happened on the last pass over it.
• Egress. This view appears only for a workstation with an egress policy. It shows the rule set Ringleader built for the workstation and the destinations it permits. It also names any destination the rule set cannot hold. If an edge VM on this machine serves the workstation, it names that too. It lists what the workstation’s Edge refused in the last 24 hours, newest first: up to 10 rows, each with the time, the destination and port, the reason and how many times it was refused. The list ends with the rl workstation egress command that shows the rest. A live reachability check dials some permitted destinations and, where it can, one the policy should block.
• Device-local port forwarding. Which port-forwarding rule (a LocalBinding) on this machine points at the workstation, and what it forwards. When none does, the section says so, because “nothing is forwarding” is usually the answer to “why can’t I reach my port”.
• Live probes. Ringleader connects to the workstation and checks what is actually there: the OS, the Ringleader agent, Docker, disk space, your login user.
• Provisioning timeline. The record the agent inside the workstation keeps of every step it ran to set the workstation up, and whether each one succeeded.

When a workstation has done a lot, narrow the timeline:

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 Ringleader daemon keeps a log on your machine: daemon.log in your data directory (~/.ringleader unless you set RINGLEADER_HOME). When you need us to look at a problem, do three things, in this order:

1. Raise the daemon’s log level so it records more detail: rl daemon log-level debug.
2. Reproduce the problem.
3. Capture the log, on its own or inside a diagnostics bundle (rl troubleshoot --all --diagnostics).

Raise the level first, because at the default level the line that explains a failure may never be written. The running daemon picks up the new level within a few seconds and keeps it across restarts. Run rl daemon log-level info to go back to the default. The rl daemon page has the details.

The desktop app’s Troubleshoot page shows two logs. Switch between App, the desktop app’s own log, and Daemon, the daemon log, and click Refresh to read the latest lines. The same page generates the bundle for you, and shows the command it runs with a Copy button. rl logs <workstation> shows a different log: the one the Ringleader agent keeps inside a workstation.

A refused write that names two builds

rl and the control plane it talks to are built at different times, and the two can disagree about what an object may contain. When a write is refused, for example with unknown field, and the two builds differ, the refusal ends with a line naming both:

This rl is 0.47.1-c0779c7733193. Origin acme runs 0.47.2-c91f3a2b7d40, which is newer than this rl.

When the two are different releases, the line says which side is older. It names no cause, because a write can be refused for another reason while the builds differ. If the control plane runs the newer release, update Ringleader on this machine and try again.

rl version prints this rl’s build and the version of the workstation agent it expects. Once the daemon has checked your control plane, it also prints the line naming both builds.

The diagnostics bundle

When you want to send us the whole picture, generate a diagnostics bundle: one .zip containing everything above, for every workstation, with no tokens, secrets or private keys in it. It is the one file we ask for.

rl troubleshoot --all --diagnostics

Generate a diagnostics bundle says exactly what is inside, how to make one from the desktop app, and what is kept out of it.

Getting help

If all of that leaves you stuck, generate a bundle and reach out. Include the .zip so we can see your install without a back-and-forth. Start at ringleader.dev.

• Diagnostics bundleCapture a single, secret-free .zip of your Ringleader install: local status, the daemon log, and every workstation, ready to share with the Ringleader team.