# Technical Documentation: rancher-sandbox/rancher-desktop

> ℹ️ **Provenance:** Hybrid Fusion: `rancher-sandbox/rancher-desktop` (README + 10 In-Tree Chapters) · [CodeWiki Reference](https://codewiki.google/github.com/rancher-sandbox/rancher-desktop) · Recency: Active (< 180 days)

## 1. Project Overview & Quickstart (rancher-sandbox/rancher-desktop)

# Rancher Desktop

[](https://deepwiki.com/rancher-sandbox/rancher-desktop)

Rancher Desktop is an open-source project that brings Kubernetes and
container management to the desktop. It runs on Windows, macOS and
Linux. This README pertains to the development of Rancher Desktop.
For user-oriented information about Rancher Desktop, please see [rancherdesktop.io][home].
For user-oriented documentation, please see [docs.rancherdesktop.io][docs].

[home]: https://rancherdesktop.io
[docs]: https://docs.rancherdesktop.io


## Overview

Rancher Desktop is an Electron application that is mainly written in TypeScript.
It bundles a variety of other technologies in order to provide one cohesive application.
It includes a command line tool, `rdctl`, which is written in Go.
Most developer activities, such as running a development build, building/packaging
Rancher Desktop, running unit tests, and running end-to-end tests, are done through
`yarn` scripts. Some exceptions exist, such as running BATS tests.


## Setup

### Windows

There are two options for building from source on Windows: with a
[Development VM Setup](#development-vm-setup) or
[Manual Development Environment Setup](#manual-development-environment-setup)
with an existing Windows installation.


#### Development VM Setup

1. Download a Microsoft Windows 10 [development virtual machine].
   All of the following steps should be done in that virtual machine.
2. Open a PowerShell prompt (hit Windows Key + `X` and open
   `Windows PowerShell`).
3. Run the [automated setup script]:

   ```powershell
   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
   iwr -useb 'https://github.com/rancher-sandbox/rancher-desktop/raw/main/scripts/windows-setup.ps1' | iex
   ```

4. Close the privileged PowerShell prompt.
5. Ensure `msbuild_path` and `msvs_version` are configured correctly in `.npmrc` file. Run the following commands to set these properties:

   ```
   npm config set msvs_version <visual-studio-version-number>
   npm config set msbuild_path 
   ```

   For example for Visual Studio 2022:

   ```
   npm config set msvs_version 2022
   npm config set msbuild_path "C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe"
   ```

   If you get an error message when trying to run `npm config set...`, run `npm config edit` and then add lines like

   ```
   msvs_version=2022
   msbuild_path=C:\Program Files (x86)\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe
   ```

   Do not quote the values to the right side of the equal sign. The quotes aren't needed, and it's possible that some
   processors will treat them as literal parts of the path, and then fail.
7. Configure `git` to work with linux- and macos-originated files:
   ```
   git config --global --replace-all core.autocrlf false
   git config --global --replace-all core.eol lf
   ```
If you find the `lint:go` tests are failing mysteriously, it's possible that the line-endings are incorrect.

You can now clone the repository and run `yarn`.

[development virtual machine]: https://developer.microsoft.com/en-us/windows/downloads/virtual-machines/
[automated setup script]: ./scripts/windows-setup.ps1


#### Manual Development Environment Setup

1. Install [Windows Subsystem for Linux (WSL)] on your machine. Skip this step, if WSL is already installed.
2. Open a PowerShell prompt (hit Windows Key + `X` and open `Windows PowerShell`).
3. Install [Scoop] via `iwr -useb get.scoop.sh | iex`.
4. Install 7zip, git, go, mingw, nvm, and unzip via `scoop install 7zip git go mingw nvm python unzip`.
   Check node version with `nvm list`. If node v22 is not installed or set as the current version, then install using `nvm install 22` and set as current using `nvm use 22.xx.xx`.
5. Install the yarn package manager via `npm install yarn`
6. Install Visual Studio 2017 or higher. As of this writing the latest version is available at [https://visualstudio.microsoft.com/downloads/]; if that's changed, a good search engine should find it.
7. Make sure you have the `Windows SDK` component installed. This [Visual Studio docs] describes steps to install components.
   The [Desktop development with C++] workload needs to be selected, too.
8. Configure `git` to work with linux- and macos-originated files:
   ```
   git config --global --replace-all core.autocrlf false
   git config --global --replace-all core.eol lf
   ```
If you find the `lint:go` tests are failing mysteriously, it's possible that the line-endings are incorrect.
9. Ensure `msbuild_path` and `msvs_version` are configured correctly in `.npmrc` file. Run the following commands to set these properties:

   ```
   npm config set msvs_version <visual-studio-version-number>
   npm config set msbuild_path 
   ```

   For example for Visual Studio 2022:

   ```
   npm config set msvs_version 2022
   npm config set msbuild_path "C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe"
   ```

   If you get an error message when trying to run `npm config set...`, run `npm config edit` and then add lines like

   ```
   msvs_version=2022
   msbuild_path=C:\Program Files (x86)\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe
   ```

   Do not quote the values to the right side of the equal sign. They aren't needed, and it's possible that some
   processor will treat them as literal parts of the path, and then fail.

You can now clone the repository and run `yarn`.

[Scoop]: https://scoop.sh/
[Visual Studio docs]: https://docs.microsoft.com/en-us/visualstudio/install/modify-visual-studio?view=vs-2022
[Windows Subsystem for Linux (WSL)]: https://docs.microsoft.com/en-us/windows/wsl/install
[Desktop development with C++]: https://learn.microsoft.com/en-us/visualstudio/install/modify-visual-studio?view=vs-2022#change-workloads-or-individual-components

### macOS

Install `nvm` to get Node.js and npm:

See https://github.com/nvm-sh/nvm#installing-and-updating and run the `curl` or `wget`
command to install nvm.

Note that this script adds code dealing with `nvm` to a profile file
(like `~/.bash_profile`). To add access to `nvm` to a current shell session,
you'll need to `source` that file.

Currently we build Rancher Desktop with Node 22. To install it, run:

```
nvm install 22.14
```

Next, you'll need to install the yarn package manager:

```
npm install yarn
```

You'll also need to run `brew install go` if you haven't installed go.

Then you can install dependencies with:
```
yarn
```

> ### ⚠️ Working on a mac with an M1 chip?
>
> You will need to set the `M1` environment variable before installing dependencies and running any npm scripts:
>
> ```
> export M1=1
> yarn
> ```
>
> You will want to run `git clean -fdx` to clean out any cached assets and re-downloaded with the correct arch before running `yarn` if you previously installed dependencies without setting `M1` first.

### Linux

Ensure you have the following installed:

- [Node.js][Node.js] v22. **Make sure you have any development packages
  installed.** For example, on openSUSE Leap 15.6 you would need to install
  `nodejs22` and `nodejs22-devel`.

- [yarn classic][yarn-classic]

- Go 1.22 or later.

- Dependencies described in the [`node-gyp` docs][node-gyp] installation.
  This is required to install the [`ffi-napi`][ffi-napi] npm package. These docs mention
  "a proper C/C++ compiler toolchain". You can install `gcc` and `g++` for this.

Then you can install dependencies with:

```
yarn
```

You can then run Rancher Desktop as described below. It may fail on the first run -
if this happens, try doing a factory reset and re-running, which has been known
to solve this issue.

[Node.js]: https://nodejs.org/
[ffi-napi]: https://www.npmjs.com/package/ffi-napi
[node-gyp]: https://github.com/nodejs/node-gyp#on-unix
[yarn-classic]: https://classic.yarnpkg.com/lang/en/docs/install/#debian-stable


## Running

Once you have your dependencies installed you can run a development version
of Rancher Desktop with:

```
yarn dev
```


## Tests

To run the unit tests:

```
yarn test
```

To run the integration tests:

```
yarn test:e2e
```


## Building

Rancher can be built from source on Windows, macOS or Linux.
Cross-compilation is currently not supported. To run a build do:

```
yarn build
yarn package
```

The build output goes to `dist/`.

### Debugging builds with the Chrome remote debugger

The Chrome remote debugger allows you to debug Electron apps using Chrome Developer Tools. You can use it to access log messages that might output to the developer console of the renderer process. This is especially helpful for getting additional debug information in production builds of Rancher Desktop.

#### Starting Rancher Desktop with Remote Debugging Enabled

To enable remote debugging, start Rancher Desktop with the `--remote-debugging-port` argument.

On Linux, start Rancher Desktop with the following command:

``` bash
rancher-desktop --remote-debugging-port="8315" --remote-allow-origins=http://localhost:8315
```

On macOS, start Rancher Desktop with the following command:

```
/Applications/Rancher\ Desktop.app/Contents/MacOS/Rancher\ Desktop --remote-debugging-port="8315" --remote-allow-origins=http://localhost:8315
```

On Windows, start Rancher Desktop with the following command:

``` powershell
cd 'C:\Program Files\Rancher Desktop\'
& '.\Rancher Desktop.exe' --remote-debugging-port="8315" --remote-allow-origins=http://localhost:8315
```

After Rancher Desktop starts, open Chrome and navigate to `http://localhost:8315/`. Select the available target to start remote debugging Rancher Desktop.





#### Remote Debugging an Extension

To remote debug an extension, follow the same process as remote debugging a build. However, you will need to load an extension before navigating to `http://localhost:8315/`. Both Rancher Desktop and the loaded extension should be listed as available targets.





### Debugging dev env with GoLand

The following steps have been tested with GoLand on Linux but might work for other
JetBrains IDEs in a similar way.

1. Install the Node.js plugin (via `File > Settings > Plugins`)

   

2. Go to the "Run/Debug Configurations" dialog (via `Run > Edit Configurations...`)
3. Add a new Node.js configuration with the following settings:
   - Name: a name for the debug configuration, e.g. `rancher desktop`
   - Node interpreter: choose your installed node interpreter, e.g. `/usr/bin/node`
   - Node parameters: `scripts/ts-wrapper.js scripts/dev.ts`
   - Working directory: choose the working directory of your project, e.g.
     `~/src/rancher-desktop`

   

4. Save the configuration
5. You can now set a breakpoint and click "Debug 'rancher desktop'" to start debugging

   


## Development Builds

### Windows and macOS

Each commit triggers a GitHub Actions run that results in application bundles
(`.exe`s and `.dmg`s) being uploaded as artifacts. This can be useful if you
want to test the latest build of Rancher Desktop as built by the build system.
You can download these artifacts from the Summary page of completed `package`
actions.


### Linux

Similar to Windows and macOS, Linux builds of Rancher Desktop are made from each
commit. However on Linux, only part of the process is done by GitHub Actions.
The final part of it is done by [Open Build Service][OBS].

There are two channels of the Rancher Desktop repositories: `dev` and `stable`.
`stable` is the channel that most users use. It is the one that users are
instructed to add in the official [documentation][docs], and the one that contains
builds that are created from official releases. `dev` is the channel that we are
interested in here: it contains builds created from the latest commit made on
the `main` branch, and on any branches that match the format `release-*`. To
learn how to install the development repositories, see below.

When using the `dev` repositories, it is important to understand the format of
the versions of Rancher Desktop available from the `dev` repositories.
The versions are in the format:

```
..<commit_time>.<commit>
```

where:

`priority` is a meaningless number that exists to give versions built from the `main`
branch priority over versions built from the `release-*` branches when updating.

`branch` is the branch name; dashes are removed due to constraints imposed by
package formats.

`commit_time` is the UNIX timestamp of the commit used to make the build.

`commit` is the shortened hash of the commit used to make the build.

[docs]: https://docs.rancherdesktop.io
[OBS]: https://build.opensuse.org/


#### `.deb` Development Repository

You can add the repo with the following steps:

```
curl -s https://download.opensuse.org/repositories/isv:/Rancher:/dev/deb/Release.key | gpg --dearmor | sudo dd status=none of=/usr/share/keyrings/isv-rancher-dev-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/isv-rancher-dev-archive-keyring.gpg] https://download.opensuse.org/repositories/isv:/Rancher:/dev/deb/ ./' | sudo dd status=none of=/etc/apt/sources.list.d/isv-rancher-dev.list
sudo apt update
```

You can see available versions with:

```
apt list -a rancher-desktop
```

Once you find the version you want to install you can install it with:

```
sudo apt install rancher-desktop=<version>
```

This works even if you already have a version of Rancher Desktop installed.


#### `.rpm` Development Repository

You can add the repo with:

```
sudo zypper addrepo https://download.opensuse.org/repositories/isv:/Rancher:/dev/rpm/isv:Rancher:dev.repo
sudo zypper refresh
```

You can see available versions with:

```
zypper search -s rancher-desktop
```

Finally, install the version you want with:

```
zypper install --oldpackage rancher-desktop=<version>
```

This works even if you already have a version of Rancher Desktop installed.


#### Development AppImages

There are no repositories for AppImages, but you can access the [latest development AppImage builds].

[latest development AppImage builds]: https://download.opensuse.org/repositories/isv:/Rancher:/dev/AppImage/

## API

Rancher Desktop supports a limited HTTP-based API. The API is defined in
`pkg/rancher-desktop/assets/specs/command-api.yaml`, and you can see examples of how it's
invoked in the client code at `go/src/rdctl`.

### Stability

The API is currently at version 1, but is still considered internal and experimental, and
is subject to change without any advance notice. At some point we expect that necessary
changes to the API will go through a warning and deprecation notice.

## Contributing

Please see [the document about contributing](CONTRIBUTING.md).


## Further Reading

Please see the [docs](docs/development/) directory for further developer documentation.

## 2. In-Tree Documentation Chapters (rancher-sandbox/rancher-desktop)

## File: README.md

# Rancher Desktop

[](https://deepwiki.com/rancher-sandbox/rancher-desktop)

Rancher Desktop is an open-source project that brings Kubernetes and
container management to the desktop. It runs on Windows, macOS and
Linux. This README pertains to the development of Rancher Desktop.
For user-oriented information about Rancher Desktop, please see [rancherdesktop.io][home].
For user-oriented documentation, please see [docs.rancherdesktop.io][docs].

[home]: https://rancherdesktop.io
[docs]: https://docs.rancherdesktop.io


## Overview

Rancher Desktop is an Electron application that is mainly written in TypeScript.
It bundles a variety of other technologies in order to provide one cohesive application.
It includes a command line tool, `rdctl`, which is written in Go.
Most developer activities, such as running a development build, building/packaging
Rancher Desktop, running unit tests, and running end-to-end tests, are done through
`yarn` scripts. Some exceptions exist, such as running BATS tests.


## Setup

### Windows

There are two options for building from source on Windows: with a
[Development VM Setup](#development-vm-setup) or
[Manual Development Environment Setup](#manual-development-environment-setup)
with an existing Windows installation.


#### Development VM Setup

1. Download a Microsoft Windows 10 [development virtual machine].
   All of the following steps should be done in that virtual machine.
2. Open a PowerShell prompt (hit Windows Key + `X` and open
   `Windows PowerShell`).
3. Run the [automated setup script]:

   ```powershell
   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
   iwr -useb 'https://github.com/rancher-sandbox/rancher-desktop/raw/main/scripts/windows-setup.ps1' | iex
   ```

4. Close the privileged PowerShell prompt.
5. Ensure `msbuild_path` and `msvs_version` are configured correctly in `.npmrc` file. Run the following commands to set these properties:

   ```
   npm config set msvs_version <visual-studio-version-number>
   npm config set msbuild_path 
   ```

   For example for Visual Studio 2022:

   ```
   npm config set msvs_version 2022
   npm config set msbuild_path "C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe"
   ```

   If you get an error message when trying to run `npm config set...`, run `npm config edit` and then add lines like

   ```
   msvs_version=2022
   msbuild_path=C:\Program Files (x86)\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe
   ```

   Do not quote the values to the right side of the equal sign. The quotes aren't needed, and it's possible that some
   processors will treat them as literal parts of the path, and then fail.
7. Configure `git` to work with linux- and macos-originated files:
   ```
   git config --global --replace-all core.autocrlf false
   git config --global --replace-all core.eol lf
   ```
If you find the `lint:go` tests are failing mysteriously, it's possible that the line-endings are incorrect.

You can now clone the repository and run `yarn`.

[development virtual machine]: https://developer.microsoft.com/en-us/windows/downloads/virtual-machines/
[automated setup script]: ./scripts/windows-setup.ps1


#### Manual Development Environment Setup

1. Install [Windows Subsystem for Linux (WSL)] on your machine. Skip this step, if WSL is already installed.
2. Open a PowerShell prompt (hit Windows Key + `X` and open `Windows PowerShell`).
3. Install [Scoop] via `iwr -useb get.scoop.sh | iex`.
4. Install 7zip, git, go, mingw, nvm, and unzip via `scoop install 7zip git go mingw nvm python unzip`.
   Check node version with `nvm list`. If node v22 is not installed or set as the current version, then install using `nvm install 22` and set as current using `nvm use 22.xx.xx`.
5. Install the yarn package manager via `npm install yarn`
6. Install Visual Studio 2017 or higher. As of this writing the latest version is available at [https://visualstudio.microsoft.com/downloads/]; if that's changed, a good search engine should find it.
7. Make sure you have the `Windows SDK` component installed. This [Visual Studio docs] describes steps to install components.
   The [Desktop development with C++] workload needs to be selected, too.
8. Configure `git` to work with linux- and macos-originated files:
   ```
   git config --global --replace-all core.autocrlf false
   git config --global --replace-all core.eol lf
   ```
If you find the `lint:go` tests are failing mysteriously, it's possible that the line-endings are incorrect.
9. Ensure `msbuild_path` and `msvs_version` are configured correctly in `.npmrc` file. Run the following commands to set these properties:

   ```
   npm config set msvs_version <visual-studio-version-number>
   npm config set msbuild_path 
   ```

   For example for Visual Studio 2022:

   ```
   npm config set msvs_version 2022
   npm config set msbuild_path "C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe"
   ```

   If you get an error message when trying to run `npm config set...`, run `npm config edit` and then add lines like

   ```
   msvs_version=2022
   msbuild_path=C:\Program Files (x86)\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe
   ```

   Do not quote the values to the right side of the equal sign. They aren't needed, and it's possible that some
   processor will treat them as literal parts of the path, and then fail.

You can now clone the repository and run `yarn`.

[Scoop]: https://scoop.sh/
[Visual Studio docs]: https://docs.microsoft.com/en-us/visualstudio/install/modify-visual-studio?view=vs-2022
[Windows Subsystem for Linux (WSL)]: https://docs.microsoft.com/en-us/windows/wsl/install
[Desktop development with C++]: https://learn.microsoft.com/en-us/visualstudio/install/modify-visual-studio?view=vs-2022#change-workloads-or-individual-components

### macOS

Install `nvm` to get Node.js and npm:

See https://github.com/nvm-sh/nvm#installing-and-updating and run the `curl` or `wget`
command to install nvm.

Note that this script adds code dealing with `nvm` to a profile file
(like `~/.bash_profile`). To add access to `nvm` to a current shell session,
you'll need to `source` that file.

Currently we build Rancher Desktop with Node 22. To install it, run:

```
nvm install 22.14
```

Next, you'll need to install the yarn package manager:

```
npm install yarn
```

You'll also need to run `brew install go` if you haven't installed go.

Then you can install dependencies with:
```
yarn
```

> ### ⚠️ Working on a mac with an M1 chip?
>
> You will need to set the `M1` environment variable before installing dependencies and running any npm scripts:
>
> ```
> export M1=1
> yarn
> ```
>
> You will want to run `git clean -fdx` to clean out any cached assets and re-downloaded with the correct arch before running `yarn` if you previously installed dependencies without setting `M1` first.

### Linux

Ensure you have the following installed:

- [Node.js][Node.js] v22. **Make sure you have any development packages
  installed.** For example, on openSUSE Leap 15.6 you would need to install
  `nodejs22` and `nodejs22-devel`.

- [yarn classic][yarn-classic]

- Go 1.22 or later.

- Dependencies described in the [`node-gyp` docs][node-gyp] installation.
  This is required to install the [`ffi-napi`][ffi-napi] npm package. These docs mention
  "a proper C/C++ compiler toolchain". You can install `gcc` and `g++` for this.

Then you can install dependencies with:

```
yarn
```

You can then run Rancher Desktop as described below. It may fail on the first run -
if this happens, try doing a factory reset and re-running, which has been known
to solve this issue.

[Node.js]: https://nodejs.org/
[ffi-napi]: https://www.npmjs.com/package/ffi-napi
[node-gyp]: https://github.com/nodejs/node-gyp#on-unix
[yarn-classic]: https://classic.yarnpkg.com/lang/en/docs/install/#debian-stable


## Running

Once you have your dependencies installed you can run a development version
of Rancher Desktop with:

```
yarn dev
```


## Tests

To run the unit tests:

```
yarn test
```

To run the integration tests:

```
yarn test:e2e
```


## Building

Rancher can be built from source on Windows, macOS or Linux.
Cross-compilation is currently not supported. To run a build do:

```
yarn build
yarn package
```

The build output goes to `dist/`.

### Debugging builds with the Chrome remote debugger

The Chrome remote debugger allows you to debug Electron apps using Chrome Developer Tools. You can use it to access log messages that might output to the developer console of the renderer process. This is especially helpful for getting additional debug information in production builds of Rancher Desktop.

#### Starting Rancher Desktop with Remote Debugging Enabled

To enable remote debugging, start Rancher Desktop with the `--remote-debugging-port` argument.

On Linux, start Rancher Desktop with the following command:

``` bash
rancher-desktop --remote-debugging-port="8315" --remote-allow-origins=http://localhost:8315
```

On macOS, start Rancher Desktop with the following command:

```
/Applications/Rancher\ Desktop.app/Contents/MacOS/Rancher\ Desktop --remote-debugging-port="8315" --remote-allow-origins=http://localhost:8315
```

On Windows, start Rancher Desktop with the following command:

``` powershell
cd 'C:\Program Files\Rancher Desktop\'
& '.\Rancher Desktop.exe' --remote-debugging-port="8315" --remote-allow-origins=http://localhost:8315
```

After Rancher Desktop starts, open Chrome and navigate to `http://localhost:8315/`. Select the available target to start remote debugging Rancher Desktop.





#### Remote Debugging an Extension

To remote debug an extension, follow the same process as remote debugging a build. However, you will need to load an extension before navigating to `http://localhost:8315/`. Both Rancher Desktop and the loaded extension should be listed as available targets.





### Debugging dev env with GoLand

The following steps have been tested with GoLand on Linux but might work for other
JetBrains IDEs in a similar way.

1. Install the Node.js plugin (via `File > Settings > Plugins`)

   

2. Go to the "Run/Debug Configurations" dialog (via `Run > Edit Configurations...`)
3. Add a new Node.js configuration with the following settings:
   - Name: a name for the debug configuration, e.g. `rancher desktop`
   - Node interpreter: choose your installed node interpreter, e.g. `/usr/bin/node`
   - Node parameters: `scripts/ts-wrapper.js scripts/dev.ts`
   - Working directory: choose the working directory of your project, e.g.
     `~/src/rancher-desktop`

   

4. Save the configuration
5. You can now set a breakpoint and click "Debug 'rancher desktop'" to start debugging

   


## Development Builds

### Windows and macOS

Each commit triggers a GitHub Actions run that results in application bundles
(`.exe`s and `.dmg`s) being uploaded as artifacts. This can be useful if you
want to test the latest build of Rancher Desktop as built by the build system.
You can download these artifacts from the Summary page of completed `package`
actions.


### Linux

Similar to Windows and macOS, Linux builds of Rancher Desktop are made from each
commit. However on Linux, only part of the process is done by GitHub Actions.
The final part of it is done by [Open Build Service][OBS].

There are two channels of the Rancher Desktop repositories: `dev` and `stable`.
`stable` is the channel that most users use. It is the one that users are
instructed to add in the official [documentation][docs], and the one that contains
builds that are created from official releases. `dev` is the channel that we are
interested in here: it contains builds created from the latest commit made on
the `main` branch, and on any branches that match the format `release-*`. To
learn how to install the development repositories, see below.

When using the `dev` repositories, it is important to understand the format of
the versions of Rancher Desktop available from the `dev` repositories.
The versions are in the format:

```
..<commit_time>.<commit>
```

where:

`priority` is a meaningless number that exists to give versions built from the `main`
branch priority over versions built from the `release-*` branches when updating.

`branch` is the branch name; dashes are removed due to constraints imposed by
package formats.

`commit_time` is the UNIX timestamp of the commit used to make the build.

`commit` is the shortened hash of the commit used to make the build.

[docs]: https://docs.rancherdesktop.io
[OBS]: https://build.opensuse.org/


#### `.deb` Development Repository

You can add the repo with the following steps:

```
curl -s https://download.opensuse.org/repositories/isv:/Rancher:/dev/deb/Release.key | gpg --dearmor | sudo dd status=none of=/usr/share/keyrings/isv-rancher-dev-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/isv-rancher-dev-archive-keyring.gpg] https://download.opensuse.org/repositories/isv:/Rancher:/dev/deb/ ./' | sudo dd status=none of=/etc/apt/sources.list.d/isv-rancher-dev.list
sudo apt update
```

You can see available versions with:

```
apt list -a rancher-desktop
```

Once you find the version you want to install you can install it with:

```
sudo apt install rancher-desktop=<version>
```

This works even if you already have a version of Rancher Desktop installed.


#### `.rpm` Development Repository

You can add the repo with:

```
sudo zypper addrepo https://download.opensuse.org/repositories/isv:/Rancher:/dev/rpm/isv:Rancher:dev.repo
sudo zypper refresh
```

You can see available versions with:

```
zypper search -s rancher-desktop
```

Finally, install the version you want with:

```
zypper install --oldpackage rancher-desktop=<version>
```

This works even if you already have a version of Rancher Desktop installed.


#### Development AppImages

There are no repositories for AppImages, but you can access the [latest development AppImage builds].

[latest development AppImage builds]: https://download.opensuse.org/repositories/isv:/Rancher:/dev/AppImage/

## API

Rancher Desktop supports a limited HTTP-based API. The API is defined in
`pkg/rancher-desktop/assets/specs/command-api.yaml`, and you can see examples of how it's
invoked in the client code at `go/src/rdctl`.

### Stability

The API is currently at version 1, but is still considered internal and experimental, and
is subject to change without any advance notice. At some point we expect that necessary
changes to the API will go through a warning and deprecation notice.

## Contributing

Please see [the document about contributing](CONTRIBUTING.md).


## Further Reading

Please see the [docs](docs/development/) directory for further developer documentation.

---

## File: bats/README.md

## Overview

BATS is a testing framework for Bash shell scripts that provides supporting libraries and helpers for customizable test automation.

## Setup

It's important to have a Rancher Desktop CI or release build installed and running with no errors before executing the BATS tests.

### On Windows:

Clone the Git repository of Rancher Desktop, whether directly inside a WSl distro or on the host Win32.
If the repository will be cloned on Win32, prior to cloning it, it's important to set up the Git configuration by running the following commands:

  ```powershell
  git config --global core.eol lf
  git config --global core.autocrlf false
  ```
Note that changing `crlf` settings is not needed when you clone it inside a WSL distro.
Regardless of the repository location, the BATS tests can be executed ONLY from inside a WSL distribution. So, if the repository is cloned on Win32, the repository can be located within a WSL distro from /mnt/c, as it represents the `C:` drive on Windows.

### On Linux:

ImageMagick is required to take screenshots on failure.

### All platforms:

From the root directory of the Git repository, run the following commands to install BATS and its helper libraries into the BATS test directory:

  ```sh
  git submodule update --init
  ```

## Running BATS

To run the BATS test, specify the path to BATS executable from bats-core and run the following commands:

To run a specific test set from a bats file:

```sh
cd bats
./bats-core/bin/bats tests/registry/creds.bats
```

To run all BATS tests:

```sh
cd bats
./bats-core/bin/bats tests/*/
```

To run the BATS test, specifying some of Rancher Desktop's configuration, run the following commands:

```sh
cd bats
RD_CONTAINER_RUNTIME=moby RD_USE_IMAGE_ALLOW_LIST=false ./bats-core/bin/bats tests/registry/creds.bats
```

There is an experimental subset of BATS tests that pass with an under-construction openSUSE based
distribution; that can be selected via the `opensuse` tag:

```sh
cd bats
./bats-core/bin/bats --filter-tags opensuse tests/*/
```

### On Windows:

BATS must be executed from within a WSL distribution. (You have to cd into `/mnt/c/REPOSITORY_LOCATION` from your unix shell.)

To test the Windows-based tools, set `RD_USE_WINDOWS_EXE` to `true` before running.

### RD_LOCATION

By default bats will use Rancher Desktop installed in a "system" location. If
that doesn't exists, it will try a "user" location, followed by the local "dist"
directory inside the local git directory. The final option if none of the above
apply is to use "dev", which uses `yarn dev`. On Linux there is no "user"
location.

You can explicitly request a specific install location by setting `RD_LOCATION` to `system`, `user`, `dist`, or `dev`:

```
cd bats
RD_LOCATION=dist ./bats-core/bin/bats ...
```

### RD_NO_MODAL_DIALOGS

By default, bats tests are run with the `--no-modal-dialogs` option so fatal errors are written to `background.log`,
rather than appearing in a blocking modal dialog box. If you *want* those dialog boxes, you can specify

```
cd bats
RD_NO_MODAL_DIALOGS=false ./bats-core/bin/bats ...
```

The default value for this environment variable is `true`.

## Writing BATS Tests

1. Add BATS test by creating files with `.bats` extension under `./bats/tests/FOLDER_NAME`
2. A Bats test file is a Bash script with special syntax for defining test cases. BATS syntax and libraries for defining test hooks, writing assertions and treating output can be accessed via BATS [documentation](https://bats-core.readthedocs.io/en/stable/):
    - [bats-core](https://github.com/rancher-sandbox/bats-core)
    - [bats-assert](https://github.com/rancher-sandbox/bats-assert)
    - [bats-file](https://github.com/rancher-sandbox/bats-file)
    - [bats-support](https://github.com/rancher-sandbox/bats-support)

## BATS linting

After finishing to develop a BATS test suite, you can locally verify the syntax and formatting feedback by linting prior to submitting a PR, following the instructions:

  1. Make sure to have installed `shellcheck` and `shfmt`.

     On macOS:
     - Assuming you have Homebrew:
       ```sh
       brew install shfmt shellcheck
       ```
     - If you have Go installed, you can also install `shfmt` by running:
       ```sh
       go install mvdan.cc/sh/v3/cmd/shfmt@v3.6.0
       ```

     On Linux:
     - The simplest way to install ShellCheck locally is through your package managers
       such as `apt/apt-get/yum`. Run commands as per your distro.
       ```
       sudo apt install shellcheck
       ```
     - `shfmt` is available as a snap application. If your distribution has snap
       installed, you can install `shfmt` using the command:
       ```sh
       sudo snap install shfmt
       ```
       The other way to install `shfmt` is by using the following one-liner command:
       ```sh
       curl -sS https://webinstall.dev/shfmt | bash
       ```
       If you have Go installed, you can also install `shfmt` by running:
       ```sh
       go install mvdan.cc/sh/v3/cmd/shfmt@v3.6.0
       ```
     On Windows:
     - The simplest way to install `shellcheck` locally is:

       Via chocolatey:
       ```powershell
       choco install shellcheck
       ```
       Via scoop:
       ```powershell
       scoop install shellcheck
       ```
     - If you have Go installed, you can install `shfmt` by running:
       ```powershell
       go install mvdan.cc/sh/v3/cmd/shfmt@v3.6.0
       ```

  2. Get the syntax and formatting feedback for BATS linting by running from the
     root directory of the Git repository:
     ```sh
     make -C bats lint
     ```
  3. Please, make sure to fix the highlighted linting errors prior to submitting
     a PR. You can automatically apply formatting changes suggested by `shfmt`
     by running the following command:
     ```sh
     shfmt -w ./bats/tests/containers/factory-reset.bats
     ```

## Running BATS in CI

We also run BATS in CI via [GitHub Actions]; at the time of writing, we do not
yet run them automatically due to failing tests.  There are many optional fields
that may be set when triggering a run manually:

[GitHub Actions]: https://github.com/rancher-sandbox/rancher-desktop/actions/workflows/bats.yaml




### Debugging BATS in CI

Sometimes we may need to drill down why a test is failing in CI (for example,
when the same test doesn't fail locally).  Some things might be helpful:

- Logs for failing runs can be downloaded by clicking on the :file_folder: icon
  in the summary table at the bottom of the run.
- If changes to the application or BATS tests are required, a new [package
  action] run will need to be manually triggered.  In that case, setting `sign`
  to `false` in that run will speed it up by a few minutes, by skipping the
  check for properly signed installers — that can be dealt with when the actual
  PR is made.
- When focusing on a particular failing platform, it may be possible to shave
  off a few minutes by setting the `package-id` field (see above) when starting
  the BATS run; this lets you start the run once the platform you're interested
  in has completed packaging, without waiting for other platforms.  This should
  be set to the number after `…/actions/runs/` in the URL.
- When testing, it is a good idea to [fork the repository] and run the tests
  there; this lets you have your own set of GitHub runner quota (which means not
  waiting for PRs other people create).  It is not necessary to set `owner` and
  `repo` fields when running the BATS action (because it defaults to the
  repository the action is running on).  You will, however, need to run the
  [package action] at least once in your fork.
- It is much faster to specify `tests`, `platforms`, and `engines` to limit
  runs to only the tests you care about; the full run takes somewhere over two
  hours total, even spread out over multiple parallel jobs.

[package action]: https://github.com/rancher-sandbox/rancher-desktop/actions/workflows/package.yaml
[fork the repository]: https://github.com/rancher-sandbox/rancher-desktop/fork

---

## File: docs/networking/windows/rancher-desktop-guest-agent.md

# **[Rancher Desktop Guest Agent](../../../src/go/guestagent)**

The Rancher Desktop Guest Agent operates within the Rancher Desktop WSL distribution, particularly in an isolated namespace when the network tunnel is enabled. It facilitates interactions between various container engine APIs like Moby, containerd, and Kubernetes. The agent monitors container/service creation events from these APIs and, upon detecting ports needing exposure, forwards the port mappings to internal services accordingly. This ensures efficient and automated port forwarding management within the Rancher Desktop environment.

```mermaid
flowchart  LR;
subgraph Host["HOST"]
host-switch["host-switch"]
end
 subgraph VM["WSL"]
  subgraph netNs["Isolated Network Namespace"]
   guest-agent["Guest Agent"]
   docker(("Docker API"))
   containerd(("Containerd API"))
   kubernetes(("K8s API"))
   iptables(("iptable scanning"))
   guest-agent <----> docker
   guest-agent <----> containerd
   guest-agent <----> kubernetes
   guest-agent <----> iptables
   guest-agent ----> host-switch
  end
  subgraph defaultNs["Default Namespace"]
  wsl-proxy["wsl-proxy"]
  end
  guest-agent ----> |UNIX socket| wsl-proxy
 end
```

### Supported Flags

-   **debug**: Enables debug logging.

-   **docker**: When this flag is enabled, port mapping via docker API monitoring is enabled. See the port mapping and Docker sections below for details.

-   **kubernetes**: Enables Kubernetes service port forwarding. When enabled, the Rancher Desktop Guest Agent creates a watcher for the Kubernetes API, monitoring NodePort and LoadBalancer services needing port forwarding. For services with exposed ports, the agent creates corresponding port mappings, forwarding them to Rancher Desktop Networking’s `host-switch`, which hosts an API for exposing ports from the host into the network namespace. If WSL integration is enabled, the port mapping is also forwarded to Rancher Desktop Networking’s `wsl-proxy`, allowing access from other WSL distributions.

-   **kubeconfig**: Specifies the path to `kubeconfig` for locating the Kubernetes API endpoint. By default, it looks in `/etc/rancher/k3s/k3s.yaml`.

-   **iptables**: This flag enables the scanning of iptables. In newer versions of Kubernetes, kubelet no longer creates listeners for NodePort and LoadBalancer services. To rectify this, we manually create those listeners so the port forwarding functions correctly. The guest agent creates a corresponding port mapping that represents the service’s exposed port. The port mapping is then forwarded to Rancher Desktop Networking’s `host-switch`, which hosts an API for exposing ports from the host into the network namespace. If WSL integration options are enabled within Rancher Desktop, a copy of that port mapping is also forwarded to Rancher Desktop Networking’s `wsl-proxy`. The `wsl-proxy` exposes the service port to enable users to access it from other WSL distros.

-   **containerd**: When this flag is enabled, the guest agent monitors container events from the containerd API. It connects to the Containerd API via the containerd socket (`/run/k3s/containerd/containerd.sock`). Whenever a container is created or deleted, if there are exposed ports associated with that container, the guest agent creates a corresponding port mapping. This port mapping is then forwarded to Rancher Desktop Networking's `host-switch`, which hosts an API for exposing ports from the host into the network namespace. If WSL integration options are enabled within Rancher Desktop, a copy of this port mapping is also forwarded to Rancher Desktop Networking's `wsl-proxy`. The `wsl-proxy` exposes the container's port to enable users to access it from other WSL distros.

-   **containerdSock**: File path for the containerd socket address. If no argument is provided, it defaults to `/run/k3s/containerd/containerd.sock`.

-   **vtunnelAddr**: Peer address for the Vtunnel process that forwards port mappings to the Vtunnel Host process over `AF_VSOCK`. This feature will soon be deprecated.

-   **k8sServiceListenerAddr**: Specifies an IP address (`0.0.0.0` or `127.0.0.1`) to bind Kubernetes services on the host.

-   **adminInstall**: This flag indicates whether Rancher Desktop is installed with administrator privileges. It is used to enable Network Tunnel mode, where port mappings are forwarded to Rancher Desktop Networking's `host-switch`. The `host-switch` hosts an API that exposes ports from the host into the network namespace.

-   **k8sAPIPort**: Specifies the Kubernetes API port, which is forwarded to `wsl-proxy` to allow other distros that are part of WSL integrations to  interact via `kubectl`.

## PortMapping

Is a struct object that represents an exposed container or a service. [Portmapping](../../../src/go/guestagent/pkg/types/portmapping.go#L23) objects consist of the following fields:

```
type PortMapping struct {
	// Remove indicates whether to remove or add the entry
	Remove bool `json:"remove"`
	// Ports are the port mappings for both IPV4 and IPV6
	Ports nat.PortMap `json:"ports"`
	// ConnectAddrs are the backend addresses to connect to
	ConnectAddrs []ConnectAddrs `json:"connectAddrs"`
}
```
## Networking Mode

Rancher Desktop Guest Agent can operate in one of two networking modes, depending on startup arguments:

**-adminInstall**

The Network Tunnel mode allows the Guest Agent to operate in an isolated network namespace with a dedicated iptables. This mode is enabled through Rancher Desktop Networking.

None  **-adminInstall**

Rancher Desktop Guest Agent operates in non-admin user mode. In this mode, all port mappings are bound to localhost, and the use of privileged ports is restricted.


## Containerd

When containerd mode is enabled, the guest agent monitors the containerd API for the following container events:
```
/tasks/start
/containers/update
/tasks/exit
```
If it detects any exposed ports associated with a container, it creates a port mapping object. Depending on the selected network mode, the port mapping object is then forwarded to the host. If the privileged service is enabled, it utilizes the vtunnel peer process to communicate the port mappings with privileged services. Alternatively, if network tunnel mode is enabled, it sends the port mappings to the API offered in the host switch process.

If network tunnel mode is enabled along with the WSL integration option, a copy of the port mapping is also forwarded to the WSL proxy process, enabling access to the exposed port from other distributions.

## Docker

Similar to containerd mode, when Docker mode is enabled, the guest agent watches Docker API with the following container events filter:
```
Filters: filters.NewArgs(
    filters.Arg("type", "container"),
    filters.Arg("event", startEvent),
    filters.Arg("event", stopEvent),
    filters.Arg("event", dieEvent)
),
```
If it detects any exposed ports associated with a container, it creates a port mapping object. Depending on the selected network mode, the port mapping object is then forwarded to the host. If the privileged service is enabled, it uses the vtunnel peer process to communicate the port mappings with privileged services. Otherwise, if network tunnel mode is enabled, it sends the port mappings to the API offered in the host switch process.

If network tunnel mode is enabled along with the WSL integration option, a copy of the port mapping is also forwarded to the `wsl-proxy` process, allowing access to the exposed port from other distributions.

Additionally, Docker mode creates a series of iptables rules associated with the `PREROUTING` and `POSTROUTING` chains.

The `PREROUTING` rule rewrites the destination IP address of any packets received by the local system and destined for `192.168.127.2` to `127.0.0.1`. Meanwhile, the `POSTROUTING` chain rule rewrites the source IP address of any packets being sent out through the eth0 network interface to the IP address of that interface (eth0). These rules are necessary because when the port binding is set to `127.0.0.1`, an additional `DNAT` rule is added in the main `DOCKER` chain after the existing rule using `--append`.

This adjustment is essential because the initial `DOCKER DNAT` rule created by Docker only allows traffic to be routed to `localhost` from `localhost`. Therefore, an additional rule is added to permit traffic to any destination IP address, enabling the service to be discoverable through the namespaced network's subnet.

These changes are necessary as the traffic is routed via the vm-switch over the tap network. The existing `DNAT` rule is as follows:

```
DNAT tcp -- anywhere localhost tcp dpt:9119 to:10.4.0.22:80
```
The following rule is added after the existing rule:
```
DNAT tcp -- anywhere anywhere tcp dpt:9119 to:10.4.0.22:80
```
## Kubernetes

When this option is enabled, the Rancher Desktop guest agent uses the Kubernetes service watcher to subscribe to the Kubernetes API for any services of type NodePort and LoadBalancer that require port exposure. If the service watcher detects such services, it creates a port mapping object representing each service. The port mapping object is then forwarded to the host based on the selected network mode. If the privileged service is enabled, it uses the vtunnel peer process to communicate the port mappings with privileged services. Otherwise, if network tunnel mode is enabled, it sends the port mappings to the API provided in the host switch process.

It is important to note that if the `k8sServiceListenerAddr` flag is provided, the specified IP address (either `0.0.0.0` or `127.0.0.1`) is used to bind the Kubernetes services on the host.

Additionally, if network tunnel mode is enabled along with the WSL integration option, a copy of the port mapping is also forwarded to the `wsl-proxy` process to allow access to the exposed port from other distributions. However, when the Kubernetes option is enabled, the guest agent statically emits a port mapping to the `wsl-proxy` process in the default network. This port mapping represents the Kubernetes API port (`6443`) to allow access to the Kubernetes API from other distributions.

Below port mapping is an example of what is emitted to `wsl-proxy`:
```
types.PortMapping {
    Remove: false,
    Ports: nat.PortMap {
        port: [] nat.PortBinding {
            {
                HostIP: "127.0.0.1",
                HostPort: 6443,
            },
        },
    },
}
```

## iptables

In [newer versions](https://github.com/rancher-sandbox/rancher-desktop/blob/bb7f71f18828c45b711d6d4982a2dcaf19f8f3fa/pkg/rancher-desktop/backend/k3sHelper.ts#L1152) of Kubernetes, kubelet no longer automatically creates listeners for NodePort and LoadBalancer services. To address this, we manually create these listeners to ensure proper port forwarding functionality. Service ports requiring forwarding are identified in iptables DNAT. When iptables identifies such ports, it creates a port mapping object representing that service. Depending on the selected network mode, the port mapping object is then forwarded to the host. If the privileged service is enabled, it uses the vtunnel peer process to communicate the port mappings with privileged services. Otherwise, if network tunnel mode is enabled, it sends the port mappings to the API provided by the host switch process.

If network tunnel mode is enabled along with the WSL integration option, a copy of the port mapping is also forwarded to the `wsl-proxy` process, allowing access to the exposed port from other distributions.

## Port forwarding (Network Tunnel)

```
/* Detailed source-code truncated for AI context efficiency. */
```

---

## File: docs/networking/windows/rancher-desktop-networking.md

# [Rancher Desktop Networking](../../../src/go/networking/)

Rancher Desktop Networking primarily acts as a layer 2 switch between the host (currently Windows only) and the VM (WSL) using the `AF_VSOCK` protocol. It facilitates the transmission of Ethernet frames from the VM to the host. Additionally, it provides `DNS`, `DHCP`, and dynamic port forwarding functionalities. The Rancher Desktop Networking comprises several key services: `host-switch`, `vm-switch`, `network-setup`, and `wsl-proxy`. It utilizes [gvisor's](https://github.com/google/gvisor) network stack and draws inspiration from the [gvisor-tap-vsock](https://github.com/google/gvisor) project.

The diagram below demonstrates the overall architecture of Rancher Desktop Networking:

```mermaid
flowchart  LR
subgraph  hostSwitch["host-switch.exe"]
vsockHost{"main loop"}
eth(("reconstruct ETH frames"))
portForwarding["Port Forwarding API"]
end
subgraph  Host["HOST"]
dns["DNS"]
syscall(("OS syscall"))
hostSwitch
end
subgraph  netNs["Isolated Network Namespace"]
vsockVM{"VM Switch"}
tapDevice("eth0")
veth-rd-ns("veth-rd-ns")
containers["containers"]
services["services"]
end
subgraph  WSL["WSL"]
netNs
other-distro(("Other Distros"))
veth-rd-wsl("veth-rd-wsl")
wsl-proxy{"wsl-proxy"}
end
vsockHost  <---->  eth  &  dns
eth  <---->  syscall
vsockHost  ---->  portForwarding
tapDevice  -- ethernet frames -->  vsockVM
veth-rd-ns  -- ethernet frames -->  vsockVM
veth-rd-wsl  <---->  veth-rd-ns
other-distro  <---->  wsl-proxy
wsl-proxy  <---->  veth-rd-wsl
containers  <---->  tapDevice
services  <---->  tapDevice
vsockVM <-- AF_VSOCK ---> vsockHost
```

## host-switch:

The host-switch runs on the Windows host and acts as a receiver for all traffic originating from the network namespace within the WSL VM. It performs a handshake to identify the correct VM to communicate with over `AF_VSOCK`. This process retrieves the GUID for the appropriate Hyper-V VM (most likely WSL). It then performs a handshake with the network-setup process running in the WSL distribution to ensure the `AF_VSOCK` connection is established with the correct VM. Once the ready signal is received from the vm-switch, an `AF_VSOCK` connection is established to listen for incoming traffic from that VM. Additionally, the host-switch provides a DNS resolver that runs in the user space network and an API for dynamic port forwarding. The port forwarding API offers the following endpoints:

- `/services/forwarder/all`: Lists all the currently forwarded ports.
- `/services/forwarder/expose`: Exposes a port.
- `/services/forwarder/unexpose`: Unexposes a port.

## Supported Flags:

- **debug**: Enables debug logging.
- **subnet**: This flag defines a subnet range with a CIDR suffix for a virtual network. If it is not defined, it uses `192.168.127.0/24` as the default range. It is important to note that this value needs to match the [subnet](https://github.com/rancher-sandbox/rancher-desktop/blob/6abacdc804d6414f17439a97f22e0c9c87f6249d/cmd/vm/switch_linux.go#L59) flag in the vm-switch.
- **port-forward**: This is a list of static ports that need to be pre-forwarded to the WSL VM. These ports are not dynamically retrieved from any of the APIs that the Rancher Desktop guest agent interacts with.

## network-setup:

The reason for its creation was that the `AF_VSOCK` connection could not be established between the host and a process residing inside the network namespace within the VM, as such capability is not currently supported by `AF_VSOCK`. As a result, the network setup was created. Its main responsibility is to respond to the handshake request from the `host-switch.exe`. Once the handshake process is successful with the `host-switch`, the `network-setup` process creates a new network namespace and attempts to start its subprocess, `vm-switch`, in the newly created network namespace. It also hands over the `AF_VSOCK` connection to the `vm-switch` as a file descriptor in the new namespace.

Additionally, it calls unshare with provided arguments through [---unshare-args](https://github.com/rancher-sandbox/rancher-desktop/blob/6abacdc804d6414f17439a97f22e0c9c87f6249d/cmd/network/setup_linux.go#L272). The process also establishes a Virtual Ethernet pair consisting of two endpoints: `veth-rd-ns` and `veth-rd-wsl`. `veth-rd-wsl` resides within the default namespace and is configured to listen on the IP address `192.168.143.2`. Conversely, `veth-rd-ns` is located within a network namespace and is assigned the IP address `192.168.143.1`. The virtual Ethernet pair allows accessibility from the default network into the network namespace, which is particularly useful when WSL integration is enabled.

## Supported Flags:

- **debug**: enable the debug logging

- **trace-packets**: Forward per-packet tracing to the `vm-switch` process (see the `vm-switch` flag below). Off by default; very verbose.

- **tap-interface**: The name of the tap interface that is created by the vm-switch upon startup, e.g., `eth0`, `eth1`. This value is passed to the `vm-switch` process when the `network-setup` attempts to start it. If no value is provided, the default name of `eth0` is used.

- **subnet**: A subnet range with a CIDR suffix that is associated with the tap interface in the network namespace. If it is not defined, it uses `192.168.127.0/24` as the default range. It is important to note that this value needs to match the [subnet](https://github.com/rancher-sandbox/rancher-desktop/blob/6abacdc804d6414f17439a97f22e0c9c87f6249d/cmd/host/switch_windows.go#L54) flag in the `host-switch`.

- **tap-mac-address**: MAC address associated with the tap interface created by the vm-switch in the network namespace. If no address is provided, the default address of `5a:94:ef:e4:0c:ee`is used.

- **vm-switch-path**: The path to the `vm-switch` binary that will run in a new namespace. This value is used with `nsenter` to switch the namespace and start the `vm-switch` in the network namespace.

- **vm-switch-logfile**: The path to the logfile for the vm-switch process.

- **unshare-arg**: The command argument to pass to the unshare program in addition to the following [arguments](https://github.com/rancher-sandbox/rancher-desktop/blob/6abacdc804d6414f17439a97f22e0c9c87f6249d/cmd/network/setup_linux.go#L272).

- **logfile**: Path to the logfile for the `network-setup` process.

## vm-switch:

Once the network-setup starts the `vm-switch` process in the new namespace, the `vm-switch` creates a tap device (`eth0`) and a loopback device (`lo`). When the `eth0` tap device is successfully created, it uses the `DHCP` client to acquire an IP address within the defined range from the `DHCP` server. Once the `eth0` tap device is up and running, the kernel forwards all raw Ethernet frames originating from the network namespace to the tap device. In addition to the traffic from the network namespace, the kernel also forwards all the traffic that arrives at `veth-rd-ns` from its pair, `veth-rd-wsl`, in the default namespace.

The tap device forwards the Ethernet frames over [vsock](https://wiki.qemu.org/Features/VirtioVsock) to the host. The process on the host (`host-switch.exe`) decapsulates the frames. Since host-switch maintains both internal (`vm-switch` to `host-switch.exe`) and external (`host-switch.exe` to the internet) connections, it connects to the external endpoints via syscalls.

## Supported Flags:

- **debug**: Enable the debug logging

- **trace-packets**: Log a decoded dump of every packet in both directions. **Off by default** and deliberately independent of `-debug`, because it is extremely verbose and writes to `vm-switch.log` on the data-plane hot path. Enable it at startup by launching Rancher Desktop with `RD_VMSWITCH_TRACE=1` in the environment, or toggle it on/off at runtime (without restarting the network stack) by sending `SIGUSR1` to the `vm-switch` process. `vm-switch` runs in the top-level WSL (init) PID namespace, so signal it from there — e.g. `wsl -d rancher-desktop --exec sh -c 'kill -USR1 $(pgrep vm-switch)'` — **not** via `rdctl shell`, which enters the Rancher Desktop network namespace where `vm-switch` is not visible.

- **tap-interface**: Tap interface name to create, eg. eth0, eth1

- **tap-mac-address** : MAC address that is associated with the tap interface

- **subnet**: The subnet range with CIDR suffix associated with the tap interface. Although this value is passed from network-setup, it must match the subnet flag in `host-switch` and `network-setup`.

- **logfile**: Path to `vm-switch` process logfile

## wsl-proxy:

Its primary function comes into play when WSL integration is activated alongside the network tunnel. Running within the default network namespace, it establishes a Unix socket listener (`/run/wsl-proxy.sock`) for the guest agent process to connect to from inside the network namespace. The guest agent forwards port mappings from various APIs (docker, containerd, and K8s) over the Unix socket to the `wsl-proxy`. Upon receiving the port mappings, the wsl-proxy sets up listeners bound to localhost for those ports. When traffic arrives at these listeners, it forwards the traffic to the bridge interface connecting the default namespace to the namespaced network, facilitating bidirectional traffic flow.

## Supported Flags:

- **debug**: Enable the debug logging

- **logfile**: Path to the logfile for `wsl-proxy` process

- **socketFile**: This is the path to the `.sock` file for the UNIX socket connection established between the Rancher Desktop guest agent and the `wsl-proxy`. If not provided, the default value of `/run/wsl-proxy.sock` is used.

- **upstreamAddress**: This is the IP address associated with the upstream server to use. It corresponds to the address of the veth pair connecting the default namespace to the network namespace, specifically `veth-rd-ns`. The default value is `192.168.143.1`.


## Process Timelines:

Below is a flow chart that demonstrates the process start up orders.

```mermaid
sequenceDiagram
    participant wsl-init (pid n)
    participant network-setup
    participant vm-switch
    participant wsl-init (pid 1)
    participant host-switch.exe
    Note over wsl-init (pid n),wsl-init (pid 1): WSL distro (Network Namespace)
    Note over host-switch.exe: windows host
    wsl-init (pid n)->>network-setup: spawn process
    host-switch.exe->>network-setup: handshake request
    network-setup->>host-switch.exe: handshake response (READY signal)
    host-switch.exe->>network-setup: vsock listener ready
    network-setup->>network-setup: open vsock
    network-setup->>network-setup: create namespace
    network-setup->>network-setup: create veth pair (veth-rd)
    network-setup->>vm-switch: spawn
    Note over network-setup,vm-switch: spawn in network namespace
    Note over network-setup,vm-switch: pass in vsock connection as fd
    network-setup->>wsl-init (pid 1): spawn
    Note over network-setup,wsl-init (pid 1): spawns in netns, new mnt/pid ns
    vm-switch->>vm-switch: create lo/eth0
    vm-switch->>vm-switch: DHCP eth0
    vm-switch->>vm-switch: listen for ethernet frames
    vm-switch->>host-switch.exe: forward ethernet
    wsl-init (pid 1)-->>wsl-init (pid 1): Spawn /sbin/init
```

---

## File: docs/networking/windows/README.md

# Rancher Desktop Network Documentation

The table of contents below provides references to all the projects that comprise the Rancher Desktop network stack on windows platform.

- [Rancher Desktop Guest Agent](rancher-desktop-guest-agent.md)
- [Rancher Desktop Networking](rancher-desktop-networking.md)

## Feature Parity

Below is table to demonstrate the feature parity between both classic networking and tunneled networking.



| feature | classic networking | tunneled network |  |  |  |
| --- | --- | --- | --- | --- | --- |
| admin | non-admin | admin | non-admin |  |  |
| Docker port forwarding | localhost | ✅ | ✅ | ✅ | ✅ |
| 0.0.0.0 | ✅ | 🚫 | ✅ | 🚫 |  |
| Containerd port forwarding | localhost | ✅ | ✅ | ✅ | ✅ |
| 0.0.0.0 | ✅ | 🚫 | ✅ | 🚫 |  |
| Kubernetes port forwarding | localhost | ✅ | ✅ | ✅ | ✅ |
| 0.0.0.0 | ✅ | 🚫 | ✅ | 🚫 |  |
| iptables port forwarding | localhost | ✅ | ✅ | ✅ | ✅ |
| 0.0.0.0 | ✅ | 🚫 | ✅ | 🚫 |  |
| WSL integration | localhost | ✅ | ✅ | ✅ | ✅ |
| VPN support | N/A | 🚫 | 🚫 | ✅ | ✅ |

---

## File: docs/development/env.md

# Internal Rancher Desktop environment variables

These variables are used for build and development purposes; they are not meant to be set by users.

They do not form an API and may be changed or removed at any time without prior notice.

## RD_DEBUG_ENABLED=anything

Forces debug logging to always be enabled. Useful to debug first-run issues when there is no `settings.yaml` yet to set debug mode.

## RD_FORCE_UPDATES_ENABLED=anything

When set, it will force auto-update to be enabled even in `yarn dev` mode. Updates will be checked and downloaded, but **not** installed.

## RD_GITHUB_API_URL=http://localhost:8314

Set an alternate GitHub API endpoint, from which the updater fetches the release
it was told about by the upgrade responder. Takes effect only when
`RD_FORCE_UPDATES_ENABLED` is also set, because the release names both the asset
to download and the checksum that verifies it. Together with
`RD_UPGRADE_RESPONDER_URL` this lets a test serve a whole release of its own.

## RD_MOCK_MACOS_VERSION=semver

Used for testing compatibility of the app with the OS version, for upgrade responder tests, and for enabling/disabling certain parts of the preferences (related to VZ emulation mode).

## RD_UPGRADE_RESPONDER_URL=http://localhost:8314/v1/checkupgrade

Set an alternate upgrade responder endpoint for testing. Takes effect only when
`RD_FORCE_UPDATES_ENABLED` is also set, because the responder chooses which
release the updater then goes looking for.

---

## File: docs/development/factory-reset.md

When `rdctl reset --factory` is launched from the UI, it writes its stdout into
`TMP/rdctl-stdout.txt`

where on linux `TMP` is usually `/tmp`,

on macOS it's given by `$TMPDIR`

and on Windows by `%TEMP%`(command shell) or `$env:TEMP`(powershell).


This is most useful during development. When the UI runs in debug mode, it spawns `rdctl reset --factory` with the `--verbose` option.

We can't write the output into the `logs` directory as `reset --factory` deletes it.

---

## File: docs/development/features.md

# Rancher Desktop Features

This document lists the high-level Rancher Desktop features and their current status.

| Symbol | Description |
| ------------- | ---------------- |
| :heavy_check_mark: | released |
| :calendar: | targeted for the [next] or the [later] milestone release |
| :sun_with_face:| not planned yet, but considering for a future release |

Note:
- Items under the [next] milestone are targeted for the upcoming monthly release, which usually happens on the 4th Wednesday of the month.
- Items under the [later] milestone and any spillover items from the [next] milestone are targeted for the release after.
- Items under the [next] and [later] milestones might change based on user feedback, technical challenges, etc.

[next]: https://github.com/rancher-sandbox/rancher-desktop/projects/1?card_filter_query=milestone%3Anext
[later]: https://github.com/rancher-sandbox/rancher-desktop/projects/1?card_filter_query=milestone%3Alater

### OS & Platform Support

:heavy_check_mark: Win 10/11

:heavy_check_mark: Mac (Intel)

:heavy_check_mark: Mac M1 (apple silicon)

:heavy_check_mark: Linux

:sun_with_face: Linux AArch64

:sun_with_face: Windows on AArch64

:sun_with_face: Windows Containers

### Container Engines

:heavy_check_mark:  Multiple CR support (containerd, dockerd)

### Docker

:heavy_check_mark: CLI

:heavy_check_mark: Swarm

:heavy_check_mark: Compose

:heavy_check_mark: Docker-only

### Kubernetes

:heavy_check_mark: K3s bundled

:heavy_check_mark: Multiple versions support

### Bundled Tooling

:heavy_check_mark: Helm

:sun_with_face: Kubectx

:sun_with_face: [kwctl]

[kwctl]: https://github.com/kubewarden/kwctl

### Image Management

:heavy_check_mark: Build, Push, Pull & Scan images

:calendar: Registry Configuration

:sun_with_face: Registry Access Control

### Networking

:heavy_check_mark: Simple VPN

:calendar: Restricted VPN (Ex: Cisco AnyConnect)

### Host Access

:sun_with_face: GPU

:sun_with_face: USB

### Performance & System Resources

:heavy_check_mark: System resource allocation

:sun_with_face: Pause app to save power  

### Security

:heavy_check_mark: Signed builds

:sun_with_face: SBOM generation for images

:sun_with_face: Image Signing

:sun_with_face: Attain SLSA Level

### Troubleshooting

:heavy_check_mark: View logs

:heavy_check_mark: Partial Reset

:heavy_check_mark: Factory Reset

### GUI/Installation

:heavy_check_mark: View Containers

:heavy_check_mark: View Images

:heavy_check_mark: Port forwarding

:heavy_check_mark: Auto updates

:heavy_check_mark: Cluster exploration - Rancher Dashboard (Preview)

:heavy_check_mark: Container Exploration

:heavy_check_mark: Container Stats (CPU, memory, network, I/O, processes)

:sun_with_face: Configuration settings

:sun_with_face: Start/Stop/Pause Containers

:sun_with_face: Silent (No-GUI) Install

:sun_with_face: CLI/Headless mode

:calendar: Offline (air gap) mode

:heavy_check_mark: Rancher Desktop CLI aka rdctl (Preview)

### IDE Compatibility

:heavy_check_mark: VS Code extension (With dockerd(moby))

:sun_with_face: Visual Studio IDE (Needs Validation)

:sun_with_face: Eclipse (Needs Validation)

### Integration with Other Rancher Projects

:heavy_check_mark: k3s

:calendar: Rancher Dashboard

:sun_with_face: Epinio

:sun_with_face: NeuVector

:sun_with_face: Marketplace

:sun_with_face: Kubewarden

### Development

:heavy_check_mark: Open source

:heavy_check_mark: Public roadmap

---

## File: docs/development/linux-release-process.md

# Linux Release Process

**Note**: please read the [OBS Tips Documentation](obs.md)
before this document. It includes information that is important to be familiar
with when working with OBS.


## When do I need to modify OBS?

OBS is set up so that you only need to act when you are releasing
a new major or minor version of Rancher Desktop. For example, when
we released 1.11.0 we had to make changes. When we released 1.11.1
nothing had to be done other than the usual checks.


## How do I modify OBS when releasing a new major or minor version?

Before you begin, you must have `osc` set up. Once you have that done,
you can create a new package for the new major-minor version. Luckily,
we don't have to create a new package from scratch: we can use the
`osc copypac` command to copy an existing package. This command has
the following signature:
```
osc copypac   <destination_project> <destination_package>
```
For example, if we wanted to copy the `rancher-desktop-release-1.11`
package from the `isv:Rancher:dev` project to
`rancher-desktop-release-1.12`, also in the `isv:Rancher:dev` project,
we would run `osc copypac` as follows:
```
osc copypac isv:Rancher:dev rancher-desktop-release-1.11 isv:Rancher:dev rancher-desktop-release-1.12
```
Once this is done, you must update the `_service` file and the `Meta`
tab in the package to refer to the new major-minor version. The
easiest way to do this is via the OBS web interface, which you will
need to be logged into. Generally speaking, you can simply replace
all instances of `1.11` with `1.12` (assuming we're using the above
example). Of course, it is best to understand what you are changing -
the next section will help you with that. Once you have made these
changes, the services will run and the builds should start and
complete successfully.

Finally, you should check the results. This is important - sometimes
the build process falls over, sometimes VMs aren't available to build
your package, and so on. If you run into issues, they are usually
resolved by triggering a rebuild in the web interface. This can
be done by clicking "Trigger Services" in the left navigation bar.
Alternatively, you can trigger a rebuild for a specific package format
by clicking on that package format (i.e. AppImage) from the main page
of the package and then clicking "Trigger rebuild". You will need to
be logged into the web interface to take these actions.

You should also check that the link used to download the "latest"
AppImage *actually* downloads the latest AppImage - the link is
sometimes not updated, at least, not updated promptly.


## How do Linux releases actually *work*?

### The `dev` Channel

The `dev` channel is intended to be used by developers and perhaps
intrepid users. It corresponds to the
[isv:Rancher:dev OBS project](https://build.opensuse.org/project/show/isv:Rancher:dev).

1. A new commit is pushed to a branch of the form `main` or `release-X.Y`
   (for example `release-1.2` or `release-1.11`), which triggers the
   `package.yml` github actions workflow. It builds Rancher Desktop and
   uploads the resultant .zip file to an S3 bucket under a name of the form
   `rancher-desktop-linux-.zip`.
3. As its last step, the `package.yml` workflow triggers a service run in
   the OBS package that corresponds to the branch that triggered the workflow
   run.it. This causes OBS to download and unpack the .zip file that was uploaded
   to S3 in step 2. It also causes OBS to pull some files related to the
   package formats will build from the rancher-desktop repository.
4. The new files trigger a build in OBS.
5. Once the build is complete in OBS, the new versions of the packages are
   available to users to download via `zypper install`, `apt install`, etc.


### The `stable` Channel

The `stable` channel is where actual releases are hosted. It is
intended for use by actual users. The `stable` channel corresponds
to the
[isv:Rancher:stable OBS project](https://build.opensuse.org/project/show/isv:Rancher:stable).
The `stable` build process is similar to the `dev` channel, but works
slightly differently: OBS builds are triggered by published github
releases rather than new commits on branches of a particular format.

1. A new release is published, causing the `linux-release.yml` github
   actions workflow to run. This workflow fetches the linux .zip file
   from the release, and uploads it to AWS S3 with a name in the format
   `rancher-desktop-linux-X.Y.zip` (for example, `rancher-desktop-linux-1.12.zip`).
2. The `linux-release.yml` workflow triggers a service run in the OBS
   package that corresponds to the major and minor version of the tag
   of the published release. This causes OBS to download and unpack the
   .zip file uploaded to S3 in step 1. It also causes OBS to pull some files
   related to the package formats will build from the rancher-desktop
   repository.
4. The new files trigger a build in OBS.
5. Once the build is complete in OBS, the new versions of the packages are
   available to users to download via `zypper install`, `apt install`, etc.

---

## File: docs/development/obs.md

# Tips for Working with OBS

This document contains information on how to use OBS effectively.
If you have not used OBS before, you should read
[Getting Started](#getting-started) and
[Important Concepts](#important-concepts) first. Then, come back to
the other sections as you begin to work with the relevant parts of OBS.


## Getting Started

The first thing you need to work with OBS is an installation of
openSUSE Leap. Tumbleweed may work, but given its bleeding-edge
nature, Leap is probably a better bet.

The reason you need an installation of openSUSE is because any
real work you do with OBS should be done using the `osc` command
line tool, which is only available on openSUSE. There *is* a web
interface, but it lacks much of the functionality that you will need.
Use it for checking on the status of your package, and possibly small
changes, but for everything else use `osc`.


## Important Concepts

There are a few concepts that one should understand in order to use OBS.
The way they work and interact can be unintuitive at first, so a brief
overview is provided here.

A **project** is the object in which you do everything in OBS.
Everything falls under projects: repositories, packages, services;
all of these things must belong to a project. Projects may have
subprojects, which are themselves full projects. You have to be an
OBS admin to create a root-level project, so our project (`Rancher`)
was created as a subproject of the `isv` root project. Projects are
referred to as each of their parent projects plus their name, all
separated by colons. So to refer to our top-level project, you use
the name `isv:Rancher`.

A **repository** is configured on a project. The best way to think of
repositories is in the context of package managers: they are a remote
endpoint from which you can download packages. There are several types of
repositories - some are true repositories in the sense that tools like
`apt` and `dnf` can be configured to use them, and others are just endpoints
you can download assets from. Also, you can configure multiple repositories
on each project. This is useful for building and serving packages of multiple
formats from the same binary or source code.

A **package** is also configured on a project. Conceptually, OBS packages
are different from packages in other contexts. In OBS, a package represents
a set of files that go into a build, such as source files and any package
metadata files (such as rpm `.spec` files). Also, from the perspective of the
user's package manager, an OBS package represents exactly one version of the
package. So if you want to provide multiple versions of the package in each
repository, you must have one OBS package for each version.

A **service** is basically a script that can be triggered in a few different
ways. A common use for services is to get the latest version of code from
version control before building and packaging that code. For more information
on services see below; also, you may find the
[documentation for services][service_documentation] helpful.

[service_documentation]: https://openbuildservice.org/help/manuals/obs-user-guide/cha.obs.source_service.html#sec.obs.sserv.about


## Service Tips

### Update your services to the latest versions

Before doing anything with services, you should ensure that you have installed
the latest versions of any services you want to work with. This is important
because the remote version of OBS (build.opensuse.org) always uses the latest
version of services - if you are working with a different version on your local
machine, you may run into issues. Also note that services do not always (ever?)
use semantic versioning despite having versions of the form `X.Y.Z`.

The repositories that openSUSE comes configured with do not contain the latest
versions of the OBS services. In order to get the latest versions you need to
add a repository:

```
zypper addrepo https://download.opensuse.org/repositories/openSUSE:/Tools/openSUSE_15.3/openSUSE:Tools.repo
zypper refresh
```

After you do this you can install/update the services you need. If you aren't
on Leap 15.3, you may have to find a different version of this repo, but this
is what works at the time of writing.

### How to find out what services are available

Services come in the form of rpm packages that can be installed via `zypper`.
In order to search your installed repos for services, simply run:

```
zypper search obs-service
```

### How to find out what configuration each service takes

Once services are installed you can look at their interface schema in order
to understand how to use them. The interface schema (as well as the source code)
are stored in the directory `/usr/lib/obs/service/`.


## Local Build Tips

### How to get around slow mirrors

When you do a local build, the first thing `osc` does is cache any dependencies
of the build. `osc` will download these dependencies from mirrors of their
repositories. Unfortunately these mirrors can be very slow. If the dependency
caching step is too slow, you can tell `osc build` to only fetch packages from
the build.opensuse.org api with the `--download-api-only` flag.

### How to skip running services before build

Use the `--no-service` flag on `osc build` for this.

### How to find the output of a local build

When you build locally, it is not always obvious where the output of the build
has been saved. To find the location of your build output, look at the text that
the build has printed at the screen. At the end of it there should be a path;
this is where you can find your built package.


## Additional Resources

- The `help-obs` and `discuss-zypp` slack channels are always friendly and helpful.
- The [OBS documentation][obs_docs] might help resolve any problems you run into.
- The output of `osc --help` and `osc <command> --help` may be helpful.
- The [Using the Open Build Service][using_obs] may be helpful for understanding
  how we build AppImages using OBS.

[obs_docs]: https://openbuildservice.org/help/manuals/obs-user-guide/
[using_obs]: https://docs.appimage.org/packaging-guide/hosted-services/opensuse-build-service.html

--- METRICS ---
- Files Extracted: 11
- Estimated Token Budget: ~19702 tokens
- Recency Window: Active (< 180 days)
- Canonical Reference: https://codewiki.google/github.com/rancher-sandbox/rancher-desktop