Providers

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

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  # a GCP workstation

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. 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 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 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 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 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 policy, it is held closed. Delete it and create it again.

wsl2 (local, Windows)

wsl2 is the default local provider on Windows, so a workstation that names no provider runs on it. Each workstation is its own WSL distribution. 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.

hcs (local, Windows)

hcs runs each workstation as its own Hyper-V virtual machine, with its own Linux kernel and its own 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 Hyper-V VM.

wsl2 stays the default on Windows. A workstation that names no provider runs on wsl2, so you ask for hcs by name, with spec.provider: hcs or --provider hcs. 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, repair Ringleader from Settings → Apps, or install it again.

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 says why your PC cannot run it when it cannot.

The OS images are debian 13 and ubuntu 26.04, the two that wsl2 has too. With no version, debian is 13 and ubuntu is 26.04.

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 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 images the disks are built from count too.

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

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 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. A namespace cannot declare an Edge for hcs because the workstation’s own network process is its Edge, and no Edge VM is needed.

Ringleader has not measured what happens to an hcs workstation when you sign out of Windows. Expect it to reach nothing until you sign in again, because its network process runs in your Windows session.

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:

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:

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.

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.

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.

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.

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.