Workstation

A Workstation is the central resource: one managed machine, kept in line with its declared spec. The provider can be a local VM (qemu on Linux, lima on macOS) or a remote cloud VM. You declare intent in spec; the control plane and in-VM agent write status.

apiVersion: workstations.ringleader.dev/v1
kind: Workstation

A workstation is namespaced. Its effective configuration is the merged configuration of every WorkstationConfig that attaches to it (by selector or explicit reference) plus the workstation’s own inline spec. That merge is computed on demand rather than stored in status — read it with rl workstation get-resolved-configuration.

Minimal example

Everything is implicit: a provider is chosen by automatic placement, and configs attach by selector.

apiVersion: workstations.ringleader.dev/v1
kind: Workstation
metadata:
  name: hello-ws
  namespace: dev
  labels:
    tier: dev
spec: {}

Spec fields

You author these. Many are config-layer fields: they can also be set on a WorkstationConfig and merged in.

Placement & provider

Lifecycle

Expiry (ttl)

spec.ttl gives a workstation a deadline the control plane enforces on its own, with no client involved. It exists for the case where nothing is left to clean up after you: a CI job killed outright, or a machine you meant to keep for an afternoon.

apiVersion: workstations.ringleader.dev/v1
kind: Workstation
metadata:
  name: ci-run-4821
  namespace: dev
spec:
  ttl: 2h            # gone two hours after it was created
  ttlAction: delete  # the default

• The duration is a plain unit string — 45s, 90m, 2h, 720h — plus a whole number of days, 7d. It must be positive; a value that cannot be read, or a zero or negative one, is rejected when you apply it rather than being silently ignored.
• The clock starts at creation and nothing moves it — not a stop, not a start, not a restart. A stopped cloud VM still bills for its disks, so a deadline that reset on a power cycle would be the wrong promise. Editing spec.ttl is the one thing that moves the deadline, and it takes effect immediately.
• ttlAction: delete (the default) removes the workstation and destroys the machine and its disk, exactly as rl workstation delete would. ttlAction: stop powers it down and leaves it there, so its disk and state survive and you can start it again.
• Enforcement is periodic, so a workstation can sit briefly past its deadline before the action lands. Treat the deadline as “at or shortly after this”, not as a precise instant.
• The deadline is published as status.expiresAt, and rl workstation get grows an EXPIRES column — counting down, or expired — as soon as any listed workstation declares one.

Configuration attachment

Machine contents (config-layer fields)

System settings (config-layer fields)

Status fields

The system writes these. They are read-only.

Lifecycle phases

Pending → Provisioning → PostInstall → Running
                                          │
                          (spec change) → Reconfiguring → Running
                          (stopped: true) → Stopping → Stopped
                                                          │
                                            (start) → Starting → Running

Stopping and Starting are real phases, not instant transitions: a power operation is issued, and it rests in them until the machine is confirmed down (or back up). Starting means an existing machine is powering on, as opposed to Provisioning, which means one is being created.

A workstation is fully configured when status.config.appliedHash equals status.config.effectiveHash and its Configured condition is True.

A configuration verdict never outlives the boot that produced it: stopping a workstation clears appliedHash and sets Configured to False, so a stopped workstation never claims a configuration it applied on a previous boot.

Conditions and their reasons

Four conditions are defined — three always published, plus ToolsReady once a tool has failed. Each carries a reason — a short machine token — and a human message. Available is the one to gate on: it is the aggregate that answers “is this workstation usable yet?”, and the CLI, the TUI and the desktop apps all fold it into the single status they show.

Available reasons

Configured reasons

While ToolsReady is present its reason names the step that failed; it flips to Installed once a workstation that previously failed has every declared tool present.

See also

• WorkstationConfig: the reusable layers a workstation merges.
• Configuration tutorial: a worked browser-IDE example.