Merge branch 'main' into add-atomic-cache-ops

The community and enterprise bootstrap scripts now generate a dedicated
`server.auth.sessionCookieEncryptionKey` from 32 random bytes for fresh
installations.
The key is Base64-encoded, persisted independently from the datastore
encryption key, and reused from the generated configuration after
restarts.

The community script now also creates `config.yaml` with mode `0600`
before writing it, matching the existing enterprise behavior.

The server already supports the session cookie encryption key, but the
bootstrap scripts left it unset.
This adds defense-in-depth for newly generated deployments while
preserving the existing server-side nonce validation.
Because this only changes newly generated configuration, existing
installations and sessions are unchanged.

A focused regression test checks key presence, decoded length,
separation from the datastore key, YAML placement, and file mode for
both scripts.
It is included in the infrastructure workflow.

.github/workflows/release.yml

@@ -475,6 +475,132 @@ jobs:
           path: dist/
           retention-days: 3
 
+  release_ui_gtk3:
+    # Legacy GTK3/WebKit2GTK 4.1 UI build for distros without WebKitGTK 6.0
+    # (Ubuntu 22.04, Debian 12, RHEL 9, Fedora <=39). Runs on ubuntu-22.04 so
+    # the binary links against the oldest supported glibc.
+    runs-on: ubuntu-22.04
+    outputs:
+      release_ui_gtk3_artifact_url: ${{ steps.upload_release_ui_gtk3.outputs.artifact-url }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0 # It is required for GoReleaser to work properly
+          persist-credentials: false
+
+      - name: Parse semver string
+        id: semver_parser
+        uses: netbirdio/shared-actions/actions/parse-semver@be5df6047383da2236e02243cceb857d8567c27e # v0.0.2
+
+      - name: Set snapshot flag
+        if: ${{ !startsWith(github.ref, 'refs/tags/v') }}
+        run: |
+          echo "flags=--snapshot" >> $GITHUB_ENV
+
+      - name: Set build vars
+        if: ${{ startsWith(github.ref, 'refs/tags/v') }}
+        run: |
+          if [[ "x-${{ steps.semver_parser.outputs.prerelease }}" == "x-" && "x-${{ github.repository }}" == "x-netbirdio/netbird" ]]; then
+            echo "x-${{ github.repository }}"
+            echo "x-${{ steps.semver_parser.outputs.prerelease }}"
+            echo "SKIP_PUBLISH=false" >> $GITHUB_ENV
+          else
+            echo "x-${{ github.repository }}"
+            echo "x-${{ steps.semver_parser.outputs.prerelease }}"
+          fi
+
+      - name: Set up Go
+        uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6.5.0
+        with:
+          go-version-file: "go.mod"
+          cache: false
+      - name: Cache Go modules
+        # Restore-only from the release_ui cache written by trusted runs; the
+        # module cache is identical (same go.sum) and stale build-cache
+        # entries just miss.
+        uses: actions/cache/restore@2c8a9bd7457de244a408f35966fab2fb45fda9c8 # v6.0.0
+        with:
+          path: |
+            ~/go/pkg/mod
+            ~/.cache/go-build
+          key: ${{ runner.os }}-ui-go-releaser-${{ hashFiles('**/go.sum') }}
+          restore-keys: |
+            ${{ runner.os }}-ui-go-releaser-
+
+      - name: Install modules
+        run: go mod tidy
+
+      - name: check git status
+        run: git --no-pager diff --exit-code
+
+      - name: Set up Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: '22'
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@a3252b78c470c02df07e9d59298aecedc3ccdd6d # v3.0.0
+        with:
+          version: 11
+
+      - name: Install dependencies
+        run: sudo apt update && sudo apt install -y -q libgtk-3-dev libwebkit2gtk-4.1-dev
+
+      - name: Decode GPG signing key
+        if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+        env:
+          GPG_RPM_PRIVATE_KEY: ${{ secrets.GPG_RPM_PRIVATE_KEY }}
+        run: |
+          echo "$GPG_RPM_PRIVATE_KEY" | base64 -d > /tmp/gpg-rpm-signing-key.asc
+          echo "GPG_RPM_KEY_FILE=/tmp/gpg-rpm-signing-key.asc" >> $GITHUB_ENV
+
+      - name: Install wails3 CLI
+        # Version derived from go.mod so the binding generator always matches
+        # the wails runtime the binary links against.
+        # -tags gtk3: the CLI links the wails runtime's cgo packages, and the
+        # default tags request gtk4/webkitgtk-6.0 pkg-config entries that do
+        # not exist on ubuntu-22.04.
+        run: |
+          WAILS_VERSION=$(go list -m -f '{{.Version}}' github.com/wailsapp/wails/v3)
+          go install -tags gtk3 github.com/wailsapp/wails/v3/cmd/wails3@$WAILS_VERSION
+
+      - name: Run GoReleaser
+        uses: goreleaser/goreleaser-action@5daf1e915a5f0af01ddbcd89a43b8061ff4f1a89 # v7.2.2
+        with:
+          version: ${{ env.GORELEASER_VER }}
+          args: release --config .goreleaser_ui_gtk3.yaml --clean ${{ env.flags }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          UPLOAD_DEBIAN_SECRET: ${{ secrets.PKG_UPLOAD_SECRET }}
+          UPLOAD_YUM_SECRET: ${{ secrets.PKG_UPLOAD_SECRET }}
+          GPG_RPM_KEY_FILE: ${{ env.GPG_RPM_KEY_FILE }}
+          NFPM_NETBIRD_UI_RPM_GTK3_PASSPHRASE: ${{ secrets.GPG_RPM_PASSPHRASE }}
+          SKIP_PUBLISH: ${{ env.SKIP_PUBLISH }}
+      - name: Verify RPM signatures
+        run: |
+          docker run --rm -v $(pwd)/dist:/dist fedora:41 bash -c '
+            dnf install -y -q rpm-sign curl >/dev/null 2>&1
+            curl -sSL https://pkgs.netbird.io/yum/repodata/repomd.xml.key -o /tmp/rpm-pub.key
+            rpm --import /tmp/rpm-pub.key
+            echo "=== Verifying RPM signatures ==="
+            for rpm_file in /dist/*.rpm; do
+              [ -f "$rpm_file" ] || continue
+              echo "--- $(basename $rpm_file) ---"
+              rpm -K "$rpm_file"
+            done
+          '
+      - name: Clean up GPG key
+        if: always()
+        run: rm -f /tmp/gpg-rpm-signing-key.asc
+      - name: upload non tags for debug purposes
+        id: upload_release_ui_gtk3
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a #v7.0.1
+        with:
+          name: release-ui-gtk3
+          path: dist/
+          retention-days: 3
+
   release_ui_darwin:
     runs-on: macos-latest
     outputs:
@@ -688,7 +814,7 @@ jobs:
   comment_release_artifacts:
     name: Comment release artifacts
     runs-on: ubuntu-latest
-    needs: [release, release_ui, release_ui_darwin]
+    needs: [release, release_ui, release_ui_gtk3, release_ui_darwin]
     if: ${{ always() && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository }}
     permissions:
       contents: read
@@ -700,12 +826,14 @@ jobs:
         env:
           RELEASE_RESULT: ${{ needs.release.result }}
           RELEASE_UI_RESULT: ${{ needs.release_ui.result }}
+          RELEASE_UI_GTK3_RESULT: ${{ needs.release_ui_gtk3.result }}
           RELEASE_UI_DARWIN_RESULT: ${{ needs.release_ui_darwin.result }}
           RELEASE_ARTIFACT_URL: ${{ needs.release.outputs.release_artifact_url }}
           LINUX_PACKAGES_ARTIFACT_URL: ${{ needs.release.outputs.linux_packages_artifact_url }}
           WINDOWS_PACKAGES_ARTIFACT_URL: ${{ needs.release.outputs.windows_packages_artifact_url }}
           MACOS_PACKAGES_ARTIFACT_URL: ${{ needs.release.outputs.macos_packages_artifact_url }}
           RELEASE_UI_ARTIFACT_URL: ${{ needs.release_ui.outputs.release_ui_artifact_url }}
+          RELEASE_UI_GTK3_ARTIFACT_URL: ${{ needs.release_ui_gtk3.outputs.release_ui_gtk3_artifact_url }}
           RELEASE_UI_DARWIN_ARTIFACT_URL: ${{ needs.release_ui_darwin.outputs.release_ui_darwin_artifact_url }}
           GHCR_IMAGES_MARKDOWN: ${{ needs.release.outputs.ghcr_images }}
         with:
@@ -728,6 +856,7 @@ jobs:
               ['Windows packages', process.env.WINDOWS_PACKAGES_ARTIFACT_URL, process.env.RELEASE_RESULT],
               ['macOS packages', process.env.MACOS_PACKAGES_ARTIFACT_URL, process.env.RELEASE_RESULT],
               ['UI artifacts', process.env.RELEASE_UI_ARTIFACT_URL, process.env.RELEASE_UI_RESULT],
+              ['UI GTK3 artifacts', process.env.RELEASE_UI_GTK3_ARTIFACT_URL, process.env.RELEASE_UI_GTK3_RESULT],
               ['UI macOS artifacts', process.env.RELEASE_UI_DARWIN_ARTIFACT_URL, process.env.RELEASE_UI_DARWIN_RESULT],
             ];
 
@@ -784,7 +913,7 @@ jobs:
 
   trigger_signer:
     runs-on: ubuntu-latest
-    needs: [release, release_ui, release_ui_darwin, test_windows_installer]
+    needs: [release, release_ui, release_ui_gtk3, release_ui_darwin, test_windows_installer]
     if: startsWith(github.ref, 'refs/tags/')
     steps:
       - name: Trigger binaries sign pipelines

.github/workflows/test-infrastructure-files.yml

@@ -257,6 +257,15 @@ jobs:
         with:
           persist-credentials: false
 
+      - name: Verify fresh-install session cookie key hardening
+        run: |
+          grep -Fxq '  SESSION_COOKIE_ENCRYPTION_KEY=$(openssl rand -base64 32)' infrastructure_files/getting-started.sh
+          grep -Fxq '    sessionCookieEncryptionKey: "$SESSION_COOKIE_ENCRYPTION_KEY"' infrastructure_files/getting-started.sh
+          grep -Fxq '  install -m 600 /dev/null config.yaml' infrastructure_files/getting-started.sh
+          grep -Fxq '  openssl rand -base64 32' infrastructure_files/getting-started-enterprise.sh
+          grep -Fxq '  NETBIRD_SESSION_COOKIE_ENCRYPTION_KEY=$(rand_b64_key)' infrastructure_files/getting-started-enterprise.sh
+          grep -Fxq '    sessionCookieEncryptionKey: "${NETBIRD_SESSION_COOKIE_ENCRYPTION_KEY}"' infrastructure_files/getting-started-enterprise.sh
+
       - name: Verify Dex retirement notice
         run: |
           if infrastructure_files/getting-started-with-dex.sh >stdout.txt 2>stderr.txt; then

.goreleaser_ui_gtk3.yaml

@@ -0,0 +1,131 @@
+version: 2
+env:
+  - SKIP_PUBLISH={{ if index .Env "SKIP_PUBLISH" }}{{ .Env.SKIP_PUBLISH }}{{ else }}true{{ end }}
+project_name: netbird-ui
+
+before:
+  hooks:
+    # Bindings are gitignored; regenerate before the frontend build so
+    # the @wailsio/runtime Vite plugin can resolve them (vite refuses to
+    # build without them).
+    # -f '-tags gtk3': the generator type-checks client/ui, whose cgo imports
+    # would otherwise resolve gtk4/webkitgtk-6.0 pkg-config entries that do
+    # not exist on ubuntu-22.04.
+    - sh -c 'cd client/ui && wails3 generate bindings -clean=true -ts -f "-tags gtk3"'
+    - sh -c 'cd client/ui/frontend && pnpm install --frozen-lockfile && pnpm build'
+
+builds:
+  # Legacy GTK3 / WebKit2GTK 4.1 build for distros without WebKitGTK 6.0
+  # (Ubuntu 22.04, Debian 12, RHEL 9, Fedora <=39). The gtk3 tag flips the
+  # Wails Linux backend to the GTK3 stack and swaps our GTK4-only XEmbed
+  # tray host for the pure-Go stub (client/ui/xembed_host_gtk3_linux.go).
+  # Must be built on the oldest supported glibc (ubuntu-22.04 runner).
+  - id: netbird-ui-gtk3
+    dir: client/ui
+    binary: netbird-ui
+    env:
+      - CGO_ENABLED=1
+    goos:
+      - linux
+    goarch:
+      - amd64
+    ldflags:
+      - -s -w -X github.com/netbirdio/netbird/version.version={{.Version}} -X main.commit={{.Commit}} -X main.date={{.CommitDate}} -X main.builtBy=goreleaser
+    mod_timestamp: "{{ .CommitTimestamp }}"
+    tags:
+      - production
+      - gtk3
+
+archives:
+  - id: linux-gtk3-arch
+    name_template: "{{ .ProjectName }}-linux-gtk3_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
+    builds:
+      - netbird-ui-gtk3
+
+nfpms:
+  # Same package_name as the GTK4 packages -- the two are mutually-exclusive
+  # alternatives served from separate repo paths (see uploads below); a given
+  # distro points at exactly one of them. The file names must still differ:
+  # the Debian pool is shared storage keyed by file name, so a default-named
+  # gtk3 .deb would overwrite the stable one.
+  - maintainer: Netbird <dev@netbird.io>
+    description: Netbird client UI.
+    homepage: https://netbird.io/
+    license: BSD-3-Clause
+    vendor: NetBird
+    id: netbird_ui_deb_gtk3
+    package_name: netbird-ui
+    file_name_template: "{{ .PackageName }}-gtk3_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
+    builds:
+      - netbird-ui-gtk3
+    formats:
+      - deb
+    scripts:
+      postinstall: "release_files/ui-post-install.sh"
+    contents:
+      - src: client/ui/build/linux/netbird.desktop
+        dst: /usr/share/applications/org.wails.netbird.desktop
+      - src: client/ui/build/appicon.png
+        dst: /usr/share/pixmaps/netbird.png
+    dependencies:
+      - netbird (>= 0.75.0)
+      - libgtk-3-0
+      - libwebkit2gtk-4.1-0
+
+  - maintainer: Netbird <dev@netbird.io>
+    description: Netbird client UI.
+    homepage: https://netbird.io/
+    license: BSD-3-Clause
+    vendor: NetBird
+    id: netbird_ui_rpm_gtk3
+    package_name: netbird-ui
+    file_name_template: "{{ .PackageName }}-gtk3_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
+    builds:
+      - netbird-ui-gtk3
+    formats:
+      - rpm
+    scripts:
+      postinstall: "release_files/ui-post-install.sh"
+    contents:
+      - src: client/ui/build/linux/netbird.desktop
+        dst: /usr/share/applications/org.wails.netbird.desktop
+      - src: client/ui/build/appicon.png
+        dst: /usr/share/pixmaps/netbird.png
+    dependencies:
+      - netbird >= 0.75.0
+      - (gtk3 or libgtk-3-0)
+      - (webkit2gtk4.1 or libwebkit2gtk-4_1-0)
+
+    rpm:
+      signature:
+        key_file: '{{ if index .Env "GPG_RPM_KEY_FILE" }}{{ .Env.GPG_RPM_KEY_FILE }}{{ end }}'
+
+# The GTK4 UI job shares project_name, so the default checksum file name would
+# collide with it on the shared GitHub release.
+checksum:
+  name_template: "{{ .ProjectName }}_gtk3_checksums.txt"
+
+changelog:
+  disable: true
+
+uploads:
+  # The gtk3 packages reuse the netbird-ui package name, so they live in
+  # dedicated repo paths (deb distribution `gtk3`, yum path `yum-gtk3`) that
+  # legacy distros point their repo config at.
+  - name: debian-gtk3
+    skip: "{{ .Env.SKIP_PUBLISH }}"
+    ids:
+      - netbird_ui_deb_gtk3
+    mode: archive
+    target: https://pkgs.wiretrustee.com/debian/pool/{{ .ArtifactName }};deb.distribution=gtk3;deb.component=main;deb.architecture={{ if .Arm }}armhf{{ else }}{{ .Arch }}{{ end }};deb.package=
+    username: dev@wiretrustee.com
+    method: PUT
+
+  - name: yum-gtk3
+    skip: "{{ .Env.SKIP_PUBLISH }}"
+    ids:
+      - netbird_ui_rpm_gtk3
+    mode: archive
+    target: https://pkgs.wiretrustee.com/yum-gtk3/{{ .Arch }}{{ if .Arm }}{{ .Arm }}{{ end }}
+    username: dev@wiretrustee.com
+    method: PUT

AGENTS.md

@@ -14,20 +14,22 @@ in this file, not duplicated there.
 
 ## Contents
 
-- [NetBird Agent Guidelines](#netbird-agent-guidelines)
-  - [Contents](#contents)
-  - [STOP and ask the user before](#stop-and-ask-the-user-before)
-  - [Quick reference](#quick-reference)
-  - [Structure](#structure)
-  - [Where to look](#where-to-look)
-  - [Repo-wide principles](#repo-wide-principles)
-  - [Error handling](#error-handling)
-  - [Comments](#comments)
-  - [Testing](#testing)
-  - [Pitfalls](#pitfalls)
-  - [Commits, PRs, releases](#commits-prs-releases)
-  - [After you push: CI and review bots](#after-you-push-ci-and-review-bots)
-  - [Discussion and support](#discussion-and-support)
+- [STOP and ask the user before](#stop-and-ask-the-user-before)
+- [Quick reference](#quick-reference)
+- [Structure](#structure)
+- [Where to look](#where-to-look)
+- [Security](#security)
+- [Agent conventions](#agent-conventions)
+- [Repo-wide principles](#repo-wide-principles)
+- [Type safety](#type-safety)
+- [Concurrency and lifecycle](#concurrency-and-lifecycle)
+- [Error handling](#error-handling)
+- [Comments](#comments)
+- [Testing](#testing)
+- [Pitfalls](#pitfalls)
+- [Commits, PRs, releases](#commits-prs-releases)
+- [After you push: CI and review bots](#after-you-push-ci-and-review-bots)
+- [Discussion and support](#discussion-and-support)
 
 ## STOP and ask the user before
 
@@ -157,11 +159,125 @@ netbird/
 | LLM routing / Agent Network | `proxy/internal/llm/`, `agent-network/`                      |
 | End-to-end tests            | `e2e/`                                                       |
 
+## Security
+
+### Never fail open
+
+When a security check — access control, an IP restriction, an auth decision —
+hits an error such as an unparseable value, an unavailable lookup, or a state it
+does not recognize, it must **deny**. Never skip the check or allow the request
+through because the check itself failed, and make the `default` and unknown cases
+of a security-related `switch` deny rather than fall through.
+
+### Daemon RPC input is untrusted
+
+The agent runs as root (LocalSystem on Windows), so a daemon RPC crosses a
+privilege boundary: treat every field as untrusted input rather than as something
+the UI or CLI validated on the way in.
+
+When you add or change an RPC, ask what the handler does with caller input while
+running as root. If the answer touches a filesystem path, a URL or host, or a
+privileged state change, it needs a gate **in the handler** — a check in the client
+that normally calls it is not a check at all.
+
+- **A caller-supplied path the daemon opens.** Never `os.Open` it as root.
+  Constrain it, then open it *as the caller* with `ipcauth.OpenOwnedFile`, which
+  opens `O_NOFOLLOW`, requires a regular file, and refuses a file the caller does
+  not own — so a symlink or hardlink aimed at a root-only file is rejected.
+- **A caller-supplied URL or host the daemon fetches.** Restrict the scheme and
+  allow only known hosts for unprivileged callers. Prefer a lexical host
+  allowlist plus TLS verification over "resolve the host, then reject private
+  IPs": the resolve-then-trust pattern has a DNS-rebinding race (public IP at
+  check time, attacker IP at connect time), while a name allowlist has no IP
+  check to race. Never accept `http://` where `https://` is expected.
+- **A privileged state change** (SSH root login, management URL, deregistration)
+  gates on the caller identity from `ipcauth.CallerIdentity(ctx)`.
+
+Caller identity comes from the kernel — `SO_PEERCRED`, `LOCAL_PEERCRED`, or the
+named-pipe client token — and never from an RPC field. When
+`ipcauth.CallerIdentity` reports that it could not determine an identity, **deny**;
+do not fall back to treating the caller as the transport peer.
+
+## Agent conventions
+
+### Three networking modes
+
+Where packets actually flow depends on the mode the agent is running in. The
+three are not interchangeable, so establish which one a change applies to — and
+what it should do in the other two — before you write it.
+
+- **kernel mode** (Linux only): in-kernel WireGuard®. The kernel handles both
+  peer-to-peer and routed traffic, and ACLs are iptables or nftables rules. The
+  client programs kernel facilities but never sees the traffic itself.
+- **userspace mode** (wireguard-go with a TUN): wireguard-go runs in-process. The
+  kernel handles peer-to-peer traffic once it leaves the TUN, while routed traffic
+  — exit nodes and network routes — goes through the userspace forwarder, which
+  terminates the connection and re-establishes it over OS sockets. Used on
+  platforms without kernel WireGuard® or when the user opts out.
+- **netstack mode**: wireguard-go in-process with no TUN and no kernel
+  networking. The forwarder does all routing by stitching userspace sockets, and
+  listeners such as the embedded SSH and DNS servers bind on a gVisor netstack.
+  Used where the process cannot create a TUN device, such as the embedded client
+  (`client/embed/`) and the WASM build.
+
+### The overlay interface is not "WireGuard"
+
+Do not put "WireGuard" in identifiers or comments unless the code is genuinely
+coupled to WireGuard® specifically — a wireguard-go call, a handshake field, a
+kernel WireGuard® netlink attribute. For the interface, the host, peers, or
+traffic in general, say "the NetBird interface", "the interface", or "the overlay".
+Most firewall, routing, and DNS code is transport-agnostic, so a WireGuard®
+reference there is simply inaccurate and rots as the transports change.
+
+### IPv6 is a soft feature
+
+The IPv6 overlay is opt-in dual-stack, and capability can change at runtime. Treat
+it as soft rather than a requirement:
+
+- Gate local v6 paths on the interface accessor (`wgIface.Address().HasIPv6()`),
+  not on raw state fields, and skip the v6 path when the host has no v6 rather
+  than returning an error.
+- Treat an empty or unparseable peer v6 address as "no v6 for that peer" and skip
+  it, keeping the v4 path working.
+- Never let a missing v6 break v4. Fail-closed is for security checks; a
+  capability mismatch skips the v6 work and carries on.
+
+### Environment variables
+
+Name the variable in a constant and parse booleans with `strconv.ParseBool` rather
+than comparing strings inline, so an unexpected value is logged instead of
+silently meaning false:
+
+```go
+const EnvDisableFeature = "NB_DISABLE_FEATURE"
+
+func isDisabledByEnv() bool {
+    val := os.Getenv(EnvDisableFeature)
+    if val == "" {
+        return false
+    }
+    disabled, err := strconv.ParseBool(val)
+    if err != nil {
+        log.Warnf("failed to parse %s: %v", EnvDisableFeature, err)
+        return false
+    }
+    return disabled
+}
+```
+
+### Validating against protocol specs
+
+When a change depends on what a protocol actually mandates, read the specification
+text from the [IETF datatracker](https://datatracker.ietf.org/) rather than a
+summary, and check that you have the current RFC — the widely cited one for a
+protocol is often superseded. Cite the section, not just the document, so a
+reviewer can jump straight to the rule.
+
 ## Repo-wide principles
 
 1. **Run `go fmt` on every modified Go file.** Formatting is not optional.
-2. **Zero unaddressed diagnostics.** Fix IDE and linter warnings on code you
-   touch, and delete imports, helpers, and parameters your refactor orphaned.
+2. **Zero unaddressed linter warnings.** Fix what `golangci-lint` reports on code
+   you touch, and delete imports, helpers, and parameters your refactor orphaned.
    Exception: unused parameters in shared code may be consumed by builds outside
    this repository — do not remove them, ask instead.
 3. **Function comments are mandatory for exported functions**, written as full
@@ -175,9 +291,12 @@ netbird/
 7. **Avoid LLM-slop tells:** em dashes, hedging narration, restating the diff in
    prose, trailing summaries. Defaults, not absolute bans. Applies to code,
    comments, commit messages, and PR descriptions alike.
-8. **Concurrency: do a two-pass race analysis after every change** that adds
-   shared state. Guard maps and slices with a mutex, keep critical sections
-   short, and run `go test -race` on the touched packages.
+8. **Concurrency: do a two-pass race analysis after every change** that touches
+   shared state, including reads of existing maps and slices. Guard them with a
+   mutex (or an atomic or channel where that fits better), keep critical
+   sections short, and run `go test -race` on the touched packages. See
+   [Concurrency and lifecycle](#concurrency-and-lifecycle) for the failure modes
+   to check for.
 9. **Cross-platform builds must keep working.** The agent targets Linux, macOS,
    Windows, FreeBSD, Android, and iOS. When you add a platform-specific file,
    add the counterpart or a build-tagged fallback for the others.
@@ -185,6 +304,93 @@ netbird/
 11. **Never log secrets** — private keys, setup keys, tokens, PAT values — and
     keep peer IPs and hostnames out of logs above debug level.
 
+## Type safety
+
+**No bare primitives for domain concepts.** A `string` parameter for an account
+ID next to a `string` parameter for a peer ID is two bugs waiting to happen,
+because the compiler cannot catch the swap. Declare the type once and use it
+throughout, converting only at the boundaries where data enters or leaves —
+protobuf, gRPC, HTTP, an external library.
+
+```go
+type ServiceID string
+type AccountID string
+
+// Internal: typed all the way through
+func (r *Router) RemoveRoute(host SNIHost, svcID ServiceID) { ... }
+
+// Proto boundary: convert once, on the way in and on the way out
+svcID := ServiceID(mapping.GetId())
+req.ServiceId = string(svcID)
+```
+
+- **IP addresses are `netip.Addr`**, not `string` and not `net.IP`. Parse at the
+  boundary and pass the typed value inward.
+- **Always `Unmap()`** after parsing an address, after converting from `net.IP`,
+  and after extracting one from `RemoteAddr()`. This normalizes a v4-mapped v6
+  address (`::ffff:10.1.2.3`) to plain v4 so IPv4 rules match it. A stored or
+  compared mapped address silently fails to match those rules.
+- **Ports are `uint16`** internally; use `int` only where a library forces it and
+  convert immediately.
+- **Enums are a typed string with constants**, so the valid set is discoverable
+  and a typo fails to compile.
+- **Map keys follow the same rule**, and must be a real type (`type ServiceID
+  string`) rather than an alias (`type serviceID = string`) — an alias silently
+  accepts bare strings.
+
+## Concurrency and lifecycle
+
+Beyond the mutex hygiene in the principles above, check for these failure
+modes.
+
+- **Never read a struct field inside a goroutine** when another goroutine may nil
+  or reassign it. Pass the value as a parameter, or capture it into a local before
+  launching. This matters most when `Stop()` nils a field without waiting for the
+  goroutine to finish.
+
+  ```go
+  go func(ifaceName string) {   // good: passed in, cannot be nilled underneath
+      m.Start(ctx, ifaceName)
+  }(iface.Name())
+  ```
+
+- **Never wait on a channel while holding a lock the sender needs.** Copy what you
+  need out from under the lock, release it, then wait.
+
+  ```go
+  func (m *Manager) Stop() {
+      m.mu.Lock()
+      cancel, done := m.cancel, m.done
+      m.mu.Unlock()
+      if cancel != nil {
+          cancel()
+          <-done
+      }
+  }
+  ```
+
+- **`Stop`/`Close` must be idempotent** — guard on an already-stopped flag or a
+  nil cancel — and must release the state they guarded. Clear maps and caches;
+  a cancelled goroutine holding a live map still pins that memory. Note that a
+  nil map only panics on writes; reads and iteration behave like an empty map,
+  so where post-close use must be rejected, check the stopped flag explicitly.
+- **Publish coupled state only after every fallible step succeeds.** When several
+  fields form an invariant, build them into locals and assign them to the receiver
+  at the end. Assigning as you go leaves the object half-initialized when a later
+  step fails, so a readiness predicate reports ready while a coupled field is nil.
+  If an earlier step already had an external side effect — a created chain, an
+  opened handle, an inserted rule — roll it back before returning the error.
+- **Clean up what you own on constructor error paths.** Once a constructor has
+  started something, every later error path must undo it: cancel a goroutine and
+  wait for it to exit, stop a ticker, close a watcher. The object is never
+  returned, so its `Close` will never run.
+- **A failed `Start` must undo everything it started.** When a component brings up
+  several subsystems in sequence — connection manager, watchers, routing, DNS,
+  flow, persisted state — a failure partway through has to tear down the ones
+  already running, not just close the handle the error came from. Put the
+  already-started guard *before* that teardown path, so a rejected second `Start`
+  cannot dismantle the one that is running.
+
 ## Error handling
 
 Use single-assignment form when the error is only needed inside the `if`:
@@ -248,6 +454,45 @@ Log the errors you choose not to act on:
 - Close errors may be ignored for read-only operations; log them at debug for
   writes.
 
+**Do not log and return the same error.** It gets reported twice, from two places,
+and the second reader cannot tell whether it happened once or twice. Return it and
+let the caller decide. The exception is an API handler that has already written a
+response. Internal helpers return errors rather than logging and swallowing them.
+
+**Never return a typed nil as an error.** A nil `*MyError` stored in an `error`
+interface is not nil, so `err != nil` is true and callers take the failure path on
+success. Return the error only where it is actually set:
+
+```go
+if _, err := conn.Write(buf); err != nil {   // good
+    return err
+}
+return nil
+```
+
+**Accumulate with `multierror` when an operation should continue past individual
+failures** — teardown, cleanup, or setup where partial success is acceptable.
+`client/errors.FormatErrorOrNil` returns nil for an empty accumulator, so callers
+still see a plain nil on full success:
+
+```go
+func (m *Manager) Cleanup() error {
+    var merr *multierror.Error
+    for _, r := range m.resources {
+        if err := r.Close(); err != nil {
+            merr = multierror.Append(merr, fmt.Errorf("close %s: %w", r.Name, err))
+        }
+    }
+    return nberrors.FormatErrorOrNil(merr)
+}
+```
+
+| Scenario              | Approach              | Why                                       |
+| --------------------- | --------------------- | ----------------------------------------- |
+| Cleanup / teardown    | Accumulate            | Clean up as much as possible              |
+| Setup with rollback   | Abort on first error  | Partial state is invalid; undo what stuck |
+| Setup with partial OK | Accumulate            | Degraded operation is still useful        |
+
 ## Comments
 
 Comment the **why**, never the **what**. Default to no comment, and add one only
@@ -269,10 +514,14 @@ checksum = updateChecksum(checksum, oldPort, newPort)
 
 ### Length budget
 
-- **90 characters per line.** Wrap the comment, do not run past it.
-- **250 characters per comment**, roughly three wrapped lines. Doc comments on
-  exported identifiers may exceed it when the API genuinely needs the
-  explanation; inline comments inside a function body may not.
+Neither of these is linter-enforced, so they are conventions the surrounding code
+mostly follows rather than hard limits:
+
+- **Around 90 characters per line.** Wrap the comment rather than running well past
+  it.
+- **Roughly 250 characters per comment**, about three wrapped lines. Doc comments
+  on exported identifiers may exceed it when the API genuinely needs the
+  explanation; inline comments inside a function body rarely should.
 
 The budget is a smell detector, not a rule to game. Do not compress a needed
 explanation into cryptic shorthand to fit — if a block of code needs more than
@@ -329,6 +578,19 @@ up, and the 250-character budget does not apply to them.
   otherwise.
 - **Message guidance:** optional for `NoError`/`Error`; always give context for
   comparison, boolean, and collection assertions.
+- **Reproduce a bug before fixing it.** Write the test, watch it fail *for the
+  reason you expect* — a test that fails for an unrelated reason proves nothing —
+  then apply the fix and confirm it passes. Add the thin surrounding cases while
+  you are there.
+- **Use `t.Setenv`** rather than `os.Setenv` so the previous value is restored on
+  cleanup. To test the unset case, call `t.Setenv` first to register the restore,
+  then `os.Unsetenv`.
+- **Prefer `t.Cleanup` over `defer`** in any test with parallel subtests: the
+  parent function returns, running its `defer`s, while parallel subtests are
+  still suspended. Sequential subtests finish inside `t.Run`, so `defer` is safe
+  there, but `t.Cleanup` works in both cases.
+- **Explanatory comments in tests are welcome.** Describe the scenario being set
+  up; the comment budget below does not apply to them.
 
 ```go
 server, err := StartTestServer()
@@ -380,7 +642,8 @@ assert.Equal(t, expectedResult, result, "Result should match expected")
   than replacing it with your own summary: describe the change, link the issue,
   tick the checklist honestly (including "ran locally" and "single purpose"),
   and complete the documentation section. Do not tick a box you have not
-  verified, and do not delete rows that do not apply.
+  verified, and do not delete rows that do not apply — the docs gate in CI reads
+  that section and fails when it is missing.
 
 - **Keep the PR description short.** Under 1000 words on top of the template's
   own text, and usually far less — a few paragraphs. Reviewers read the diff;
@@ -439,6 +702,12 @@ assert.Equal(t, expectedResult, result, "Result should match expected")
   on their own. Propose that split to the user rather than opening one large PR
   and hoping.
 
+  Prefer GitHub's stacked pull requests for such a sequence, rather than
+  hand-managing base branches: open each PR against the branch below it instead of
+  `main`, so every PR's diff shows only its own change. Merging a layer retargets
+  the PRs above it, and branch protections and required checks on the base branch
+  still apply to each one.
+
 - **User-facing changes need a docs PR** in
   [netbirdio/docs](https://github.com/netbirdio/docs), linked from the PR
   description.

client/ui/frontend/src/hooks/useKeepConnectedOnQuit.ts

@@ -0,0 +1,35 @@
+import { useCallback, useEffect, useState } from "react";
+import { Preferences } from "@bindings/services";
+
+export const useKeepConnectedOnQuit = () => {
+    const [keepConnected, setKeepConnected] = useState<boolean | null>(null);
+
+    useEffect(() => {
+        let cancelled = false;
+        Preferences.Get()
+            .then((prefs) => {
+                if (cancelled) return;
+                setKeepConnected(prefs?.keepConnectedOnQuit ?? false);
+            })
+            .catch((err: unknown) => {
+                if (cancelled) return;
+                console.warn("[useKeepConnectedOnQuit] load preferences failed", err);
+                setKeepConnected(false);
+            });
+        return () => {
+            cancelled = true;
+        };
+    }, []);
+
+    const setKeepConnectedOnQuit = useCallback(async (keep: boolean) => {
+        setKeepConnected(keep);
+        try {
+            await Preferences.SetKeepConnectedOnQuit(keep);
+        } catch (err: unknown) {
+            setKeepConnected(!keep);
+            console.error("[useKeepConnectedOnQuit] SetKeepConnectedOnQuit failed", err);
+        }
+    }, []);
+
+    return { keepConnected, setKeepConnectedOnQuit };
+};

client/ui/frontend/src/modules/settings/SettingsGeneral.tsx

@@ -11,6 +11,7 @@ import { ManagementServerSwitch } from "@/components/ManagementServerSwitch.tsx"
 import { ManagementMode, useManagementUrl } from "@/hooks/useManagementUrl.ts";
 import { LanguagePicker } from "@/components/LanguagePicker.tsx";
 import { useRestrictions } from "@/contexts/RestrictionsContext.tsx";
+import { useKeepConnectedOnQuit } from "@/hooks/useKeepConnectedOnQuit.ts";
 
 export function SettingsGeneral() {
     const { t } = useTranslation();
@@ -19,6 +20,7 @@ export function SettingsGeneral() {
     const { mode, setMode, setUrl, displayUrl, showError, canSave, save, checking, unreachable } =
         useManagementUrl();
     const { mdm, features } = useRestrictions();
+    const { keepConnected, setKeepConnectedOnQuit } = useKeepConnectedOnQuit();
 
     const inputRef = useRef<HTMLInputElement>(null);
     const managementUrlId = useId();
@@ -57,6 +59,15 @@ export function SettingsGeneral() {
                         helpText={t("settings.general.autostart.help")}
                     />
                 )}
+                <FancyToggleSwitch
+                    value={keepConnected ?? false}
+                    onChange={(v) => {
+                        void setKeepConnectedOnQuit(v);
+                    }}
+                    loading={keepConnected === null}
+                    label={t("settings.general.keepConnectedOnQuit.label")}
+                    helpText={t("settings.general.keepConnectedOnQuit.help")}
+                />
             </SectionGroup>
 
             {!mdm.managementURL && !features.disableUpdateSettings && (

client/ui/i18n/locales/de/common.json

@@ -551,6 +551,14 @@
     "settings.general.autostart.errorTitle": {
         "message": "Ändern des Autostarts fehlgeschlagen"
     },
+    "settings.general.keepConnectedOnQuit.label": {
+        "message": "Nach dem Beenden verbunden bleiben",
+        "description": "Toggle label: keep the VPN connection up after quitting the UI."
+    },
+    "settings.general.keepConnectedOnQuit.help": {
+        "message": "Die Verbindung bleibt im Hintergrund bestehen, nachdem Sie NetBird schließen. Sie endet erst, wenn Sie sie selbst trennen.",
+        "description": "Helper text for the stay-connected-after-quitting toggle."
+    },
     "settings.general.language.label": {
         "message": "Anzeigesprache"
     },

client/ui/i18n/locales/en/common.json

@@ -735,6 +735,14 @@
         "message": "Autostart Change Failed",
         "description": "Error-dialog title when changing the autostart setting fails."
     },
+    "settings.general.keepConnectedOnQuit.label": {
+        "message": "Stay Connected After Quitting",
+        "description": "Toggle label: keep the VPN connection up after quitting the UI."
+    },
+    "settings.general.keepConnectedOnQuit.help": {
+        "message": "The connection stays up in the background after you close NetBird. It only stops when you disconnect it yourself.",
+        "description": "Helper text for the stay-connected-after-quitting toggle."
+    },
     "settings.general.language.label": {
         "message": "Display Language",
         "description": "Label for the display-language picker."

client/ui/i18n/locales/es/common.json

@@ -551,6 +551,14 @@
     "settings.general.autostart.errorTitle": {
         "message": "Error al cambiar el inicio automático"
     },
+    "settings.general.keepConnectedOnQuit.label": {
+        "message": "Permanecer conectado al salir",
+        "description": "Toggle label: keep the VPN connection up after quitting the UI."
+    },
+    "settings.general.keepConnectedOnQuit.help": {
+        "message": "La conexión sigue activa en segundo plano después de cerrar NetBird. Solo se detiene cuando la desconectas tú.",
+        "description": "Helper text for the stay-connected-after-quitting toggle."
+    },
     "settings.general.language.label": {
         "message": "Idioma de la interfaz"
     },

client/ui/i18n/locales/fr/common.json

@@ -551,6 +551,14 @@
     "settings.general.autostart.errorTitle": {
         "message": "Échec de la modification du démarrage automatique"
     },
+    "settings.general.keepConnectedOnQuit.label": {
+        "message": "Rester connecté après la fermeture",
+        "description": "Toggle label: keep the VPN connection up after quitting the UI."
+    },
+    "settings.general.keepConnectedOnQuit.help": {
+        "message": "La connexion reste active en arrière-plan après la fermeture de NetBird. Elle ne s'arrête que si vous la coupez vous-même.",
+        "description": "Helper text for the stay-connected-after-quitting toggle."
+    },
     "settings.general.language.label": {
         "message": "Langue d’affichage"
     },

client/ui/i18n/locales/hu/common.json

@@ -551,6 +551,14 @@
     "settings.general.autostart.errorTitle": {
         "message": "Az automatikus indítás módosítása sikertelen"
     },
+    "settings.general.keepConnectedOnQuit.label": {
+        "message": "Kapcsolat megtartása kilépéskor",
+        "description": "Toggle label: keep the VPN connection up after quitting the UI."
+    },
+    "settings.general.keepConnectedOnQuit.help": {
+        "message": "A kapcsolat a háttérben megmarad, miután bezárod a NetBirdöt. Csak akkor szakad meg, ha te magad bontod.",
+        "description": "Helper text for the stay-connected-after-quitting toggle."
+    },
     "settings.general.language.label": {
         "message": "Megjelenítési nyelv"
     },

client/ui/i18n/locales/it/common.json

@@ -551,6 +551,14 @@
     "settings.general.autostart.errorTitle": {
         "message": "Modifica avvio automatico non riuscita"
     },
+    "settings.general.keepConnectedOnQuit.label": {
+        "message": "Resta connesso dopo la chiusura",
+        "description": "Toggle label: keep the VPN connection up after quitting the UI."
+    },
+    "settings.general.keepConnectedOnQuit.help": {
+        "message": "La connessione resta attiva in background dopo la chiusura di NetBird. Si interrompe solo quando la disconnetti tu.",
+        "description": "Helper text for the stay-connected-after-quitting toggle."
+    },
     "settings.general.language.label": {
         "message": "Lingua dell'interfaccia"
     },

client/ui/i18n/locales/ja/common.json

@@ -551,6 +551,14 @@
     "settings.general.autostart.errorTitle": {
         "message": "自動起動の変更に失敗しました"
     },
+    "settings.general.keepConnectedOnQuit.label": {
+        "message": "終了後も接続を維持",
+        "description": "Toggle label: keep the VPN connection up after quitting the UI."
+    },
+    "settings.general.keepConnectedOnQuit.help": {
+        "message": "NetBird を閉じたあとも接続はバックグラウンドで維持されます。自分で切断したときにだけ停止します。",
+        "description": "Helper text for the stay-connected-after-quitting toggle."
+    },
     "settings.general.language.label": {
         "message": "表示言語"
     },

client/ui/i18n/locales/pt/common.json

@@ -551,6 +551,14 @@
     "settings.general.autostart.errorTitle": {
         "message": "Falha ao alterar o início automático"
     },
+    "settings.general.keepConnectedOnQuit.label": {
+        "message": "Permanecer conectado ao sair",
+        "description": "Toggle label: keep the VPN connection up after quitting the UI."
+    },
+    "settings.general.keepConnectedOnQuit.help": {
+        "message": "A conexão continua ativa em segundo plano depois de fechar o NetBird. Ela só para quando você mesmo a desconecta.",
+        "description": "Helper text for the stay-connected-after-quitting toggle."
+    },
     "settings.general.language.label": {
         "message": "Idioma de exibição"
     },

client/ui/i18n/locales/ru/common.json

@@ -551,6 +551,14 @@
     "settings.general.autostart.errorTitle": {
         "message": "Не удалось изменить автозапуск"
     },
+    "settings.general.keepConnectedOnQuit.label": {
+        "message": "Оставаться подключённым после выхода",
+        "description": "Toggle label: keep the VPN connection up after quitting the UI."
+    },
+    "settings.general.keepConnectedOnQuit.help": {
+        "message": "Соединение остаётся активным в фоне после закрытия NetBird. Оно прервётся, только когда вы отключите его сами.",
+        "description": "Helper text for the stay-connected-after-quitting toggle."
+    },
     "settings.general.language.label": {
         "message": "Язык интерфейса"
     },

client/ui/i18n/locales/zh-CN/common.json

@@ -551,6 +551,14 @@
     "settings.general.autostart.errorTitle": {
         "message": "更改自启动设置失败"
     },
+    "settings.general.keepConnectedOnQuit.label": {
+        "message": "退出后保持连接",
+        "description": "Toggle label: keep the VPN connection up after quitting the UI."
+    },
+    "settings.general.keepConnectedOnQuit.help": {
+        "message": "关闭 NetBird 后，连接会在后台保持。只有你自己断开时才会停止。",
+        "description": "Helper text for the stay-connected-after-quitting toggle."
+    },
     "settings.general.language.label": {
         "message": "显示语言"
     },

client/ui/main.go

@@ -180,6 +180,7 @@ func main() {
 		WindowManager:   windowManager,
 		Session:         authSession,
 		Localizer:       localizer,
+		Preferences:     prefStore,
 	})
 	listenForShowSignal(context.Background(), tray)
 

client/ui/preferences/store.go

@@ -58,6 +58,10 @@ type UIPreferences struct {
 	// decision has run for this OS user. It only ever transitions to true
 	// and is never reset, so the default-on flow runs at most once, ever.
 	AutostartInitialized bool `json:"autostartInitialized"`
+	// KeepConnectedOnQuit leaves the daemon connected when the GUI quits.
+	// Its false zero value preserves the historical disconnect-on-quit
+	// behaviour for preference files written before the field existed.
+	KeepConnectedOnQuit bool `json:"keepConnectedOnQuit"`
 }
 
 // LanguageValidator rejects SetLanguage inputs with no shipped bundle.
@@ -183,6 +187,26 @@ func (s *Store) SetAutostartInitialized(done bool) error {
 	return nil
 }
 
+// SetKeepConnectedOnQuit persists the disconnect-on-quit opt-out. No-op if unchanged.
+func (s *Store) SetKeepConnectedOnQuit(keep bool) error {
+	s.mu.Lock()
+	if s.current.KeepConnectedOnQuit == keep {
+		s.mu.Unlock()
+		return nil
+	}
+	next := s.current
+	next.KeepConnectedOnQuit = keep
+	if err := s.persistLocked(next); err != nil {
+		s.mu.Unlock()
+		return fmt.Errorf("persist preferences: %w", err)
+	}
+	s.current = next
+	s.mu.Unlock()
+
+	s.broadcast(next)
+	return nil
+}
+
 // SetLanguage validates, persists, and broadcasts. No-op if unchanged.
 func (s *Store) SetLanguage(lang i18n.LanguageCode) error {
 	if lang == "" {

client/ui/preferences/store_test.go

@@ -238,6 +238,42 @@ func TestStore_SetAutostartInitializedPersistsAcrossReload(t *testing.T) {
 	assert.True(t, reloaded.Get().AutostartInitialized, "marker must survive a reload from disk")
 }
 
+func TestStore_SetKeepConnectedOnQuitPersistsAcrossReload(t *testing.T) {
+	withTempConfigDir(t)
+	emitter := &recordingEmitter{}
+	s, err := NewStore(nil, emitter)
+	require.NoError(t, err)
+
+	assert.False(t, s.Get().KeepConnectedOnQuit, "quitting must disconnect by default")
+
+	require.NoError(t, s.SetKeepConnectedOnQuit(true))
+	assert.True(t, s.Get().KeepConnectedOnQuit, "Get should reflect the persisted opt-out")
+	require.Len(t, emitter.calledWith(EventPreferencesChanged), 1, "first write should broadcast")
+
+	require.NoError(t, s.SetKeepConnectedOnQuit(true))
+	assert.Len(t, emitter.calledWith(EventPreferencesChanged), 1, "idempotent write should not broadcast again")
+
+	reloaded, err := NewStore(nil, nil)
+	require.NoError(t, err)
+	assert.True(t, reloaded.Get().KeepConnectedOnQuit, "opt-out must survive a reload from disk")
+}
+
+func TestStore_KeepConnectedOnQuitDefaultsFalseForPreExistingFile(t *testing.T) {
+	withTempConfigDir(t)
+
+	// A preferences file written before the field existed must keep the
+	// historical disconnect-on-quit behaviour rather than silently opting out.
+	path, err := preferencesPath()
+	require.NoError(t, err)
+	require.NoError(t, os.MkdirAll(filepath.Dir(path), 0o755))
+	require.NoError(t, os.WriteFile(path, []byte(`{"language":"en","viewMode":"default"}`), 0o600))
+
+	s, err := NewStore(nil, nil)
+	require.NoError(t, err)
+	assert.False(t, s.Get().KeepConnectedOnQuit, "a file predating the field must not opt out of disconnect-on-quit")
+	assert.True(t, s.ExistedAtLoad(), "the pre-existing file must be seen on disk")
+}
+
 func TestStore_ExistedAtLoad(t *testing.T) {
 	withTempConfigDir(t)
 

client/ui/services/cursor_linux.go

@@ -49,5 +49,11 @@ func getCursorPosition(app *application.App) (application.Point, bool) {
 	if app == nil || app.Screen == nil {
 		return p, true
 	}
+	// The wails GTK3 backend caches screens from the active window; a tray app
+	// has none at startup, so the cache is empty and PhysicalToDipPoint would
+	// dereference a nil nearest screen. Raw pixels are correct there anyway.
+	if app.Screen.ScreenNearestPhysicalPoint(p) == nil {
+		return p, true
+	}
 	return app.Screen.PhysicalToDipPoint(p), true
 }

client/ui/services/preferences.go

@@ -34,3 +34,7 @@ func (s *Preferences) SetViewMode(_ context.Context, mode preferences.ViewMode)
 func (s *Preferences) SetOnboardingCompleted(_ context.Context, done bool) error {
 	return s.store.SetOnboardingCompleted(done)
 }
+
+func (s *Preferences) SetKeepConnectedOnQuit(_ context.Context, keep bool) error {
+	return s.store.SetKeepConnectedOnQuit(keep)
+}

client/ui/tray.go

@@ -16,6 +16,7 @@ import (
 
 	"github.com/netbirdio/netbird/client/ui/authsession"
 	"github.com/netbirdio/netbird/client/ui/i18n"
+	"github.com/netbirdio/netbird/client/ui/preferences"
 	"github.com/netbirdio/netbird/client/ui/services"
 	"github.com/netbirdio/netbird/version"
 )
@@ -50,8 +51,9 @@ type TrayServices struct {
 	WindowManager   *services.WindowManager
 	// Session is bound to authsession directly because the services wrapper
 	// only re-exposes the React subset.
-	Session   *authsession.Session
-	Localizer *Localizer
+	Session     *authsession.Session
+	Localizer   *Localizer
+	Preferences *preferences.Store
 }
 
 type Tray struct {
@@ -461,10 +463,12 @@ func (t *Tray) handleQuit() {
 	t.profileMu.Unlock()
 	t.svc.DaemonFeed.CancelProfileSwitch()
 
-	ctx, cancel := context.WithTimeout(context.Background(), quitDownTimeout)
-	defer cancel()
-	if err := t.svc.Connection.Down(ctx); err != nil {
-		log.Errorf("disconnect on quit: %v", err)
+	if t.svc.Preferences == nil || !t.svc.Preferences.Get().KeepConnectedOnQuit {
+		ctx, cancel := context.WithTimeout(context.Background(), quitDownTimeout)
+		defer cancel()
+		if err := t.svc.Connection.Down(ctx); err != nil {
+			log.Errorf("disconnect on quit: %v", err)
+		}
 	}
 	t.app.Quit()
 }

client/ui/xembed_host_gtk3_linux.go

@@ -0,0 +1,40 @@
+//go:build linux && gtk3 && !(linux && 386)
+
+package main
+
+import (
+	"errors"
+
+	"github.com/godbus/dbus/v5"
+)
+
+// The legacy GTK3 / WebKit2GTK 4.1 build (-tags gtk3) drops the in-process
+// XEmbed StatusNotifierWatcher entirely. The real implementation
+// (xembed_host_linux.go + xembed_tray_linux.c) links GTK4 and uses GTK4-only
+// popup-menu APIs that have no drop-in GTK3 equivalent, so rather than port the
+// C layer we stub the host out on gtk3 builds. The tray still works on every
+// desktop that ships its own StatusNotifierWatcher (KDE, GNOME+AppIndicator,
+// Cinnamon/xapp, XFCE, …); only the minimal-WM fallback (Fluxbox/OpenBox/i3/
+// dwm/vanilla GNOME) is unavailable on gtk3 packages. See LINUX-TRAY.md.
+
+// xembedHost is a placeholder so the package compiles on gtk3 builds; the real
+// type (with X11/GTK4 state) lives in xembed_host_linux.go. It is never
+// instantiated here because xembedTrayAvailable always reports false.
+type xembedHost struct{}
+
+// run satisfies the call in tray_watcher_linux.go; unreachable on gtk3 because
+// newXembedHost never returns a non-nil host.
+func (*xembedHost) run() {}
+
+// xembedTrayAvailable always reports false on gtk3 builds, so the watcher probe
+// loop in startStatusNotifierWatcher exits immediately and newXembedHost is
+// never reached. recenter_linux.go's predicate becomes a harmless no-op too.
+func xembedTrayAvailable() bool {
+	return false
+}
+
+// newXembedHost exists only to satisfy the reference in tray_watcher_linux.go;
+// it is unreachable because xembedTrayAvailable returns false on gtk3.
+func newXembedHost(conn *dbus.Conn, busName string, objPath dbus.ObjectPath) (*xembedHost, error) {
+	return nil, errors.New("xembed host unsupported on gtk3 build")
+}

client/ui/xembed_host_linux.go

@@ -1,4 +1,4 @@
-//go:build linux && !(linux && 386)
+//go:build linux && !gtk3 && !(linux && 386)
 
 package main
 

client/ui/xembed_tray_linux.c

@@ -1,3 +1,5 @@
+//go:build linux && !gtk3 && !(linux && 386)
+
 #include "xembed_tray_linux.h"
 
 #include <X11/Xatom.h>

infrastructure_files/getting-started-enterprise.sh

@@ -262,6 +262,7 @@ init_environment() {
   POSTGRES_DB="netbird"
   POSTGRES_PASSWORD=$(rand_secret)
   NETBIRD_ENCRYPTION_KEY=$(rand_b64_key)
+  NETBIRD_SESSION_COOKIE_ENCRYPTION_KEY=$(rand_b64_key)
   NETBIRD_RELAY_AUTH_SECRET=$(rand_secret)
 
   POSTGRES_DSN="host=postgres user=${POSTGRES_USER} password=${POSTGRES_PASSWORD} dbname=${POSTGRES_DB} port=5432 sslmode=disable TimeZone=UTC"
@@ -696,6 +697,7 @@ server:
     issuer: "https://${NETBIRD_DOMAIN}/oauth2"
     localAuthDisabled: false
     signKeyRefreshEnabled: false
+    sessionCookieEncryptionKey: "${NETBIRD_SESSION_COOKIE_ENCRYPTION_KEY}"
     dashboardRedirectURIs:
       - "https://${NETBIRD_DOMAIN}/nb-auth"
       - "https://${NETBIRD_DOMAIN}/nb-silent-auth"

infrastructure_files/getting-started.sh

@@ -348,6 +348,7 @@ initialize_default_values() {
   NETBIRD_RELAY_AUTH_SECRET=$(openssl rand -base64 32 | sed "$SED_STRIP_PADDING")
   # Note: DataStoreEncryptionKey must keep base64 padding (=) for Go's base64.StdEncoding
   DATASTORE_ENCRYPTION_KEY=$(openssl rand -base64 32)
+  SESSION_COOKIE_ENCRYPTION_KEY=$(openssl rand -base64 32)
   NETBIRD_STUN_PORT=3478
 
   # Docker images
@@ -527,7 +528,8 @@ generate_configuration_files() {
 
   # Common files for all configurations
   render_dashboard_env > dashboard.env
-  render_combined_yaml > config.yaml
+  install -m 600 /dev/null config.yaml
+  render_combined_yaml >> config.yaml
   return 0
 }
 
@@ -911,6 +913,7 @@ server:
   auth:
     issuer: "$NETBIRD_HTTP_PROTOCOL://$NETBIRD_DOMAIN/oauth2"
     signKeyRefreshEnabled: true
+    sessionCookieEncryptionKey: "$SESSION_COOKIE_ENCRYPTION_KEY"
     dashboardRedirectURIs:
       - "$NETBIRD_HTTP_PROTOCOL://$NETBIRD_DOMAIN/nb-auth"
       - "$NETBIRD_HTTP_PROTOCOL://$NETBIRD_DOMAIN/nb-silent-auth"

management/internals/modules/reverseproxy/service/manager/manager_test.go

@@ -7,7 +7,6 @@ import (
 	"testing"
 	"time"
 
-	cachestore "github.com/eko/gocache/lib/v4/store"
 	"github.com/golang/mock/gomock"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -31,7 +30,7 @@ import (
 	"github.com/netbirdio/netbird/shared/management/status"
 )
 
-func testCacheStore(t *testing.T) cachestore.StoreInterface {
+func testCacheStore(t *testing.T) nbcache.Store {
 	t.Helper()
 	s, err := nbcache.NewStore(context.Background(), 30*time.Minute, 10*time.Minute, 100)
 	require.NoError(t, err)
@@ -295,6 +294,7 @@ func TestPersistNewService(t *testing.T) {
 		assert.Equal(t, status.AlreadyExists, sErr.Type())
 	})
 }
+
 func TestPreserveExistingAuthSecrets(t *testing.T) {
 	mgr := &Manager{}
 

management/internals/server/boot.go

@@ -20,8 +20,6 @@ import (
 	"google.golang.org/grpc/credentials"
 	"google.golang.org/grpc/keepalive"
 
-	cachestore "github.com/eko/gocache/lib/v4/store"
-
 	"github.com/netbirdio/netbird/encryption"
 	"github.com/netbirdio/netbird/formatter/hook"
 	"github.com/netbirdio/netbird/management/internals/modules/agentnetwork"
@@ -70,8 +68,8 @@ func (s *BaseServer) Metrics() telemetry.AppMetrics {
 
 // CacheStore returns a shared cache store backed by Redis or in-memory depending on the environment.
 // All consumers should reuse this store to avoid creating multiple Redis connections.
-func (s *BaseServer) CacheStore() cachestore.StoreInterface {
-	return Create(s, func() cachestore.StoreInterface {
+func (s *BaseServer) CacheStore() nbcache.Store {
+	return Create(s, func() nbcache.Store {
 		cs, err := nbcache.NewStore(context.Background(), nbcache.DefaultStoreMaxTimeout, nbcache.DefaultStoreCleanupInterval, nbcache.DefaultStoreMaxConn)
 		if err != nil {
 			log.Fatalf("failed to create shared cache store: %v", err)

management/internals/shared/grpc/pkce_verifier.go

@@ -5,22 +5,23 @@ import (
 	"fmt"
 	"time"
 
-	"github.com/eko/gocache/lib/v4/cache"
 	"github.com/eko/gocache/lib/v4/store"
 	log "github.com/sirupsen/logrus"
+
+	nbcache "github.com/netbirdio/netbird/management/server/cache"
 )
 
 // PKCEVerifierStore manages PKCE verifiers for OAuth flows.
 // Supports both in-memory and Redis storage via NB_IDP_CACHE_REDIS_ADDRESS env var.
 type PKCEVerifierStore struct {
-	cache *cache.Cache[string]
+	cache nbcache.Store
 	ctx   context.Context
 }
 
 // NewPKCEVerifierStore creates a PKCE verifier store using the provided shared cache store.
-func NewPKCEVerifierStore(ctx context.Context, cacheStore store.StoreInterface) *PKCEVerifierStore {
+func NewPKCEVerifierStore(ctx context.Context, cacheStore nbcache.Store) *PKCEVerifierStore {
 	return &PKCEVerifierStore{
-		cache: cache.New[string](cacheStore),
+		cache: cacheStore,
 		ctx:   ctx,
 	}
 }
@@ -40,14 +41,14 @@ func (s *PKCEVerifierStore) Store(state, verifier string, ttl time.Duration) err
 // Returns the verifier and true if found, or empty string and false if not found.
 // This enforces single-use semantics for PKCE verifiers.
 func (s *PKCEVerifierStore) LoadAndDelete(state string) (string, bool) {
-	verifier, err := s.cache.Get(s.ctx, state)
+	verifier, found, err := s.cache.GetDel(s.ctx, state)
 	if err != nil {
-		log.Debugf("PKCE verifier not found for state")
+		log.Warnf("Failed to consume PKCE verifier: %v", err)
 		return "", false
 	}
-
-	if err := s.cache.Delete(s.ctx, state); err != nil {
-		log.Warnf("Failed to delete PKCE verifier for state: %v", err)
+	if !found {
+		log.Debug("PKCE verifier not found for state")
+		return "", false
 	}
 
 	return verifier, true

management/internals/shared/grpc/pkce_verifier_test.go

@@ -0,0 +1,85 @@
+package grpc
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+func TestPKCEVerifierStoreLoadAndDelete(t *testing.T) {
+	const (
+		state    = "state"
+		verifier = "verifier"
+		attempts = 64
+	)
+
+	t.Run("exactly one concurrent caller consumes the verifier", func(t *testing.T) {
+		store := NewPKCEVerifierStore(context.Background(), testCacheStore(t))
+		if err := store.Store(state, verifier, time.Minute); err != nil {
+			t.Fatalf("couldn't store PKCE verifier: %s", err)
+		}
+
+		start := make(chan struct{})
+		type result struct {
+			verifier string
+			found    bool
+		}
+		results := make(chan result, attempts)
+		for range attempts {
+			go func() {
+				<-start
+				verifier, found := store.LoadAndDelete(state)
+				results <- result{verifier: verifier, found: found}
+			}()
+		}
+		close(start)
+
+		winners := 0
+		for range attempts {
+			result := <-results
+			if result.found {
+				winners++
+				if result.verifier != verifier {
+					t.Fatalf("unexpected verifier: got %q, expected %q", result.verifier, verifier)
+				}
+			}
+		}
+		if winners != 1 {
+			t.Fatalf("expected exactly one PKCE verifier consumer, got %d", winners)
+		}
+	})
+
+	t.Run("replayed state is rejected", func(t *testing.T) {
+		store := NewPKCEVerifierStore(context.Background(), testCacheStore(t))
+		if err := store.Store(state, verifier, time.Minute); err != nil {
+			t.Fatalf("couldn't store PKCE verifier: %s", err)
+		}
+
+		if got, found := store.LoadAndDelete(state); !found || got != verifier {
+			t.Fatalf("first load should return the verifier, got %q, found %t", got, found)
+		}
+		if got, found := store.LoadAndDelete(state); found {
+			t.Fatalf("replayed state should not resolve, got %q", got)
+		}
+	})
+
+	t.Run("unknown state is rejected", func(t *testing.T) {
+		store := NewPKCEVerifierStore(context.Background(), testCacheStore(t))
+
+		if got, found := store.LoadAndDelete("never-stored"); found {
+			t.Fatalf("unknown state should not resolve, got %q", got)
+		}
+	})
+
+	t.Run("expired verifier is rejected", func(t *testing.T) {
+		store := NewPKCEVerifierStore(context.Background(), testCacheStore(t))
+		if err := store.Store(state, verifier, 50*time.Millisecond); err != nil {
+			t.Fatalf("couldn't store PKCE verifier: %s", err)
+		}
+
+		time.Sleep(100 * time.Millisecond)
+		if got, found := store.LoadAndDelete(state); found {
+			t.Fatalf("expired verifier should not resolve, got %q", got)
+		}
+	})
+}

management/internals/shared/grpc/proxy_test.go

@@ -9,7 +9,6 @@ import (
 	"testing"
 	"time"
 
-	cachestore "github.com/eko/gocache/lib/v4/store"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"google.golang.org/grpc/codes"
@@ -21,7 +20,7 @@ import (
 	"github.com/netbirdio/netbird/shared/management/proto"
 )
 
-func testCacheStore(t *testing.T) cachestore.StoreInterface {
+func testCacheStore(t *testing.T) nbcache.Store {
 	t.Helper()
 	s, err := nbcache.NewStore(context.Background(), 30*time.Minute, 10*time.Minute, 100)
 	require.NoError(t, err)

management/server/auth/session.go

@@ -7,9 +7,6 @@ import (
 	"errors"
 	"fmt"
 	"time"
-
-	"github.com/eko/gocache/lib/v4/cache"
-	"github.com/eko/gocache/lib/v4/store"
 )
 
 const (
@@ -22,12 +19,17 @@ var (
 	ErrTokenExpired     = errors.New("JWT expired")
 )
 
-type SessionStore struct {
-	cache *cache.Cache[string]
+// TokenCache atomically records used JWTs until their expiration.
+type TokenCache interface {
+	SetNX(ctx context.Context, key, value string, ttl time.Duration) (bool, error)
 }
 
-func NewSessionStore(cacheStore store.StoreInterface) *SessionStore {
-	return &SessionStore{cache: cache.New[string](cacheStore)}
+type SessionStore struct {
+	cache TokenCache
+}
+
+func NewSessionStore(cacheStore TokenCache) *SessionStore {
+	return &SessionStore{cache: cacheStore}
 }
 
 // RegisterToken records a JWT until its exp time and rejects reuse.
@@ -38,19 +40,13 @@ func (s *SessionStore) RegisterToken(ctx context.Context, token string, expiresA
 	}
 
 	key := usedTokenKeyPrefix + hashToken(token)
-	_, err := s.cache.Get(ctx, key)
-	if err == nil {
-		return ErrTokenAlreadyUsed
-	}
-
-	var notFound *store.NotFound
-	if !errors.As(err, &notFound) {
-		return fmt.Errorf("failed to lookup used token entry: %w", err)
-	}
-
-	if err := s.cache.Set(ctx, key, usedTokenMarker, store.WithExpiration(ttl)); err != nil {
+	created, err := s.cache.SetNX(ctx, key, usedTokenMarker, ttl)
+	if err != nil {
 		return fmt.Errorf("failed to store used token entry: %w", err)
 	}
+	if !created {
+		return ErrTokenAlreadyUsed
+	}
 
 	return nil
 }

management/server/auth/session_test.go

@@ -2,6 +2,7 @@ package auth
 
 import (
 	"context"
+	"errors"
 	"testing"
 	"time"
 
@@ -38,6 +39,39 @@ func TestSessionStore_RegisterSameTokenTwiceIsRejected(t *testing.T) {
 	assert.ErrorIs(t, err, ErrTokenAlreadyUsed)
 }
 
+func TestSessionStore_ConcurrentRegistrationAllowsOneCaller(t *testing.T) {
+	s := newTestSessionStore(t)
+	ctx := context.Background()
+	const attempts = 100
+
+	start := make(chan struct{})
+	results := make(chan error, attempts)
+	for range attempts {
+		go func() {
+			<-start
+			results <- s.RegisterToken(ctx, "token", time.Now().Add(time.Hour))
+		}()
+	}
+	close(start)
+
+	succeeded := 0
+	alreadyUsed := 0
+	for range attempts {
+		err := <-results
+		switch {
+		case err == nil:
+			succeeded++
+		case errors.Is(err, ErrTokenAlreadyUsed):
+			alreadyUsed++
+		default:
+			require.NoError(t, err)
+		}
+	}
+
+	assert.Equal(t, 1, succeeded)
+	assert.Equal(t, attempts-1, alreadyUsed)
+}
+
 func TestSessionStore_RegisterDifferentTokensAreIndependent(t *testing.T) {
 	s := newTestSessionStore(t)
 	ctx := context.Background()
@@ -72,6 +106,23 @@ func TestSessionStore_EntryEvictsAtTTLAndAllowsReRegistration(t *testing.T) {
 	require.NoError(t, s.RegisterToken(ctx, token, time.Now().Add(time.Hour)))
 }
 
+type failingTokenCache struct {
+	err error
+}
+
+func (f failingTokenCache) SetNX(context.Context, string, string, time.Duration) (bool, error) {
+	return false, f.err
+}
+
+func TestSessionStore_CacheErrorIsReturned(t *testing.T) {
+	cacheErr := errors.New("cache unavailable")
+	s := NewSessionStore(failingTokenCache{err: cacheErr})
+
+	err := s.RegisterToken(context.Background(), "token", time.Now().Add(time.Hour))
+	require.Error(t, err)
+	assert.ErrorIs(t, err, cacheErr)
+}
+
 func TestHashToken_StableAndDoesNotLeak(t *testing.T) {
 	a := hashToken("tokenA")
 	b := hashToken("tokenB")

management/server/cache/memory.go

@@ -0,0 +1,51 @@
+package cache
+
+import (
+	"context"
+	"fmt"
+	"sync"
+	"time"
+
+	"github.com/eko/gocache/lib/v4/store"
+	gocachestore "github.com/eko/gocache/store/go_cache/v4"
+	gocache "github.com/patrickmn/go-cache"
+)
+
+type goCacheStore struct {
+	store.StoreInterface
+	client *gocache.Cache
+	mu     sync.Mutex
+}
+
+func newMemoryStore(maxTimeout, cleanupInterval time.Duration) Store {
+	client := gocache.New(maxTimeout, cleanupInterval)
+	return &goCacheStore{
+		StoreInterface: gocachestore.NewGoCache(client),
+		client:         client,
+	}
+}
+
+func (s *goCacheStore) SetNX(_ context.Context, key, value string, ttl time.Duration) (bool, error) {
+	// Add only returns an error when a non-expired entry already exists.
+	if err := s.client.Add(key, value, ttl); err != nil {
+		return false, nil //nolint:nilerr
+	}
+	return true, nil
+}
+
+func (s *goCacheStore) GetDel(_ context.Context, key string) (string, bool, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	value, found := s.client.Get(key)
+	if !found {
+		return "", false, nil
+	}
+	s.client.Delete(key)
+
+	str, ok := value.(string)
+	if !ok {
+		return "", false, fmt.Errorf("cached value is %T, not a string", value)
+	}
+	return str, true, nil
+}

management/server/cache/memory_test.go

@@ -0,0 +1,90 @@
+package cache_test
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/netbirdio/netbird/management/server/cache"
+)
+
+func TestMemoryStore(t *testing.T) {
+	memStore, err := cache.NewStore(context.Background(), 100*time.Millisecond, 300*time.Millisecond, 100)
+	if err != nil {
+		t.Fatalf("couldn't create memory store: %s", err)
+	}
+	ctx := context.Background()
+	key, value := "testing", "tested"
+	err = memStore.Set(ctx, key, value)
+	if err != nil {
+		t.Errorf("couldn't set testing data: %s", err)
+	}
+	result, err := memStore.Get(ctx, key)
+	if err != nil {
+		t.Errorf("couldn't get testing data: %s", err)
+	}
+	if value != result.(string) {
+		t.Errorf("value returned doesn't match testing data, got %s, expected %s", result, value)
+	}
+	created, err := memStore.SetNX(ctx, "atomic", value, 100*time.Millisecond)
+	if err != nil {
+		t.Fatalf("couldn't atomically set testing data: %s", err)
+	}
+	if !created {
+		t.Fatal("first atomic set should create the entry")
+	}
+	created, err = memStore.SetNX(ctx, "atomic", value, 100*time.Millisecond)
+	if err != nil {
+		t.Fatalf("couldn't atomically check testing data: %s", err)
+	}
+	if created {
+		t.Fatal("second atomic set should not replace the entry")
+	}
+	// test expiration
+	time.Sleep(300 * time.Millisecond)
+	_, err = memStore.Get(ctx, key)
+	if err == nil {
+		t.Error("value should not be found")
+	}
+}
+
+func TestMemoryStoreGetDel(t *testing.T) {
+	ctx := context.Background()
+	newStore := func(t *testing.T) cache.Store {
+		t.Helper()
+		memStore, err := cache.NewStore(ctx, time.Minute, time.Minute, 100)
+		if err != nil {
+			t.Fatalf("couldn't create memory store: %s", err)
+		}
+		return memStore
+	}
+
+	const (
+		key   = "consume"
+		value = "verifier"
+	)
+
+	t.Run("exactly one concurrent caller consumes the key", func(t *testing.T) {
+		memStore := newStore(t)
+		if err := memStore.Set(ctx, key, value); err != nil {
+			t.Fatalf("couldn't set testing data: %s", err)
+		}
+
+		assertGetDelConsumedOnce(ctx, t, []cache.Store{memStore}, key, value)
+		assertGetDelMisses(ctx, t, memStore, key)
+	})
+
+	t.Run("missing key is not an error", func(t *testing.T) {
+		assertGetDelMisses(ctx, t, newStore(t), "never-set")
+	})
+
+	t.Run("expired key is not found", func(t *testing.T) {
+		memStore := newStore(t)
+		if _, err := memStore.SetNX(ctx, key, value, 50*time.Millisecond); err != nil {
+			t.Fatalf("couldn't set testing data: %s", err)
+		}
+
+		time.Sleep(100 * time.Millisecond)
+		assertGetDelMisses(ctx, t, memStore, key)
+	})
+}

management/server/cache/redis.go

@@ -0,0 +1,63 @@
+package cache
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"math"
+	"time"
+
+	"github.com/eko/gocache/lib/v4/store"
+	redisstore "github.com/eko/gocache/store/redis/v4"
+	"github.com/redis/go-redis/v9"
+	log "github.com/sirupsen/logrus"
+)
+
+type redisStore struct {
+	store.StoreInterface
+	client *redis.Client
+}
+
+func getRedisStore(ctx context.Context, redisEnvAddr string, maxConn int) (Store, error) {
+	options, err := redis.ParseURL(redisEnvAddr)
+	if err != nil {
+		return nil, fmt.Errorf("parsing redis cache url: %s", err)
+	}
+
+	options.MaxIdleConns = int(math.Ceil(float64(maxConn) * 0.5)) // 50% of max conns
+	options.MinIdleConns = int(math.Ceil(float64(maxConn) * 0.1)) // 10% of max conns
+	options.MaxActiveConns = maxConn
+	options.ConnMaxIdleTime = 30 * time.Minute
+	options.ConnMaxLifetime = 0
+	options.PoolTimeout = 10 * time.Second
+	redisClient := redis.NewClient(options)
+	subCtx, cancel := context.WithTimeout(ctx, 2*time.Second)
+	defer cancel()
+
+	_, err = redisClient.Ping(subCtx).Result()
+	if err != nil {
+		return nil, err
+	}
+
+	log.WithContext(subCtx).Infof("using redis cache at %s", redisEnvAddr)
+
+	return &redisStore{
+		StoreInterface: redisstore.NewRedis(redisClient),
+		client:         redisClient,
+	}, nil
+}
+
+func (s *redisStore) SetNX(ctx context.Context, key, value string, ttl time.Duration) (bool, error) {
+	return s.client.SetNX(ctx, key, value, ttl).Result()
+}
+
+func (s *redisStore) GetDel(ctx context.Context, key string) (string, bool, error) {
+	value, err := s.client.GetDel(ctx, key).Result()
+	if errors.Is(err, redis.Nil) {
+		return "", false, nil
+	}
+	if err != nil {
+		return "", false, err
+	}
+	return value, true, nil
+}

management/server/cache/redis_test.go

@@ -0,0 +1,178 @@
+package cache_test
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/eko/gocache/lib/v4/store"
+	"github.com/redis/go-redis/v9"
+	"github.com/stretchr/testify/require"
+	testcontainersredis "github.com/testcontainers/testcontainers-go/modules/redis"
+
+	"github.com/netbirdio/netbird/management/server/cache"
+)
+
+func startRedis(t *testing.T) string {
+	t.Helper()
+
+	ctx := context.Background()
+	redisContainer, err := testcontainersredis.Run(ctx, "redis:7")
+	require.NoError(t, err, "couldn't start redis container")
+
+	t.Cleanup(func() {
+		if err := redisContainer.Terminate(ctx); err != nil {
+			t.Logf("failed to terminate container: %s", err)
+		}
+	})
+
+	redisURL, err := redisContainer.ConnectionString(ctx)
+	require.NoError(t, err, "couldn't get connection string")
+
+	t.Setenv(cache.RedisStoreEnvVar, redisURL)
+	return redisURL
+}
+
+func newRedisStore(t *testing.T) cache.Store {
+	t.Helper()
+
+	redisStore, err := cache.NewStore(context.Background(), 100*time.Millisecond, 300*time.Millisecond, 100)
+	require.NoError(t, err)
+
+	return redisStore
+}
+
+func TestRedisStoreConnectionFailure(t *testing.T) {
+	t.Setenv(cache.RedisStoreEnvVar, "redis://127.0.0.1:6379")
+	_, err := cache.NewStore(context.Background(), 10*time.Millisecond, 30*time.Millisecond, 100)
+	if err == nil {
+		t.Fatal("getting redis cache store should return error")
+	}
+}
+
+func TestRedisStoreConnectionSuccess(t *testing.T) {
+	ctx := context.Background()
+	redisURL := startRedis(t)
+	redisStore := newRedisStore(t)
+
+	key, value := "testing", "tested"
+	err := redisStore.Set(ctx, key, value, store.WithExpiration(100*time.Millisecond))
+	if err != nil {
+		t.Errorf("couldn't set testing data: %s", err)
+	}
+	result, err := redisStore.Get(ctx, key)
+	if err != nil {
+		t.Errorf("couldn't get testing data: %s", err)
+	}
+	if value != result.(string) {
+		t.Errorf("value returned doesn't match testing data, got %s, expected %s", result, value)
+	}
+
+	options, err := redis.ParseURL(redisURL)
+	if err != nil {
+		t.Errorf("parsing redis cache url: %s", err)
+	}
+
+	redisClient := redis.NewClient(options)
+	r, e := redisClient.Get(ctx, key).Result()
+	if e != nil {
+		t.Errorf("couldn't get testing data from redis: %s", e)
+	}
+	if value != r {
+		t.Errorf("value returned from redis doesn't match testing data, got %s, expected %s", r, value)
+	}
+
+	// test expiration
+	time.Sleep(300 * time.Millisecond)
+	_, err = redisStore.Get(ctx, key)
+	if err == nil {
+		t.Error("value should not be found")
+	}
+}
+
+func TestRedisStoreSetNX(t *testing.T) {
+	ctx := context.Background()
+	redisURL := startRedis(t)
+	redisStore, secondRedisStore := newRedisStore(t), newRedisStore(t)
+
+	const (
+		key   = "atomic"
+		value = "tested"
+	)
+
+	start := make(chan struct{})
+	type setResult struct {
+		created bool
+		err     error
+	}
+	results := make(chan setResult, 2)
+	for _, cacheStore := range []cache.Store{redisStore, secondRedisStore} {
+		go func() {
+			<-start
+			created, err := cacheStore.SetNX(ctx, key, value, time.Minute)
+			results <- setResult{created: created, err: err}
+		}()
+	}
+	close(start)
+
+	created := 0
+	for range 2 {
+		result := <-results
+		if result.err != nil {
+			t.Fatalf("atomic redis set failed: %s", result.err)
+		}
+		if result.created {
+			created++
+		}
+	}
+	if created != 1 {
+		t.Fatalf("expected exactly one redis client to create the entry, got %d", created)
+	}
+
+	options, err := redis.ParseURL(redisURL)
+	if err != nil {
+		t.Fatalf("parsing redis cache url: %s", err)
+	}
+	ttl, err := redis.NewClient(options).PTTL(ctx, key).Result()
+	if err != nil {
+		t.Fatalf("couldn't read atomic entry TTL: %s", err)
+	}
+	if ttl <= 0 {
+		t.Fatalf("atomic entry should have a positive TTL, got %s", ttl)
+	}
+}
+
+func TestRedisStoreGetDel(t *testing.T) {
+	ctx := context.Background()
+	startRedis(t)
+	redisStore, secondRedisStore := newRedisStore(t), newRedisStore(t)
+
+	const (
+		key   = "consume"
+		value = "verifier"
+	)
+
+	t.Run("exactly one caller across independent clients consumes the key", func(t *testing.T) {
+		// A generous TTL: the key is consumed explicitly, so expiry racing the
+		// concurrent callers would only make the test flaky on a loaded runner.
+		if err := redisStore.Set(ctx, key, value, store.WithExpiration(time.Minute)); err != nil {
+			t.Fatalf("couldn't set value to consume: %s", err)
+		}
+
+		assertGetDelConsumedOnce(ctx, t, []cache.Store{redisStore, secondRedisStore}, key, value)
+		assertGetDelMisses(ctx, t, secondRedisStore, key)
+	})
+
+	t.Run("missing key is not an error", func(t *testing.T) {
+		assertGetDelMisses(ctx, t, redisStore, "never-set")
+	})
+
+	t.Run("expired key is not found", func(t *testing.T) {
+		if err := redisStore.Set(ctx, key, value, store.WithExpiration(50*time.Millisecond)); err != nil {
+			t.Fatalf("couldn't set value to consume: %s", err)
+		}
+
+		time.Sleep(100 * time.Millisecond)
+		assertGetDelMisses(ctx, t, redisStore, key)
+	})
+}

management/server/cache/store.go

@@ -2,17 +2,10 @@ package cache
 
 import (
 	"context"
-	"fmt"
-	"math"
 	"os"
 	"time"
 
 	"github.com/eko/gocache/lib/v4/store"
-	gocache_store "github.com/eko/gocache/store/go_cache/v4"
-	redis_store "github.com/eko/gocache/store/redis/v4"
-	gocache "github.com/patrickmn/go-cache"
-	"github.com/redis/go-redis/v9"
-	log "github.com/sirupsen/logrus"
 )
 
 // RedisStoreEnvVar is the environment variable that determines if a redis store should be used.
@@ -31,15 +24,23 @@ const (
 	DefaultStoreMaxConn = 1000
 )
 
+// Store extends the shared cache interface with conditional and consuming operations.
+type Store interface {
+	store.StoreInterface
+	// SetNX stores a value with a TTL only when the key does not exist.
+	SetNX(ctx context.Context, key, value string, ttl time.Duration) (bool, error)
+	// GetDel reads a value and removes it, so only one caller can consume a key.
+	GetDel(ctx context.Context, key string) (value string, found bool, err error)
+}
+
 // NewStore creates a new cache store with the given max timeout and cleanup interval. It checks for the environment Variable RedisStoreEnvVar
 // to determine if a redis store should be used. If the environment variable is set, it will attempt to connect to the redis store.
-func NewStore(ctx context.Context, maxTimeout, cleanupInterval time.Duration, maxConn int) (store.StoreInterface, error) {
+func NewStore(ctx context.Context, maxTimeout, cleanupInterval time.Duration, maxConn int) (Store, error) {
 	redisAddr := GetAddrFromEnv()
 	if redisAddr != "" {
 		return getRedisStore(ctx, redisAddr, maxConn)
 	}
-	goc := gocache.New(maxTimeout, cleanupInterval)
-	return gocache_store.NewGoCache(goc), nil
+	return newMemoryStore(maxTimeout, cleanupInterval), nil
 }
 
 // GetAddrFromEnv returns the redis address from the environment variable RedisStoreEnvVar or its legacy counterpart.
@@ -50,29 +51,3 @@ func GetAddrFromEnv() string {
 	}
 	return addr
 }
-
-func getRedisStore(ctx context.Context, redisEnvAddr string, maxConn int) (store.StoreInterface, error) {
-	options, err := redis.ParseURL(redisEnvAddr)
-	if err != nil {
-		return nil, fmt.Errorf("parsing redis cache url: %s", err)
-	}
-
-	options.MaxIdleConns = int(math.Ceil(float64(maxConn) * 0.5)) // 50% of max conns
-	options.MinIdleConns = int(math.Ceil(float64(maxConn) * 0.1)) // 10% of max conns
-	options.MaxActiveConns = maxConn
-	options.ConnMaxIdleTime = 30 * time.Minute
-	options.ConnMaxLifetime = 0
-	options.PoolTimeout = 10 * time.Second
-	redisClient := redis.NewClient(options)
-	subCtx, cancel := context.WithTimeout(ctx, 2*time.Second)
-	defer cancel()
-
-	_, err = redisClient.Ping(subCtx).Result()
-	if err != nil {
-		return nil, err
-	}
-
-	log.WithContext(subCtx).Infof("using redis cache at %s", redisEnvAddr)
-
-	return redis_store.NewRedis(redisClient), nil
-}

management/server/cache/store_test.go

@@ -3,101 +3,53 @@ package cache_test
 import (
 	"context"
 	"testing"
-	"time"
 
-	"github.com/eko/gocache/lib/v4/store"
-	"github.com/redis/go-redis/v9"
-	testcontainersredis "github.com/testcontainers/testcontainers-go/modules/redis"
+	"github.com/stretchr/testify/require"
 
 	"github.com/netbirdio/netbird/management/server/cache"
 )
 
-func TestMemoryStore(t *testing.T) {
-	memStore, err := cache.NewStore(context.Background(), 100*time.Millisecond, 300*time.Millisecond, 100)
-	if err != nil {
-		t.Fatalf("couldn't create memory store: %s", err)
-	}
-	ctx := context.Background()
-	key, value := "testing", "tested"
-	err = memStore.Set(ctx, key, value)
-	if err != nil {
-		t.Errorf("couldn't set testing data: %s", err)
-	}
-	result, err := memStore.Get(ctx, key)
-	if err != nil {
-		t.Errorf("couldn't get testing data: %s", err)
-	}
-	if value != result.(string) {
-		t.Errorf("value returned doesn't match testing data, got %s, expected %s", result, value)
-	}
-	// test expiration
-	time.Sleep(300 * time.Millisecond)
-	_, err = memStore.Get(ctx, key)
-	if err == nil {
-		t.Error("value should not be found")
-	}
-}
+func assertGetDelConsumedOnce(ctx context.Context, t *testing.T, stores []cache.Store, key, value string) {
+	t.Helper()
 
-func TestRedisStoreConnectionFailure(t *testing.T) {
-	t.Setenv(cache.RedisStoreEnvVar, "redis://127.0.0.1:6379")
-	_, err := cache.NewStore(context.Background(), 10*time.Millisecond, 30*time.Millisecond, 100)
-	if err == nil {
-		t.Fatal("getting redis cache store should return error")
-	}
-}
+	const getDelAttempts = 64
 
-func TestRedisStoreConnectionSuccess(t *testing.T) {
-	ctx := context.Background()
-	redisContainer, err := testcontainersredis.Run(ctx, "redis:7")
-	if err != nil {
-		t.Fatalf("couldn't start redis container: %s", err)
+	type getDelResult struct {
+		value string
+		found bool
+		err   error
 	}
-	defer func() {
-		if err := redisContainer.Terminate(ctx); err != nil {
-			t.Logf("failed to terminate container: %s", err)
+
+	start := make(chan struct{})
+	results := make(chan getDelResult, getDelAttempts)
+	for i := range getDelAttempts {
+		cacheStore := stores[i%len(stores)]
+		go func() {
+			<-start
+			value, found, err := cacheStore.GetDel(ctx, key)
+			results <- getDelResult{value: value, found: found, err: err}
+		}()
+	}
+	close(start)
+
+	consumers := 0
+	for range getDelAttempts {
+		result := <-results
+		require.NoError(t, result.err, "concurrent GetDel failed")
+		if !result.found {
+			continue
 		}
-	}()
-	redisURL, err := redisContainer.ConnectionString(ctx)
-	if err != nil {
-		t.Fatalf("couldn't get connection string: %s", err)
-	}
-
-	t.Setenv(cache.RedisStoreEnvVar, redisURL)
-	redisStore, err := cache.NewStore(context.Background(), 100*time.Millisecond, 300*time.Millisecond, 100)
-	if err != nil {
-		t.Fatalf("couldn't create redis store: %s", err)
-	}
-
-	key, value := "testing", "tested"
-	err = redisStore.Set(ctx, key, value, store.WithExpiration(100*time.Millisecond))
-	if err != nil {
-		t.Errorf("couldn't set testing data: %s", err)
-	}
-	result, err := redisStore.Get(ctx, key)
-	if err != nil {
-		t.Errorf("couldn't get testing data: %s", err)
-	}
-	if value != result.(string) {
-		t.Errorf("value returned doesn't match testing data, got %s, expected %s", result, value)
-	}
-
-	options, err := redis.ParseURL(redisURL)
-	if err != nil {
-		t.Errorf("parsing redis cache url: %s", err)
-	}
-
-	redisClient := redis.NewClient(options)
-	r, e := redisClient.Get(ctx, key).Result()
-	if e != nil {
-		t.Errorf("couldn't get testing data from redis: %s", e)
-	}
-	if value != r {
-		t.Errorf("value returned from redis doesn't match testing data, got %s, expected %s", r, value)
-	}
-	// test expiration
-	time.Sleep(300 * time.Millisecond)
-	_, err = redisStore.Get(ctx, key)
-	if err == nil {
-		t.Error("value should not be found")
+		consumers++
+		require.Equal(t, value, result.value, "consumed value doesn't match testing data")
 	}
+	require.Equal(t, 1, consumers, "expected exactly one consumer")
+}
+
+func assertGetDelMisses(ctx context.Context, t *testing.T, cacheStore cache.Store, key string) {
+	t.Helper()
+
+	value, found, err := cacheStore.GetDel(ctx, key)
+	require.NoError(t, err, "GetDel on a missing key should not error")
+	require.False(t, found, "GetDel should not find key %q, got value %q", key, value)
+	require.Empty(t, value, "GetDel should return an empty value when not found")
 }