Adding tools

In the first tutorial you brought up a bare workstation. Now you will give it real tools. Along the way you will meet the second half of Ringleader’s resource model: the configuration layer, and the way it attaches to a workstation through labels rather than direct references.

Two resources, one environment

Ringleader deliberately separates what to install from which machine:

• A Workstation is an instance, the machine itself.
• A WorkstationConfig is a reusable layer of contents and settings: packages, development tools, ports, environment variables, and more.

Keeping them apart means one config can apply to many workstations, and one workstation can pick up several configs. A config attaches to a workstation in one of two ways. It can match by selector, where the config’s spec.selector.matchLabels line up with the workstation’s metadata.labels, or it can be referenced explicitly from the workstation’s spec.configs. In this tutorial you will use the selector approach, because it is how shared, team-wide configuration spreads without anyone editing each workstation by hand.

Step 1: Label the workstation

Open your my-first-box.yaml from the previous tutorial and give it a label so a config can find it:

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

Apply the change:

rl apply -f my-first-box.yaml

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

The verb tells you what apply did: created (new resource), configured (the stored resource changed), or unchanged (it already matched).

The workstation itself is unchanged so far. The label is just a handle that a config can grab.

Step 2: Write a configuration

Create a new file called tutorial-tools.yaml:

apiVersion: workstations.ringleader.dev/v1
kind: WorkstationConfig
metadata:
  name: tutorial-tools
  namespace: local
spec:
  # Attach to every workstation in this namespace whose labels match.
  selector:
    matchLabels:
      role: tutorial

  # OS packages. Each entry is a bare name, or an object with a version and an
  # update policy when you need that control.
  packages:
    - git

  # Curated install recipes, installed inside the VM by the devtool registry.
  devtools:
    - name: nodejs

Notice that this config never names my-first-box. It only says “any workstation labelled role: tutorial.” That indirection is what lets the same config land on one machine today and a teammate’s machine tomorrow.

Apply it:

rl apply -f tutorial-tools.yaml

Because your workstation carries the matching label, Ringleader pairs the two and begins installing git and Node.js inside the VM in the background.

Step 3: Wait for the tools to land

Installing tools is real work that happens inside the VM, so it takes a little time. Wait until the in-VM agent has applied everything:

rl workstation wait my-first-box --for condition=Configured --timeout 15m -n local

The Configured condition is Ringleader’s signal that the effective configuration has been fully applied on the workstation, as opposed to Ready, which only means the machine is up. When you add or change tools, Configured is the one to wait on.

Step 4: See the merged result

Before you connect, look at how Ringleader combined the workstation and its config. Every matching config plus the workstation’s own spec is merged into one effective spec, which you can ask for directly:

rl workstation get-resolved-configuration my-first-box -n local

Under effective, the output shows git in packages and nodejs in devtools, even though neither appears on the workstation itself. appliedConfigs names the config that contributed them and says it arrived by selector — the label match you just wrote. That merged view is the source of truth for what actually gets installed.

Step 5: Confirm inside the VM

Open a shell and check that the tools are really there:

rl shell my-first-box -n local

git --version
node --version
npm --version

You should see real versions for all three. When you are done, leave with exit or Ctrl-D.

What just happened?

You introduced the configuration layer and let label matching do the wiring:

1. You gave the workstation a label, a plain key and value with no meaning of its own.
2. You wrote a WorkstationConfig that selects workstations by that label rather than by name.
3. Ringleader matched the two, merged the config with the workstation’s spec into one resolved spec, and the in-VM agent installed the packages and devtools to make the real machine match.
4. The workstation reported Configured once everything had been applied.

Nothing about this depended on my-first-box specifically. Label another workstation role: tutorial and it would pick up exactly the same tools, which is how a team keeps many environments consistent from a small set of shared configs.

Next steps

You now have a configured workstation. Next you will learn to manage its lifecycle, stopping, starting, restarting, and deleting it, and to do all of it from a single terminal UI. Continue to Managing workstations.