Install on macOS

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

• the Ringleader macOS native app: a native app that lives in your menu bar, runs the local container runtime, and boots your workstations, and
• the rl CLI (plus the bundled docker, kubectl, kind, lima, and limactl tools), placed on your PATH.

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 and is designed to replace it.

1. Download the installer

Download the latest Ringleader-<version>.pkg from the link your beta invitation provided. Save it somewhere easy to find, such as your Downloads folder.

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 symlinks. When it finishes you will see a confirmation screen.

What gets installed

The package installs the app and symlinks the bundled command-line tools into /usr/local/bin (and the Docker CLI plugins into /usr/local/lib/docker):

Ringleader owns these names as a Docker Desktop replacement: if a real file already exists at one of these paths, it is backed up to <name>.pre-ringleader and restored if you later uninstall.

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. Start the app

Open Ringleader from /Applications (or Spotlight). On first launch it starts a background rl daemon, the control loop that boots workstations and forwards the Docker socket.

5. Complete first-run onboarding

The first time it runs, the app shows a short onboarding wizard with a few opt-in actions: sign in to Ringleader Cloud, create the local container runtime, and launch at login. Pick the ones you want, or skip and do them later from Settings.

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 for a live list of your workstations with status pills and per-row start / stop / shell controls.

The Settings window

Choose Settings from the menu-bar app to configure Ringleader. The window groups options into several panes (General, Local Container Workstation, Account & Local, Tools, and Troubleshoot) plus an About pane that shows the installed app and daemon versions. For what each pane does, see the Settings reference.

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:

# Create ~/.ssh/config if you don't have one.
mkdir -p ~/.ssh && chmod 700 ~/.ssh
touch ~/.ssh/config && chmod 600 ~/.ssh/config

# Add the Include as the FIRST line (see the warning below).
printf 'Include ~/.ringleader/ssh/config\n\n%s\n' "$(cat ~/.ssh/config)" > ~/.ssh/config.new \
  && mv ~/.ssh/config.new ~/.ssh/config

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.

See Using ssh directly in the CLI reference for the host aliases, what each generated block contains, and the caveats.

Uninstalling

To remove Ringleader, quit the app, then delete the bundle and the symlinks that point into it (Ringleader only ever created symlinks, so removing the ones that resolve into Ringleader.app is safe):

# Stop the app and its daemon first.
pkill -f Ringleader.app
rl daemon stop 2>/dev/null || true

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

# Remove the CLI symlinks that point into the bundle, restoring any backup.
for f in /usr/local/bin/rl /usr/local/bin/ringleader /usr/local/bin/docker \
         /usr/local/bin/kubectl /usr/local/bin/kind /usr/local/bin/lima \
         /usr/local/bin/limactl; do
  [ -L "$f" ] && readlink "$f" | grep -q Ringleader.app && sudo rm -f "$f"
  [ -e "$f.pre-ringleader" ] && sudo mv -f "$f.pre-ringleader" "$f"
done

Your data directory (~/.ringleader) is left in place; remove it too if you want a completely clean slate.