Providers

A provider is the backend that runs a Workstation: a local VM (vz on macOS, qemu on Linux, hcs or wsl2 on Windows) or a cloud VM (GCP, Azure, AWS). A Mac that cannot run vz uses lima instead. On Windows, hcs is the default when it registers. WSL2 is the fallback when hcs does not register and WSL2 does. A local workstation needs no provider name: Ringleader places it on your machine’s default local provider. A cloud workstation names its cloud, with spec.provider: gcp or --provider gcp.

Choosing a provider

A workstation gets its provider in one of two ways:

• It names no provider, and Ringleader places it on your machine’s default local provider. rl status marks which provider that is.
• It names one with spec.provider: gcp, or --provider gcp on rl workstation create. This is shorthand for adding provider:gcp to spec.requirements. A cloud workstation always names its provider this way.

Only a Workstation can name a provider. A WorkstationConfig that sets provider or requirements is refused.

rl workstation create my-box                                     # your machine's default local provider
rl workstation create my-box --provider gcp -l cloud=gcp -n dev  # a GCP workstation

A cloud workstation lives in a namespace on a control plane, so log in first: the local namespace stays on your machine, and rl workstation create refuses a cloud workstation there. It also needs a CloudIdentity in that namespace whose selector matches its labels. --provider adds no label. The -l cloud=gcp above matches the CloudIdentity examples on this site, which select cloud: gcp. Without a matching label the workstation fails, and --wait reports the failure.

The selected backend is reported at status.provider. A local workstation that names no provider stays on the one it was created with, even if your machine’s default changes later.

Per-provider machine tuning goes in spec.providerConfig, an opaque block read from the Workstation spec only (it is not merged from config layers). Its shape is provider-specific, described below.

The local providers do not all have the same images. debian 13 and ubuntu 26.04 are the two that vz, lima, qemu, wsl2 and hcs all have, so a manifest you share with people on macOS, Linux and Windows should name one of them, with its version. ubuntu 24.04 runs on every local provider except wsl2. With no version, ubuntu is 24.04 on vz and lima, and 26.04 on qemu, wsl2 and hcs.

vz (local, macOS)

vz is the default local provider on macOS. It runs each workstation as a Linux VM on Apple’s Virtualization framework, which is part of macOS. A workstation that names no provider runs on vz.

vz needs three things from your Mac:

• An Apple Silicon Mac.
• macOS 13 or later.
• The ringleader-vz helper, which the macOS native app installs. If it is missing, reinstall the app.

rl status marks the provider your Mac uses, and says why vz cannot run when it cannot. A Mac that cannot run vz uses lima instead.

The OS images are debian 12/13 and ubuntu 24.04/26.04. With no version, debian is 13 and ubuntu is 24.04, as on lima.

providerConfig knobs (all optional, an empty config is sized to the host: all CPUs, half its RAM, half the size of its disk):

Changing cpus, memory or disk on an existing workstation stops it, applies the new size and starts it again. A disk can grow but never shrink: a smaller disk is refused, and the workstation reports the field it cannot change. A workstation that names no size keeps the one it was created with, even when your Mac’s defaults change.

apiVersion: workstations.ringleader.dev/v1
kind: Workstation
metadata:
  name: local-box
  namespace: local
spec:
  provider: vz
  providerConfig:
    cpus: 4
    memory: 8
    disk: 60

A vz workstation resolves names the way your Mac does, including names that only a VPN’s resolver or a file in /etc/resolver answers.

A lima workstation reaches anything listening on your Mac’s own 127.0.0.1. A vz workstation reaches only what Ringleader itself needs there. Nothing running in it, an AI coding agent included, reaches your Mac’s databases or model servers unless you carry them in. To carry in a service, such as a local model server, add it to a LocalBinding’s reversePorts. The workstation then reaches it at its own 127.0.0.1. A container on Docker’s default bridge network inside the workstation does not reach that port, and a container started with docker run --network host does.

A lima workstation enforces no egress policy, and it injects a credential without an Edge. A vz workstation enforces a policy and injects a credential with no Edge too. Each vz workstation has a network process on your Mac that carries its traffic. When the workstation has an egress policy, or an Integration injects a credential into it, that process acts as the workstation’s Edge. It enforces the policy by name and by address, and adds the credential. Nothing is built or downloaded for it, and a strict or audit policy is accepted when you apply the workstation.

To run that work in an edge VM on your Mac instead, a namespace administrator declares an Edge for vz.

A vz workstation created before vz gave each workstation its own address cannot be served by its own network process, and it cannot sit behind an edge VM either. With no Edge for vz, it runs on the open network and reports NoEdge on its EgressEnforced condition, or, under a strict or audit policy, it is held closed. Delete it and create it again.

Sharing folders from your Mac

mounts shares folders from your Mac into a vz workstation, so a project on your Mac is the same project inside the workstation. Each entry names a folder on the Mac and, if you want it somewhere else, where it appears in the workstation:

apiVersion: workstations.ringleader.dev/v1
kind: Workstation
metadata:
  name: local-box
  namespace: local
spec:
  provider: vz
  providerConfig:
    mounts:
      - hostPath: /Users/alice/src/app      # read-only, at the same path
      - hostPath: /Users/alice/datasets
        guestPath: /mnt/datasets
        writable: true

Write both paths plainly: no .., no doubled / and no / at the end. If that is all you need, you are done. The rest of this section covers changes to the list, what is refused, and what a share gives the workstation.

Only the Workstation’s own spec lists shares. A WorkstationConfig cannot carry providerConfig, so it cannot add a share to the workstations it reaches. lima, qemu, wsl2, hcs and the cloud providers ignore mounts and share nothing, but the list is still checked when you apply a workstation on any of them.

Changing the list stops the workstation and starts it again once. Changing only the order of the entries changes nothing.

A folder that does not exist on your Mac when the workstation starts is left out, and the workstation starts without it. rl workstation describe lists it under Shared folders not attached. Create the folder, then restart the workstation (rl workstation restart <name>) to attach it.

Inside the workstation, the files in a share belong to your Mac user, and chown changes nothing. A file the workstation writes to a writable share appears on your Mac at once, owned by your Mac user. A change you make on the Mac does not reach a program in the workstation that watches files for changes.

A guestPath is refused when you apply the workstation if it:

• is /, /bin, /boot, /dev, /etc, /home, /lib, /opt/ringleader, /proc, /root, /run, /sbin, /sys, /tmp, /usr, /var or /var/lib/docker, or a folder that holds one of them, such as /opt or /var/lib;
• is inside /boot, /dev, /etc, /opt/ringleader, /proc, /run, /sys or /usr;
• is, or goes through, a symlink in the workstation: /bin, /lib, /lib32, /lib64, /libx32, /sbin, /var/lock, /var/run or /var/spool/mail;
• ends in a space. A hostPath that ends in a space needs a guestPath of its own;
• is the same as another entry’s guestPath;
• is inside another entry’s guestPath, unless its hostPath is the folder at the same place inside that entry’s hostPath. So /Users with /Users/alice/src/app is accepted, and /mnt/data from one folder with /mnt/data/raw from another is refused;
• is too long. The limit is about 240 characters, and a space, a hyphen and each byte of a non-ASCII character count as four.

/Users, /Volumes, /private, /var/folders and folders under /mnt or /srv are accepted. The refusal names the entry and suggests sharing the folder under /mnt instead.

lima (local, macOS fallback)

Lima is the local provider a Mac uses when it cannot run vz. It runs a local Linux VM under the platform hypervisor and needs limactl on PATH, bundled with the macOS native app. The in-VM agent is downloaded over HTTP at boot, like every provider. Nothing is copied in over a mount.

A workstation that names no provider runs on lima when vz cannot run on your Mac. That is the case when:

• The Mac has an Intel processor.
• The Mac runs macOS below 13.
• The vz helper is missing, unsigned or built for a newer macOS than the Mac runs.

A workstation created on lima stays on lima, so a Mac that now runs vz by default moves none of its existing workstations. To put a new workstation on lima anyway, name it with provider: lima, as in the example below.

The OS images are debian 12/13 and ubuntu 24.04/26.04. With no version, debian is 13 and ubuntu is 24.04.

providerConfig knobs (all optional, an empty config is sized to the host: all CPUs, half its RAM, half the size of its disk):

Changing cpus, memory or disk on an existing workstation stops it, applies the new size and starts it again. A disk can grow but never shrink: a smaller disk is refused, and the workstation reports the field it cannot change. A workstation that names no size keeps the one it was created with, even when your Mac’s defaults change.

apiVersion: workstations.ringleader.dev/v1
kind: Workstation
metadata:
  name: local-box
  namespace: local
spec:
  provider: lima
  providerConfig:
    cpus: 4
    memory: 8
    disk: 60

A lima workstation enforces no egress policy: it accepts a bestEffort one and reports it as not in force, and refuses a strict or audit one. It can use credential injection. A rule adds its key on a lima workstation its Integration’s author owns, and on any other lima workstation the Integration reaches when the rule sets allowDaemonPlacement: true.

qemu (local, Linux)

qemu is the local provider on Linux. It boots a local VM from a base image and gives each workstation its own copy-on-write overlay disk. The in-VM agent is downloaded over HTTP at boot, like every provider.

qemu needs two things from the machine it runs on:

• Linux on x86-64 with KVM. Linux on arm64 is not supported.
• qemu 7.2 or later on PATH. Ringleader does not install it.

rl status marks the default. It also says whether this machine can run qemu, and why not when it cannot.

The OS images are debian 12/13 and ubuntu 24.04/26.04. With no version, debian is 13 and ubuntu is 26.04.

providerConfig knobs are flat (memory, cpus, disk), not nested under a per-cloud block:

apiVersion: workstations.ringleader.dev/v1
kind: Workstation
metadata:
  name: local-box
  namespace: local
spec:
  provider: qemu
  providerConfig:
    cpus: 4
    memory: 8
    disk: 60

A qemu workstation enforces an egress policy and injects a credential with no Edge. Each qemu workstation has a network process on your machine that carries its traffic. When the workstation has an egress policy, or an Integration injects a credential into it, that process acts as the workstation’s Edge. It enforces the policy by name and by address, and adds the credential. Nothing is built or downloaded for it, and a strict or audit policy is accepted when you apply the workstation. A qemu workstation restarts once when it gets its first egress policy or injected credential, and once more when it loses its last, because its network cards change.

To run that work in an edge VM on your machine instead, a namespace administrator declares an Edge for qemu. Moving a workstation between its own network process and the edge VM does not restart it.

A qemu workstation created before qemu gave each workstation its own address, or before Ringleader could set up the network cards its own Edge needs, cannot be served by its own network process, and it cannot sit behind an edge VM either. With no Edge for qemu, it runs on the open network and reports NoEdge on its EgressEnforced condition, or, under a strict or audit policy, it is held closed. Delete it and create it again.

wsl2 (local, Windows fallback)

wsl2 runs each workstation in its own WSL distribution. It is the default local provider only when hcs does not register and WSL2 does. A workstation already created on WSL2 stays there. To create another WSL2 workstation while hcs is available, name provider: wsl2. Installing on Windows says what the machine needs. The OS image is chosen with the ordinary image field: debian 13 (the default) or ubuntu 26.04.

providerConfig knobs (both optional):

A wsl2 workstation enforces no egress policy and cannot use credential injection. It accepts a bestEffort policy and reports it as not in force, and refuses a strict or audit one.

hcs (local, Windows)

hcs runs each workstation as its own HCS (Host Compute Service) VM, with its own Linux kernel and memory. A wsl2 workstation sees your Windows drives and can start Windows programs. An hcs workstation does neither. The Ringleader Windows app labels an hcs workstation HCS VM.

hcs is the default local provider on Windows when it registers. A workstation that names no provider runs on hcs then. If hcs cannot register and WSL2 does, a new workstation runs on WSL2. If neither registers, the daemon has no default local provider. A workstation cannot move between providers. To switch one, delete it and create it again.

hcs needs two things from your PC:

• Hyper-V and Virtual Machine Platform turned on. Open Turn Windows features on or off, tick both, and restart when Windows asks. Ringleader has tested hcs only on Windows 11 Pro.
• The Ringleader VM Service, which the Windows installer adds and starts. If it is stopped or missing, open Control Panel → Programs and Features, right-click Ringleader and choose Repair.

Creating a workstation needs no administrator rights and no membership in the Hyper-V Administrators group. The service does the work that needs them, for the Windows account that asks and for no other.

rl status lists hcs and marks it as the default, or says why your PC cannot run it. While hcs is the default and your PC can also run wsl2, the table leaves wsl2 out. You can still name provider: wsl2. rl status -o json keeps the wsl2 row and sets namedOnly to true on it.

The OS images are debian 13 and ubuntu 24.04/26.04. wsl2 has the same images except ubuntu 24.04. With no version, debian is 13 and ubuntu is 26.04, as on wsl2.

All providerConfig knobs are optional. An empty config is sized from your PC, as the table says:

Changing cpus, memory or disk on an existing workstation stops it, applies the new size and starts it again. A disk can grow but never shrink: a smaller disk is refused, and the workstation reports the field it cannot change. A workstation that names no size keeps the one it was created with, even when your PC’s defaults change.

apiVersion: workstations.ringleader.dev/v1
kind: Workstation
metadata:
  name: local-box
  namespace: local
spec:
  provider: hcs
  providerConfig:
    cpus: 4
    memory: 8
    disk: 60

The Ringleader VM Service holds each Windows account to these limits, which are fixed for now:

• At most 32 workstations, stopped ones included.
• For each workstation, at most all of your PC’s CPUs and three quarters of its memory.
• For all of the account’s running workstations together, at most three quarters of your PC’s memory. Three workstations of the default size fit in that on a PC with at least 8 GiB. A workstation that would pass it does not start until you stop another one.
• For everything the account’s workstations store, at most half the size of the drive that holds %ProgramData%, but not less than 64 GiB or more than 1 TiB. Each disk counts at its full size, even while most of it is empty. The base disks described below count too.

A request over a limit is refused, and the workstation’s status says which limit it hit.

Each workstation’s disk is layered on a base disk, which the service builds once for each image your Windows account uses. A base disk stays after you delete the last workstation that uses it, so the next workstation of that image starts without building it again. An account can keep at most 8 base disks. When a new workstation, a larger disk or another base disk needs the room, the service deletes the base disks nothing uses, least recently used first, until the request fits. If deleting all of them would not be enough, it deletes none and refuses the request.

Run rl image list to see your base disks. rl image delete <name> deletes one now, and rl image delete --unused deletes every image nothing uses, downloaded images included. The Images page describes both commands.

Each hcs workstation has a network process on your PC that carries its traffic, as on vz. The workstation reaches the internet and the other machines on your network, over IPv4 only. It does not reach your PC: connections to the PC’s own 127.0.0.1 and its own addresses are refused, and so are link-local addresses, such as a cloud’s metadata address. Nothing on your network can connect to an hcs workstation. A workstation looks up a host name’s IPv4 address through Windows' own resolver, the one your PC’s programs use.

To reach a service on your PC, such as a local model server, add it to a LocalBinding’s reversePorts. The workstation then reaches it at its own 127.0.0.1.

Each workstation’s SSH listens on a Windows loopback port that Ringleader picks, and you cannot choose it. If something else takes that port, Ringleader moves the workstation to another one and records an SSHPortMoved event.

An hcs workstation enforces an egress policy and injects a credential with no Edge. Its network process carries its traffic, enforces names and addresses, and adds credentials where a rule’s allowDaemonPlacement gate permits it. A strict or audit policy is accepted when you apply the workstation. The process also checks an Integration host marked inspect: true and records refusals and credential use on your PC.

To run that work in an edge VM on your PC instead, a namespace administrator declares an Edge for hcs. The edge VM takes about 1 GiB of your PC’s memory, and the Ringleader VM Service counts it as one of your workstations against the limits above. Moving a workstation between its own network process and the edge VM does not restart it.

An hcs workstation created before hcs gave each workstation its own address cannot be served by its own network process, and it cannot sit behind an edge VM either. With no Edge for hcs, it runs on the open network and reports NoEdge on its EgressEnforced condition, or, under a strict or audit policy, it is held closed. Delete it and create it again.

When you sign out of your last Windows session, Ringleader stops your hcs workstations, and whatever runs inside them stops too. Each one starts again once you have signed back in and the Ringleader daemon is running. The Ringleader Windows app starts the daemon at sign-in when its Launch at login setting is on. Otherwise the workstations stay stopped until you run rl daemon start or open the app.

When a workstation starts again after a sign-out, its events carry a StoppedAtSignOut warning that gives the time of the sign-out and names keepRunningAfterSignOut. Run rl workstation describe <name> to read the events.

To keep a workstation running through a sign-out, set keepRunningAfterSignOut:

spec:
  provider: hcs
  providerConfig:
    keepRunningAfterSignOut: true

Changing the value on a running workstation does not restart it. A workstation that keeps running carries on with whatever runs inside it. It holds its memory while you are away, so another account that signs in shares your PC with it.

That workstation reaches nothing after you sign out, and you cannot connect to it, because its network process runs in your Windows session and ends with it. A workstation under an egress policy stays restricted the whole time. When you sign in again, the Ringleader daemon starts each network process again once it is running itself. On the PC we measured, with Launch at login on, the workstations that kept running were reachable again two to four minutes after sign-in. Until the daemon runs, rl get shows each workstation as it was before you signed out. If a workstation’s status then says another program holds its port, stop and start it to give it a new one.

When your PC sleeps, its hcs workstations pause and carry on when it wakes, with their clocks set to the right time. Locking the screen or switching to another Windows account changes nothing for them.

If an hcs workstation does not start, run rl status. To collect what we need to diagnose it, run rl troubleshoot <name> --diagnostics. The bundle then holds hcs-host-logs.txt, with the workstation’s network log and its console output from the current and the previous start. The Windows Application event log, under the source RingleaderVM, says why the service will not start. The service’s own log is %ProgramData%\RingleaderVM\service.log, and only an elevated program can read it.

GCP (cloud)

The GCP provider creates a Compute Engine VM. It authenticates through a CloudIdentity in the workstation’s namespace, which brokers the short-lived credentials through per-organization federation, an impersonation chain, or the control plane’s own default identity. Set that up first; see the CloudIdentity reference for the credential paths, and cloud onboarding for what to configure in your account.

Machine and disk knobs live under providerConfig.gcp:

When the matching CloudIdentity declares a serviceAccount, the block appears in the output of rl workstation get-resolved-configuration and names the service account the VM runs as. To change it, edit the CloudIdentity; see Runtime identity.

The OS image is the ordinary config-layer image field (distribution + version): debian 12/13, or ubuntu 22.04/24.04/26.04, each resolved to the matching Google-published image family for the machine type’s architecture. A workstation that names no image boots debian 13:

apiVersion: workstations.ringleader.dev/v1
kind: Workstation
metadata:
  name: cloud-box
  namespace: dev
  labels:
    cloud: gcp
spec:
  provider: gcp
  image:
    distribution: debian
    version: "13"
  providerConfig:
    gcp:
      machineType: e2-standard-4
      diskGiB: 100

project and zone are typically supplied by the CloudIdentity’s overrideProviderConfig, so the workstation only needs machineType. Leaving out the image block boots Debian 13 as well.

Reachability

A GCP workstation gets an external IP by default. Use assignPublicIp: false for a workstation with no public IP that you reach privately, and networkTags to match a firewall rule of your own. See Reaching a cloud workstation for the SSH rule Ringleader writes and how to narrow it.

Azure (cloud)

The Azure provider creates a VM in one resource group, authenticating through a CloudIdentity exactly as GCP does. Ringleader synthesizes the per-VM NIC in the subnet you give it (and tears it down with the VM), so subnetId is required unless you supply a pre-existing NIC.

spec:
  provider: azure
  providerConfig:
    azure:
      subscriptionId: 22222222-2222-2222-2222-222222222222
      resourceGroup: ringleader-workstations
      location: eastus
      subnetId: /subscriptions/…/virtualNetworks/ringleader-vnet/subnets/workstations
      publicIp: true
      size: Standard_D4s_v5

The OS image is the ordinary config-layer image field (distribution + version): debian 12/13, or ubuntu 22.04/24.04/26.04, each resolved to the matching marketplace image for the size’s architecture. A workstation that names no image boots debian 13.

Placement is typically supplied by the CloudIdentity’s defaultProviderConfig, so a workstation names only the values that should differ.

Reachability

See Reaching a cloud workstation for the SSH rule Ringleader writes and how to narrow it. On Azure, Ringleader adds one rule, with a priority from 3000 to 3999, to the subnet’s network security group. Keep that priority range free in that group. A workstation with no egress policy also gets a network security group of Ringleader’s on its network interface. That group admits only TCP 22 and 2222 from outside the virtual network, from the addresses Ringleader’s SSH rule allows.

AWS (cloud)

The AWS provider creates an EC2 instance, authenticating through a CloudIdentity exactly as GCP and Azure do. Set that up first; see onboarding AWS for the IAM role and trust to create in your account, and the CloudIdentity reference for the credential path.

The OS image is the ordinary config-layer image field (distribution + version), resolved to a vendor-published public AMI: debian 12/13, ubuntu 22.04/24.04/26.04, or amazonlinux 2023. The AMI is resolved at launch, so you always get the latest patched image for the release you named rather than a pinned snapshot. A workstation that names no image boots debian 13.

spec:
  provider: aws
  image:
    distribution: ubuntu
    version: "24.04"
  providerConfig:
    aws:
      region: us-east-1
      instanceType: m6i.xlarge
      subnetId: subnet-0abc123
      securityGroupIds: [sg-0abc123]
      assignPublicIp: true

Placement is typically supplied by the CloudIdentity’s defaultProviderConfig, so a workstation names only the values that should differ.

Choosing a zone

zone places the instance in an availability zone, and how it does that depends on the subnet:

• With a subnetId, the instance takes the subnet’s zone, so zone is a check. A zone that is not the subnet’s is refused before the instance is created, and the message names the subnet’s zone.
• With no subnetId, EC2 picks a subnet of the region’s default VPC in that zone.

A zone outside region is refused. Changing zone on an existing workstation fails the workstation without stopping its instance. To move a workstation to another zone, delete it and create it again.

Security groups

Name security groups by id in securityGroupIds, by name in securityGroupNames, or both. The instance gets every group either list names. A name is looked up in the VPC of the workstation’s subnet, or in the region’s default VPC when there is no subnetId, because a group name is unique only within one VPC. A name containing * or ?, or one the VPC has no group for, is refused before the instance is created.

Both lists are read only when the instance is created. Editing either on an existing workstation changes nothing, so to change a workstation’s groups, delete it and create it again.

If neither list names a group, the instance gets the VPC’s default security group, beside the SSH security group Ringleader creates (see Reachability below). What the default group must allow depends on whether the workstation has an egress policy:

• With no egress policy, the workstation needs outbound access to finish setting up. The create is refused when the default group has no outbound rule, and the message says to set securityGroupIds to a group that allows outbound traffic.
• With an egress policy, the default group must have no outbound rule, like every other group beside the policy’s own. Two security groups explains why.

Removing the egress policy from a workstation that sits on a default group with no outbound rule leaves it with no outbound access, and the control plane logs a warning. Delete the workstation and create it again with a group that allows outbound traffic.

Reachability

An AWS workstation gets a public IP by default, so the internet gateway alone gives it egress. Use assignPublicIp: false for a private workstation reached over VPN or peering, with a NAT gateway for its egress. See Reaching a cloud workstation for the SSH rule Ringleader writes and how to narrow it. On AWS, the rule is a security group of Ringleader’s own, attached beside yours.

Reaching a cloud workstation

Ringleader creates and maintains the firewall rule that admits SSH to each cloud workstation, on TCP ports 22 and 2222. It admits any address unless the CloudAccount lists sshSourceRanges. A rule your own onboarding created still applies alongside it. The exception is an Azure workstation with no egress policy, which accepts SSH only from the addresses Ringleader’s rule allows. Writing the rule needs the egress control grant in your cloud onboarding, which is on by default. If Ringleader cannot write it, the workstation still runs and reports the SSHAdmissionMissing condition with what the cloud refused.

rl shell connects to the workstation directly. There is no bastion and no tunnel. A workstation behind an Edge that has a public address of its own is reached through a port on the edge instance instead. The Edge can turn those ports off, and you then reach the workstation over your own private network.

A workstation’s public address is set when its VM is created. Changing the setting later on the workstation fails it. A change that comes from a CloudIdentity or the CloudAccount is reported with the PublicAddressChangeNotApplied condition instead. To apply either change, delete the workstation and create it again. A CloudAccount with allowPublicAddresses: false gives none of its workstations a public address.

See also

• CloudIdentity: how the control plane authenticates to a cloud provider and injects provider-config defaults and overrides.
• Workstation: requirements, provider, and providerConfig.