Document the redesigned NetBird desktop app (release candidate) (#802)

* Add RC notes and documentation

* Add download links

* Updates lang and daemon
This commit is contained in:
Brandon Hopkins
2026-06-19 14:21:23 -07:00
committed by GitHub
parent 59405c5e73
commit 3ef558be01
11 changed files with 126 additions and 0 deletions

Binary file not shown.

After

Width:  |  Height:  |  Size: 315 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 643 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 629 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 234 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 701 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 437 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 493 KiB

View File

@@ -764,6 +764,7 @@ export const docsNavigation = [
{
title: 'CLIENT',
links: [
{ title: 'Desktop App', href: '/client/desktop-app' },
{ title: 'Profiles', href: '/client/profiles' },
{ title: 'Environment Variables', href: '/client/environment-variables' },
{ title: 'MDM Integration', href: '/client/mdm-integration' },

View File

@@ -0,0 +1,100 @@
import {Note} from "@/components/mdx";
export const description = "Overview of the redesigned NetBird desktop app: Default and Advanced views, peer details, a reorganized Settings page, MDM-driven UI, non-disruptive session renewal, and localization."
# NetBird Desktop App
<Note>
The redesigned desktop app described on this page is currently available as a **release candidate**. Behavior and screenshots may change before the stable release. To try it, download [v0.75.0-rc.1](https://github.com/netbirdio/netbird/releases/tag/v0.75.0-rc.1) from GitHub releases.
</Note>
The NetBird desktop app has been rebuilt from the ground up. It runs on a [Wails](https://wails.io/) webview with a React frontend, while the Go backend that talks to the daemon stays the same. The management server and wire protocol are unchanged. The redesigned app is not backward compatible with older agents, though, so the app and the agent need to be updated together. If their versions do not match, the app shows a notification prompting you to update.
## Default and Advanced Views
The main window opens in a compact **Default** view that shows the essentials: the active profile, connection status, hostname, overlay IP, and current exit node.
<p>
<img src="/docs-static/img/client/desktop-app/default-view.png" alt="NetBird desktop app default view" className="imagewrapper"/>
</p>
Switch to the **Advanced** view and the window expands with a peers and resources browser on the right. The **Peers** tab lists the peers in your network.
<p>
<img src="/docs-static/img/client/desktop-app/peers-view.png" alt="Advanced view showing the Peers tab" className="imagewrapper"/>
</p>
The **Resources** tab lists the network resources available to you.
<p>
<img src="/docs-static/img/client/desktop-app/resources-view.png" alt="Advanced view showing the Resources tab" className="imagewrapper"/>
</p>
## Peer Details
Clicking a peer opens a detail panel with the information you would otherwise look up from the CLI: address, status, route, connection details, and group membership.
## A Reactive UI
Changes made by the NetBird agent or the CLI are reflected in the app immediately. Connect or disconnect from the CLI and the toggle flips on its own. Switch profiles and the window catches up. There is no need to refresh or relaunch the app.
## System Tray
A colored status dot sits next to the tray icon so you can read the state of your network without opening the app:
* **Green** when connected.
* **Yellow** when you need to log in.
* **Grey** when disconnected.
<p>
<img src="/docs-static/img/client/desktop-app/tray-status.png" alt="NetBird system tray status indicator" className="imagewrapper"/>
</p>
The app also includes per-platform refinements: improved behavior on Linux X11 desktops, a macOS Dock icon that only appears when an app window is open, and improved status rendering on Windows.
## Settings
The settings page uses a tabbed layout that groups options by what they control. The tabs you see depend on your role and on any [MDM policy](#mdm-driven-ui) in effect. The full set is:
* **General** for everyday toggles: auto-start, notifications, and display language.
* **Network** and **Security** for connection-side options such as PSK, custom DNS port, lazy connections, and server SSH.
* **Profiles** for managing the accounts the app knows about. See [Profiles](/client/profiles).
* **SSH** and **Advanced** for options such as log level, network monitor, and native SSH.
* **Troubleshoot** for [capturing a debug bundle](#capturing-a-debug-bundle).
* **About** for version information, useful links, and updating the app.
<p>
<img src="/docs-static/img/client/desktop-app/settings-language.png" alt="Settings page with the General tab and Display Language picker" className="imagewrapper"/>
</p>
## MDM-Driven UI
If you roll out NetBird through MDM, the app reads the policy in effect on the device and adjusts itself to match, so users only see the options they are allowed to use. For deploying NetBird through an MDM provider, see the [MDM deployment guides](/manage/integrations/mdm-deployment/intune-netbird-integration).
* **Hide whole views.** `DisableAdvancedView` hides the Advanced view of the main window, so managed users only see the compact one.
* **Gate specific capabilities.** Flags such as `AllowServerSSH` control whether the corresponding toggle is available in the app.
* **Refresh in the background.** Restrictions are re-read when the window becomes visible or the connection status changes, so MDM-pushed policy updates apply without a restart.
<Note>
Profile management can also be locked down. See [Disabling the Profiles feature](/client/profiles#disabling-profiles-feature) for the `--disable-profiles` and `--disable-update-settings` options.
</Note>
## Session Expiration and Renewal
When a session is about to expire, the app shows a dialog with a countdown and two clear actions: renew or log out. An operating system notification fires ahead of time, so the dialog is not the first signal you get.
<p>
<img src="/docs-static/img/client/desktop-app/session-expiration.png" alt="Session expiry dialog with a countdown and renew or logout actions" className="imagewrapper"/>
</p>
The renewal flow follows one rule: re-authenticating never closes an active connection. **Renew session** runs the browser sign-in flow while your existing connection stays up. Your tunnels, SSH sessions, and remote desktop sessions keep running through the renewal. Only the underlying session ticket changes.
## Localization
You can switch languages from the **Display Language** picker in **Settings → General**, and the change applies instantly. The release candidate ships with initial translations for English, French, German, Hungarian, Italian, Portuguese, Russian, Simplified Chinese, and Spanish.
These initial translations are still a work in progress. If your language is missing or a phrase reads incorrectly, please [open a pull request](https://github.com/netbirdio/netbird). Feedback from native speakers is exactly what helps here.
## Capturing a Debug Bundle
The **Troubleshoot** tab can capture a debug bundle that collects both the daemon logs and the UI logs at the current log level in one step. Attach the bundle when you report an issue so the team has the full picture.

View File

@@ -40,6 +40,16 @@ if needed.
<img src="/docs-static/img/client/profiles/manage-profiles.png" alt="profiles" className="imagewrapper"/>
</p>
<Note>
The redesigned desktop app, currently available as a **release candidate**, expands profile management. You can now **rename and edit** existing profiles, not just add and delete them. Profile names accept uppercase letters and spaces, so names like `Work Prod` or `Home Lab` are valid. Each profile is assigned an **icon based on its type** (Work, Home, Default, and others) so the active profile is easy to recognize in the tray and switcher.
In the new app, profiles are managed from the dedicated **Profiles** tab in Settings.
</Note>
<p>
<img src="/docs-static/img/client/profiles/profiles-edit.png" alt="Editing and renaming profiles in the new desktop app" className="imagewrapper"/>
</p>
## What Is a Profile?
A **profile** is your NetBird configuration bundle: WireGuard keys, login state, and network settings all in one file.

View File

@@ -4,6 +4,21 @@ import {Note} from "@/components/mdx";
The NetBird client (agent) allows a peer to join a pre-existing NetBird deployment. If a NetBird deployment is not yet available, there are both managed and [self-hosted](https://docs.netbird.io/selfhosted/selfhosted-quickstart) options available.
## Desktop App Dependencies
<Note>
This applies to the redesigned NetBird desktop app, currently available as a **release candidate** ([v0.75.0-rc.1](https://github.com/netbirdio/netbird/releases/tag/v0.75.0-rc.1)). The current stable GUI does not require these packages.
</Note>
The redesigned desktop app renders its interface in a GTK 4 WebKit webview. Linux distributions package these libraries under inconsistent names, so install them manually before launching the GUI.
**Debian / Ubuntu**
```bash
sudo apt-get install libgtk-4-1 libwebkitgtk-6.0-4 xdg-utils
```
On other distributions, install the equivalent **GTK 4**, **WebKitGTK 6.0**, and **xdg-utils** packages from your package manager.
## Linux Install Script