Workstation

A Workstation is a development machine that Ringleader creates and manages for you: a VM on your laptop (vz on macOS, hcs or WSL2 on Windows, or qemu on Linux) or in your cloud account. On Windows, hcs is the default when it registers. WSL2 is the fallback when hcs does not register and WSL2 does. You describe the machine you want (OS, tools, code, settings) and Ringleader builds it and keeps it matching that description.

So you can delete the machine and get an identical one back, hand a teammate or a coding agent the same environment from the same file, and change the environment by editing the description instead of shelling in.

This page is the field-by-field reference. spec is the description you write; status is what the control plane and the in-machine agent report as actually true.

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

How long a workstation lives

A workstation nobody turned off keeps costing money, and a stopped cloud VM still bills for its disks. spec.lifecycle declares deadlines 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.

There are three things you can ask for, and they combine. Stop the workstation when nobody is using it, with idle. Stop it once the current run has gone on long enough, with maxRunTime. Delete it at a deadline, with ttl.

apiVersion: workstations.ringleader.dev/v1
kind: Workstation
metadata:
  name: ci-run-4821
  namespace: dev
spec:
  lifecycle:
    idle:
      timeout: 30m         # stopped after 30 minutes with nothing going on
      action: stop
      sshSessions: true    # an SSH session means somebody is using it
    maxRunTime: 8h         # stopped once this run has lasted 8 hours
    ttl: 7d                # deleted a week after it was created

If that is all you need, you are done. The rest of this section says what each field does on its own.

Every duration is a plain unit string (45s, 90m, 2h, 720h) or 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.

Stopping an idle workstation. lifecycle.idle powers the machine down after a period in which nothing you named as activity happened. A probe inside the workstation reports what it sees, and the control plane decides.

spec:
  lifecycle:
    idle:
      timeout: 45m
      action: stop
      sshSessions: true
      processes: ["pytest"]
      ports: [5432]

The block takes a timeout, an action, and the conditions that say what “in use” means for this workstation.

• timeout is how long every condition must agree the workstation is idle before it stops.
• action accepts only stop. A workstation that should go away declares ttl with ttlAction: delete instead. A machine that reported itself idle and then went quiet keeps its last verdict and its clock, so the timeout still elapses, which is safe only because a stop can be undone.
• sshSessions: true counts a person’s SSH session as activity.
• processes lists executable names as they appear in /proc/<pid>/comm, at most 15 characters each. A path or a wildcard is rejected when you apply it, because the probe compares the executable name and never the command line.
• ports lists ports on the machine, and counts established connections rather than listening sockets. A dev server nobody has connected to is exactly the workstation this is meant to power down.
• checkCommand is the last resort, for activity none of the others describes. A non-zero exit means the machine is in use. It runs as root on a repeating timer, so it may use only letters, digits, spaces and - _ . / = : , @ + %, at most 256 characters. Put anything longer in spec.files and name the script.

Every condition you declare must agree the workstation is idle before the timeout runs, and there is no setting that weakens that. Declaring more conditions makes a stop less likely, never more. A timeout with no condition is rejected, and so is a condition with no timeout.

Stopping a workstation after a fixed run. lifecycle.maxRunTime powers the machine down once the current run has lasted that long, whatever is happening on it. The anchor is the run rather than the creation time, so starting the workstation again gives it a fresh period: one that stops in the evening can be started the next morning. The status message names the field that stopped it and tells you to start the workstation to begin another run.

It is rejected together with ttlAction: stop, which is the older spelling of the same thing.

Deleting a workstation at a deadline. lifecycle.ttl is the delete deadline, measured from when the workstation was created. Its action is ttlAction.

• ttlAction: delete is the default. It removes the workstation and destroys the machine and its disk, exactly as rl workstation delete would. The clock starts at creation and nothing moves it, not a stop, a start, or a restart. Editing the value is the one thing that moves the deadline, and it takes effect immediately.
• ttlAction: stop is the older spelling of maxRunTime. It powers the machine down and leaves it there, so its disk and state survive and you can start it again. Its deadline is anchored on the current run rather than on creation.

Two things hold whichever deadline you declare. Declaring a lifetime twice is rejected when you apply it: the lifecycle block is read whole, so spec.ttl beside spec.lifecycle.ttlAction is rejected as well, not only the same field written in both places. And enforcement is periodic, so a workstation can sit briefly past its deadline before the action lands. Treat a deadline as “at or shortly after this”, not as a precise instant.

The next deadline is published as status.expiresAt, and rl workstation get grows an EXPIRES column, counting down or reading 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.

Fields that report a problem

Four status fields report trouble. A healthy workstation carries none of them, apart from configState while a configuration pass runs. Their absence is normal, and does not by itself prove that anything succeeded.

configState reads {state: configuring} while a configuration pass runs, and {state: failed} when the in-VM agent reports that its configuration pass keeps failing. The failed state carries the same fact as the Configured condition’s ConfigurationFailed reason, which rl workstation describe prints. It also names the failing step ({kind, target}) and a cause: disk-full, permission-denied, read-only-filesystem, network-unreachable, step-timeout or other. The Configured message and rl troubleshoot both name the cause and what to do about it.

nonFatalConfig appears while an optional step is failing: a step from a personal layer, a dotfiles fragment, a dotfiles repository, or a personal Integration’s endpoint file. An optional step blocks nothing, so the workstation still reports Configured. rl workstation describe prints it as Optional configuration, and rl troubleshoot has the failing step and its output. It clears on recovery, and on a power cycle along with the rest of the configuration verdict.

ambientAgent appears while ambient SSH_AUTH_SOCK delivery has come up short, as {profile, sshd, reason, detail, observedAt}: the two booleans say which of the env files are in place, and reason names the precondition that stopped the other. A workstation your daemon has never connected to also carries no ambientAgent, so absence alone does not prove delivery worked. rl workstation describe prints it as Ambient SSH agent, and rl troubleshoot confirms the live state with its ssh-agent-env probe. See SSHKey.

userConfig appears while Ringleader cannot set up the login user, its groups or its sudo setting, as {state, reason, since, message}. since is when the failure started and message describes it. reason says which of two problems it is:

• PushFailing: Ringleader reaches the workstation, and setting up the login user keeps failing. The Configured condition reports it as UserConfigFailed.
• Unreachable: the workstation does not answer SSH as the login user its configuration declares, so nothing can be set up. No condition reports this one.

rl workstation describe prints it as User config. It clears once the login user is set up.

Lifecycle phases

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

Available, Ready and Configured are always published. The others appear only when there is something to report. Each condition 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 takes Configured and ToolsReady into account. It ignores every condition listed after ToolsReady below, so a workstation can be Available while one of them reports a problem.

Available reasons

Ready reasons

Ready is True with reason Running once the machine is up. While the workstation is on its way there, or on its way down, the reason is the phase it is in, such as Provisioning, Starting or Stopped. When Ready is False because something needs you, the message says what, and the reason is usually one of these:

Configured reasons

The first three differ in what is actually known, and that is what decides where to look:

• ConfigurationStalled is silence, so it stays a diagnosis rather than a verdict. A failed boot-time agent bootstrap is the usual cause, but a slow install looks identical from outside, and the workstation is neither failed nor destroyed.
• ConfigurationFailed is a report, so it names a real problem. Read the agent log and the diagnostic ledger (status.diagnostics), or run rl troubleshoot.
• ConfigurationNotCompleting means the agent is alive and a pass is outstanding, so the boot console and the agent service are the two places not to look. A slow step such as a large image build and a pass that will never return look the same from outside; the workstation’s own configuration log and on-box ledger name the step.

ConfigurationNotDelivered is the only reason here that does not send you inside the machine, because the problem is upstream of it. UserConfigFailed is about the login user rather than the applied configuration, so a workstation can carry it while its configuration hashes match exactly.

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.

Finished reasons

Finished tells you when a job you run on the workstation, such as a CI build, has ended and what it exited with. To report one, have the job write its exit status as a number from 0 to 255 to ~/.ringleader/job-exit in the login user’s home:

mkdir -p "$HOME/.ringleader"
make test; echo $? > "$HOME/.ringleader/job-exit"

Then wait for it from anywhere, whatever the job exited with:

rl wait workstation my-box --for=condition=Finished

Finished is True for a failed job too, because it reports that the job is over. The reason and the message carry the result. A failed job says nothing about the workstation’s health, so Finished counts toward neither Configured nor Available. A workstation that has never reported a result carries no Finished condition.

EgressEnforced reasons

The reasons on the False arm say the declared policy is not in force, and why:

On a cloud, a workstation that is held closed reaches only what it needs to stay managed by Ringleader and the endpoints of its attached Integrations, until an edge instance serves its policy. It keeps running, and you can still edit it and reach it over SSH. On hcs, vz and qemu, a workstation that is held closed reaches nothing until an Edge serves it.

The reasons on the True arm say the policy is in force:

When more than one of these applies, the reason is the first that applies of BoundaryIncomplete, InboundUnreachable, DestinationUnreachable, InterceptionPending and Enforced, and the message carries every sentence. On an audit policy, Audit takes Enforced’s place in that list.

A strict policy is checked when you apply the workstation. The workstation must name its provider, and the namespace must hold an Edge for that provider wherever the policy needs one, which is for a host on a cloud. An hcs, vz or qemu workstation needs no Edge, because its own network process serves it. The check is on the merged policy. It does not require a matching region or a ready edge machine, and an Edge that is being deleted does not count. EgressEnforced reports what is actually held once the workstation is set up. See Where it can be enforced.

An audit policy is checked when you apply the workstation too. The workstation must name its provider, though a WorkstationConfig that declares audit need not. The provider must be GCP, AWS, Azure, hcs, vz or qemu, and lima and wsl2 refuse the policy. On a cloud, the namespace must hold an Edge for that provider that is not being deleted, and the region is not checked. An hcs, vz or qemu workstation needs no Edge. Where you apply it matters too:

• On a control plane, the operator must have turned audit on. Until then the apply is refused with a message that says so, and only whoever runs the control plane can change that.
• On your own machine, a one-shot rl refuses audit until a daemon that supports it is running, and its message tells you to run rl daemon start. If that daemon cannot serve the workstation’s own network process, the message tells you to run rl daemon restart if the daemon is older than your rl, update rl if the daemon is newer, or declare an Edge.

Conditions that report a problem

These conditions are absent on a healthy workstation, except EgressCredential. RootDiskShortfall, SSHAdmissionMissing, PublicAddressChangeNotApplied and AgentNotReporting turn True when something needs your attention, and False once it has cleared, so their last transition time records when it cleared. SteeredWithoutServing is present only while it applies. EgressCredential runs the other way: True is the healthy state.

AgentNotReporting applies to a workstation whose in-VM agent connects out to Ringleader to fetch its configuration, which is the default for cloud workstations. A workstation that Ringleader configures over SSH never carries it. Ringleader counts the 15 minutes from the later of the last time it heard the agent and the moment the workstation reached Running, and that last time is the agent.seenAt status field. The condition counts toward neither Configured nor Available, so a workstation whose agent has stopped can still be Available.

See also

• WorkstationConfig: the reusable layers a workstation merges.
• WorkstationPool: a set of workstations built from one template and leased out one at a time.
• Integration: attaching a shared service, and the file that lets a program on the workstation find it.
• Edge: the VM that enforces a hostname destination and adds injected credentials.
• Configuration tutorial: a worked browser-IDE example.