Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified public/docs-static/img/manage/peers/ssh/ssh-client.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
8 changes: 8 additions & 0 deletions src/pages/agent-network/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,14 @@ That makes agent access a natural responsibility for IT.
Because NetBird connects seamlessly with existing identity providers, IT teams can integrate NetBird Agent Network into
their enterprise stack with minimal changes.

## Focused Dashboard View

Some accounts open directly into Agent Network, with the rest of the NetBird Dashboard—such as Peers, Networks, and DNS—hidden to keep the experience focused on agents. This is the default for accounts onboarded specifically for Agent Network.

To use the full NetBird platform, open **Settings** and turn off **Agent Network focused view**. You can re-enable it from the same setting at any time.

For API-managed accounts, `agent_network_only` requires `dashboard_features.agent_network` to be enabled. See the [Accounts API reference](/ipa/resources/accounts) for the account settings schema.

## Next steps

- [Quickstart](/agent-network/quickstart). Deploy NetBird Agent Network and make your first routed LLM call.
Expand Down
14 changes: 4 additions & 10 deletions src/pages/client/block-inbound-connections.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -28,13 +28,11 @@ When Block Inbound Connections is enabled, the client will not add any inbound f
This setting overrides all policies from the management service. Even if an access control policy explicitly allows traffic to this peer, inbound connections will still be blocked.
</Note>

## Enabling via the system tray
## Changing the setting in the desktop app

1. Click the NetBird icon in the system tray.
2. Go to **Settings**.
3. Click **Block Inbound Connections** to toggle the setting.

When enabled, a checkmark will appear next to the menu item.
1. Open the NetBird desktop app.
2. Go to **Settings → Security**.
3. Toggle **Block Inbound Traffic**.

## Enabling via the CLI

Expand All @@ -49,7 +47,3 @@ To disable it, run:
```bash
netbird up --block-inbound=false
```

<Note>
When toggling this setting via the CLI, the system tray UI may not reflect the change until the NetBird GUI is restarted.
</Note>
16 changes: 6 additions & 10 deletions src/pages/client/connect-on-startup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -18,20 +18,20 @@ When Connect on Startup is **enabled** (default behavior):

When Connect on Startup is **disabled**:
- The NetBird service starts but does not connect automatically.
- You must manually run `netbird up` or use the system tray to connect.
- You must manually run `netbird up` or click **Connect** in the desktop app or tray menu.
- The peer remains offline until an explicit connection is initiated.

<Note>
Whether the device successfully connects also depends on the <a href="/manage/settings/enforce-periodic-user-authentication">Peer Session Expiration</a> setting under Settings &gt; Authentication. If the peer's session has expired, the user must reauthenticate before the peer can connect.
</Note>

## Enabling via the system tray
## Changing the setting in the desktop app

1. Click the NetBird icon in the system tray.
2. Go to **Settings**.
3. Click **Connect on Startup** to toggle the setting.
1. Open the NetBird desktop app.
2. Go to **Settings → General**.
3. Toggle **Connect on Startup**.

When enabled, a checkmark will appear next to the menu item.
This setting controls the background network connection. It is separate from **Launch NetBird UI at Login**, which controls only whether the graphical interface opens when you sign in to the operating system.

## Enabling via the CLI

Expand All @@ -46,7 +46,3 @@ To re-enable it:
```bash
netbird up --disable-auto-connect=false
```

<Note>
When toggling this setting via the CLI, the system tray UI may not reflect the change until the NetBird GUI is restarted.
</Note>
44 changes: 29 additions & 15 deletions src/pages/client/desktop-app.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,13 @@ export const description = "Overview of the redesigned NetBird desktop app: Defa

# 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 the latest release candidate from [pkgs.netbird.io](https://pkgs.netbird.io/releases/rc).
</Note>
Starting with NetBird v0.75.0, the desktop app uses a [Wails](https://wails.io/) webview with a React frontend. The management server and wire protocol are unchanged, but the UI and agent need to be updated together. If their versions do not match, the app displays an update notification.

## First Launch

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.
On first launch, the welcome dialog points you to the NetBird icon in the Windows or Linux system tray, or the macOS menu bar. Choose whether to connect to **NetBird Cloud** or a **Self-hosted** deployment. For a self-hosted deployment, enter its management URL before connecting.

Click **Connect** in the main window or tray menu. NetBird opens your browser to authenticate the device. Once authorization completes, the desktop app connects and displays the device's NetBird IP address.

## Default and Advanced Views

Expand All @@ -24,7 +26,7 @@ Switch to the **Advanced** view and the window expands with a peers and resource
<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.
The **Resources** tab lists the network resources available to you. You can search resources, show only active or overlapping entries, toggle individual resources, or enable and disable all resources at once.

<p>
<img src="/docs-static/img/client/desktop-app/resources-view.png" alt="Advanced view showing the Resources tab" className="imagewrapper"/>
Expand All @@ -50,29 +52,37 @@ A colored status dot sits next to the tray icon so you can read the state of you
<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.
The tray menu also provides profile switching, session-renewal access, exit-node selection, Settings, Help & Support, and **Quit NetBird**. Closing the main window only hides it while the daemon and network connection continue running. Choosing **Quit NetBird** disconnects the daemon before the desktop app exits.

## Exit Nodes

The compact view shows the active exit node. Open the exit-node selector in the main window or tray menu to select another available exit node or return to a direct connection by deselecting it.

## 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.
* **General** for everyday toggles: Connect on Startup, Launch NetBird UI at Login, notifications, and display language.
* **Network** for connectivity, DNS, routes, and IPv6 settings.
* **Security** for inbound traffic, LAN access, and quantum-resistant encryption settings.
* **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.
* **SSH** for the native SSH server and its optional features.
* **Advanced** for log-level and custom configuration options.
* **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>

**Connect on Startup** controls whether the background service reconnects when it starts. **Launch NetBird UI at Login** controls only whether the graphical interface opens when you sign in to the operating system. On a fresh desktop installation, launch at login is enabled once by default. Upgrades preserve the user's existing preference. Administrators can manage this behavior with [`disableAutostart`](/client/mdm-integration#disableAutostart).

## 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.
* **Hide whole views.** `disableAdvancedView` hides the Advanced view of the main window, so managed users only see the compact one.
* **Gate specific capabilities.** Keys 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>
Expand All @@ -81,7 +91,7 @@ If you roll out NetBird through MDM, the app reads the policy in effect on the d

## 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.
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, and the session deadline remains visible across reconnects.

<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"/>
Expand All @@ -91,10 +101,14 @@ The renewal flow follows one rule: re-authenticating never closes an active conn

## 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.
You can switch languages from the **Display Language** picker in **Settings → General**, and the change applies instantly. NetBird v0.75 ships with English, French, German, Hungarian, Italian, Japanese, 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.
Translations are a continuing community effort. If your language is missing or a phrase reads incorrectly, please [open a pull request](https://github.com/netbirdio/netbird).

## 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.
The **Troubleshoot** tab can capture a debug bundle that collects daemon and UI logs in one step. You can collect new trace logs for 1–30 minutes, cycle the connection, include a packet capture and system information, anonymize sensitive data, and either upload the result to NetBird or keep it locally. See [Troubleshooting the client](/help/troubleshooting-client#debug-bundle-uploads-with-gui) for the complete flow.

<p>
<img src="/docs-static/img/help/troubleshooting-client/ui-bundle-local-success.png" alt="Completed debug bundle saved locally in the NetBird desktop app" className="imagewrapper"/>
</p>
3 changes: 2 additions & 1 deletion src/pages/client/environment-variables.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ To clear all saved service parameters (including env vars), run `sudo netbird se
| `NB_ICE_FAILED_TIMEOUT_SEC` | All | Seconds of silence before ICE gives up on the connection entirely and falls back to relay (default: `6`). |
| `NB_ICE_RELAY_ACCEPTANCE_MIN_WAIT_SEC` | All | Minimum seconds ICE waits for a direct (P2P) candidate before accepting a relay candidate. Higher values give direct connections more time to succeed at the cost of slower initial connection (default: `2`). |
| `NB_ICE_MONITOR_PERIOD` | All | Interval between ICE connection health checks that verify handshake freshness and trigger reconnection if needed (Go duration, default: `5m`). |
| `NB_ENABLE_EXPERIMENTAL_LAZY_CONN` | All | Open WireGuard tunnels to peers only when traffic is detected, instead of connecting to all peers at startup. Same effect as the `--enable-lazy-connection` CLI flag. |
| `NB_LAZY_CONN` | All | Local lazy-connection override. `on` forces lazy connections enabled, `off` forces them disabled, and leaving it unset defers to the Management or MDM setting. Overrides MDM when both are configured. Replaces the removed `NB_ENABLE_EXPERIMENTAL_LAZY_CONN`; the deprecated `--enable-lazy-connection` CLI flag is inert. |
| `NB_LAZY_CONN_INACTIVITY_THRESHOLD` | All | How long a lazy connection can be idle before it is torn down (Go duration, default: `15m`). Only applies when lazy connections are enabled. |

## DNS
Expand All @@ -81,6 +81,7 @@ To clear all saved service parameters (including env vars), run `sudo netbird se
|---|---|---|
| `NB_DNS_FORWARDER_PORT` | All | Override the port the internal DNS forwarder binds to for handling DNS routes received from clients (default: `22054`). The forwarder is separate from the local resolver. |
| `NB_SKIP_DNS_PROBE` | All | Skip the startup check that sends a test query to the local resolver to verify it is reachable. Set this if the probe causes delays (e.g. in air-gapped networks). |
| `NB_DNS_LAZY_WARMUP_TIMEOUT` | All | Per-query budget for waking an idle peer when the local resolver returns one of its A or AAAA records (Go duration, default: `2s`). The value must be positive; invalid, zero, or negative values use the default. |
| `NB_UNCLEAN_SHUTDOWN_RESOLV_FILE` | Linux, FreeBSD | Custom file path to store a backup of `/etc/resolv.conf` before the client modifies it. Used to restore the original on next startup if the client crashed without cleaning up (default: `<state-dir>/resolv.conf`, i.e. `/var/lib/netbird/resolv.conf` on Linux, `/var/db/netbird/resolv.conf` on FreeBSD). |

## Connection retry
Expand Down
3 changes: 2 additions & 1 deletion src/pages/client/mdm-integration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,8 @@ PascalCase variant in the Group Policy Editor — both are recognized.
| `wireguardPort` | integer | UDP port the local WireGuard interface binds to. Range `1–65535`. |
| `allowServerSSH` | boolean | Allow the embedded NetBird SSH server on this peer. |
| `disableAutoConnect` | boolean | Skip auto-connecting on startup; require an explicit `netbird up`. |
| `disableAutostart` | boolean | Prevent the GUI from registering itself as an OS autostart entry on fresh installs, and — when enabled at any later point — remove an existing registration on the next GUI launch (Windows Registry `Run` key, macOS Login Item, Linux `.desktop`). Desktop GUIs only; no-op on iOS/Android. Once the admin lifts the policy, the setting stays off until the user re-enables it in Settings. |
| <span id="disableAutostart"></span>`disableAutostart` | boolean | Prevent the GUI from registering itself as an OS autostart entry on fresh installs, and — when enabled at any later point — remove an existing registration on the next GUI launch (Windows Registry `Run` key, macOS Login Item, Linux `.desktop`). Desktop GUIs only; no-op on iOS/Android. Once the admin lifts the policy, the setting stays off until the user re-enables it in Settings. |
| `lazyConnection` | boolean | Local override for lazy connections. `true` forces lazy connections on, `false` forces them off, and an absent key defers to the Management setting. `NB_LAZY_CONN` takes precedence when both are configured. |
| `rosenpassEnabled` | boolean | Turn on the post-quantum Rosenpass key exchange. |
| `rosenpassPermissive` | boolean | Permissive mode for Rosenpass (interop with non-Rosenpass peers). |
| `blockInbound` | boolean | Drop all inbound traffic except established/related — kill-switch style. |
Expand Down
8 changes: 4 additions & 4 deletions src/pages/client/post-quantum-cryptography.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -25,11 +25,11 @@ that automatically rotates and applies WireGuard pre-shared keys to every point-
This is still an experimental feature, may contain bugs, and is not supported on mobile devices.
</Note>

### Enabling via the system tray
### Enabling via the desktop app

1. Click the NetBird icon in the system tray.
2. Go to **Settings**.
3. Click **Enable Quantum-Resistance** to toggle the setting.
1. Open the NetBird desktop app.
2. Go to **Settings → Security**.
3. Toggle **Enable Quantum-Resistance**.

### Enabling via the CLI

Expand Down
Loading
Loading