Your first workstation

Go from an empty machine to a shell on a local Ringleader workstation, and learn the core apply-and-connect loop.

In this tutorial you will go from nothing to a shell inside a Linux virtual machine running on your Mac. By the end you will know the core Ringleader loop that every other tutorial builds on: write a manifest, apply it, and connect.

Note

Already booted my-first-box during Onboarding? Then you have run this flow once. This tutorial slows down and explains each piece (the manifest fields, namespaces, and the lifecycle phases), and the rest of the series builds on the workstation it creates. Skim it, or jump ahead to Adding tools.

Before you begin

This walkthrough uses macOS with the local runtime. The steps and every command are the same on other platforms; only the install differs, so Windows users can follow along after Install on Windows. The apply-and-connect loop you learn here is identical whether the workstation runs locally or in the cloud.

You need Ringleader installed on your machine. If you have not done that yet, follow Install on macOS and then return here. You do not need a Ringleader Cloud account for this tutorial, because the workstation runs locally.

Confirm the CLI is on your path:

rl version

What you will build

A single Linux workstation that runs locally through Ringleader’s bundled container runtime. No cloud account, no manual setup, just one file and one command.

Step 1: Write the manifest

Ringleader environments are described declaratively, the same way you would describe resources to kubectl. Create a file called my-first-box.yaml with the smallest possible workstation:

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

Here is what each field means:

  • apiVersion names the resource’s API group and version. Workstation resources belong to the workstations.ringleader.dev group, and v1 is the version of their schema. Together they tell Ringleader how to interpret the rest of the file.
  • kind: Workstation tells Ringleader this manifest defines a workstation, the resource that becomes a real machine.
  • metadata.name is the name you will use to connect to, stop, and delete this workstation. It must be unique within its namespace.
  • metadata.namespace: local places the workstation in the reserved local namespace, which is where your machine’s own runtime lives. It is the natural home for local, single-developer work.
  • spec: {} is intentionally empty. With nothing specified, 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 clean Linux workstation without choosing anything yourself.

Note

YAML is sensitive to indentation. Use spaces rather than tabs, and keep nested fields indented consistently by two spaces.

Where does this file live?

Wherever you want. my-first-box.yaml is just the input you hand to rl apply; Ringleader reads it once and records the desired state as a resource in its own store, keyed by metadata.name and metadata.namespace, not as a copy of the file. Nothing later depends on this file staying in this folder, keeping this name, or even continuing to exist, only on you handing the same content to apply again when you want to change something. For real projects, keep it in your repository under version control. See Where manifests live for more.

Step 2: Apply the manifest

Apply the file to create the workstation:

rl apply -f my-first-box.yaml
workstation/my-first-box created → self (reserved local namespace)

apply is declarative and safe to re-run. Running it again with the same file brings the workstation in line with your file and reports unchanged when nothing differs, so you can re-apply as often as you like. If you already created my-first-box during onboarding, this very first apply answers unchanged for the same reason: the stored resource already matches your file.

Step 3: Watch it come up

Note

The commands below take -n local to match the namespace: local in your manifest. When you omit -n, Ringleader targets your default namespace, which is local for local-only use but becomes your control plane’s namespace once you are logged into one. Passing -n local keeps these commands pointed at your local workstation either way.

A workstation moves through several lifecycle phases as Ringleader brings it into line with the state you declared:

Pending  →  Provisioning  →  PostInstall  →  Running

The phases advance in the background from the moment you apply, so depending on how quickly you run the next command you may catch the workstation mid-flight or already Running. Watch the transitions live:

rl workstation get -w -n local

You will see the STATUS column advance through the boot phases and settle at Ready once the workstation is up and fully configured. The first time you create a local workstation, Ringleader downloads the default base image (Debian 13), which can take a few minutes depending on your connection; rl describe reports the exact image the workstation was created from. Later workstations on the same image start much faster because the image is cached.

You can also block until the workstation is ready instead of watching:

rl workstation wait my-first-box --for Ready --timeout 10m -n local

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

rl workstation describe my-first-box -n local

Step 4: Connect

Once the workstation reports Ready, open a shell:

rl shell my-first-box -n local

You are now inside the VM. The prompt changes to reflect the workstation, and rl shell has set up the SSH session for you using the workstation’s node key. You did not configure SSH, copy a key, or look up an address. Ringleader resolved all of that from the workstation’s status.

Step 5: Look around

Run a few commands inside the VM to confirm everything is working:

cat /etc/os-release      # which Linux distribution you are on
whoami                   # the login user Ringleader set up
free -h                  # available memory

When you are done exploring, leave the shell by typing exit or pressing Ctrl-D.

Step 6: Notice that it stays

Back on your Mac, check the workstation again:

rl workstation get -n local

It is still Ready. Leaving the shell does not stop the workstation. It stays up and waiting for you to reconnect, and it keeps its state. Close your laptop, come back tomorrow, run rl shell my-first-box -n local again, and you are right where you left off. This persistence is the whole point: the environment is a durable thing you return to, not something you rebuild each morning.

What just happened?

You completed the loop that the rest of Ringleader is built on:

  1. You wrote a manifest describing the workstation you wanted.
  2. rl apply recorded that desired state and handed it to the local control loop.
  3. The control loop provisioned a real Linux VM through the bundled runtime, working through the lifecycle phases on its own. You never told it the order in which to do things. You only told it the result you wanted.
  4. rl shell opened an SSH session into the workstation, resolving the address and login user from its live status.

This same pattern, manifest then apply then connect, is identical for a workstation running in the cloud. The only thing that changes is where the machine runs, which you will see in a later tutorial.

Next steps

Your workstation is running, but it is a bare Linux install with no tools yet. In the next tutorial you will add development tools to it using a separate, reusable configuration layer. Continue to Adding tools.