The stripes behind the selected tab mark a pre-release build, and the app icon wears the same pattern. Development builds of 2.0 get them too, and the stripes will come off in the final 2.0.0 release.

What's in it​

The dialog has three sections. Application turns automatic update checks on or off. Virtual Machine sets how many CPUs and how much memory the VM gets. Kubernetes enables the cluster and picks its version.

That's a short list next to Rancher Desktop 1.x. More settings will be reintroduced as they are added to the App object and implemented by the daemon.

It's an API client​

Two earlier posts explained that rdd is a Kubernetes API server, and that you can watch it reconcile a change you make with rdd set. The Preferences dialog is just another client of that same API. Every control is bound to a field path on the App object, so applying the changes you made in the dialog and running rdd set both update the same field.

Where the controls get their values​

The dialog doesn't invent the choices it offers. The CPU and memory controls get their limits from the daemon, which publishes them as a HostInfo object:

$ rdd ctl get hostinfo
NAME     CPUS   MEMORY
system   20     137438953472

Those are the same numbers the daemon checks against, so asking for more than the machine has gets you turned down:

$ rdd set virtualMachine.cpus=192
ERRO[0000] failed to update App: admission webhook "app-validator.app.rancherdesktop.io" denied the request: spec.virtualMachine.cpus 192 exceeds the host CPU count of 20

The Kubernetes dropdown comes from the same place. The daemon publishes the versions it supports as a k3s-versions ConfigMap, and the dropdown is a view of it. Versions that head a channel appear under Recommended Versions, the rest under Other Versions. This build carries k3s 1.32 through 1.35.

You can read that one too:

$ rdd ctl get configmap k3s-versions --namespace rancher-desktop --output jsonpath='{.data.channels}'
{"1.32":"1.32.13","1.33":"1.33.10","1.34":"1.34.6","1.35":"1.35.3","latest":"1.35.3","stable":"1.34.6"}

The channel aliases work from the command line:

rdd set kubernetes.version=stable

rdd set exists so you don't have to write the JSON or know which kind of patch to use. Underneath, this is the request it sends for you:

rdd ctl patch app app --type merge --patch '{"spec":{"kubernetes":{"version":"stable"}}}'

When you read the value back you can see that the alias has been replaced by the defaulter¹ with the actual version before it was stored in the object:

$ rdd ctl get app app --output jsonpath='{.spec.kubernetes.version}'
1.34.6

There's no rdd get yet, so you have to use the generic rdd ctl get.

Right now a static k3s version list ships with the app. In the future it will update itself at runtime, just like in Rancher Desktop 1.x.

The rest of Alpha 2​

The release notes have the full list; here are three of the changes:

1. On Linux, 2.0 finally installs beside 1.x. The RPM and DEB claimed the same file names, so the two packages conflicted, and the launcher we shipped ran the 1.x binary.
2. On Windows, the host-side network bridge moved into the per-VM host agent, so its ports and listeners now go away with the VM instead of outliving it.
3. ~/.kube/config is safe from overlapping writers, which could previously tear it into invalid YAML or drop the clusters you use with other tools.

Still an alpha​

This is a preview. Expect rough edges, and don't put it in front of anything you care about. There's no upgrade path between previews, and Alpha 2 refuses to start against a backend Alpha 1 created. Clear the old one first:

rdd svc delete

That takes the containers, images, volumes, and cluster with it. So there's nothing to carry across. Then install Alpha 2. It sits alongside Rancher Desktop 1.x without touching it, though only one of them can run at a time.

On Windows, the Virtual Machine tab shows the CPU and memory controls, but WSL2 ignores them because the VM settings are global across all WSL2 distros. You can change the defaults in .wslconfig.

Downloads and the full list of changes are in the release, and the installation post still covers getting it running, GUI or backend-only.

💬 Questions or feedback? Discuss this post on GitHub →

The companion post explains why Rancher Desktop can behave this way. rdd is a Kubernetes API server, and Rancher Desktop's own configuration lives in it as a single object called App. This post is about what that buys you in practice.

The API describes itself​

There are no external docs for the App object, but it doesn't need any, because you can query the API itself for documentation. You can read it with explain, for example:

$ rdd ctl explain app.spec.kubernetes
FIELD: kubernetes <Object>

DESCRIPTION:
    kubernetes specifies the Kubernetes configuration.

FIELDS:
  enabled   <boolean> -required-
    enabled specifies whether Kubernetes should be enabled in the VM.
  version   <string>
    version is the Kubernetes version to use (e.g. "1.32.2").

You can walk any part of the object, from app.spec down to a single field. The descriptions are not baked into explain; they come straight from the Go source. Each field on the App type carries a comment, a build step turns those types into the CRD¹ and copies the comments into its OpenAPI schema, and the API server hands that schema to any client that asks (explain is just one such client). So the documentation is generated from the code, and it cannot drift out of sync with it.

The writable side works the same way. rdd set is how you change the App object, and it says up front where its knobs come from: "Valid property names and types are derived from the App CRD at runtime." So the property list in its help comes straight from the CRD too:

$ rdd set --help   # trimmed to the property list
Available properties:
  containerEngine.name  (moby|containerd)
  kubernetes.enabled    (boolean)
  kubernetes.version    (string)
  running               (boolean)

Each of those shows the same description you'd get from explain, and nobody maintains this list by hand; when we add a field to the App type, it turns up here, typed and documented, in the next build.

One setting in motion​

So let's change something, and turn Kubernetes on:

rdd set kubernetes.enabled=true

The command doesn't return right away. It writes your one-line change into the App object's spec and then waits, quietly, until everything has settled. rdd logs at warn level by default, and a condition changing is only info, so you see nothing unless you ask for it. Ask, and you can watch it work:

$ rdd --log-level=info set kubernetes.enabled=true   # trimmed
INFO[0000] App updated
INFO[0000] Waiting for App to settle
INFO[0000] ContainerEngineReady=True: Container engine synced (Connected)
INFO[0000] Settled=False: Applying the configuration change to the VM (ApplyingTemplate)
INFO[0000] ContainerEngineReady=False: failed to ping Docker: ... no such file or directory (ConnectFailed)
INFO[0002] Running=False: Stopped for restart (Stopped)
INFO[0002] Running=False: Lima instance is starting (Starting)
INFO[0002] ContainerEngineReady=False: Container engine stopped (Stopped)
INFO[0022] Running=True: Lima instance is running (Started)
INFO[0022] KubernetesReady=False: Waiting for k3s API server (Probing)
INFO[0022] ContainerEngineReady=True: Container engine synced (Connected)
INFO[0027] KubernetesReady=True: Kubernetes cluster is ready (Ready)
INFO[0027] Settled=True: App has reached the desired state (Settled)

The whole change took 27 seconds,² and 20 of those were the VM restarting. The Docker error partway through comes from that same restart. The container engine goes down with the VM, so its socket disappears for a while, and ContainerEngineReady goes from connected to failed to stopped and back again. Conditions describe the state at that moment. They change as often as the state does.

That's all ordinary Kubernetes behaviour. You wrote down a desired state. A controller saw the gap between what you asked for and what was actually true, and closed it. To do that, it reconfigured the virtual machine and restarted it, waited for k3s to answer, and merged the new cluster into your kubeconfig. Most of those lines are a condition changing on the App object's status; these are the same conditions you'd watch on a Deployment rolling out. rdd set returns once Settled reaches True. The cluster is up at that point.

That's the reconcile loop, the pattern Kubernetes itself is built on. Rancher Desktop manages a VM and a cluster the same way Kubernetes manages your pods; the approach survives interruption. Kill rdd in the middle of a change, and the next start should pick up from wherever the world actually is. A script would have to remember which steps it had already run, because a crash loses that record.

Why build it this way​

Modelling the app as a controller puts everything it can do behind an API, and Rancher Desktop's own GUI is just another client of it. Nothing is locked inside the window. Anything you can do by clicking, you can do from a script, with kubectl or with the standard Kubernetes client libraries, and our own integration tests exercise the application the same way a GUI user would.

The API also describes itself, which is what explain was doing earlier. You can find out what a field is for without hunting down a separate document that has since gone stale, and so can an autonomous AI agent working on your behalf.

💬 Questions or feedback? Discuss this post on GitHub →

Back in the install walkthrough I ran rdd ctl get app, watched Rancher Desktop's own state print as a Kubernetes object, and said it deserved a post of its own, so here it is.

rdd's API server runs whether or not you ever enable Kubernetes, and it stays up after you turn Kubernetes off again. That sounds odd, but it makes sense once you know that Kubernetes really is two separate things sharing a single name.

Kubernetes is two things​

The part everyone knows is the workload layer: the kubelet on each node, the pods, and your containers. You hand it a Deployment, and it finds a node and runs the thing. But the other part is the control plane, where an API server holds resources and controllers reconcile them. You write down what you want; the controllers work to make it true.

The control plane knows nothing about containers; it just stores objects and runs reconcile loops. Containers are only created when the workload layer acts on those objects.¹ The control plane is a general engine for "here's the state I want, go make it so." That engine is the part of Kubernetes rdd uses for its own state and interface.

The App object​

Everything Rancher Desktop needs to know about itself lives in a single object called App.² You can ask for it the same way you'd ask any cluster for a resource:

# rdd ctl get app app --output yaml   (trimmed)
apiVersion: app.rancherdesktop.io/v1alpha1
kind: App
metadata:
  name: app
spec:
  containerEngine:
    name: moby
  kubernetes:
    enabled: true
    version: 1.34.6
  running: true
status:
  kubernetesPort: 7443
  conditions:
  - type: ContainerEngineReady
    status: "True"
    reason: Connected
  - type: KubernetesReady
    status: "True"
    reason: Ready
  - type: Settled
    status: "True"
    reason: Settled

The spec is what you asked for: the moby engine, Kubernetes enabled at version 1.34.6, and the VM running. The status is what rdd observed, so the port it put the cluster on (7443) shows up there, along with a list of conditions reporting how far along it got. You only ever edit the spec; the controllers write the status. Every Kubernetes resource works this way, from a pod to a deployment, and now Rancher Desktop itself does too.

A control plane with nothing to run​

Ask this API server what kinds of objects it holds, and the list is short:

$ rdd ctl api-resources   # trimmed
NAME               APIVERSION                              KIND
configmaps         v1                                      ConfigMap
secrets            v1                                      Secret
apps               app.rancherdesktop.io/v1alpha1          App
limavms            lima.rancherdesktop.io/v1alpha1         LimaVM
containers         containers.rancherdesktop.io/v1alpha1   Container
images             containers.rancherdesktop.io/v1alpha1   Image
volumes            containers.rancherdesktop.io/v1alpha1   Volume

The standard building blocks are there (ConfigMaps, Secrets), right next to Rancher Desktop's own kinds. But the whole workload layer is missing, so there are no pods and no nodes. The server hasn't even heard of a node:

$ rdd ctl get nodes
error: the server doesn't have a resource type "nodes"

rdd runs no containers, so it needs no kubelet, no scheduler, and none of the other machinery that ties Kubernetes to a Linux host. The control plane is just storage and reconcile loops, which is why the same one runs natively on macOS, Windows, and Linux. The history post made the case for a single backend on every platform. Dropping the workload layer is most of what makes that possible.

It does still need somewhere to keep its objects. Kubernetes stores them in etcd;³ rdd uses SQLite instead, which is the same mechanism k3s uses so it can ship as a single binary.

So where is the cluster?​

You did start a cluster, and it's real; rdd ctl get nodes came up empty because the cluster lives somewhere else. It runs inside the virtual machine, as a separate Kubernetes with its own API server. Point kubectl at that one, and the node is right there:

$ kubectl --context rancher-desktop-2 get nodes
NAME      STATUS   ROLES           AGE   VERSION
lima-rd   Ready    control-plane   44s   v1.34.6+k3s1

The two API servers do different jobs. The one rdd ctl talks to is Rancher Desktop describing itself; the one kubectl talks to is the k3s cluster where your workloads run. And rdd's API server manages the cluster's; setting spec.kubernetes.enabled: true on the App object is how you tell the control plane to start the k3s cluster. I suspect two API servers on one machine will trip people up for a while, until reaching for the right one becomes automatic.

Your tools already work​

Because Rancher Desktop represents itself as Kubernetes objects, and serves them from a real Kubernetes API server, everything that already speaks that API can drive rdd. rdd ctl really is just kubectl, pointed at the control plane. So get, --output yaml, --output jsonpath, label selectors, and watches all work, because there's never been anything custom to support.

This is quite different from a custom application API. There's no rdd SDK to import, and no private protocol to figure out.

That leaves the question of how the control plane turns a one-line change to the App object into a running cluster, and how you find your way around this API when there are no docs for it. I take both up in a companion post.

💬 Questions or feedback? Discuss this post on GitHub →

Sometimes the fix or feature you want hasn't been merged to main¹ yet and lives only in an open pull request². You can install that build too, and try the change before it lands.

So this is really for people who are comfortable switching between versions and running factory resets, and who can put things back when a build breaks something. If that's not you, I'd wait for the release; the fix will land there soon enough.

The short version​

On Rancher Desktop 1.x

1. Take a snapshot first.
2. Find the build and download the artifact for your machine.
3. Unpack and install it. On macOS, clear the quarantine flag, or it refuses to open.
4. Check whether it fixes your problem, or try the feature you wanted.
5. Factory-reset from the development build.
6. Install the release by hand, then restore the snapshot from step 1.

On Rancher Desktop 2.0

1. There's no snapshot to take, so your existing workloads are gone either way.
2. Find the build and download the artifact for your machine.
3. Unpack and install it. On macOS, clear the quarantine flag, or it refuses to open.
4. Clear the existing backend with rdd svc delete before you start.
5. Check whether it fixes your problem, or try the feature you wanted.
6. Clear the backend again with rdd svc delete, then install the release by hand.

Have a way back before you start​

There's no in-place downgrade back to a release. Going back takes a factory reset, and that reset wipes everything the backend is holding: your containers, images, volumes, and Kubernetes cluster.

So on Rancher Desktop 1.x, take a snapshot before you install the development build. It captures all of that, and you can restore it once you're back on a release. Rancher Desktop 2.0 has no snapshot mechanism yet. It also refuses to start on a backend that a different rdd³ version created; switching versions there means clearing the backend and losing those workloads, in either direction. And even where you can snapshot, it only covers what's in the VM. A snapshot is not a backup of your host, and it won't save you from a build that damages files there.

A development build also turns off auto-updates. It won't quietly replace itself, and it won't pull you back onto a release either. You reinstall the release build by hand when you're done.

Find the build​

Development builds come from GitHub Actions⁴, from the workflow named Package.

For the latest main, open the Actions tab, then filter to the Package workflow and the main branch. Or skip both dropdowns and type branch:main workflow:Package into the search box. Now pick the newest run with a green checkmark, which means the whole run passed and its builds are complete.

For a pull request, open the PR and scroll down to its checks. Expand them, find a green check whose name starts with Package / package, and click it. The platform in the parentheses doesn't matter. They all belong to the same run; any of them gets you there.

Either way, you land on a workflow run. Click Summary in the left sidebar, then scroll to the bottom, where GitHub lists the artifacts. Each artifact is one operating system and CPU architecture. Find the one for your machine and click the download icon beside it. They're large, 600 MB and up.

On 2.0, the same run also produces an RDD artifact for each platform, which holds just the rdd binary with no app and no bundled tools. For testing a backend fix you could use just this binary, as it's 50 to 60 MB (rather than 600 plus), but GUI changes would still require downloading the full app. The binary still needs its quarantine flag cleared on macOS. The installation post covers using rdd on its own.

Unpack and install​

What you downloaded is a ZIP, even on macOS and Windows, where a release hands you a .dmg or an installer directly. GitHub wraps every build artifact in a ZIP of its own. On every platform you unzip what you got first; the real artifact is inside.

$ unzip "Rancher Desktop.aarch64.dmg.zip"
Archive:  Rancher Desktop.aarch64.dmg.zip
  inflating: Rancher Desktop-1.23.1-300-ge397ee701-arm64.dmg

The name changes on the way out⁵. That 1.23.1-300-ge397ee701 is git describe output, which pins down which build you ran⁶. Don't go hunting for that commit though. On a pull request GitHub builds a throwaway merge of the branch into its base, so it only exists for that run. Link the run itself when you report back.

On macOS, that inner artifact is a .dmg (pick the one matching your chip, aarch64 for Apple silicon or x86_64 for Intel). Open it and drag the app into Applications, the same as a release. Because the build is unsigned, macOS marks it as quarantined and refuses to open it, so clear that flag once from a terminal. The 1.x app is Rancher Desktop; the 2.0 app is Rancher Desktop 2. Use the one you installed:

xattr -rd com.apple.quarantine "/Applications/Rancher Desktop.app"     # 1.x
xattr -rd com.apple.quarantine "/Applications/Rancher Desktop 2.app"   # 2.0

On Windows, the inner artifact is an .msi installer. Run it. Windows will warn that it comes from an unknown publisher, again because the build is unsigned; approve it to continue.

On Linux, the development build extracts to /opt/rancher-desktop, the same place our RPM and DEB packages install to. So if you have Rancher Desktop from one of those repositories, remove the package first; otherwise the two fight over that directory. If you extracted a development build there before, clear it out with sudo rm -rf /opt/rancher-desktop.

The download itself holds a second ZIP with the application. Unpack that inner ZIP into place, then make the sandbox helper setuid so the app can launch:

unzip "Rancher Desktop-linux.zip"   # yields rancher-desktop-<version>-linux.zip
sudo unzip -o rancher-desktop-*-linux.zip -d /opt/rancher-desktop
sudo chmod 04755 /opt/rancher-desktop/chrome-sandbox

A manual extract leaves no desktop entry behind. Launch it directly with /opt/rancher-desktop/rancher-desktop⁷.

On Rancher Desktop 2.0, the app refuses to start on a backend that a different rdd version created. You have to clear any existing one first (this removes your current 2.0 workloads). The command is the same on every platform:

rdd svc delete

Then start Rancher Desktop the way you normally would; it runs like any release.

Going back to a release​

Once you're finished with the development build, clear its backend so a release can start clean. On Rancher Desktop 1.x that's rdctl factory-reset; on 2.0 it's rdd svc delete.

rdctl factory-reset   # Rancher Desktop 1.x
rdd svc delete        # Rancher Desktop 2.0

Then install the release the normal way, from the project's releases page, or on Linux from our package repositories. On Rancher Desktop 1.x, restore the snapshot you took at the start, and your containers and cluster come back as they were. On 2.0 there's no snapshot to restore; you start fresh.

It's a lot of steps, though it does answer "is this actually fixed?" weeks ahead of the release.

💬 Questions or feedback? Discuss this post on GitHub →

Let's call it what it is: an early tech preview. It's rough, and not meant for production. It exists so you can see that 2.0 is real and already running, and so you can tell us what you'd like while the architecture is still soft enough to change.

What 2.0 is​

We rewrote Rancher Desktop because the old design made every new feature take more effort than the one before it. The history post tells that story; the short version is one backend instead of two, the engine lifted out of the GUI, and a different guest OS underneath. 2.0 is that idea, built from scratch.

At the center is a new background program called rdd, the Rancher Desktop Daemon, and it's the part that does the real work. It runs the virtual machine (using Lima on all platforms now, including Windows), it starts your container engine, and it manages your Kubernetes cluster. rdd exposes all of this through an API, but not a custom one; it actually speaks the Kubernetes API, so you can talk to it directly with kubectl or any of the standard client libraries, and there's no new SDK to learn. The desktop app is really just another client without any special privileges; it talks to rdd the same way any other tool would.

Because the work lives in rdd instead of inside a window, you can run the whole thing without ever opening the GUI. And rdd is one self-contained executable; there's no installer and no separate daemon and command-line tool, just one file that is both the backend and the way you drive it. Download it, start it from the command line, and you have a container engine and a cluster: on a headless server, on a CI runner, or in your own terminal. Deploying it just means copying one file. Rancher Desktop never had a way to do this, because the engine lived inside the app, and the app had to be on screen.

The guest VM runs openSUSE Leap now instead of Alpine, and the reason is glibc; much of the GPU and AI tooling people ask for needs it, and Alpine's musl doesn't provide it. GPU support isn't built yet, but the guest OS no longer rules it out.

Why an alpha, and why now​

We could have kept this private until it looked polished, but we'd rather not. Putting it out now, rough edges and all, does two things for us.

It shows that "we'll do that in 2.0" means a workstream already running, not a promise about some distant year. And it puts the design in front of you early, when your feedback still counts. If your setup depends on something specific, this is the moment to say so, before we lock in decisions.

What you can do today​

This is a working preview, not a finished product. Here's what runs right now:

• Start, stop, and delete Rancher Desktop 2.0, from the GUI or the command line.
• Install and run it with no GUI at all: the daemon with your local command-line tools.
• Build and run containers with the Docker (moby) engine.
• Manage containers from the dashboard: start, stop, pause, resume, delete.
• Turn on Kubernetes (version 1.31 or newer), switch versions, and browse the cluster in the built-in dashboard.

What is not there yet​

So you're not caught off guard:

• moby is the only container engine for now.
• There's no settings screen. You pick your Kubernetes version from the command line.
• So far, the interface covers containers, images, and volumes, plus the cluster dashboard.
• There's no upgrade path between previews. Each new build means a clean slate: factory reset, then install fresh. It stays that way until 2.0 reaches a real release.

It can be installed beside Rancher Desktop 1.x​

You don't have to choose. 2.0 installs next to Rancher Desktop 1.x, and the two ignore each other, with a separate package and separate data. Install or remove them in either order. The Linux RPM and DEB packages are the exception in this alpha.¹ Don't run them both at once, though; there are likely to be port and socket conflicts.

How to try it​

The full app, GUI plus bundled tools, comes from the latest release on GitHub for Windows and macOS (Intel and Apple silicon), and from our RPM and DEB repositories and AppImages on Linux, the same places you'd reach for Rancher Desktop 1.x. If all you want is the daemon, download the single rdd binary for your platform and you're two commands away from a running container.

A real installation and usage walkthrough is a separate post in this series.

This is alpha software. Things will break, especially in corners we've never tested on a machine configured like yours. When they do, please tell us; that feedback is a big part of why we're shipping this early.

Staying in the loop​

There are no docs for 2.0 yet, so for now this blog takes their place. As the work moves, we'll write about how the pieces fit and what becomes newly possible: the daemon and its API, networking, snapshots, the AI story, whatever we just released. To find out when the next preview drops, subscribe to the feed.

Curious, and feeling adventurous? Give it a try. Cautious? Follow along, and jump in when it looks ready for you.

💬 Questions or feedback? Discuss this post on GitHub →

2.0 installs beside Rancher Desktop 1.x without touching it, with a separate package and separate data. Install or remove them in any order. (The welcome post covers what 2.0 is and how it differs; this one is about getting it running.)

Install the desktop app​

The full app, including the GUI and a set of bundled command-line tools, comes from the latest release on GitHub; its notes list the download for every platform. Open the Assets list there.

On macOS, download the .dmg that matches your chip¹: Rancher.Desktop-2.0.0-alpha.1.aarch64.dmg on Apple silicon, or the x86_64 build on an Intel Mac. Open it, drag the app into Applications, and launch it from there.

On Windows, download the installer, Rancher.Desktop.Setup.2.0.0-alpha.1.msi, and run it. Install WSL2 first if you haven't already; 2.0 runs its Linux VM through WSL2, just as Rancher Desktop 1.x does.

On Linux, install from our RPM or DEB repositories², or run the AppImage, similar to the channels used for Rancher Desktop 1.x.

The first time you launch the app, it sets up the backend and downloads the VM image, which can take a while on a slow connection. After that the app is talking to a running container engine, and you can manage containers, images, and volumes from its window.

One thing the app won't do for you: turn on Kubernetes. It starts with Kubernetes off. Turn it on from the Kubernetes section of Preferences, or from the command line. The first run installs rdd into ~/.rd2/bin; put that on your PATH (or call ~/.rd2/bin/rdd directly) and run:

rdd set kubernetes.enabled=true

The VM is already running without Kubernetes, so this restarts it once.

Or just the daemon​

If you want a container engine and a cluster with no window on screen, skip the app and download the single rdd binary instead. It's the whole backend in one file; there's no installer and nothing to unpack.

The binaries are in the same GitHub release. The name is rdd- followed by the version, the operating system, and the CPU architecture: on an Apple silicon Mac you want rdd-2.0.0-alpha.1.darwin.aarch64; on x86_64 Linux, rdd-2.0.0-alpha.1.linux.x86_64. Download the one for your machine, put it on your PATH, and make it executable:

curl --location --output /usr/local/bin/rdd \
  https://github.com/rancher-sandbox/rancher-desktop-2/releases/download/v2.0.0-alpha.1/rdd-2.0.0-alpha.1.darwin.aarch64
chmod +x /usr/local/bin/rdd

From there, one command gets you a running container:

rdd run docker run --rm hello-world

rdd run is the no-commitment way to use 2.0. It starts the daemon if it's not already up, then runs your command with the PATH and the Docker and Kubernetes contexts pointed at 2.0 for that command only. It leaves your own configuration untouched. So if your machine is already set up for Rancher Desktop 1.x, leave it that way and reach for 2.0 with rdd run when you want to try something. The very first start downloads the openSUSE Leap image and brings the VM up, which can take a while on a slow connection; after that it's quick.

Kubernetes works the same way. On a fresh setup, rdd run kubectl get node enables Kubernetes at the default version and runs against the new cluster, with no separate step to turn it on:

rdd run kubectl get node

That shortcut fires only the first time, while nothing is configured yet. Once Rancher Desktop exists, turn Kubernetes on with rdd set:

rdd set kubernetes.enabled=true

The version defaults to the latest stable; pass kubernetes.version=1.32.2 to pin a specific one (1.32 through 1.35).

Driving it​

The same rdd commands drive 2.0 whether you installed the full app or only the binary. The GUI is an additional client; underneath, it runs the same daemon as you do.

rdd run is fine for the occasional command. If you use 2.0 a lot, add ~/.rd2/bin to your PATH and call the tools directly. The first start populates that directory; add it to your PATH yourself, in this shell and in your profile:

export PATH="$HOME/.rd2/bin:$PATH"

What you find there depends on how you installed. rdd provides kubectl itself, so it's there either way. docker and helm come with the full app, which links them into ~/.rd2/bin alongside its other bundled tools and the credential helpers; with the daemon-only download, supply docker and helm yourself.

Both the Docker and Kubernetes contexts are named rancher-desktop-2, and 2.0 won't take over a context you already have selected. If you run both side by side, move between them by switching contexts:

docker context use rancher-desktop-2
kubectl config use-context rancher-desktop-2

You don't need rdd run to manage the backend itself; rdd start brings it up and rdd stop takes it down, keeping your data for next time:

rdd start   # bring the backend up
rdd stop    # take it down, keep your data

There's no upgrade path between previews yet, so each new alpha starts from a clean slate. rdd svc delete stops the daemon and removes everything 2.0 created (the VM, the cluster, your settings, and the daemon's own data), keeping only the download cache so a reinstall doesn't refetch the VM image. It's also how you uninstall; after it runs, just delete the rdd binary or remove the app. The cache it leaves behind is Lima's, not ours (~/Library/Caches/lima on macOS, ~/.cache/lima on Linux, ~/AppData/Local/lima on Windows); delete it too if you want to reclaim all the space. A later release will handle that for you, clearing distro images from earlier previews automatically and adding a command to empty the cache.

That's the alpha: install it one of two ways, start it, and run a container. It may break on setups we've never seen, and if it does, please tell us.

A glimpse underneath​

rdd is a Kubernetes API server in its own right, and Rancher Desktop's own state lives inside it as Kubernetes objects. rdd ctl is kubectl aimed at that API. Ask it for the App object and the whole machine prints as YAML: the container engine, the requested Kubernetes version, and the conditions tracking its progress toward the state you asked for.

# rdd ctl get app -o yaml
apiVersion: v1
items:
- apiVersion: app.rancherdesktop.io/v1alpha1
  kind: App
  metadata:
    creationTimestamp: "2026-06-17T17:44:58Z"
    finalizers:
    - rdd.rancherdesktop.io/cleanup
    generation: 4
    name: app
    resourceVersion: "507"
    uid: 3ab44aec-8949-41b8-8432-03224fe38ce5
  spec:
    containerEngine:
      name: moby
    kubernetes:
      enabled: true
      version: 1.34.6
    namespace: rancher-desktop
    running: true
  status:
    conditions:
    - lastTransitionTime: "2026-06-19T00:57:05Z"
      message: Container engine synced
      observedGeneration: 4
      reason: Connected
      status: "True"
      type: ContainerEngineReady
    - lastTransitionTime: "2026-06-19T00:57:10Z"
      message: Kubernetes cluster is ready
      observedGeneration: 4
      reason: Ready
      status: "True"
      type: KubernetesReady
    - lastTransitionTime: "2026-06-17T17:45:19Z"
      message: Lima instance created successfully
      observedGeneration: 4
      reason: Created
      status: "True"
      type: Created
    - lastTransitionTime: "2026-06-19T00:57:10Z"
      message: App has reached the desired state
      observedGeneration: 4
      reason: Settled
      status: "True"
      type: Settled
    - lastTransitionTime: "2026-06-19T00:57:05Z"
      message: Lima instance is running
      observedGeneration: 4
      reason: Started
      status: "True"
      type: Running
    kubernetesPort: 7443
kind: List
metadata:
  resourceVersion: ""

This is not the cluster you turned on earlier; it's Rancher Desktop representing itself through the same API your tools already speak. That means anything that drives Kubernetes can also drive Rancher Desktop, without a bespoke SDK or a private protocol. There's a lot to say about that, and it has a post of its own.

The commands in one place​

💬 Questions or feedback? Discuss this post on GitHub →

SUSE had just bought Rancher Labs, and the goal was easy to state and hard to build: make Kubernetes easy on a developer's laptop. We called it Rancher Desktop because, at the time, "Rancher" was how SUSE said "Kubernetes." That branding has gotten more complicated since, the way branding does, but the name stuck.

About seven months later, in May 2021, the first public build shipped, with macOS and Windows support, k3s¹ for Kubernetes, an image builder called kim², and a way to switch Kubernetes versions. It was alpha software and looked like it. Five years on it's a different program, and the story of how it got here is mostly the story of how much work it took to keep one simple promise on three operating systems at once.

Two operating systems, two backends​

On a Mac, Kubernetes needs a Linux virtual machine. On Windows, it needs WSL2. So from the very first release, Rancher Desktop had two backends, and we spent the next five years discovering how different "two backends" really are.

The Mac side never sat still. We started with minikube, dropped it to drive Apple's Hypervisor.framework via the docker-machine-driver-hyperkit, then replaced it with Lima and QEMU³. Each move was a rebuild of the layer that creates the VM, installs k3s, and wires up the network. When Apple later shipped its own Virtualization framework, VZ, moving to it was mostly a matter of telling Lima to use it.

Windows went its own way, with k3s running inside a dedicated WSL distribution we imported from an image we built ourselves. When Linux arrived as a tech preview in late 2021, it didn't add a third backend; it joined the Mac under Lima, which manages the VM on macOS and Linux alike, and which we got to build on as an upstream open-source project instead of maintaining alone. That part worked out; macOS and Linux became one backend, where a fix landed once instead of twice.

Building on Lima also meant helping to build it. Lima started narrow, just a way to run containers with nerdctl on a Mac. The provisioning scripts we added a few weeks in, the mechanism that runs setup inside a fresh VM, are how Rancher Desktop installs k3s and a container engine. They also opened up Lima so you could provision for almost anything. Other contributions are the rules-based port forwarding configuration and host-based DNS lookup to extend VPN connections into the VM. What we needed, we built upstream, where every Lima user got to benefit from it.

Windows stayed separate. We tried more than once to fold the two together but never fully managed it. The systems were too different: a VM you own end to end on one side, a WSL distro living under someone else's rules on the other. So most features had to be built twice, into two backends similar enough to look the same and different enough to break in their own ways.

A small guest with sharp edges​

The VM ran Alpine Linux, picked because it's tiny, which meant a smaller download and a faster boot. Alpine stays small by using musl⁴ and OpenRC instead of the glibc and systemd⁵ most Linux software is built against. Usually that difference is invisible, but sometimes it isn't. You can't run the NVIDIA Container Toolkit on it, which means no CUDA, which means machines with a GPU can't run the AI workloads people increasingly want to run. A choice that saved a few megabytes early on walled off a whole category of work once GPUs and AI showed up.

More than Kubernetes​

We set out to ship Kubernetes, and users kept asking for the rest of the container toolbox. The first image builder, kim, ran inside the cluster; we replaced it with nerdctl, the standard containerd CLI, and most people never noticed kim was gone. Then we hit something we hadn't planned for; a lot of real projects simply wouldn't build under nerdctl and buildkit. We added moby (dockerd and the Docker CLI) as a second engine, so those projects would build. Later we let people turn Kubernetes off entirely and run nothing but the container engine. Rancher Desktop had quietly grown from "Kubernetes on your desktop" into "containers and Kubernetes on your desktop."

Networking never got easy​

Networking was the part that never stopped being hard. A container's ports, the right DNS answers, a corporate VPN that doesn't break everything: getting all three to coexist took years of work on each platform, and little of it carried across. On macOS the VM reaches the network through a layer called vmnet⁶, where we moved from one implementation to another and carried both for a while. Windows needed something else entirely. WSL puts every distribution on one shared network, so to avoid port conflicts with the others, we gave our VM a tunnelling network in its own network namespace.

Some of that split is just the operating systems being different; there's no single answer that works on both. A clean design can't avoid writing two of them, so the question it has to get right is where that code should live, pushed as far down into the shared foundation as it will go instead of tangled through the app.

What people actually wanted​

The request for Linux support surprised us. On Linux you can already run k3s, containerd, and Docker natively, so a desktop app doesn't add the containers. Its value was being able to throw the whole thing away. A factory reset wipes the VM back to nothing, worth a lot when your environment drifts into a state you no longer understand. People wanted an undo button for their development machine (and later, snapshots).

A backend trapped in the app​

Two features we built to make Rancher Desktop easier to work with ran into the same limit.

rdctl was a command-line tool for driving Rancher Desktop without touching the GUI. It let us write our integration tests as plain shell scripts instead of clicking through the interface, and it let users automate their setup. But not everything was reachable from it. Port forwarding, for one, still went through private messaging between the GUI and the backend, never exposed through the REST API, so the GUI could do things no script could.

Snapshots hit it too. Saving the VM's state to restore later was a simple feature with an awkward implementation, because the backend has to stop while its disk is copied, and the backend lives inside the GUI. So taking a snapshot turned into a small contortion. The GUI launches rdctl, which calls back into the GUI to ask it to shut its own backend down, takes the snapshot, then asks it to start back up. Cancelling was worse. There was no clean channel for it, so the GUI found the running rdctl process and killed it by name.

Underneath both was the same fact: you can't run the backend without the GUI. You can hide the window, you can tuck it into the background, but the app is always loaded, because the engine lives inside it. There is no headless Rancher Desktop. For something a developer wants to script, drop on a CI runner, or hand to an AI agent to drive, that's real friction.

What five years taught us​

Step back, and a pattern runs through all of it. Every feature got a little more difficult to implement than the last. We had two backends to change in lockstep, an engine welded to its own UI, and a guest OS that couldn't reach the GPU. None of it was a mistake exactly (each call was reasonable when we made it), but the costs compounded, until we were spending more time maintaining the existing machinery than building anything new.

The parts that aged well point the way. Building on Lima gave us one backend for macOS and Linux and an upstream community to share the load. And the command-line tool we'd built for our own tests turned out to matter more than we planned. A tool an AI model can explore and drive on its own is also exactly what you want now that so much work is handed to agents.

So Rancher Desktop 2.0 starts over, on purpose. It runs one backend across every platform (including Windows). The backend lives outside the UI now, so you can run it on its own: headless, scripted, snapshotted by itself. And the guest can talk to your GPU. The first five years weren't wrong; they taught us exactly what the foundation needed to be. The rest of this blog is about what we're building on it.

💬 Questions or feedback? Discuss this post on GitHub →