Quick Start with Windows


1. Install the Meshery command line client, mesheryctl .


To set up and run Meshery on Windows

  1. Configure Windows and enable Docker
  2. Install a Kubernetes cluster on top
  3. Run Meshery


The following minimum Windows build versions are required:

Name Version
WSL1 x64 - Windows 7
WSL2 x64 - Version 1903, Build 18362; ARM 64 - Version 2004, Build 19041
Custom Kernel Build 18945
Kernel with K8s required modules Build 19013

Run the following command on Powershell to check your Windows build and version:



Perform the following steps in order:

1. Install Windows Subsystem for Linux (WSL)

Open Powershell in administrator mode and run:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart Restart-Computer
Choosing your WSL version:
WSL2 (Recommended)

Set the default version to WSL2, which will be inherited by any distro you wish to use.

Enable VM (Virtual Machine) feature: Open PowerShell in administrator mode and run:

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Set WSL2 as the default version:

wsl --set-default-version 2

Warning: It is recommended to update to WSL2 as WSL1 doesn’t support the Docker Desktop application for Windows. Instead, it only supports the deprecated version, Docker Toolbox.

If you still wish to continue, follow the instructions for

1. The default version of WSL is set to WSL1 by default. You can move forward to install the distro of your choice.

2. Docker Toolbox
Warning: Docker Toolbox is a deprecated version. It is recommended to update your system and install the Docker Desktop application with WSL2.

Docker Toolbox uses Linux-specific kernel features, and can’t run natively on Windows. Instead, it creates and uses a small Linux VM on your machine along with docker-machine, and uses VirtualBox to run Docker.

  • Go to Toolbox Releases and download the latest release .exe file
  • Follow these instructions to successfully set up the Docker Toolbox application.

2. Install a new distro

In this tutorial, Ubuntu 18.04 will be the distro used. Feel free to use any distro of your choice.

Note: If you choose to run Meshery without installing a distro, skip step 2.

3. Enable Docker

The Docker Desktop application for Windows includes a comprehensive set of tools, including Docker Engine, Docker CLI client, Docker Compose, Notary, Kubernetes, and a Credential Helper.

Windows 10 Version Docker Desktop
Pro/Education/Enterprise Docker Desktop for Windows Pro
Home Docker Desktop for Windows Home

4. Install a Kubernetes cluster

Once Docker is installed, the next step will be to install a Kubernetes cluster. Under “Settings” in the Docker Desktop application, enable Kubernetes. In this how-to, K3d will be used as it relies only on Docker.

curl -s https://raw.githubusercontent.com/rancher/k3d/main/install.sh | bash k3d cluster create export KUBECONFIG="$(k3d kubeconfig get 'k3s-default')"

If using Scoop, run the following in the PowerShell to install a Kubernetes cluster :

scoop install k3d k3d cluster create export KUBECONFIG="$(k3d kubeconfig get 'k3s-default')"

5. Set up Meshery

Follow the installation steps to install the mesheryctl CLI. Then, execute:

./mesheryctl system start

Meshery server supports customizing authentication flow callback URL, which can be configured in the following way

MESHERY_SERVER_CALLBACK_URL=https://custom-host ./mesheryctl system start

Type yes when prompted to choose to configure a file. To get started, choose Docker as your platform to deploy Meshery.

6. Aftermath errors

Meshery is unable to detect the Kubernetes connection running on your local system, even after manually uploading the .kube config file :

  1. To display a list of the contexts in Kubernetes, run:
kubectl config get-contexts
  1. Change your current context to docker-desktop:
kubectl config use-context docker-desktop
  1. Restart Meshery.

Stuck at another error? Tell us about it