Install on macOS

Ringleader ships for macOS as a signed installer package (.pkg). Installing it gives you two things at once:

• the Ringleader app: one window, opened from an icon in your menu bar, that runs the local container runtime and boots your workstations, and
• the rl CLI, placed on your PATH, along with the bundled docker, kubectl, kind and helm wherever you don’t already have your own.

Requirements

• A Mac with Apple Silicon (M1 or newer).
• macOS 13 (Ventura) or later.
• Administrator rights (the installer creates symlinks under /usr/local/bin).

You do not need Docker Desktop: Ringleader bundles its own container runtime. If you already use Docker Desktop, OrbStack, Colima or Rancher Desktop, Ringleader installs alongside it. The installer leaves your existing docker command where it is, and the first-run wizard switches docker to Ringleader’s runtime only if you ask it to. What gets installed has the details.

1. Download the installer

How you download depends on the invitation email you received:

• A Download Ringleader button opens your personal download page. Download Ringleader-<version>.pkg there.
• A Sign in to Ringleader button means you sign in first. Sign in at app.ringleader.dev with that address, using your Google account, open Downloads in the top menu, and download the latest Ringleader-<version>.pkg.

2. Run the installer

Double-click the .pkg to launch the macOS Installer, then follow the steps.

Click Continue through the introduction, and review the license if one is shown, then click Install. macOS will ask for your password to authorize the installation.

The installer copies Ringleader.app into /Applications and creates the command-line links described below. When it finishes you will see a confirmation screen.

What gets installed

The package installs the app, and links its command-line tools into /usr/local/bin for your terminal. The Docker CLI plugins go into /usr/local/lib/docker/cli-plugins:

If Docker Desktop, OrbStack, Homebrew or anything else already put one of these tools at its path, the installer leaves it exactly as it is, and your terminal keeps using it. The installer log, /var/log/install.log, names each path it left alone with Skipped (not ours). A link whose target no longer exists is the one exception: the installer replaces it. Dragging Docker Desktop to the Trash leaves one of those at /usr/local/bin/docker.

rl and ringleader are Ringleader’s own names. If something else is at one of those two paths, the installer moves it to <name>.pre-ringleader, and uninstalling puts it back.

Ringleader runs vz, and Lima for the workstations that use it, from inside the app. None of lima, limactl or the vz helper ringleader-vz is added to your PATH. If you use Lima yourself, your own copy stays the one your terminal runs.

sudo ln -sf /Applications/Docker.app/Contents/Resources/bin/docker /usr/local/bin/docker

3. Verify the install

Open a new terminal (so it picks up the updated PATH) and confirm the CLI is available:

rl version
which rl
# /usr/local/bin/rl

4. Open the app

When you install Ringleader for the first time, the installer opens the Ringleader window as it finishes, so you can go on to step 5.

The window does not open on its own after an upgrade, or after an install you ran from a terminal with installer -pkg. An upgrade starts Ringleader again in the menu bar if it was running before. To bring up the window, open Ringleader from /Applications or Spotlight. If it was not already running, it starts in the menu bar without a window, so click the Ringleader mark in the menu bar to open it.

Each time the app starts, it also starts a background rl daemon, the control loop that boots workstations and forwards the Docker socket.

5. Complete first-run onboarding

Until you sign in or create a workstation, the Ringleader window shows a short onboarding wizard with four opt-in actions: sign in to Ringleader Cloud, create the local container runtime, set up ssh for workstations, and launch at login. Pick the ones you want, or skip and do them later from Settings. Creating the runtime switches docker in every terminal to it, so on a Mac that already uses another Docker runtime the wizard leaves that option unticked.

See Onboarding for a full walkthrough of signing in and bringing up your first workstation.

6. Find the app in the menu bar

Ringleader lives in the macOS menu bar, near the clock and Control Center icons. Look for the Ringleader mark there rather than in the Dock. Click it to show or hide the Ringleader window. The window opens on its Workstations page, which lists your workstations with a status for each and per-row start, stop, shell and Open in VS Code buttons. Closing the window hides it and the app keeps running in the menu bar. The mark shows a dot while something is waiting for you, such as a sign-in awaiting approval. Quit from the bottom of the window’s sidebar.

The window’s pages

The window’s sidebar has seven pages: Workstations, Local runtime, Account, Bundled Tools, Settings, Troubleshoot and About, which shows the installed app and daemon versions. For what each page does, see The app’s pages.

Optional: reach workstations with plain ssh

rl shell is a convenience, not a requirement. The daemon continuously writes a real OpenSSH configuration for your workstations under ~/.ringleader/ssh/, and keeps it current as workstations come and go. Wire it into your own SSH config once:

rl ssh-config install

From then on ssh my-box, scp, rsync, sftp, git clone my-box:repo.git, and VS Code / Cursor Remote-SSH all reach your workstations by name, with the host key pinned and connections multiplexed.

The command adds one Include line at the top of ~/.ssh/config and leaves the rest of the file alone. What it writes, and how to check or remove it, is in rl ssh-config. Using ssh directly has the host aliases and what each generated block contains.

Uninstalling

To remove Ringleader, quit the app, then remove the command-line links that lead into it, and then the app itself. Remove the links first, while they still resolve. The installer only ever created links, and it moved aside anything it found at rl or ringleader, so these steps put back exactly what was there before. If you turned on Let tools find Docker at /var/run/docker.sock in Settings, they also remove that link and the startup job that makes it again:

# Stop the app and its daemon first. This also asks every vz workstation to
# shut down.
pkill -f Ringleader.app
rl daemon stop 2>/dev/null || true

# Give the vz workstations up to 90 seconds to power off, then stop any that
# remain.
helper=/Applications/Ringleader.app/Contents/Resources/bin/ringleader-vz
for _ in $(seq 45); do
  pgrep -f "^$helper" >/dev/null || break
  sleep 2
done
pkill -9 -f "^$helper" || true

# Find the links that lead into the app. `ringleader` leads there through `rl`,
# so check every one before removing any.
ours=()
for f in /usr/local/bin/{rl,ringleader,docker,kubectl,kind,helm,lima,limactl} \
         /usr/local/lib/docker/cli-plugins/docker-{compose,buildx} /usr/local/share/lima; do
  if [ -L "$f" ] && realpath "$f" 2>/dev/null | grep -q '^/Applications/Ringleader.app/'; then
    ours+=("$f")
  fi
done

# Remove them, and put back anything the installer moved aside.
for f in "${ours[@]}"; do
  sudo rm -f "$f"
  if [ -e "$f.pre-ringleader" ] || [ -L "$f.pre-ringleader" ]; then
    sudo mv "$f.pre-ringleader" "$f"
  fi
done

# Remove the startup job that links /var/run/docker.sock to the local runtime,
# and the link itself when it leads where the job points it. If you never turned
# the setting on, these change nothing.
job=/Library/LaunchDaemons/dev.ringleader.default-docker-socket.plist
target=$(/usr/libexec/PlistBuddy -c 'Print :ProgramArguments:2' "$job" 2>/dev/null)
if [ -n "$target" ] && [ "$(readlink /var/run/docker.sock)" = "$target" ]; then
  sudo rm -f /var/run/docker.sock
fi
sudo launchctl bootout system/dev.ringleader.default-docker-socket 2>/dev/null || true
sudo rm -f "$job"

# Remove the app.
sudo rm -rf /Applications/Ringleader.app

If the local container runtime switched docker to Ringleader’s context, switch it back too: docker context use desktop-linux for Docker Desktop, for example, or docker context use default.

Your data directory (~/.ringleader) is left in place. It holds the disks of your local workstations, vz ones included. Remove it too only if you want a completely clean slate and no longer need them.