Automate Rancher Desktop with rdctl: Settings, Snapshots and Profiles

Why rdctl #

Everything in the Rancher Desktop window can also be done from the terminal with rdctl. That makes your setup scriptable: onboard a new developer with one script, switch the container engine for a test, or reset a damaged environment, without clicking through menus.

rdctl is installed with Rancher Desktop. Check it:

$ rdctl version

Start, stop and change settings #

$ rdctl start                                  # launch Rancher Desktop (or apply settings to a running one)
$ rdctl start --container-engine.name moby --kubernetes.enabled=false
$ rdctl shutdown                               # stop it gracefully

moby is the dockerd engine, and containerd the other one. Change settings in a running instance with set. Changing the engine or Kubernetes restarts the backend:

$ rdctl set --container-engine.name containerd
$ rdctl set --kubernetes.enabled=true --kubernetes.version v1.31.2
$ rdctl set --virtual-machine.memory-in-gb 8 --virtual-machine.number-cpus 4

The options are grouped like the preferences:

See the current settings as JSON, which is easy to process with jq:

$ rdctl list-settings
$ rdctl list-settings | jq '.containerEngine.name, .kubernetes.version'

A development environment script #

#!/usr/bin/env bash
set -euo pipefail

rdctl start \
  --container-engine.name moby \
  --kubernetes.enabled=true \
  --virtual-machine.memory-in-gb 8 \
  --virtual-machine.number-cpus 4

# wait until the Docker API answers
until docker info >/dev/null 2>&1; do sleep 2; done
until kubectl get nodes >/dev/null 2>&1; do sleep 2; done

docker compose up -d
kubectl get nodes

Snapshots #

A snapshot saves the state of the virtual machine (images, containers, volumes and the Kubernetes cluster). Take one before a risky experiment such as a Kubernetes upgrade, then go back in seconds:

$ rdctl snapshot create before-upgrade
$ rdctl snapshot list
$ rdctl snapshot restore before-upgrade
$ rdctl snapshot delete before-upgrade
$ rdctl snapshot list --json

Snapshots take disk space, so delete the ones you no longer need.

Extensions #

Rancher Desktop can run Docker Desktop extensions published as images. Manage them with:

$ rdctl extension install docker/logs-explorer-extension:0.2.2
$ rdctl extension ls
$ rdctl extension uninstall docker/logs-explorer-extension:0.2.2

Call the API directly #

rdctl is a thin client of the local API of the application. List what it offers and use it for anything that has no command:

$ rdctl api /
$ rdctl api /v1
$ rdctl api /v1/settings --method PUT --body '{"kubernetes": {"enabled": false}}'

Deployment profiles for a team #

Organizations can preconfigure Rancher Desktop for everyone with deployment profiles: a macOS .plist file or a Windows registry (.reg) file that sets defaults (or locks settings) such as the engine, the Kubernetes version and the proxy. Generate one from your current settings and then edit it:

$ rdctl create-profile --output reg --hive=hkcu --from-settings

Distribute the result with your device management tool. Users then start from the same, supported configuration. The official guide on deployment profiles lists every setting and how the defaults and the locked values differ.

Next steps #

When something goes wrong, see troubleshooting Docker and Rancher Desktop.