Onboarding & your first workstation

The first time you launch the Ringleader macOS native app it runs a short onboarding wizard and starts a background rl daemon, the control loop that boots workstations, delivers the in-VM agent, and forwards the Docker socket. This page walks through onboarding and then brings up your first workstation.

The onboarding wizard

Onboarding shows once on a fresh install and offers three opt-in actions. Pick the ones you want; you can do any of them later from Settings.

1. Sign in to Ringleader Cloud

Signing in federates your machine with the Ringleader control plane so you can create cloud workstations and share configuration. The app uses a device-code flow: it opens your browser to a verification page and shows you a short code to confirm.

The app already knows which control plane to use, so the wizard’s Sign in button is the easiest path. To do the same from the command line, pass your control-plane URL (the app pre-fills it for you):

rl auth login https://your-control-plane.example.com

Confirm you are signed in:

rl auth status

2. Create the local container runtime

Ringleader replaces Docker Desktop with a local Linux VM running dockerd. Under the hood it forwards the Docker socket to your Mac and sets up a ringleader Docker context, but you don’t need to think about any of that. Once it is up, the bundled docker CLI just works:

docker context use ringleader
docker ps

Ports a container publishes are forwarded to your machine’s localhost automatically, the way Docker Desktop behaves — so a container started in the runtime is reachable from your own browser and tools with no extra step:

docker run -d -p 8888:80 nginx
curl localhost:8888        # works from your machine

Only ports a container actually publishes surface this way; the runtime’s own system services are not exposed.

The local runtime lives in the reserved local namespace and appears in the menu-bar app’s workstation list like any other workstation.

3. Launch at login

Check Launch at login during onboarding to start Ringleader automatically when you sign in, so the daemon and your runtime are always ready. You can change this anytime from Settings → General → “Launch Ringleader at login” (see the Settings reference), and macOS also exposes the same toggle under System Settings → General → Login Items.

After onboarding

The menu-bar app shows a live list of your workstations with status pills and per-row start / stop / shell controls. The Settings window has an Account & Local pane (identity, backend version, token expiry) and a Local Daemon section with Start / Stop / Restart and a Troubleshoot view.

Boot your first workstation

A workstation is just a resource. The simplest possible way to configure a workstation is to specify nothing at all. Ringleader picks where to run the workstation for you (the provider, here a local Linux VM on your Mac) and fills in sensible defaults, so you get a working Linux machine without configuring anything:

rl workstation create my-first-box

Or describe it declaratively in a manifest, a YAML file you write and apply like kubectl. Create my-first-box.yaml:

apiVersion: workstations.ringleader.dev/v1
kind: Workstation
metadata:
  name: my-first-box
  namespace: local
spec: {}

rl apply -f my-first-box.yaml

Ringleader records it and reports what it did and where the resource now lives:

workstation/my-first-box created → self (reserved local namespace)

The arrow is placement feedback: self means this machine’s own store, and the reserved local namespace always stays on your device.

Watch it come up

The rl create or rl apply command from the last step begins the process of starting up your workstation in the background. It moves through several lifecycle phases as it does (Pending → Provisioning → PostInstall → Running), so watch its progress in the menu-bar app (the live list with status pills) or in the terminal by running the commands below. In the table’s STATUS column you will see these phases go by, then Ready once the workstation is up and fully configured.

rl workstation get -w
rl workstation wait my-first-box --for Ready --timeout 10m

For a human-friendly summary of phase, headline message, and conditions:

rl workstation describe my-first-box

Connect

Once it shows Ready, open a shell:

rl shell my-first-box

rl shell connects over SSH using the node key, resolving the address and login user from the workstation’s status. Run a one-off command instead of an interactive shell by appending it:

rl shell my-first-box -- uname -a

That’s it. The environment is persistent. Stop it, come back tomorrow, and it picks up where you left off. Apply the same file again and Ringleader brings the machine back in line with it.

Next, learn how to make these environments do real work in Configuration.