Managing workstations

You can create and configure workstations, so now you will learn to manage their lifecycle: pausing one to free up resources, bringing it back, forcing a restart, and finally deleting it. As with everything in Ringleader, lifecycle is declared state: a workstation is stopped because its spec says stopped: true, and Ringleader brings the machine into line with it. The CLI does offer workstation start and stop verbs as a convenience, but they are shorthands that set that same spec field, not a separate imperative path against the machine. At the end you will see the terminal UI, which gives you all of this interactively.

Inspecting state

Two commands cover most of what you need day to day. List your workstations and their phases:

rl workstation get -n local

Add -w to watch transitions live, which is useful whenever you have just changed something:

rl workstation get -w -n local

For the full picture of a single workstation — its phase, its headline message, and its conditions — use describe:

rl workstation describe my-first-box -n local

To see the configuration it resolves to, ask for it directly:

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

Stopping a workstation

A workstation you are not using does not need to keep running. Stop it declaratively by setting stopped: true in the workstation’s spec (the spec: block of the manifest, the YAML file you write and apply). Edit my-first-box.yaml:

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

Apply it:

rl apply -f my-first-box.yaml

Watch the phase settle into Stopped:

rl workstation get -w -n local

The machine is halted but nothing is lost. Its disk, its installed tools, and its state all remain. You declared that you want it stopped, and Ringleader brought the real machine into line with that.

Starting it again

To bring the workstation back, set stopped to false or remove the field entirely, then apply again:

spec:
  stopped: false

rl apply -f my-first-box.yaml

It returns to Running with everything intact, and rl shell my-first-box -n local drops you back into the same environment.

The shorthand verbs

Editing a file to flip one field is the durable, reviewable way to manage a workstation whose manifest you keep in git, but for day-to-day toggling the CLI has shorthand verbs that set the same field for you:

rl workstation stop my-first-box -n local
rl workstation start my-first-box -n local

These patch spec.stopped on the stored resource, exactly as your edited manifest did, and the same control loop brings the machine along. One thing to keep in mind: if you keep the manifest in a file, the file now says one thing and the stored spec another, so the next apply -f of your file wins and may start a workstation you stopped with the verb. Whichever way you flip the field, the declarative story is unchanged.

Forcing a restart

Sometimes you want to restart a running workstation without stopping and starting it in two steps, for example to clear in-memory state. Change the value of spec.restartNonce to anything new. Ringleader notices the change and restarts the workstation:

spec:
  restartNonce: "1"

Apply it, then bump the value again ("2", "3", and so on) the next time you want another restart. The value itself does not matter. Only that it changed.

Deleting a workstation

When you are finished with a workstation, delete it by name:

rl workstation delete my-first-box -n local

Ringleader tears down the underlying machine and removes the resource. Deletion is final for that instance, so its disk and state are gone. The tutorial-tools config you wrote is a separate resource and is untouched. It would simply attach to the next workstation you label role: tutorial.

Do it all from the terminal UI

Everything above also lives in a single interactive view. Launch the terminal UI:

rl tui

This is a k9s-style management screen over your workstations, configurations, and local bindings. Each workstation shows a live status, and you can start, stop, and shell into a workstation without leaving the view. Any control planes you have signed into appear alongside your local resources. The TUI is a convenience layer over the same resource API that the individual commands use, so anything you can see there you can also reach with get and the other verbs.

What just happened?

Lifecycle management in Ringleader is the same declarative loop as everything else:

1. You changed a field in the spec, stopped or restartNonce, to describe the state you wanted: by editing the manifest, or by letting workstation start/stop set the same field for you.
2. Ringleader brought the real machine into line, moving it between Running and Stopped or restarting it, with no manual sequence of steps from you.
3. Deleting the resource told Ringleader to tear the machine down entirely, while leaving separate resources like your config in place.

Because the desired state lives in a file you control, your environments are reproducible. You can commit these manifests, share them, and recreate the same workstation later by applying them again.

Next steps

Now for the payoff. In the final tutorial you will install an AI coding agent inside the workstation and watch it use your own browser to log in, even though it is running inside the VM. Continue to Coding with Claude Code.