Merge branch 'nat-pmp-upnp' into pcp-support

# Conflicts:
#	client/internal/portforward/manager.go

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,14 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Community Support
+    url: https://forum.netbird.io/
+    about: Community support forum
+  - name: Cloud Support
+    url: https://docs.netbird.io/help/report-bug-issues
+    about: Contact us for support
+  - name: Client/Connection Troubleshooting
+    url: https://docs.netbird.io/help/troubleshooting-client
+    about: See our client troubleshooting guide for help addressing common issues
+  - name: Self-host Troubleshooting
+    url: https://docs.netbird.io/selfhosted/troubleshooting
+    about: See our self-host troubleshooting guide for help addressing common issues

.github/workflows/golangci-lint.yml

@@ -19,7 +19,7 @@ jobs:
       - name: codespell
         uses: codespell-project/actions-codespell@v2
         with:
-          ignore_words_list: erro,clienta,hastable,iif,groupd,testin,groupe,cros,ans,deriver
+          ignore_words_list: erro,clienta,hastable,iif,groupd,testin,groupe,cros,ans,deriver,te
           skip: go.mod,go.sum,**/proxy/web/**
   golangci:
     strategy:

.github/workflows/pr-title-check.yml

@@ -0,0 +1,51 @@
+name: PR Title Check
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+jobs:
+  check-title:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate PR title prefix
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const title = context.payload.pull_request.title;
+            const allowedTags = [
+              'management',
+              'client',
+              'signal',
+              'proxy',
+              'relay',
+              'misc',
+              'infrastructure',
+              'self-hosted',
+              'doc',
+            ];
+
+            const pattern = /^\[([^\]]+)\]\s+.+/;
+            const match = title.match(pattern);
+
+            if (!match) {
+              core.setFailed(
+                `PR title must start with a tag in brackets.\n` +
+                `Example: [client] fix something\n` +
+                `Allowed tags: ${allowedTags.join(', ')}`
+              );
+              return;
+            }
+
+            const tags = match[1].split(',').map(t => t.trim().toLowerCase());
+
+            const invalid = tags.filter(t => !allowedTags.includes(t));
+            if (invalid.length > 0) {
+              core.setFailed(
+                `Invalid tag(s): ${invalid.join(', ')}\n` +
+                `Allowed tags: ${allowedTags.join(', ')}`
+              );
+              return;
+            }
+
+            console.log(`Valid PR title tags: [${tags.join(', ')}]`);

.github/workflows/release.yml

@@ -10,7 +10,7 @@ on:
 
 env:
   SIGN_PIPE_VER: "v0.1.1"
-  GORELEASER_VER: "v2.3.2"
+  GORELEASER_VER: "v2.14.3"
   PRODUCT_NAME: "NetBird"
   COPYRIGHT: "NetBird GmbH"
 
@@ -169,6 +169,13 @@ jobs:
       - name: Install OS build dependencies
         run: sudo apt update && sudo apt install -y -q gcc-arm-linux-gnueabihf gcc-aarch64-linux-gnu
 
+      - name: Decode GPG signing key
+        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 goversioninfo
         run: go install github.com/josephspurrier/goversioninfo/cmd/goversioninfo@233067e
       - name: Generate windows syso amd64
@@ -186,18 +193,54 @@ jobs:
           HOMEBREW_TAP_GITHUB_TOKEN: ${{ secrets.HOMEBREW_TAP_GITHUB_TOKEN }}
           UPLOAD_DEBIAN_SECRET: ${{ secrets.PKG_UPLOAD_SECRET }}
           UPLOAD_YUM_SECRET: ${{ secrets.PKG_UPLOAD_SECRET }}
-      - name: Tag and push PR images (amd64 only)
-        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
+          GPG_RPM_KEY_FILE: ${{ env.GPG_RPM_KEY_FILE }}
+          NFPM_NETBIRD_RPM_PASSPHRASE: ${{ secrets.GPG_RPM_PASSPHRASE }}
+      - name: Verify RPM signatures
         run: |
-          PR_TAG="pr-${{ github.event.pull_request.number }}"
+          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/*amd64*.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: Tag and push images (amd64 only)
+        if: |
+          (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository) ||
+          (github.event_name == 'push' && github.ref == 'refs/heads/main')
+        run: |
+          resolve_tags() {
+            if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+              echo "pr-${{ github.event.pull_request.number }}"
+            else
+              echo "main sha-$(git rev-parse --short HEAD)"
+            fi
+          }
+
+          tag_and_push() {
+            local src="$1" img_name tag dst
+            img_name="${src%%:*}"
+            for tag in $(resolve_tags); do
+              dst="${img_name}:${tag}"
+              echo "Tagging ${src} -> ${dst}"
+              docker tag "$src" "$dst"
+              docker push "$dst"
+            done
+          }
+
+          export -f tag_and_push resolve_tags
+
           echo '${{ steps.goreleaser.outputs.artifacts }}' | \
             jq -r '.[] | select(.type == "Docker Image") | select(.goarch == "amd64") | .name' | \
             grep '^ghcr.io/' | while read -r SRC; do
-              IMG_NAME="${SRC%%:*}"
-              DST="${IMG_NAME}:${PR_TAG}"
-              echo "Tagging ${SRC} -> ${DST}"
-              docker tag "$SRC" "$DST"
-              docker push "$DST"
+              tag_and_push "$SRC"
             done
       - name: upload non tags for debug purposes
         uses: actions/upload-artifact@v4
@@ -265,6 +308,13 @@ jobs:
       - name: Install dependencies
         run: sudo apt update && sudo apt install -y -q libappindicator3-dev gir1.2-appindicator3-0.1 libxxf86vm-dev gcc-mingw-w64-x86-64
 
+      - name: Decode GPG signing key
+        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 LLVM-MinGW for ARM64 cross-compilation
         run: |
           cd /tmp
@@ -289,6 +339,24 @@ jobs:
           HOMEBREW_TAP_GITHUB_TOKEN: ${{ secrets.HOMEBREW_TAP_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_PASSPHRASE: ${{ secrets.GPG_RPM_PASSPHRASE }}
+      - 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
         uses: actions/upload-artifact@v4
         with:

.goreleaser.yaml

@@ -171,13 +171,12 @@ nfpms:
   - maintainer: Netbird <dev@netbird.io>
     description: Netbird client.
     homepage: https://netbird.io/
-    id: netbird-deb
+    id: netbird_deb
     bindir: /usr/bin
     builds:
       - netbird
     formats:
       - deb
-
     scripts:
       postinstall: "release_files/post_install.sh"
       preremove: "release_files/pre_remove.sh"
@@ -185,16 +184,18 @@ nfpms:
   - maintainer: Netbird <dev@netbird.io>
     description: Netbird client.
     homepage: https://netbird.io/
-    id: netbird-rpm
+    id: netbird_rpm
     bindir: /usr/bin
     builds:
       - netbird
     formats:
       - rpm
-
     scripts:
       postinstall: "release_files/post_install.sh"
       preremove: "release_files/pre_remove.sh"
+    rpm:
+      signature:
+        key_file: '{{ if index .Env "GPG_RPM_KEY_FILE" }}{{ .Env.GPG_RPM_KEY_FILE }}{{ end }}'
 dockers:
   - image_templates:
       - netbirdio/netbird:{{ .Version }}-amd64
@@ -876,7 +877,7 @@ brews:
 uploads:
   - name: debian
     ids:
-      - netbird-deb
+      - netbird_deb
     mode: archive
     target: https://pkgs.wiretrustee.com/debian/pool/{{ .ArtifactName }};deb.distribution=stable;deb.component=main;deb.architecture={{ if .Arm }}armhf{{ else }}{{ .Arch }}{{ end }};deb.package=
     username: dev@wiretrustee.com
@@ -884,7 +885,7 @@ uploads:
 
   - name: yum
     ids:
-      - netbird-rpm
+      - netbird_rpm
     mode: archive
     target: https://pkgs.wiretrustee.com/yum/{{ .Arch }}{{ if .Arm }}{{ .Arm }}{{ end }}
     username: dev@wiretrustee.com

.goreleaser_ui.yaml

@@ -61,7 +61,7 @@ nfpms:
   - maintainer: Netbird <dev@netbird.io>
     description: Netbird client UI.
     homepage: https://netbird.io/
-    id: netbird-ui-deb
+    id: netbird_ui_deb
     package_name: netbird-ui
     builds:
       - netbird-ui
@@ -80,7 +80,7 @@ nfpms:
   - maintainer: Netbird <dev@netbird.io>
     description: Netbird client UI.
     homepage: https://netbird.io/
-    id: netbird-ui-rpm
+    id: netbird_ui_rpm
     package_name: netbird-ui
     builds:
       - netbird-ui
@@ -95,11 +95,14 @@ nfpms:
         dst: /usr/share/pixmaps/netbird.png
     dependencies:
       - netbird
+    rpm:
+      signature:
+        key_file: '{{ if index .Env "GPG_RPM_KEY_FILE" }}{{ .Env.GPG_RPM_KEY_FILE }}{{ end }}'
 
 uploads:
   - name: debian
     ids:
-      - netbird-ui-deb
+      - netbird_ui_deb
     mode: archive
     target: https://pkgs.wiretrustee.com/debian/pool/{{ .ArtifactName }};deb.distribution=stable;deb.component=main;deb.architecture={{ if .Arm }}armhf{{ else }}{{ .Arch }}{{ end }};deb.package=
     username: dev@wiretrustee.com
@@ -107,7 +110,7 @@ uploads:
 
   - name: yum
     ids:
-      - netbird-ui-rpm
+      - netbird_ui_rpm
     mode: archive
     target: https://pkgs.wiretrustee.com/yum/{{ .Arch }}{{ if .Arm }}{{ .Arm }}{{ end }}
     username: dev@wiretrustee.com

README.md

@@ -126,6 +126,7 @@ See a complete [architecture overview](https://docs.netbird.io/about-netbird/how
 ### Community projects
 -  [NetBird installer script](https://github.com/physk/netbird-installer)
 -  [NetBird ansible collection by Dominion Solutions](https://galaxy.ansible.com/ui/repo/published/dominion_solutions/netbird/)
+-  [netbird-tui](https://github.com/n0pashkov/netbird-tui) — terminal UI for managing NetBird peers, routes, and settings
 
 **Note**: The `main` branch may be in an *unstable or even broken state* during development.
 For stable versions, see [releases](https://github.com/netbirdio/netbird/releases).

client/Dockerfile

@@ -4,7 +4,7 @@
 #   sudo podman build -t localhost/netbird:latest -f client/Dockerfile --ignorefile .dockerignore-client .
 #   sudo podman run --rm -it --cap-add={BPF,NET_ADMIN,NET_RAW} localhost/netbird:latest
 
-FROM alpine:3.23.2
+FROM alpine:3.23.3
 # iproute2: busybox doesn't display ip rules properly
 RUN apk add --no-cache \
     bash \

client/android/client.go

@@ -124,7 +124,7 @@ func (c *Client) Run(platformFiles PlatformFiles, urlOpener URLOpener, isAndroid
 
 	// todo do not throw error in case of cancelled context
 	ctx = internal.CtxInitState(ctx)
-	c.connectClient = internal.NewConnectClient(ctx, cfg, c.recorder, false)
+	c.connectClient = internal.NewConnectClient(ctx, cfg, c.recorder)
 	return c.connectClient.RunOnAndroid(c.tunAdapter, c.iFaceDiscover, c.networkChangeListener, slices.Clone(dns.items), dnsReadyListener, stateFile)
 }
 
@@ -157,7 +157,7 @@ func (c *Client) RunWithoutLogin(platformFiles PlatformFiles, dns *DNSList, dnsR
 
 	// todo do not throw error in case of cancelled context
 	ctx = internal.CtxInitState(ctx)
-	c.connectClient = internal.NewConnectClient(ctx, cfg, c.recorder, false)
+	c.connectClient = internal.NewConnectClient(ctx, cfg, c.recorder)
 	return c.connectClient.RunOnAndroid(c.tunAdapter, c.iFaceDiscover, c.networkChangeListener, slices.Clone(dns.items), dnsReadyListener, stateFile)
 }
 

client/cmd/expose.go

@@ -0,0 +1,280 @@
+package cmd
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"os/signal"
+	"regexp"
+	"strconv"
+	"strings"
+	"syscall"
+
+	log "github.com/sirupsen/logrus"
+	"github.com/spf13/cobra"
+
+	"github.com/netbirdio/netbird/client/proto"
+	"github.com/netbirdio/netbird/util"
+)
+
+var pinRegexp = regexp.MustCompile(`^\d{6}$`)
+
+var (
+	exposePin          string
+	exposePassword     string
+	exposeUserGroups   []string
+	exposeDomain       string
+	exposeNamePrefix   string
+	exposeProtocol     string
+	exposeExternalPort uint16
+)
+
+var exposeCmd = &cobra.Command{
+	Use:   "expose <port>",
+	Short: "Expose a local port via the NetBird reverse proxy",
+	Args:  cobra.ExactArgs(1),
+	Example: `  netbird expose --with-password safe-pass 8080
+  netbird expose --protocol tcp 5432
+  netbird expose --protocol tcp --with-external-port 5433 5432
+  netbird expose --protocol tls --with-custom-domain tls.example.com 4443`,
+	RunE: exposeFn,
+}
+
+func init() {
+	exposeCmd.Flags().StringVar(&exposePin, "with-pin", "", "Protect the exposed service with a 6-digit PIN (e.g. --with-pin 123456)")
+	exposeCmd.Flags().StringVar(&exposePassword, "with-password", "", "Protect the exposed service with a password (e.g. --with-password my-secret)")
+	exposeCmd.Flags().StringSliceVar(&exposeUserGroups, "with-user-groups", nil, "Restrict access to specific user groups with SSO (e.g. --with-user-groups devops,Backend)")
+	exposeCmd.Flags().StringVar(&exposeDomain, "with-custom-domain", "", "Custom domain for the exposed service, must be configured to your account (e.g. --with-custom-domain myapp.example.com)")
+	exposeCmd.Flags().StringVar(&exposeNamePrefix, "with-name-prefix", "", "Prefix for the generated service name (e.g. --with-name-prefix my-app)")
+	exposeCmd.Flags().StringVar(&exposeProtocol, "protocol", "http", "Protocol to use: http, https, tcp, udp, or tls (e.g. --protocol tcp)")
+	exposeCmd.Flags().Uint16Var(&exposeExternalPort, "with-external-port", 0, "Public-facing external port on the proxy cluster (defaults to the target port for L4)")
+}
+
+// isClusterProtocol returns true for L4/TLS protocols that reject HTTP-style auth flags.
+func isClusterProtocol(protocol string) bool {
+	switch strings.ToLower(protocol) {
+	case "tcp", "udp", "tls":
+		return true
+	default:
+		return false
+	}
+}
+
+// isPortBasedProtocol returns true for pure port-based protocols (TCP/UDP)
+// where domain display doesn't apply. TLS uses SNI so it has a domain.
+func isPortBasedProtocol(protocol string) bool {
+	switch strings.ToLower(protocol) {
+	case "tcp", "udp":
+		return true
+	default:
+		return false
+	}
+}
+
+// extractPort returns the port portion of a URL like "tcp://host:12345", or
+// falls back to the given default formatted as a string.
+func extractPort(serviceURL string, fallback uint16) string {
+	u := serviceURL
+	if idx := strings.Index(u, "://"); idx != -1 {
+		u = u[idx+3:]
+	}
+	if i := strings.LastIndex(u, ":"); i != -1 {
+		if p := u[i+1:]; p != "" {
+			return p
+		}
+	}
+	return strconv.FormatUint(uint64(fallback), 10)
+}
+
+// resolveExternalPort returns the effective external port, defaulting to the target port.
+func resolveExternalPort(targetPort uint64) uint16 {
+	if exposeExternalPort != 0 {
+		return exposeExternalPort
+	}
+	return uint16(targetPort)
+}
+
+func validateExposeFlags(cmd *cobra.Command, portStr string) (uint64, error) {
+	port, err := strconv.ParseUint(portStr, 10, 32)
+	if err != nil {
+		return 0, fmt.Errorf("invalid port number: %s", portStr)
+	}
+	if port == 0 || port > 65535 {
+		return 0, fmt.Errorf("invalid port number: must be between 1 and 65535")
+	}
+
+	if !isProtocolValid(exposeProtocol) {
+		return 0, fmt.Errorf("unsupported protocol %q: must be http, https, tcp, udp, or tls", exposeProtocol)
+	}
+
+	if isClusterProtocol(exposeProtocol) {
+		if exposePin != "" || exposePassword != "" || len(exposeUserGroups) > 0 {
+			return 0, fmt.Errorf("auth flags (--with-pin, --with-password, --with-user-groups) are not supported for %s protocol", exposeProtocol)
+		}
+	} else if cmd.Flags().Changed("with-external-port") {
+		return 0, fmt.Errorf("--with-external-port is not supported for %s protocol", exposeProtocol)
+	}
+
+	if exposePin != "" && !pinRegexp.MatchString(exposePin) {
+		return 0, fmt.Errorf("invalid pin: must be exactly 6 digits")
+	}
+
+	if cmd.Flags().Changed("with-password") && exposePassword == "" {
+		return 0, fmt.Errorf("password cannot be empty")
+	}
+
+	if cmd.Flags().Changed("with-user-groups") && len(exposeUserGroups) == 0 {
+		return 0, fmt.Errorf("user groups cannot be empty")
+	}
+
+	return port, nil
+}
+
+func isProtocolValid(exposeProtocol string) bool {
+	switch strings.ToLower(exposeProtocol) {
+	case "http", "https", "tcp", "udp", "tls":
+		return true
+	default:
+		return false
+	}
+}
+
+func exposeFn(cmd *cobra.Command, args []string) error {
+	SetFlagsFromEnvVars(rootCmd)
+
+	if err := util.InitLog(logLevel, util.LogConsole); err != nil {
+		log.Errorf("failed initializing log %v", err)
+		return err
+	}
+
+	cmd.Root().SilenceUsage = false
+
+	port, err := validateExposeFlags(cmd, args[0])
+	if err != nil {
+		return err
+	}
+
+	cmd.Root().SilenceUsage = true
+
+	ctx, cancel := context.WithCancel(cmd.Context())
+	defer cancel()
+
+	sigCh := make(chan os.Signal, 1)
+	signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
+	go func() {
+		<-sigCh
+		cancel()
+	}()
+
+	conn, err := DialClientGRPCServer(ctx, daemonAddr)
+	if err != nil {
+		return fmt.Errorf("connect to daemon: %w", err)
+	}
+	defer func() {
+		if err := conn.Close(); err != nil {
+			log.Debugf("failed to close daemon connection: %v", err)
+		}
+	}()
+
+	client := proto.NewDaemonServiceClient(conn)
+
+	protocol, err := toExposeProtocol(exposeProtocol)
+	if err != nil {
+		return err
+	}
+
+	req := &proto.ExposeServiceRequest{
+		Port:       uint32(port),
+		Protocol:   protocol,
+		Pin:        exposePin,
+		Password:   exposePassword,
+		UserGroups: exposeUserGroups,
+		Domain:     exposeDomain,
+		NamePrefix: exposeNamePrefix,
+	}
+	if isClusterProtocol(exposeProtocol) {
+		req.ListenPort = uint32(resolveExternalPort(port))
+	}
+
+	stream, err := client.ExposeService(ctx, req)
+	if err != nil {
+		return fmt.Errorf("expose service: %w", err)
+	}
+
+	if err := handleExposeReady(cmd, stream, port); err != nil {
+		return err
+	}
+
+	return waitForExposeEvents(cmd, ctx, stream)
+}
+
+func toExposeProtocol(exposeProtocol string) (proto.ExposeProtocol, error) {
+	switch strings.ToLower(exposeProtocol) {
+	case "http":
+		return proto.ExposeProtocol_EXPOSE_HTTP, nil
+	case "https":
+		return proto.ExposeProtocol_EXPOSE_HTTPS, nil
+	case "tcp":
+		return proto.ExposeProtocol_EXPOSE_TCP, nil
+	case "udp":
+		return proto.ExposeProtocol_EXPOSE_UDP, nil
+	case "tls":
+		return proto.ExposeProtocol_EXPOSE_TLS, nil
+	default:
+		return 0, fmt.Errorf("unsupported protocol %q: must be http, https, tcp, udp, or tls", exposeProtocol)
+	}
+}
+
+func handleExposeReady(cmd *cobra.Command, stream proto.DaemonService_ExposeServiceClient, port uint64) error {
+	event, err := stream.Recv()
+	if err != nil {
+		return fmt.Errorf("receive expose event: %w", err)
+	}
+
+	ready, ok := event.Event.(*proto.ExposeServiceEvent_Ready)
+	if !ok {
+		return fmt.Errorf("unexpected expose event: %T", event.Event)
+	}
+	printExposeReady(cmd, ready.Ready, port)
+	return nil
+}
+
+func printExposeReady(cmd *cobra.Command, r *proto.ExposeServiceReady, port uint64) {
+	cmd.Println("Service exposed successfully!")
+	cmd.Printf("  Name:     %s\n", r.ServiceName)
+	if r.ServiceUrl != "" {
+		cmd.Printf("  URL:      %s\n", r.ServiceUrl)
+	}
+	if r.Domain != "" && !isPortBasedProtocol(exposeProtocol) {
+		cmd.Printf("  Domain:   %s\n", r.Domain)
+	}
+	cmd.Printf("  Protocol: %s\n", exposeProtocol)
+	cmd.Printf("  Internal: %d\n", port)
+	if isClusterProtocol(exposeProtocol) {
+		cmd.Printf("  External: %s\n", extractPort(r.ServiceUrl, resolveExternalPort(port)))
+	}
+	if r.PortAutoAssigned && exposeExternalPort != 0 {
+		cmd.Printf("\n  Note: requested port %d was reassigned\n", exposeExternalPort)
+	}
+	cmd.Println()
+	cmd.Println("Press Ctrl+C to stop exposing.")
+}
+
+func waitForExposeEvents(cmd *cobra.Command, ctx context.Context, stream proto.DaemonService_ExposeServiceClient) error {
+	for {
+		_, err := stream.Recv()
+		if err != nil {
+			if ctx.Err() != nil {
+				cmd.Println("\nService stopped.")
+				//nolint:nilerr
+				return nil
+			}
+			if errors.Is(err, io.EOF) {
+				return fmt.Errorf("connection to daemon closed unexpectedly")
+			}
+			return fmt.Errorf("stream error: %w", err)
+		}
+	}
+}

client/cmd/root.go

@@ -22,6 +22,7 @@ import (
 	"google.golang.org/grpc"
 	"google.golang.org/grpc/credentials/insecure"
 
+	daddr "github.com/netbirdio/netbird/client/internal/daemonaddr"
 	"github.com/netbirdio/netbird/client/internal/profilemanager"
 )
 
@@ -80,6 +81,15 @@ var (
 		Short:        "",
 		Long:         "",
 		SilenceUsage: true,
+		PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
+			SetFlagsFromEnvVars(cmd.Root())
+
+			// Don't resolve for service commands — they create the socket, not connect to it.
+			if !isServiceCmd(cmd) {
+				daemonAddr = daddr.ResolveUnixDaemonAddr(daemonAddr)
+			}
+			return nil
+		},
 	}
 )
 
@@ -144,6 +154,7 @@ func init() {
 	rootCmd.AddCommand(forwardingRulesCmd)
 	rootCmd.AddCommand(debugCmd)
 	rootCmd.AddCommand(profileCmd)
+	rootCmd.AddCommand(exposeCmd)
 
 	networksCMD.AddCommand(routesListCmd)
 	networksCMD.AddCommand(routesSelectCmd, routesDeselectCmd)
@@ -385,7 +396,6 @@ func migrateToNetbird(oldPath, newPath string) bool {
 }
 
 func getClient(cmd *cobra.Command) (*grpc.ClientConn, error) {
-	SetFlagsFromEnvVars(rootCmd)
 	cmd.SetOut(cmd.OutOrStdout())
 
 	conn, err := DialClientGRPCServer(cmd.Context(), daemonAddr)
@@ -398,3 +408,13 @@ func getClient(cmd *cobra.Command) (*grpc.ClientConn, error) {
 
 	return conn, nil
 }
+
+// isServiceCmd returns true if cmd is the "service" command or a child of it.
+func isServiceCmd(cmd *cobra.Command) bool {
+	for c := cmd; c != nil; c = c.Parent() {
+		if c.Name() == "service" {
+			return true
+		}
+	}
+	return false
+}

client/cmd/signer/artifactkey.go

@@ -7,7 +7,7 @@ import (
 
 	"github.com/spf13/cobra"
 
-	"github.com/netbirdio/netbird/client/internal/updatemanager/reposign"
+	"github.com/netbirdio/netbird/client/internal/updater/reposign"
 )
 
 var (

client/cmd/signer/artifactsign.go

@@ -6,7 +6,7 @@ import (
 
 	"github.com/spf13/cobra"
 
-	"github.com/netbirdio/netbird/client/internal/updatemanager/reposign"
+	"github.com/netbirdio/netbird/client/internal/updater/reposign"
 )
 
 const (

client/cmd/signer/revocation.go

@@ -7,7 +7,7 @@ import (
 
 	"github.com/spf13/cobra"
 
-	"github.com/netbirdio/netbird/client/internal/updatemanager/reposign"
+	"github.com/netbirdio/netbird/client/internal/updater/reposign"
 )
 
 const (

client/cmd/signer/rootkey.go

@@ -7,7 +7,7 @@ import (
 
 	"github.com/spf13/cobra"
 
-	"github.com/netbirdio/netbird/client/internal/updatemanager/reposign"
+	"github.com/netbirdio/netbird/client/internal/updater/reposign"
 )
 
 var (

client/cmd/up.go

@@ -197,7 +197,7 @@ func runInForegroundMode(ctx context.Context, cmd *cobra.Command, activeProf *pr
 	r := peer.NewRecorder(config.ManagementURL.String())
 	r.GetFullStatus()
 
-	connectClient := internal.NewConnectClient(ctx, config, r, false)
+	connectClient := internal.NewConnectClient(ctx, config, r)
 	SetupDebugHandler(ctx, config, r, connectClient, "")
 
 	return connectClient.Run(nil, util.FindFirstLogPath(logFiles))

client/cmd/update_supported.go

@@ -11,7 +11,7 @@ import (
 	log "github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
 
-	"github.com/netbirdio/netbird/client/internal/updatemanager/installer"
+	"github.com/netbirdio/netbird/client/internal/updater/installer"
 	"github.com/netbirdio/netbird/util"
 )
 

client/embed/embed.go

@@ -14,6 +14,7 @@ import (
 	"github.com/sirupsen/logrus"
 	wgnetstack "golang.zx2c4.com/wireguard/tun/netstack"
 
+	"github.com/netbirdio/netbird/client/iface"
 	"github.com/netbirdio/netbird/client/iface/netstack"
 	"github.com/netbirdio/netbird/client/internal"
 	"github.com/netbirdio/netbird/client/internal/auth"
@@ -81,6 +82,12 @@ type Options struct {
 	BlockInbound bool
 	// WireguardPort is the port for the WireGuard interface. Use 0 for a random port.
 	WireguardPort *int
+	// MTU is the MTU for the WireGuard interface.
+	// Valid values are in the range 576..8192 bytes.
+	// If non-nil, this value overrides any value stored in the config file.
+	// If nil, the existing config MTU (if non-zero) is preserved; otherwise it defaults to 1280.
+	// Set to a higher value (e.g. 1400) if carrying QUIC or other protocols that require larger datagrams.
+	MTU *uint16
 }
 
 // validateCredentials checks that exactly one credential type is provided
@@ -112,6 +119,12 @@ func New(opts Options) (*Client, error) {
 		return nil, err
 	}
 
+	if opts.MTU != nil {
+		if err := iface.ValidateMTU(*opts.MTU); err != nil {
+			return nil, fmt.Errorf("invalid MTU: %w", err)
+		}
+	}
+
 	if opts.LogOutput != nil {
 		logrus.SetOutput(opts.LogOutput)
 	}
@@ -151,6 +164,7 @@ func New(opts Options) (*Client, error) {
 		DisableClientRoutes: &opts.DisableClientRoutes,
 		BlockInbound:        &opts.BlockInbound,
 		WireguardPort:       opts.WireguardPort,
+		MTU:                 opts.MTU,
 	}
 	if opts.ConfigPath != "" {
 		config, err = profilemanager.UpdateOrCreateConfig(input)
@@ -202,7 +216,7 @@ func (c *Client) Start(startCtx context.Context) error {
 	if err, _ := authClient.Login(ctx, c.setupKey, c.jwtToken); err != nil {
 		return fmt.Errorf("login: %w", err)
 	}
-	client := internal.NewConnectClient(ctx, c.config, c.recorder, false)
+	client := internal.NewConnectClient(ctx, c.config, c.recorder)
 	client.SetSyncResponsePersistence(true)
 
 	// either startup error (permanent backoff err) or nil err (successful engine up)

client/iface/configurer/uapi.go

@@ -5,20 +5,18 @@ package configurer
 import (
 	"net"
 
-	log "github.com/sirupsen/logrus"
 	"golang.zx2c4.com/wireguard/ipc"
 )
 
 func openUAPI(deviceName string) (net.Listener, error) {
 	uapiSock, err := ipc.UAPIOpen(deviceName)
 	if err != nil {
-		log.Errorf("failed to open uapi socket: %v", err)
 		return nil, err
 	}
 
 	listener, err := ipc.UAPIListen(deviceName, uapiSock)
 	if err != nil {
-		log.Errorf("failed to listen on uapi socket: %v", err)
+		_ = uapiSock.Close()
 		return nil, err
 	}
 

client/iface/configurer/usp.go

@@ -54,6 +54,14 @@ func NewUSPConfigurer(device *device.Device, deviceName string, activityRecorder
 	return wgCfg
 }
 
+func NewUSPConfigurerNoUAPI(device *device.Device, deviceName string, activityRecorder *bind.ActivityRecorder) *WGUSPConfigurer {
+	return &WGUSPConfigurer{
+		device:           device,
+		deviceName:       deviceName,
+		activityRecorder: activityRecorder,
+	}
+}
+
 func (c *WGUSPConfigurer) ConfigureInterface(privateKey string, port int) error {
 	log.Debugf("adding Wireguard private key")
 	key, err := wgtypes.ParseKey(privateKey)

client/iface/device/device_netstack.go

@@ -79,7 +79,7 @@ func (t *TunNetstackDevice) create() (WGConfigurer, error) {
 		device.NewLogger(wgLogLevel(), "[netbird] "),
 	)
 
-	t.configurer = configurer.NewUSPConfigurer(t.device, t.name, t.bind.ActivityRecorder())
+	t.configurer = configurer.NewUSPConfigurerNoUAPI(t.device, t.name, t.bind.ActivityRecorder())
 	err = t.configurer.ConfigureInterface(t.key, t.port)
 	if err != nil {
 		if cErr := tunIface.Close(); cErr != nil {

client/internal/connect.go

@@ -27,8 +27,8 @@ import (
 	"github.com/netbirdio/netbird/client/internal/profilemanager"
 	"github.com/netbirdio/netbird/client/internal/statemanager"
 	"github.com/netbirdio/netbird/client/internal/stdnet"
-	"github.com/netbirdio/netbird/client/internal/updatemanager"
-	"github.com/netbirdio/netbird/client/internal/updatemanager/installer"
+	"github.com/netbirdio/netbird/client/internal/updater"
+	"github.com/netbirdio/netbird/client/internal/updater/installer"
 	nbnet "github.com/netbirdio/netbird/client/net"
 	cProto "github.com/netbirdio/netbird/client/proto"
 	"github.com/netbirdio/netbird/client/ssh"
@@ -44,13 +44,13 @@ import (
 )
 
 type ConnectClient struct {
-	ctx                 context.Context
-	config              *profilemanager.Config
-	statusRecorder      *peer.Status
-	doInitialAutoUpdate bool
+	ctx            context.Context
+	config         *profilemanager.Config
+	statusRecorder *peer.Status
 
-	engine      *Engine
-	engineMutex sync.Mutex
+	engine        *Engine
+	engineMutex   sync.Mutex
+	updateManager *updater.Manager
 
 	persistSyncResponse bool
 }
@@ -59,17 +59,19 @@ func NewConnectClient(
 	ctx context.Context,
 	config *profilemanager.Config,
 	statusRecorder *peer.Status,
-	doInitalAutoUpdate bool,
 ) *ConnectClient {
 	return &ConnectClient{
-		ctx:                 ctx,
-		config:              config,
-		statusRecorder:      statusRecorder,
-		doInitialAutoUpdate: doInitalAutoUpdate,
-		engineMutex:         sync.Mutex{},
+		ctx:            ctx,
+		config:         config,
+		statusRecorder: statusRecorder,
+		engineMutex:    sync.Mutex{},
 	}
 }
 
+func (c *ConnectClient) SetUpdateManager(um *updater.Manager) {
+	c.updateManager = um
+}
+
 // Run with main logic.
 func (c *ConnectClient) Run(runningChan chan struct{}, logPath string) error {
 	return c.run(MobileDependency{}, runningChan, logPath)
@@ -187,14 +189,13 @@ func (c *ConnectClient) run(mobileDependency MobileDependency, runningChan chan
 	stateManager := statemanager.New(path)
 	stateManager.RegisterState(&sshconfig.ShutdownState{})
 
-	updateManager, err := updatemanager.NewManager(c.statusRecorder, stateManager)
-	if err == nil {
-		updateManager.CheckUpdateSuccess(c.ctx)
+	if c.updateManager != nil {
+		c.updateManager.CheckUpdateSuccess(c.ctx)
+	}
 
-		inst := installer.New()
-		if err := inst.CleanUpInstallerFiles(); err != nil {
-			log.Errorf("failed to clean up temporary installer file: %v", err)
-		}
+	inst := installer.New()
+	if err := inst.CleanUpInstallerFiles(); err != nil {
+		log.Errorf("failed to clean up temporary installer file: %v", err)
 	}
 
 	defer c.statusRecorder.ClientStop()
@@ -308,7 +309,15 @@ func (c *ConnectClient) run(mobileDependency MobileDependency, runningChan chan
 		checks := loginResp.GetChecks()
 
 		c.engineMutex.Lock()
-		engine := NewEngine(engineCtx, cancel, signalClient, mgmClient, relayManager, engineConfig, mobileDependency, c.statusRecorder, checks, stateManager)
+		engine := NewEngine(engineCtx, cancel, engineConfig, EngineServices{
+			SignalClient:   signalClient,
+			MgmClient:      mgmClient,
+			RelayManager:   relayManager,
+			StatusRecorder: c.statusRecorder,
+			Checks:         checks,
+			StateManager:   stateManager,
+			UpdateManager:  c.updateManager,
+		}, mobileDependency)
 		engine.SetSyncResponsePersistence(c.persistSyncResponse)
 		c.engine = engine
 		c.engineMutex.Unlock()
@@ -318,21 +327,15 @@ func (c *ConnectClient) run(mobileDependency MobileDependency, runningChan chan
 			return wrapErr(err)
 		}
 
-		if loginResp.PeerConfig != nil && loginResp.PeerConfig.AutoUpdate != nil {
-			// AutoUpdate will be true when the user click on "Connect" menu on the UI
-			if c.doInitialAutoUpdate {
-				log.Infof("start engine by ui, run auto-update check")
-				c.engine.InitialUpdateHandling(loginResp.PeerConfig.AutoUpdate)
-				c.doInitialAutoUpdate = false
-			}
-		}
-
 		log.Infof("Netbird engine started, the IP is: %s", peerConfig.GetAddress())
 		state.Set(StatusConnected)
 
 		if runningChan != nil {
-			close(runningChan)
-			runningChan = nil
+			select {
+			case <-runningChan:
+			default:
+				close(runningChan)
+			}
 		}
 
 		<-engineCtx.Done()

client/internal/daemonaddr/resolve.go

@@ -0,0 +1,60 @@
+//go:build !windows && !ios && !android
+
+package daemonaddr
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+
+	log "github.com/sirupsen/logrus"
+)
+
+var scanDir = "/var/run/netbird"
+
+// setScanDir overrides the scan directory (used by tests).
+func setScanDir(dir string) {
+	scanDir = dir
+}
+
+// ResolveUnixDaemonAddr checks whether the default Unix socket exists and, if not,
+// scans /var/run/netbird/ for a single .sock file to use instead. This handles the
+// mismatch between the netbird@.service template (which places the socket under
+// /var/run/netbird/<instance>.sock) and the CLI default (/var/run/netbird.sock).
+func ResolveUnixDaemonAddr(addr string) string {
+	if !strings.HasPrefix(addr, "unix://") {
+		return addr
+	}
+
+	sockPath := strings.TrimPrefix(addr, "unix://")
+	if _, err := os.Stat(sockPath); err == nil {
+		return addr
+	}
+
+	entries, err := os.ReadDir(scanDir)
+	if err != nil {
+		return addr
+	}
+
+	var found []string
+	for _, e := range entries {
+		if e.IsDir() {
+			continue
+		}
+		if strings.HasSuffix(e.Name(), ".sock") {
+			found = append(found, filepath.Join(scanDir, e.Name()))
+		}
+	}
+
+	switch len(found) {
+	case 1:
+		resolved := "unix://" + found[0]
+		log.Debugf("Default daemon socket not found, using discovered socket: %s", resolved)
+		return resolved
+	case 0:
+		return addr
+	default:
+		log.Warnf("Default daemon socket not found and multiple sockets discovered in %s; pass --daemon-addr explicitly", scanDir)
+		return addr
+	}
+}

client/internal/daemonaddr/resolve_stub.go

@@ -0,0 +1,8 @@
+//go:build windows || ios || android
+
+package daemonaddr
+
+// ResolveUnixDaemonAddr is a no-op on platforms that don't use Unix sockets.
+func ResolveUnixDaemonAddr(addr string) string {
+	return addr
+}

client/internal/daemonaddr/resolve_test.go

@@ -0,0 +1,121 @@
+//go:build !windows && !ios && !android
+
+package daemonaddr
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// createSockFile creates a regular file with a .sock extension.
+// ResolveUnixDaemonAddr uses os.Stat (not net.Dial), so a regular file is
+// sufficient and avoids Unix socket path-length limits on macOS.
+func createSockFile(t *testing.T, path string) {
+	t.Helper()
+	if err := os.WriteFile(path, nil, 0o600); err != nil {
+		t.Fatalf("failed to create test sock file at %s: %v", path, err)
+	}
+}
+
+func TestResolveUnixDaemonAddr_DefaultExists(t *testing.T) {
+	tmp := t.TempDir()
+	sock := filepath.Join(tmp, "netbird.sock")
+	createSockFile(t, sock)
+
+	addr := "unix://" + sock
+	got := ResolveUnixDaemonAddr(addr)
+	if got != addr {
+		t.Errorf("expected %s, got %s", addr, got)
+	}
+}
+
+func TestResolveUnixDaemonAddr_SingleDiscovered(t *testing.T) {
+	tmp := t.TempDir()
+
+	// Default socket does not exist
+	defaultAddr := "unix://" + filepath.Join(tmp, "netbird.sock")
+
+	// Create a scan dir with one socket
+	sd := filepath.Join(tmp, "netbird")
+	if err := os.MkdirAll(sd, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	instanceSock := filepath.Join(sd, "main.sock")
+	createSockFile(t, instanceSock)
+
+	origScanDir := scanDir
+	setScanDir(sd)
+	t.Cleanup(func() { setScanDir(origScanDir) })
+
+	got := ResolveUnixDaemonAddr(defaultAddr)
+	expected := "unix://" + instanceSock
+	if got != expected {
+		t.Errorf("expected %s, got %s", expected, got)
+	}
+}
+
+func TestResolveUnixDaemonAddr_MultipleDiscovered(t *testing.T) {
+	tmp := t.TempDir()
+
+	defaultAddr := "unix://" + filepath.Join(tmp, "netbird.sock")
+
+	sd := filepath.Join(tmp, "netbird")
+	if err := os.MkdirAll(sd, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	createSockFile(t, filepath.Join(sd, "main.sock"))
+	createSockFile(t, filepath.Join(sd, "other.sock"))
+
+	origScanDir := scanDir
+	setScanDir(sd)
+	t.Cleanup(func() { setScanDir(origScanDir) })
+
+	got := ResolveUnixDaemonAddr(defaultAddr)
+	if got != defaultAddr {
+		t.Errorf("expected original %s, got %s", defaultAddr, got)
+	}
+}
+
+func TestResolveUnixDaemonAddr_NoSocketsFound(t *testing.T) {
+	tmp := t.TempDir()
+
+	defaultAddr := "unix://" + filepath.Join(tmp, "netbird.sock")
+
+	sd := filepath.Join(tmp, "netbird")
+	if err := os.MkdirAll(sd, 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	origScanDir := scanDir
+	setScanDir(sd)
+	t.Cleanup(func() { setScanDir(origScanDir) })
+
+	got := ResolveUnixDaemonAddr(defaultAddr)
+	if got != defaultAddr {
+		t.Errorf("expected original %s, got %s", defaultAddr, got)
+	}
+}
+
+func TestResolveUnixDaemonAddr_NonUnixAddr(t *testing.T) {
+	addr := "tcp://127.0.0.1:41731"
+	got := ResolveUnixDaemonAddr(addr)
+	if got != addr {
+		t.Errorf("expected %s, got %s", addr, got)
+	}
+}
+
+func TestResolveUnixDaemonAddr_ScanDirMissing(t *testing.T) {
+	tmp := t.TempDir()
+
+	defaultAddr := "unix://" + filepath.Join(tmp, "netbird.sock")
+
+	origScanDir := scanDir
+	setScanDir(filepath.Join(tmp, "nonexistent"))
+	t.Cleanup(func() { setScanDir(origScanDir) })
+
+	got := ResolveUnixDaemonAddr(defaultAddr)
+	if got != defaultAddr {
+		t.Errorf("expected original %s, got %s", defaultAddr, got)
+	}
+}

client/internal/debug/debug.go

@@ -27,7 +27,7 @@ import (
 	"github.com/netbirdio/netbird/client/anonymize"
 	"github.com/netbirdio/netbird/client/internal/peer"
 	"github.com/netbirdio/netbird/client/internal/profilemanager"
-	"github.com/netbirdio/netbird/client/internal/updatemanager/installer"
+	"github.com/netbirdio/netbird/client/internal/updater/installer"
 	nbstatus "github.com/netbirdio/netbird/client/status"
 	mgmProto "github.com/netbirdio/netbird/shared/management/proto"
 	"github.com/netbirdio/netbird/util"

client/internal/dns/host_windows.go

@@ -277,7 +277,7 @@ func (r *registryConfigurator) addDNSMatchPolicy(domains []string, ip netip.Addr
 		}
 	}
 
-	log.Infof("added %d NRPT rules for %d domains. Domain list: %v", ruleIndex, len(domains), domains)
+	log.Infof("added %d NRPT rules for %d domains", ruleIndex, len(domains))
 	return ruleIndex, nil
 }
 

client/internal/dns/local/local.go

@@ -77,7 +77,7 @@ func (d *Resolver) ID() types.HandlerID {
 	return "local-resolver"
 }
 
-func (d *Resolver) ProbeAvailability() {}
+func (d *Resolver) ProbeAvailability(context.Context) {}
 
 // ServeDNS handles a DNS request
 func (d *Resolver) ServeDNS(w dns.ResponseWriter, r *dns.Msg) {

client/internal/dns/local/local_test.go

@@ -1263,9 +1263,9 @@ func TestLocalResolver_AuthoritativeFlag(t *testing.T) {
 	})
 }
 
-// TestLocalResolver_Stop tests cleanup on Stop
+// TestLocalResolver_Stop tests cleanup on GracefullyStop
 func TestLocalResolver_Stop(t *testing.T) {
-	t.Run("Stop clears all state", func(t *testing.T) {
+	t.Run("GracefullyStop clears all state", func(t *testing.T) {
 		resolver := NewResolver()
 		resolver.Update([]nbdns.CustomZone{{
 			Domain: "example.com.",
@@ -1285,7 +1285,7 @@ func TestLocalResolver_Stop(t *testing.T) {
 		assert.False(t, resolver.isInManagedZone("host.example.com."))
 	})
 
-	t.Run("Stop is safe to call multiple times", func(t *testing.T) {
+	t.Run("GracefullyStop is safe to call multiple times", func(t *testing.T) {
 		resolver := NewResolver()
 		resolver.Update([]nbdns.CustomZone{{
 			Domain: "example.com.",
@@ -1299,7 +1299,7 @@ func TestLocalResolver_Stop(t *testing.T) {
 		resolver.Stop()
 	})
 
-	t.Run("Stop cancels in-flight external resolution", func(t *testing.T) {
+	t.Run("GracefullyStop cancels in-flight external resolution", func(t *testing.T) {
 		resolver := NewResolver()
 
 		lookupStarted := make(chan struct{})

client/internal/dns/mgmt/mgmt.go

@@ -376,9 +376,9 @@ func (m *Resolver) extractDomainsFromServerDomains(serverDomains dnsconfig.Serve
 		}
 	}
 
-	if serverDomains.Flow != "" {
-		domains = append(domains, serverDomains.Flow)
-	}
+	// Flow receiver domain is intentionally excluded from caching.
+	// Cloud providers may rotate the IP behind this domain; a stale cached record
+	// causes TLS certificate verification failures on reconnect.
 
 	for _, stun := range serverDomains.Stuns {
 		if stun != "" {

client/internal/dns/mgmt/mgmt_test.go

@@ -391,7 +391,8 @@ func TestResolver_PartialUpdateAddsNewTypePreservesExisting(t *testing.T) {
 	}
 	assert.Len(t, resolver.GetCachedDomains(), 3)
 
-	// Update with partial ServerDomains (only flow domain - new type, should preserve all existing)
+	// Update with partial ServerDomains (only flow domain - flow is intentionally excluded from
+	// caching to prevent TLS failures from stale records, so all existing domains are preserved)
 	partialDomains := dnsconfig.ServerDomains{
 		Flow: "github.com",
 	}
@@ -400,10 +401,10 @@ func TestResolver_PartialUpdateAddsNewTypePreservesExisting(t *testing.T) {
 		t.Skipf("Skipping test due to DNS resolution failure: %v", err)
 	}
 
-	assert.Len(t, removedDomains, 0, "Should not remove any domains when adding new type")
+	assert.Len(t, removedDomains, 0, "Should not remove any domains when only flow domain is provided")
 
 	finalDomains := resolver.GetCachedDomains()
-	assert.Len(t, finalDomains, 4, "Should have all original domains plus new flow domain")
+	assert.Len(t, finalDomains, 3, "Flow domain is not cached; all original domains should be preserved")
 
 	domainStrings := make([]string, len(finalDomains))
 	for i, d := range finalDomains {
@@ -412,5 +413,5 @@ func TestResolver_PartialUpdateAddsNewTypePreservesExisting(t *testing.T) {
 	assert.Contains(t, domainStrings, "example.org")
 	assert.Contains(t, domainStrings, "google.com")
 	assert.Contains(t, domainStrings, "cloudflare.com")
-	assert.Contains(t, domainStrings, "github.com")
+	assert.NotContains(t, domainStrings, "github.com")
 }

client/internal/dns/server.go

@@ -104,12 +104,16 @@ type DefaultServer struct {
 
 	statusRecorder *peer.Status
 	stateManager   *statemanager.Manager
+
+	probeMu     sync.Mutex
+	probeCancel context.CancelFunc
+	probeWg     sync.WaitGroup
 }
 
 type handlerWithStop interface {
 	dns.Handler
 	Stop()
-	ProbeAvailability()
+	ProbeAvailability(context.Context)
 	ID() types.HandlerID
 }
 
@@ -362,7 +366,13 @@ func (s *DefaultServer) DnsIP() netip.Addr {
 
 // Stop stops the server
 func (s *DefaultServer) Stop() {
+	s.probeMu.Lock()
+	if s.probeCancel != nil {
+		s.probeCancel()
+	}
 	s.ctxCancel()
+	s.probeMu.Unlock()
+	s.probeWg.Wait()
 	s.shutdownWg.Wait()
 
 	s.mux.Lock()
@@ -479,7 +489,8 @@ func (s *DefaultServer) SearchDomains() []string {
 }
 
 // ProbeAvailability tests each upstream group's servers for availability
-// and deactivates the group if no server responds
+// and deactivates the group if no server responds.
+// If a previous probe is still running, it will be cancelled before starting a new one.
 func (s *DefaultServer) ProbeAvailability() {
 	if val := os.Getenv(envSkipDNSProbe); val != "" {
 		skipProbe, err := strconv.ParseBool(val)
@@ -492,15 +503,52 @@ func (s *DefaultServer) ProbeAvailability() {
 		}
 	}
 
-	var wg sync.WaitGroup
-	for _, mux := range s.dnsMuxMap {
-		wg.Add(1)
-		go func(mux handlerWithStop) {
-			defer wg.Done()
-			mux.ProbeAvailability()
-		}(mux.handler)
+	s.probeMu.Lock()
+
+	// don't start probes on a stopped server
+	if s.ctx.Err() != nil {
+		s.probeMu.Unlock()
+		return
 	}
+
+	// cancel any running probe
+	if s.probeCancel != nil {
+		s.probeCancel()
+		s.probeCancel = nil
+	}
+
+	// wait for the previous probe goroutines to finish while holding
+	// the mutex so no other caller can start a new probe concurrently
+	s.probeWg.Wait()
+
+	// start a new probe
+	probeCtx, probeCancel := context.WithCancel(s.ctx)
+	s.probeCancel = probeCancel
+
+	s.probeWg.Add(1)
+	defer s.probeWg.Done()
+
+	// Snapshot handlers under s.mux to avoid racing with updateMux/dnsMuxMap writers.
+	s.mux.Lock()
+	handlers := make([]handlerWithStop, 0, len(s.dnsMuxMap))
+	for _, mux := range s.dnsMuxMap {
+		handlers = append(handlers, mux.handler)
+	}
+	s.mux.Unlock()
+
+	var wg sync.WaitGroup
+	for _, handler := range handlers {
+		wg.Add(1)
+		go func(h handlerWithStop) {
+			defer wg.Done()
+			h.ProbeAvailability(probeCtx)
+		}(handler)
+	}
+
+	s.probeMu.Unlock()
+
 	wg.Wait()
+	probeCancel()
 }
 
 func (s *DefaultServer) UpdateServerConfig(domains dnsconfig.ServerDomains) error {

client/internal/dns/server_test.go

@@ -1065,7 +1065,7 @@ type mockHandler struct {
 
 func (m *mockHandler) ServeDNS(dns.ResponseWriter, *dns.Msg) {}
 func (m *mockHandler) Stop()                                 {}
-func (m *mockHandler) ProbeAvailability()                    {}
+func (m *mockHandler) ProbeAvailability(context.Context)     {}
 func (m *mockHandler) ID() types.HandlerID                   { return types.HandlerID(m.Id) }
 
 type mockService struct{}

client/internal/dns/upstream.go

@@ -65,6 +65,7 @@ type upstreamResolverBase struct {
 	mutex            sync.Mutex
 	reactivatePeriod time.Duration
 	upstreamTimeout  time.Duration
+	wg               sync.WaitGroup
 
 	deactivate     func(error)
 	reactivate     func()
@@ -115,6 +116,11 @@ func (u *upstreamResolverBase) MatchSubdomains() bool {
 func (u *upstreamResolverBase) Stop() {
 	log.Debugf("stopping serving DNS for upstreams %s", u.upstreamServers)
 	u.cancel()
+
+	u.mutex.Lock()
+	u.wg.Wait()
+	u.mutex.Unlock()
+
 }
 
 // ServeDNS handles a DNS request
@@ -260,16 +266,10 @@ func formatFailures(failures []upstreamFailure) string {
 
 // ProbeAvailability tests all upstream servers simultaneously and
 // disables the resolver if none work
-func (u *upstreamResolverBase) ProbeAvailability() {
+func (u *upstreamResolverBase) ProbeAvailability(ctx context.Context) {
 	u.mutex.Lock()
 	defer u.mutex.Unlock()
 
-	select {
-	case <-u.ctx.Done():
-		return
-	default:
-	}
-
 	// avoid probe if upstreams could resolve at least one query
 	if u.successCount.Load() > 0 {
 		return
@@ -279,31 +279,39 @@ func (u *upstreamResolverBase) ProbeAvailability() {
 	var mu sync.Mutex
 	var wg sync.WaitGroup
 
-	var errors *multierror.Error
+	var errs *multierror.Error
 	for _, upstream := range u.upstreamServers {
-		upstream := upstream
-
 		wg.Add(1)
-		go func() {
+		go func(upstream netip.AddrPort) {
 			defer wg.Done()
-			err := u.testNameserver(upstream, 500*time.Millisecond)
+			err := u.testNameserver(u.ctx, ctx, upstream, 500*time.Millisecond)
 			if err != nil {
-				errors = multierror.Append(errors, err)
+				mu.Lock()
+				errs = multierror.Append(errs, err)
+				mu.Unlock()
 				log.Warnf("probing upstream nameserver %s: %s", upstream, err)
 				return
 			}
 
 			mu.Lock()
-			defer mu.Unlock()
 			success = true
-		}()
+			mu.Unlock()
+		}(upstream)
 	}
 
 	wg.Wait()
 
+	select {
+	case <-ctx.Done():
+		return
+	case <-u.ctx.Done():
+		return
+	default:
+	}
+
 	// didn't find a working upstream server, let's disable and try later
 	if !success {
-		u.disable(errors.ErrorOrNil())
+		u.disable(errs.ErrorOrNil())
 
 		if u.statusRecorder == nil {
 			return
@@ -339,7 +347,7 @@ func (u *upstreamResolverBase) waitUntilResponse() {
 		}
 
 		for _, upstream := range u.upstreamServers {
-			if err := u.testNameserver(upstream, probeTimeout); err != nil {
+			if err := u.testNameserver(u.ctx, nil, upstream, probeTimeout); err != nil {
 				log.Tracef("upstream check for %s: %s", upstream, err)
 			} else {
 				// at least one upstream server is available, stop probing
@@ -351,16 +359,22 @@ func (u *upstreamResolverBase) waitUntilResponse() {
 		return fmt.Errorf("upstream check call error")
 	}
 
-	err := backoff.Retry(operation, exponentialBackOff)
+	err := backoff.Retry(operation, backoff.WithContext(exponentialBackOff, u.ctx))
 	if err != nil {
-		log.Warn(err)
+		if errors.Is(err, context.Canceled) {
+			log.Debugf("upstream retry loop exited for upstreams %s", u.upstreamServersString())
+		} else {
+			log.Warnf("upstream retry loop exited for upstreams %s: %v", u.upstreamServersString(), err)
+		}
 		return
 	}
 
 	log.Infof("upstreams %s are responsive again. Adding them back to system", u.upstreamServersString())
 	u.successCount.Add(1)
 	u.reactivate()
+	u.mutex.Lock()
 	u.disabled = false
+	u.mutex.Unlock()
 }
 
 // isTimeout returns true if the given error is a network timeout error.
@@ -383,7 +397,11 @@ func (u *upstreamResolverBase) disable(err error) {
 	u.successCount.Store(0)
 	u.deactivate(err)
 	u.disabled = true
-	go u.waitUntilResponse()
+	u.wg.Add(1)
+	go func() {
+		defer u.wg.Done()
+		u.waitUntilResponse()
+	}()
 }
 
 func (u *upstreamResolverBase) upstreamServersString() string {
@@ -394,13 +412,18 @@ func (u *upstreamResolverBase) upstreamServersString() string {
 	return strings.Join(servers, ", ")
 }
 
-func (u *upstreamResolverBase) testNameserver(server netip.AddrPort, timeout time.Duration) error {
-	ctx, cancel := context.WithTimeout(u.ctx, timeout)
+func (u *upstreamResolverBase) testNameserver(baseCtx context.Context, externalCtx context.Context, server netip.AddrPort, timeout time.Duration) error {
+	mergedCtx, cancel := context.WithTimeout(baseCtx, timeout)
 	defer cancel()
 
+	if externalCtx != nil {
+		stop2 := context.AfterFunc(externalCtx, cancel)
+		defer stop2()
+	}
+
 	r := new(dns.Msg).SetQuestion(testRecord, dns.TypeSOA)
 
-	_, _, err := u.upstreamClient.exchange(ctx, server.String(), r)
+	_, _, err := u.upstreamClient.exchange(mergedCtx, server.String(), r)
 	return err
 }
 

client/internal/dns/upstream_test.go

@@ -188,7 +188,7 @@ func TestUpstreamResolver_DeactivationReactivation(t *testing.T) {
 		reactivated = true
 	}
 
-	resolver.ProbeAvailability()
+	resolver.ProbeAvailability(context.TODO())
 
 	if !failed {
 		t.Errorf("expected that resolving was deactivated")

client/internal/engine.go

@@ -36,6 +36,7 @@ import (
 	"github.com/netbirdio/netbird/client/internal/dns"
 	dnsconfig "github.com/netbirdio/netbird/client/internal/dns/config"
 	"github.com/netbirdio/netbird/client/internal/dnsfwd"
+	"github.com/netbirdio/netbird/client/internal/expose"
 	"github.com/netbirdio/netbird/client/internal/ingressgw"
 	"github.com/netbirdio/netbird/client/internal/netflow"
 	nftypes "github.com/netbirdio/netbird/client/internal/netflow/types"
@@ -44,22 +45,21 @@ import (
 	"github.com/netbirdio/netbird/client/internal/peer/guard"
 	icemaker "github.com/netbirdio/netbird/client/internal/peer/ice"
 	"github.com/netbirdio/netbird/client/internal/peerstore"
+	"github.com/netbirdio/netbird/client/internal/portforward"
 	"github.com/netbirdio/netbird/client/internal/profilemanager"
 	"github.com/netbirdio/netbird/client/internal/relay"
 	"github.com/netbirdio/netbird/client/internal/rosenpass"
 	"github.com/netbirdio/netbird/client/internal/routemanager"
 	"github.com/netbirdio/netbird/client/internal/routemanager/systemops"
 	"github.com/netbirdio/netbird/client/internal/statemanager"
-	"github.com/netbirdio/netbird/client/internal/updatemanager"
+	"github.com/netbirdio/netbird/client/internal/updater"
 	"github.com/netbirdio/netbird/client/jobexec"
 	cProto "github.com/netbirdio/netbird/client/proto"
-	"github.com/netbirdio/netbird/shared/management/domain"
-	semaphoregroup "github.com/netbirdio/netbird/util/semaphore-group"
-
 	"github.com/netbirdio/netbird/client/system"
 	nbdns "github.com/netbirdio/netbird/dns"
 	"github.com/netbirdio/netbird/route"
 	mgm "github.com/netbirdio/netbird/shared/management/client"
+	"github.com/netbirdio/netbird/shared/management/domain"
 	mgmProto "github.com/netbirdio/netbird/shared/management/proto"
 	auth "github.com/netbirdio/netbird/shared/relay/auth/hmac"
 	relayClient "github.com/netbirdio/netbird/shared/relay/client"
@@ -75,13 +75,11 @@ import (
 const (
 	PeerConnectionTimeoutMax = 45000 // ms
 	PeerConnectionTimeoutMin = 30000 // ms
-	connInitLimit            = 200
 	disableAutoUpdate        = "disabled"
 )
 
 var ErrResetConnection = fmt.Errorf("reset connection")
 
-// EngineConfig is a config for the Engine
 type EngineConfig struct {
 	WgPort      int
 	WgIfaceName string
@@ -143,6 +141,17 @@ type EngineConfig struct {
 	LogPath string
 }
 
+// EngineServices holds the external service dependencies required by the Engine.
+type EngineServices struct {
+	SignalClient   signal.Client
+	MgmClient      mgm.Client
+	RelayManager   *relayClient.Manager
+	StatusRecorder *peer.Status
+	Checks         []*mgmProto.Checks
+	StateManager   *statemanager.Manager
+	UpdateManager  *updater.Manager
+}
+
 // Engine is a mechanism responsible for reacting on Signal and Management stream events and managing connections to the remote peers.
 type Engine struct {
 	// signal is a Signal Service client
@@ -200,19 +209,19 @@ type Engine struct {
 	// checks are the client-applied posture checks that need to be evaluated on the client
 	checks []*mgmProto.Checks
 
-	relayManager *relayClient.Manager
-	stateManager *statemanager.Manager
-	srWatcher    *guard.SRWatcher
+	relayManager       *relayClient.Manager
+	stateManager       *statemanager.Manager
+	portForwardManager *portforward.Manager
+	srWatcher          *guard.SRWatcher
 
 	// Sync response persistence (protected by syncRespMux)
 	syncRespMux         sync.RWMutex
 	persistSyncResponse bool
 	latestSyncResponse  *mgmProto.SyncResponse
-	connSemaphore       *semaphoregroup.SemaphoreGroup
 	flowManager         nftypes.FlowManager
 
 	// auto-update
-	updateManager *updatemanager.Manager
+	updateManager *updater.Manager
 
 	// WireGuard interface monitor
 	wgIfaceMonitor *WGIfaceMonitor
@@ -224,6 +233,8 @@ type Engine struct {
 
 	jobExecutor   *jobexec.Executor
 	jobExecutorWG sync.WaitGroup
+
+	exposeManager *expose.Manager
 }
 
 // Peer is an instance of the Connection Peer
@@ -240,35 +251,30 @@ type localIpUpdater interface {
 func NewEngine(
 	clientCtx context.Context,
 	clientCancel context.CancelFunc,
-	signalClient signal.Client,
-	mgmClient mgm.Client,
-	relayManager *relayClient.Manager,
 	config *EngineConfig,
+	services EngineServices,
 	mobileDep MobileDependency,
-	statusRecorder *peer.Status,
-	checks []*mgmProto.Checks,
-	stateManager *statemanager.Manager,
 ) *Engine {
 	engine := &Engine{
-		clientCtx:      clientCtx,
-		clientCancel:   clientCancel,
-		signal:         signalClient,
-		signaler:       peer.NewSignaler(signalClient, config.WgPrivateKey),
-		mgmClient:      mgmClient,
-		relayManager:   relayManager,
-		peerStore:      peerstore.NewConnStore(),
-		syncMsgMux:     &sync.Mutex{},
-		config:         config,
-		mobileDep:      mobileDep,
-		STUNs:          []*stun.URI{},
-		TURNs:          []*stun.URI{},
-		networkSerial:  0,
-		statusRecorder: statusRecorder,
-		stateManager:   stateManager,
-		checks:         checks,
-		connSemaphore:  semaphoregroup.NewSemaphoreGroup(connInitLimit),
-		probeStunTurn:  relay.NewStunTurnProbe(relay.DefaultCacheTTL),
-		jobExecutor:    jobexec.NewExecutor(),
+		clientCtx:          clientCtx,
+		clientCancel:       clientCancel,
+		signal:             services.SignalClient,
+		signaler:           peer.NewSignaler(services.SignalClient, config.WgPrivateKey),
+		mgmClient:          services.MgmClient,
+		relayManager:       services.RelayManager,
+		peerStore:          peerstore.NewConnStore(),
+		syncMsgMux:         &sync.Mutex{},
+		config:             config,
+		mobileDep:          mobileDep,
+		STUNs:              []*stun.URI{},
+		TURNs:              []*stun.URI{},
+		networkSerial:      0,
+		statusRecorder:     services.StatusRecorder,
+		stateManager:       services.StateManager,
+		portForwardManager: portforward.NewManager(),
+		checks:             services.Checks,
+		probeStunTurn:      relay.NewStunTurnProbe(relay.DefaultCacheTTL),
+		jobExecutor:        jobexec.NewExecutor(), updateManager: services.UpdateManager,
 	}
 
 	log.Infof("I am: %s", config.WgPrivateKey.PublicKey().String())
@@ -311,7 +317,7 @@ func (e *Engine) Stop() error {
 	}
 
 	if e.updateManager != nil {
-		e.updateManager.Stop()
+		e.updateManager.SetDownloadOnly()
 	}
 
 	log.Info("cleaning up status recorder states")
@@ -419,6 +425,7 @@ func (e *Engine) Start(netbirdConfig *mgmProto.NetbirdConfig, mgmtURL *url.URL)
 		e.cancel()
 	}
 	e.ctx, e.cancel = context.WithCancel(e.clientCtx)
+	e.exposeManager = expose.NewManager(e.ctx, e.mgmClient)
 
 	wgIface, err := e.newWgIface()
 	if err != nil {
@@ -510,6 +517,13 @@ func (e *Engine) Start(netbirdConfig *mgmProto.NetbirdConfig, mgmtURL *url.URL)
 	// conntrack entries from being created before the rules are in place
 	e.setupWGProxyNoTrack()
 
+	// Start after interface is up since port may have been resolved from 0 or changed if occupied
+	e.shutdownWg.Add(1)
+	go func() {
+		defer e.shutdownWg.Done()
+		e.portForwardManager.Start(e.ctx, uint16(e.config.WgPort))
+	}()
+
 	// Set the WireGuard interface for rosenpass after interface is up
 	if e.rpManager != nil {
 		e.rpManager.SetInterface(e.wgInterface)
@@ -560,13 +574,6 @@ func (e *Engine) Start(netbirdConfig *mgmProto.NetbirdConfig, mgmtURL *url.URL)
 	return nil
 }
 
-func (e *Engine) InitialUpdateHandling(autoUpdateSettings *mgmProto.AutoUpdateSettings) {
-	e.syncMsgMux.Lock()
-	defer e.syncMsgMux.Unlock()
-
-	e.handleAutoUpdateVersion(autoUpdateSettings, true)
-}
-
 func (e *Engine) createFirewall() error {
 	if e.config.DisableFirewall {
 		log.Infof("firewall is disabled")
@@ -794,39 +801,22 @@ func (e *Engine) PopulateNetbirdConfig(netbirdConfig *mgmProto.NetbirdConfig, mg
 	return nil
 }
 
-func (e *Engine) handleAutoUpdateVersion(autoUpdateSettings *mgmProto.AutoUpdateSettings, initialCheck bool) {
+func (e *Engine) handleAutoUpdateVersion(autoUpdateSettings *mgmProto.AutoUpdateSettings) {
+	if e.updateManager == nil {
+		return
+	}
+
 	if autoUpdateSettings == nil {
 		return
 	}
 
-	disabled := autoUpdateSettings.Version == disableAutoUpdate
-
-	// Stop and cleanup if disabled
-	if e.updateManager != nil && disabled {
-		log.Infof("auto-update is disabled, stopping update manager")
-		e.updateManager.Stop()
-		e.updateManager = nil
+	if autoUpdateSettings.Version == disableAutoUpdate {
+		log.Infof("auto-update is disabled")
+		e.updateManager.SetDownloadOnly()
 		return
 	}
 
-	// Skip check unless AlwaysUpdate is enabled or this is the initial check at startup
-	if !autoUpdateSettings.AlwaysUpdate && !initialCheck {
-		log.Debugf("skipping auto-update check, AlwaysUpdate is false and this is not the initial check")
-		return
-	}
-
-	// Start manager if needed
-	if e.updateManager == nil {
-		log.Infof("starting auto-update manager")
-		updateManager, err := updatemanager.NewManager(e.statusRecorder, e.stateManager)
-		if err != nil {
-			return
-		}
-		e.updateManager = updateManager
-		e.updateManager.Start(e.ctx)
-	}
-	log.Infof("handling auto-update version: %s", autoUpdateSettings.Version)
-	e.updateManager.SetVersion(autoUpdateSettings.Version)
+	e.updateManager.SetVersion(autoUpdateSettings.Version, autoUpdateSettings.AlwaysUpdate)
 }
 
 func (e *Engine) handleSync(update *mgmProto.SyncResponse) error {
@@ -843,7 +833,7 @@ func (e *Engine) handleSync(update *mgmProto.SyncResponse) error {
 	}
 
 	if update.NetworkMap != nil && update.NetworkMap.PeerConfig != nil {
-		e.handleAutoUpdateVersion(update.NetworkMap.PeerConfig.AutoUpdate, false)
+		e.handleAutoUpdateVersion(update.NetworkMap.PeerConfig.AutoUpdate)
 	}
 
 	if update.GetNetbirdConfig() != nil {
@@ -1316,8 +1306,7 @@ func (e *Engine) updateNetworkMap(networkMap *mgmProto.NetworkMap) error {
 
 	// Test received (upstream) servers for availability right away instead of upon usage.
 	// If no server of a server group responds this will disable the respective handler and retry later.
-	e.dnsServer.ProbeAvailability()
-
+	go e.dnsServer.ProbeAvailability()
 	return nil
 }
 
@@ -1534,12 +1523,12 @@ func (e *Engine) createPeerConn(pubKey string, allowedIPs []netip.Prefix, agentV
 	}
 
 	serviceDependencies := peer.ServiceDependencies{
-		StatusRecorder: e.statusRecorder,
-		Signaler:       e.signaler,
-		IFaceDiscover:  e.mobileDep.IFaceDiscover,
-		RelayManager:   e.relayManager,
-		SrWatcher:      e.srWatcher,
-		Semaphore:      e.connSemaphore,
+		StatusRecorder:     e.statusRecorder,
+		Signaler:           e.signaler,
+		IFaceDiscover:      e.mobileDep.IFaceDiscover,
+		RelayManager:       e.relayManager,
+		SrWatcher:          e.srWatcher,
+		PortForwardManager: e.portForwardManager,
 	}
 	peerConn, err := peer.NewConn(config, serviceDependencies)
 	if err != nil {
@@ -1696,6 +1685,12 @@ func (e *Engine) close() {
 	if e.rpManager != nil {
 		_ = e.rpManager.Close()
 	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	if err := e.portForwardManager.GracefullyStop(ctx); err != nil {
+		log.Warnf("failed to gracefully stop port forwarding manager: %s", err)
+	}
 }
 
 func (e *Engine) readInitialSettings() ([]*route.Route, *nbdns.Config, bool, error) {
@@ -1824,11 +1819,18 @@ func (e *Engine) GetRouteManager() routemanager.Manager {
 	return e.routeManager
 }
 
-// GetFirewallManager returns the firewall manager
+// GetFirewallManager returns the firewall manager.
 func (e *Engine) GetFirewallManager() firewallManager.Manager {
 	return e.firewall
 }
 
+// GetExposeManager returns the expose session manager.
+func (e *Engine) GetExposeManager() *expose.Manager {
+	e.syncMsgMux.Lock()
+	defer e.syncMsgMux.Unlock()
+	return e.exposeManager
+}
+
 func findIPFromInterfaceName(ifaceName string) (net.IP, error) {
 	iface, err := net.InterfaceByName(ifaceName)
 	if err != nil {

client/internal/engine_test.go

@@ -251,9 +251,6 @@ func TestEngine_SSH(t *testing.T) {
 	relayMgr := relayClient.NewManager(ctx, nil, key.PublicKey().String(), iface.DefaultMTU)
 	engine := NewEngine(
 		ctx, cancel,
-		&signal.MockClient{},
-		&mgmt.MockClient{},
-		relayMgr,
 		&EngineConfig{
 			WgIfaceName:      "utun101",
 			WgAddr:           "100.64.0.1/24",
@@ -263,10 +260,13 @@ func TestEngine_SSH(t *testing.T) {
 			MTU:              iface.DefaultMTU,
 			SSHKey:           sshKey,
 		},
+		EngineServices{
+			SignalClient:   &signal.MockClient{},
+			MgmClient:      &mgmt.MockClient{},
+			RelayManager:   relayMgr,
+			StatusRecorder: peer.NewRecorder("https://mgm"),
+		},
 		MobileDependency{},
-		peer.NewRecorder("https://mgm"),
-		nil,
-		nil,
 	)
 
 	engine.dnsServer = &dns.MockServer{
@@ -428,13 +428,18 @@ func TestEngine_UpdateNetworkMap(t *testing.T) {
 	defer cancel()
 
 	relayMgr := relayClient.NewManager(ctx, nil, key.PublicKey().String(), iface.DefaultMTU)
-	engine := NewEngine(ctx, cancel, &signal.MockClient{}, &mgmt.MockClient{}, relayMgr, &EngineConfig{
+	engine := NewEngine(ctx, cancel, &EngineConfig{
 		WgIfaceName:  "utun102",
 		WgAddr:       "100.64.0.1/24",
 		WgPrivateKey: key,
 		WgPort:       33100,
 		MTU:          iface.DefaultMTU,
-	}, MobileDependency{}, peer.NewRecorder("https://mgm"), nil, nil)
+	}, EngineServices{
+		SignalClient:   &signal.MockClient{},
+		MgmClient:      &mgmt.MockClient{},
+		RelayManager:   relayMgr,
+		StatusRecorder: peer.NewRecorder("https://mgm"),
+	}, MobileDependency{})
 
 	wgIface := &MockWGIface{
 		NameFunc: func() string { return "utun102" },
@@ -647,13 +652,18 @@ func TestEngine_Sync(t *testing.T) {
 		return nil
 	}
 	relayMgr := relayClient.NewManager(ctx, nil, key.PublicKey().String(), iface.DefaultMTU)
-	engine := NewEngine(ctx, cancel, &signal.MockClient{}, &mgmt.MockClient{SyncFunc: syncFunc}, relayMgr, &EngineConfig{
+	engine := NewEngine(ctx, cancel, &EngineConfig{
 		WgIfaceName:  "utun103",
 		WgAddr:       "100.64.0.1/24",
 		WgPrivateKey: key,
 		WgPort:       33100,
 		MTU:          iface.DefaultMTU,
-	}, MobileDependency{}, peer.NewRecorder("https://mgm"), nil, nil)
+	}, EngineServices{
+		SignalClient:   &signal.MockClient{},
+		MgmClient:      &mgmt.MockClient{SyncFunc: syncFunc},
+		RelayManager:   relayMgr,
+		StatusRecorder: peer.NewRecorder("https://mgm"),
+	}, MobileDependency{})
 	engine.ctx = ctx
 
 	engine.dnsServer = &dns.MockServer{
@@ -812,13 +822,18 @@ func TestEngine_UpdateNetworkMapWithRoutes(t *testing.T) {
 			wgAddr := fmt.Sprintf("100.66.%d.1/24", n)
 
 			relayMgr := relayClient.NewManager(ctx, nil, key.PublicKey().String(), iface.DefaultMTU)
-			engine := NewEngine(ctx, cancel, &signal.MockClient{}, &mgmt.MockClient{}, relayMgr, &EngineConfig{
+			engine := NewEngine(ctx, cancel, &EngineConfig{
 				WgIfaceName:  wgIfaceName,
 				WgAddr:       wgAddr,
 				WgPrivateKey: key,
 				WgPort:       33100,
 				MTU:          iface.DefaultMTU,
-			}, MobileDependency{}, peer.NewRecorder("https://mgm"), nil, nil)
+			}, EngineServices{
+				SignalClient:   &signal.MockClient{},
+				MgmClient:      &mgmt.MockClient{},
+				RelayManager:   relayMgr,
+				StatusRecorder: peer.NewRecorder("https://mgm"),
+			}, MobileDependency{})
 			engine.ctx = ctx
 			newNet, err := stdnet.NewNet(context.Background(), nil)
 			if err != nil {
@@ -1014,13 +1029,18 @@ func TestEngine_UpdateNetworkMapWithDNSUpdate(t *testing.T) {
 			wgAddr := fmt.Sprintf("100.66.%d.1/24", n)
 
 			relayMgr := relayClient.NewManager(ctx, nil, key.PublicKey().String(), iface.DefaultMTU)
-			engine := NewEngine(ctx, cancel, &signal.MockClient{}, &mgmt.MockClient{}, relayMgr, &EngineConfig{
+			engine := NewEngine(ctx, cancel, &EngineConfig{
 				WgIfaceName:  wgIfaceName,
 				WgAddr:       wgAddr,
 				WgPrivateKey: key,
 				WgPort:       33100,
 				MTU:          iface.DefaultMTU,
-			}, MobileDependency{}, peer.NewRecorder("https://mgm"), nil, nil)
+			}, EngineServices{
+				SignalClient:   &signal.MockClient{},
+				MgmClient:      &mgmt.MockClient{},
+				RelayManager:   relayMgr,
+				StatusRecorder: peer.NewRecorder("https://mgm"),
+			}, MobileDependency{})
 			engine.ctx = ctx
 
 			newNet, err := stdnet.NewNet(context.Background(), nil)
@@ -1546,7 +1566,12 @@ func createEngine(ctx context.Context, cancel context.CancelFunc, setupKey strin
 	}
 
 	relayMgr := relayClient.NewManager(ctx, nil, key.PublicKey().String(), iface.DefaultMTU)
-	e, err := NewEngine(ctx, cancel, signalClient, mgmtClient, relayMgr, conf, MobileDependency{}, peer.NewRecorder("https://mgm"), nil, nil), nil
+	e, err := NewEngine(ctx, cancel, conf, EngineServices{
+		SignalClient:   signalClient,
+		MgmClient:      mgmtClient,
+		RelayManager:   relayMgr,
+		StatusRecorder: peer.NewRecorder("https://mgm"),
+	}, MobileDependency{}), nil
 	e.ctx = ctx
 	return e, err
 }

client/internal/expose/manager.go

@@ -0,0 +1,97 @@
+package expose
+
+import (
+	"context"
+	"time"
+
+	mgm "github.com/netbirdio/netbird/shared/management/client"
+	log "github.com/sirupsen/logrus"
+)
+
+const renewTimeout = 10 * time.Second
+
+// Response holds the response from exposing a service.
+type Response struct {
+	ServiceName      string
+	ServiceURL       string
+	Domain           string
+	PortAutoAssigned bool
+}
+
+type Request struct {
+	NamePrefix string
+	Domain     string
+	Port       uint16
+	Protocol   int
+	Pin        string
+	Password   string
+	UserGroups []string
+	ListenPort uint16
+}
+
+type ManagementClient interface {
+	CreateExpose(ctx context.Context, req mgm.ExposeRequest) (*mgm.ExposeResponse, error)
+	RenewExpose(ctx context.Context, domain string) error
+	StopExpose(ctx context.Context, domain string) error
+}
+
+// Manager handles expose session lifecycle via the management client.
+type Manager struct {
+	mgmClient ManagementClient
+	ctx       context.Context
+}
+
+// NewManager creates a new expose Manager using the given management client.
+func NewManager(ctx context.Context, mgmClient ManagementClient) *Manager {
+	return &Manager{mgmClient: mgmClient, ctx: ctx}
+}
+
+// Expose creates a new expose session via the management server.
+func (m *Manager) Expose(ctx context.Context, req Request) (*Response, error) {
+	log.Infof("exposing service on port %d", req.Port)
+	resp, err := m.mgmClient.CreateExpose(ctx, toClientExposeRequest(req))
+	if err != nil {
+		return nil, err
+	}
+
+	log.Infof("expose session created for %s", resp.Domain)
+
+	return fromClientExposeResponse(resp), nil
+}
+
+func (m *Manager) KeepAlive(ctx context.Context, domain string) error {
+	ticker := time.NewTicker(30 * time.Second)
+	defer ticker.Stop()
+	defer m.stop(domain)
+
+	for {
+		select {
+		case <-ctx.Done():
+			log.Infof("context canceled, stopping keep alive for %s", domain)
+
+			return nil
+		case <-ticker.C:
+			if err := m.renew(ctx, domain); err != nil {
+				log.Errorf("renewing expose session for %s: %v", domain, err)
+				return err
+			}
+		}
+	}
+}
+
+// renew extends the TTL of an active expose session.
+func (m *Manager) renew(ctx context.Context, domain string) error {
+	renewCtx, cancel := context.WithTimeout(ctx, renewTimeout)
+	defer cancel()
+	return m.mgmClient.RenewExpose(renewCtx, domain)
+}
+
+// stop terminates an active expose session.
+func (m *Manager) stop(domain string) {
+	stopCtx, cancel := context.WithTimeout(m.ctx, renewTimeout)
+	defer cancel()
+	err := m.mgmClient.StopExpose(stopCtx, domain)
+	if err != nil {
+		log.Warnf("Failed stopping expose session for %s: %v", domain, err)
+	}
+}

client/internal/expose/manager_test.go

@@ -0,0 +1,95 @@
+package expose
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	daemonProto "github.com/netbirdio/netbird/client/proto"
+	mgm "github.com/netbirdio/netbird/shared/management/client"
+)
+
+func TestManager_Expose_Success(t *testing.T) {
+	mock := &mgm.MockClient{
+		CreateExposeFunc: func(ctx context.Context, req mgm.ExposeRequest) (*mgm.ExposeResponse, error) {
+			return &mgm.ExposeResponse{
+				ServiceName: "my-service",
+				ServiceURL:  "https://my-service.example.com",
+				Domain:      "my-service.example.com",
+			}, nil
+		},
+	}
+
+	m := NewManager(context.Background(), mock)
+	result, err := m.Expose(context.Background(), Request{Port: 8080})
+	require.NoError(t, err)
+	assert.Equal(t, "my-service", result.ServiceName, "service name should match")
+	assert.Equal(t, "https://my-service.example.com", result.ServiceURL, "service URL should match")
+	assert.Equal(t, "my-service.example.com", result.Domain, "domain should match")
+}
+
+func TestManager_Expose_Error(t *testing.T) {
+	mock := &mgm.MockClient{
+		CreateExposeFunc: func(ctx context.Context, req mgm.ExposeRequest) (*mgm.ExposeResponse, error) {
+			return nil, errors.New("permission denied")
+		},
+	}
+
+	m := NewManager(context.Background(), mock)
+	_, err := m.Expose(context.Background(), Request{Port: 8080})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "permission denied", "error should propagate")
+}
+
+func TestManager_Renew_Success(t *testing.T) {
+	mock := &mgm.MockClient{
+		RenewExposeFunc: func(ctx context.Context, domain string) error {
+			assert.Equal(t, "my-service.example.com", domain, "domain should be passed through")
+			return nil
+		},
+	}
+
+	m := NewManager(context.Background(), mock)
+	err := m.renew(context.Background(), "my-service.example.com")
+	require.NoError(t, err)
+}
+
+func TestManager_Renew_Timeout(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	mock := &mgm.MockClient{
+		RenewExposeFunc: func(ctx context.Context, domain string) error {
+			return ctx.Err()
+		},
+	}
+
+	m := NewManager(ctx, mock)
+	err := m.renew(ctx, "my-service.example.com")
+	require.Error(t, err)
+}
+
+func TestNewRequest(t *testing.T) {
+	req := &daemonProto.ExposeServiceRequest{
+		Port:       8080,
+		Protocol:   daemonProto.ExposeProtocol_EXPOSE_HTTPS,
+		Pin:        "123456",
+		Password:   "secret",
+		UserGroups: []string{"group1", "group2"},
+		Domain:     "custom.example.com",
+		NamePrefix: "my-prefix",
+	}
+
+	exposeReq := NewRequest(req)
+
+	assert.Equal(t, uint16(8080), exposeReq.Port, "port should match")
+	assert.Equal(t, int(daemonProto.ExposeProtocol_EXPOSE_HTTPS), exposeReq.Protocol, "protocol should match")
+	assert.Equal(t, "123456", exposeReq.Pin, "pin should match")
+	assert.Equal(t, "secret", exposeReq.Password, "password should match")
+	assert.Equal(t, []string{"group1", "group2"}, exposeReq.UserGroups, "user groups should match")
+	assert.Equal(t, "custom.example.com", exposeReq.Domain, "domain should match")
+	assert.Equal(t, "my-prefix", exposeReq.NamePrefix, "name prefix should match")
+}

client/internal/expose/request.go

@@ -0,0 +1,42 @@
+package expose
+
+import (
+	daemonProto "github.com/netbirdio/netbird/client/proto"
+	mgm "github.com/netbirdio/netbird/shared/management/client"
+)
+
+// NewRequest converts a daemon ExposeServiceRequest to a management ExposeServiceRequest.
+func NewRequest(req *daemonProto.ExposeServiceRequest) *Request {
+	return &Request{
+		Port:       uint16(req.Port),
+		Protocol:   int(req.Protocol),
+		Pin:        req.Pin,
+		Password:   req.Password,
+		UserGroups: req.UserGroups,
+		Domain:     req.Domain,
+		NamePrefix: req.NamePrefix,
+		ListenPort: uint16(req.ListenPort),
+	}
+}
+
+func toClientExposeRequest(req Request) mgm.ExposeRequest {
+	return mgm.ExposeRequest{
+		NamePrefix: req.NamePrefix,
+		Domain:     req.Domain,
+		Port:       req.Port,
+		Protocol:   req.Protocol,
+		Pin:        req.Pin,
+		Password:   req.Password,
+		UserGroups: req.UserGroups,
+		ListenPort: req.ListenPort,
+	}
+}
+
+func fromClientExposeResponse(response *mgm.ExposeResponse) *Response {
+	return &Response{
+		ServiceName:      response.ServiceName,
+		Domain:           response.Domain,
+		ServiceURL:       response.ServiceURL,
+		PortAutoAssigned: response.PortAutoAssigned,
+	}
+}

client/internal/networkmonitor/check_change_common.go

@@ -22,51 +22,56 @@ func prepareFd() (int, error) {
 
 func routeCheck(ctx context.Context, fd int, nexthopv4, nexthopv6 systemops.Nexthop) error {
 	for {
-		select {
-		case <-ctx.Done():
-			return ctx.Err()
-		default:
-			buf := make([]byte, 2048)
-			n, err := unix.Read(fd, buf)
+		// Wait until fd is readable or context is cancelled, to avoid a busy-loop
+		// when the routing socket returns EAGAIN (e.g. immediately after wakeup).
+		if err := waitReadable(ctx, fd); err != nil {
+			return err
+		}
+
+		buf := make([]byte, 2048)
+		n, err := unix.Read(fd, buf)
+		if err != nil {
+			if errors.Is(err, unix.EAGAIN) || errors.Is(err, unix.EINTR) {
+				continue
+			}
+			if errors.Is(err, unix.EBADF) || errors.Is(err, unix.EINVAL) {
+				return fmt.Errorf("routing socket closed: %w", err)
+			}
+			return fmt.Errorf("read routing socket: %w", err)
+		}
+
+		if n < unix.SizeofRtMsghdr {
+			log.Debugf("Network monitor: read from routing socket returned less than expected: %d bytes", n)
+			continue
+		}
+
+		msg := (*unix.RtMsghdr)(unsafe.Pointer(&buf[0]))
+
+		switch msg.Type {
+		// handle route changes
+		case unix.RTM_ADD, syscall.RTM_DELETE:
+			route, err := parseRouteMessage(buf[:n])
 			if err != nil {
-				if !errors.Is(err, unix.EBADF) && !errors.Is(err, unix.EINVAL) {
-					log.Warnf("Network monitor: failed to read from routing socket: %v", err)
-				}
-				continue
-			}
-			if n < unix.SizeofRtMsghdr {
-				log.Debugf("Network monitor: read from routing socket returned less than expected: %d bytes", n)
+				log.Debugf("Network monitor: error parsing routing message: %v", err)
 				continue
 			}
 
-			msg := (*unix.RtMsghdr)(unsafe.Pointer(&buf[0]))
+			if route.Dst.Bits() != 0 {
+				continue
+			}
 
+			intf := "<nil>"
+			if route.Interface != nil {
+				intf = route.Interface.Name
+			}
 			switch msg.Type {
-			// handle route changes
-			case unix.RTM_ADD, syscall.RTM_DELETE:
-				route, err := parseRouteMessage(buf[:n])
-				if err != nil {
-					log.Debugf("Network monitor: error parsing routing message: %v", err)
-					continue
-				}
-
-				if route.Dst.Bits() != 0 {
-					continue
-				}
-
-				intf := "<nil>"
-				if route.Interface != nil {
-					intf = route.Interface.Name
-				}
-				switch msg.Type {
-				case unix.RTM_ADD:
-					log.Infof("Network monitor: default route changed: via %s, interface %s", route.Gw, intf)
+			case unix.RTM_ADD:
+				log.Infof("Network monitor: default route changed: via %s, interface %s", route.Gw, intf)
+				return nil
+			case unix.RTM_DELETE:
+				if nexthopv4.Intf != nil && route.Gw.Compare(nexthopv4.IP) == 0 || nexthopv6.Intf != nil && route.Gw.Compare(nexthopv6.IP) == 0 {
+					log.Infof("Network monitor: default route removed: via %s, interface %s", route.Gw, intf)
 					return nil
-				case unix.RTM_DELETE:
-					if nexthopv4.Intf != nil && route.Gw.Compare(nexthopv4.IP) == 0 || nexthopv6.Intf != nil && route.Gw.Compare(nexthopv6.IP) == 0 {
-						log.Infof("Network monitor: default route removed: via %s, interface %s", route.Gw, intf)
-						return nil
-					}
 				}
 			}
 		}
@@ -90,3 +95,33 @@ func parseRouteMessage(buf []byte) (*systemops.Route, error) {
 
 	return systemops.MsgToRoute(msg)
 }
+
+// waitReadable blocks until fd has data to read, or ctx is cancelled.
+func waitReadable(ctx context.Context, fd int) error {
+	var fdset unix.FdSet
+	if fd < 0 || fd/unix.NFDBITS >= len(fdset.Bits) {
+		return fmt.Errorf("fd %d out of range for FdSet", fd)
+	}
+
+	for {
+		if err := ctx.Err(); err != nil {
+			return err
+		}
+
+		fdset = unix.FdSet{}
+		fdset.Set(fd)
+		// Use a 1-second timeout so we can re-check ctx periodically.
+		tv := unix.Timeval{Sec: 1}
+		n, err := unix.Select(fd+1, &fdset, nil, nil, &tv)
+		if err != nil {
+			if errors.Is(err, unix.EINTR) {
+				continue
+			}
+			return fmt.Errorf("select on routing socket: %w", err)
+		}
+		if n > 0 {
+			return nil
+		}
+		// timeout — loop back and re-check ctx
+	}
+}

client/internal/peer/conn.go

@@ -3,7 +3,6 @@ package peer
 import (
 	"context"
 	"fmt"
-	"math/rand"
 	"net"
 	"net/netip"
 	"runtime"
@@ -22,10 +21,10 @@ import (
 	icemaker "github.com/netbirdio/netbird/client/internal/peer/ice"
 	"github.com/netbirdio/netbird/client/internal/peer/id"
 	"github.com/netbirdio/netbird/client/internal/peer/worker"
+	"github.com/netbirdio/netbird/client/internal/portforward"
 	"github.com/netbirdio/netbird/client/internal/stdnet"
 	"github.com/netbirdio/netbird/route"
 	relayClient "github.com/netbirdio/netbird/shared/relay/client"
-	semaphoregroup "github.com/netbirdio/netbird/util/semaphore-group"
 )
 
 type ServiceDependencies struct {
@@ -34,8 +33,8 @@ type ServiceDependencies struct {
 	IFaceDiscover      stdnet.ExternalIFaceDiscover
 	RelayManager       *relayClient.Manager
 	SrWatcher          *guard.SRWatcher
-	Semaphore          *semaphoregroup.SemaphoreGroup
 	PeerConnDispatcher *dispatcher.ConnectionDispatcher
+	PortForwardManager *portforward.Manager
 }
 
 type WgConfig struct {
@@ -77,16 +76,17 @@ type ConnConfig struct {
 }
 
 type Conn struct {
-	Log            *log.Entry
-	mu             sync.Mutex
-	ctx            context.Context
-	ctxCancel      context.CancelFunc
-	config         ConnConfig
-	statusRecorder *Status
-	signaler       *Signaler
-	iFaceDiscover  stdnet.ExternalIFaceDiscover
-	relayManager   *relayClient.Manager
-	srWatcher      *guard.SRWatcher
+	Log                *log.Entry
+	mu                 sync.Mutex
+	ctx                context.Context
+	ctxCancel          context.CancelFunc
+	config             ConnConfig
+	statusRecorder     *Status
+	signaler           *Signaler
+	iFaceDiscover      stdnet.ExternalIFaceDiscover
+	relayManager       *relayClient.Manager
+	srWatcher          *guard.SRWatcher
+	portForwardManager *portforward.Manager
 
 	onConnected                               func(remoteWireGuardKey string, remoteRosenpassPubKey []byte, wireGuardIP string, remoteRosenpassAddr string)
 	onDisconnected                            func(remotePeer string)
@@ -111,9 +111,8 @@ type Conn struct {
 	wgProxyRelay wgproxy.Proxy
 	handshaker   *Handshaker
 
-	guard     *guard.Guard
-	semaphore *semaphoregroup.SemaphoreGroup
-	wg        sync.WaitGroup
+	guard *guard.Guard
+	wg    sync.WaitGroup
 
 	// debug purpose
 	dumpState *stateDump
@@ -132,19 +131,19 @@ func NewConn(config ConnConfig, services ServiceDependencies) (*Conn, error) {
 
 	dumpState := newStateDump(config.Key, connLog, services.StatusRecorder)
 	var conn = &Conn{
-		Log:             connLog,
-		config:          config,
-		statusRecorder:  services.StatusRecorder,
-		signaler:        services.Signaler,
-		iFaceDiscover:   services.IFaceDiscover,
-		relayManager:    services.RelayManager,
-		srWatcher:       services.SrWatcher,
-		semaphore:       services.Semaphore,
-		statusRelay:     worker.NewAtomicStatus(),
-		statusICE:       worker.NewAtomicStatus(),
-		dumpState:       dumpState,
-		endpointUpdater: NewEndpointUpdater(connLog, config.WgConfig, isController(config)),
-		wgWatcher:       NewWGWatcher(connLog, config.WgConfig.WgInterface, config.Key, dumpState),
+		Log:                connLog,
+		config:             config,
+		statusRecorder:     services.StatusRecorder,
+		signaler:           services.Signaler,
+		iFaceDiscover:      services.IFaceDiscover,
+		relayManager:       services.RelayManager,
+		srWatcher:          services.SrWatcher,
+		portForwardManager: services.PortForwardManager,
+		statusRelay:        worker.NewAtomicStatus(),
+		statusICE:          worker.NewAtomicStatus(),
+		dumpState:          dumpState,
+		endpointUpdater:    NewEndpointUpdater(connLog, config.WgConfig, isController(config)),
+		wgWatcher:          NewWGWatcher(connLog, config.WgConfig.WgInterface, config.Key, dumpState),
 	}
 
 	return conn, nil
@@ -154,15 +153,10 @@ func NewConn(config ConnConfig, services ServiceDependencies) (*Conn, error) {
 // It will try to establish a connection using ICE and in parallel with relay. The higher priority connection type will
 // be used.
 func (conn *Conn) Open(engineCtx context.Context) error {
-	if err := conn.semaphore.Add(engineCtx); err != nil {
-		return err
-	}
-
 	conn.mu.Lock()
 	defer conn.mu.Unlock()
 
 	if conn.opened {
-		conn.semaphore.Done()
 		return nil
 	}
 
@@ -173,7 +167,6 @@ func (conn *Conn) Open(engineCtx context.Context) error {
 	relayIsSupportedLocally := conn.workerRelay.RelayIsSupportedLocally()
 	workerICE, err := NewWorkerICE(conn.ctx, conn.Log, conn.config, conn, conn.signaler, conn.iFaceDiscover, conn.statusRecorder, relayIsSupportedLocally)
 	if err != nil {
-		conn.semaphore.Done()
 		return err
 	}
 	conn.workerICE = workerICE
@@ -207,10 +200,6 @@ func (conn *Conn) Open(engineCtx context.Context) error {
 	conn.wg.Add(1)
 	go func() {
 		defer conn.wg.Done()
-
-		conn.waitInitialRandomSleepTime(conn.ctx)
-		conn.semaphore.Done()
-
 		conn.guard.Start(conn.ctx, conn.onGuardEvent)
 	}()
 	conn.opened = true
@@ -670,19 +659,6 @@ func (conn *Conn) doOnConnected(remoteRosenpassPubKey []byte, remoteRosenpassAdd
 	}
 }
 
-func (conn *Conn) waitInitialRandomSleepTime(ctx context.Context) {
-	maxWait := 300
-	duration := time.Duration(rand.Intn(maxWait)) * time.Millisecond
-
-	timeout := time.NewTimer(duration)
-	defer timeout.Stop()
-
-	select {
-	case <-ctx.Done():
-	case <-timeout.C:
-	}
-}
-
 func (conn *Conn) isRelayed() bool {
 	switch conn.currentConnPriority {
 	case conntype.Relay, conntype.ICETurn:

client/internal/peer/conn_test.go

@@ -15,7 +15,6 @@ import (
 	"github.com/netbirdio/netbird/client/internal/peer/ice"
 	"github.com/netbirdio/netbird/client/internal/stdnet"
 	"github.com/netbirdio/netbird/util"
-	semaphoregroup "github.com/netbirdio/netbird/util/semaphore-group"
 )
 
 var testDispatcher = dispatcher.NewConnectionDispatcher()
@@ -53,7 +52,6 @@ func TestConn_GetKey(t *testing.T) {
 
 	sd := ServiceDependencies{
 		SrWatcher:          swWatcher,
-		Semaphore:          semaphoregroup.NewSemaphoreGroup(1),
 		PeerConnDispatcher: testDispatcher,
 	}
 	conn, err := NewConn(connConf, sd)
@@ -71,7 +69,6 @@ func TestConn_OnRemoteOffer(t *testing.T) {
 	sd := ServiceDependencies{
 		StatusRecorder:     NewRecorder("https://mgm"),
 		SrWatcher:          swWatcher,
-		Semaphore:          semaphoregroup.NewSemaphoreGroup(1),
 		PeerConnDispatcher: testDispatcher,
 	}
 	conn, err := NewConn(connConf, sd)
@@ -110,7 +107,6 @@ func TestConn_OnRemoteAnswer(t *testing.T) {
 	sd := ServiceDependencies{
 		StatusRecorder:     NewRecorder("https://mgm"),
 		SrWatcher:          swWatcher,
-		Semaphore:          semaphoregroup.NewSemaphoreGroup(1),
 		PeerConnDispatcher: testDispatcher,
 	}
 	conn, err := NewConn(connConf, sd)

client/internal/peer/worker_ice.go

@@ -16,6 +16,7 @@ import (
 	"github.com/netbirdio/netbird/client/iface/udpmux"
 	"github.com/netbirdio/netbird/client/internal/peer/conntype"
 	icemaker "github.com/netbirdio/netbird/client/internal/peer/ice"
+	"github.com/netbirdio/netbird/client/internal/portforward"
 	"github.com/netbirdio/netbird/client/internal/stdnet"
 	"github.com/netbirdio/netbird/route"
 )
@@ -61,6 +62,9 @@ type WorkerICE struct {
 
 	// we record the last known state of the ICE agent to avoid duplicate on disconnected events
 	lastKnownState ice.ConnectionState
+
+	// portForwardAttempted tracks if we've already tried port forwarding this session
+	portForwardAttempted bool
 }
 
 func NewWorkerICE(ctx context.Context, log *log.Entry, config ConnConfig, conn *Conn, signaler *Signaler, ifaceDiscover stdnet.ExternalIFaceDiscover, statusRecorder *Status, hasRelayOnLocally bool) (*WorkerICE, error) {
@@ -214,6 +218,8 @@ func (w *WorkerICE) Close() {
 }
 
 func (w *WorkerICE) reCreateAgent(dialerCancel context.CancelFunc, candidates []ice.CandidateType) (*icemaker.ThreadSafeAgent, error) {
+	w.portForwardAttempted = false
+
 	agent, err := icemaker.NewAgent(w.ctx, w.iFaceDiscover, w.config.ICEConfig, candidates, w.localUfrag, w.localPwd)
 	if err != nil {
 		return nil, fmt.Errorf("create agent: %w", err)
@@ -370,6 +376,93 @@ func (w *WorkerICE) onICECandidate(candidate ice.Candidate) {
 			w.log.Errorf("failed signaling candidate to the remote peer %s %s", w.config.Key, err)
 		}
 	}()
+
+	if candidate.Type() == ice.CandidateTypeServerReflexive {
+		w.injectPortForwardedCandidate(candidate)
+	}
+}
+
+// injectPortForwardedCandidate signals an additional candidate using the pre-created port mapping.
+func (w *WorkerICE) injectPortForwardedCandidate(srflxCandidate ice.Candidate) {
+	pfManager := w.conn.portForwardManager
+	if pfManager == nil {
+		return
+	}
+
+	mapping := pfManager.GetMapping()
+	if mapping == nil {
+		return
+	}
+
+	w.muxAgent.Lock()
+	if w.portForwardAttempted {
+		w.muxAgent.Unlock()
+		return
+	}
+	w.portForwardAttempted = true
+	w.muxAgent.Unlock()
+
+	forwardedCandidate, err := w.createForwardedCandidate(srflxCandidate, mapping)
+	if err != nil {
+		w.log.Warnf("create forwarded candidate: %v", err)
+		return
+	}
+
+	w.log.Debugf("injecting port-forwarded candidate: %s (mapping: %d -> %d via %s, priority: %d)",
+		forwardedCandidate.String(), mapping.InternalPort, mapping.ExternalPort, mapping.NATType, forwardedCandidate.Priority())
+
+	go func() {
+		if err := w.signaler.SignalICECandidate(forwardedCandidate, w.config.Key); err != nil {
+			w.log.Errorf("signal port-forwarded candidate: %v", err)
+		}
+	}()
+}
+
+// createForwardedCandidate creates a new server reflexive candidate with the forwarded port.
+// It uses the NAT gateway's external IP with the forwarded port.
+func (w *WorkerICE) createForwardedCandidate(srflxCandidate ice.Candidate, mapping *portforward.Mapping) (ice.Candidate, error) {
+	var externalIP string
+	if mapping.ExternalIP != nil && !mapping.ExternalIP.IsUnspecified() {
+		externalIP = mapping.ExternalIP.String()
+	} else {
+		// Fallback to STUN-discovered address if NAT didn't provide external IP
+		externalIP = srflxCandidate.Address()
+	}
+
+	// Per RFC 8445, the related address for srflx is the base (host candidate address).
+	// If the original srflx has unspecified related address, use its own address as base.
+	relAddr := srflxCandidate.RelatedAddress().Address
+	if relAddr == "" || relAddr == "0.0.0.0" || relAddr == "::" {
+		relAddr = srflxCandidate.Address()
+	}
+
+	// Arbitrary +1000 boost on top of RFC 8445 priority to favor port-forwarded candidates
+	// over regular srflx during ICE connectivity checks.
+	priority := srflxCandidate.Priority() + 1000
+
+	candidate, err := ice.NewCandidateServerReflexive(&ice.CandidateServerReflexiveConfig{
+		Network:   srflxCandidate.NetworkType().String(),
+		Address:   externalIP,
+		Port:      int(mapping.ExternalPort),
+		Component: srflxCandidate.Component(),
+		Priority:  priority,
+		RelAddr:   relAddr,
+		RelPort:   int(mapping.InternalPort),
+	})
+	if err != nil {
+		return nil, fmt.Errorf("create candidate: %w", err)
+	}
+
+	for _, e := range srflxCandidate.Extensions() {
+		if e.Key == ice.ExtensionKeyCandidateID {
+			e.Value = srflxCandidate.ID()
+		}
+		if err := candidate.AddExtension(e); err != nil {
+			return nil, fmt.Errorf("add extension: %w", err)
+		}
+	}
+
+	return candidate, nil
 }
 
 func (w *WorkerICE) onICESelectedCandidatePair(agent *icemaker.ThreadSafeAgent, c1, c2 ice.Candidate) {
@@ -411,10 +504,10 @@ func (w *WorkerICE) logSuccessfulPaths(agent *icemaker.ThreadSafeAgent) {
 			if !lok || !rok {
 				continue
 			}
-			w.log.Debugf("successful ICE path %s: [%s %s %s] <-> [%s %s %s] rtt=%.3fms",
+			w.log.Debugf("successful ICE path %s: [%s %s %s:%d] <-> [%s %s %s:%d] rtt=%.3fms",
 				sessionID,
-				local.NetworkType(), local.Type(), local.Address(),
-				remote.NetworkType(), remote.Type(), remote.Address(),
+				local.NetworkType(), local.Type(), local.Address(), local.Port(),
+				remote.NetworkType(), remote.Type(), remote.Address(), remote.Port(),
 				stat.CurrentRoundTripTime*1000)
 		}
 	}

client/internal/portforward/env.go

@@ -0,0 +1,35 @@
+package portforward
+
+import (
+	"os"
+	"strconv"
+
+	log "github.com/sirupsen/logrus"
+)
+
+const (
+	envDisableNATMapper      = "NB_DISABLE_NAT_MAPPER"
+	envDisablePCPHealthCheck = "NB_DISABLE_PCP_HEALTH_CHECK"
+)
+
+func isDisabledByEnv() bool {
+	return parseBoolEnv(envDisableNATMapper)
+}
+
+func isHealthCheckDisabled() bool {
+	return parseBoolEnv(envDisablePCPHealthCheck)
+}
+
+func parseBoolEnv(key string) bool {
+	val := os.Getenv(key)
+	if val == "" {
+		return false
+	}
+
+	disabled, err := strconv.ParseBool(val)
+	if err != nil {
+		log.Warnf("failed to parse %s: %v", key, err)
+		return false
+	}
+	return disabled
+}

client/internal/portforward/manager.go

@@ -0,0 +1,298 @@
+//go:build !js
+
+package portforward
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"sync"
+	"time"
+
+	"github.com/libp2p/go-nat"
+	log "github.com/sirupsen/logrus"
+
+	"github.com/netbirdio/netbird/client/internal/portforward/pcp"
+)
+
+const (
+	defaultMappingTTL   = 2 * time.Hour
+	renewalInterval     = defaultMappingTTL / 2
+	healthCheckInterval = 1 * time.Minute
+	discoveryTimeout    = 10 * time.Second
+	mappingDescription  = "NetBird"
+)
+
+type Mapping struct {
+	Protocol     string
+	InternalPort uint16
+	ExternalPort uint16
+	ExternalIP   net.IP
+	NATType      string
+}
+
+type Manager struct {
+	cancel context.CancelFunc
+
+	mapping     *Mapping
+	mappingLock sync.Mutex
+
+	wgPort uint16
+
+	done    chan struct{}
+	stopCtx chan context.Context
+
+	// protect exported functions
+	mu sync.Mutex
+}
+
+func NewManager() *Manager {
+	return &Manager{
+		stopCtx: make(chan context.Context, 1),
+	}
+}
+
+func (m *Manager) Start(ctx context.Context, wgPort uint16) {
+	m.mu.Lock()
+	if m.cancel != nil {
+		m.mu.Unlock()
+		return
+	}
+
+	if isDisabledByEnv() {
+		log.Infof("NAT port mapper disabled via %s", envDisableNATMapper)
+		m.mu.Unlock()
+		return
+	}
+
+	if wgPort == 0 {
+		log.Warnf("invalid WireGuard port 0; NAT mapping disabled")
+		m.mu.Unlock()
+		return
+	}
+	m.wgPort = wgPort
+
+	m.done = make(chan struct{})
+	defer close(m.done)
+
+	ctx, m.cancel = context.WithCancel(ctx)
+	m.mu.Unlock()
+
+	gateway, mapping, err := m.setup(ctx)
+	if err != nil {
+		log.Errorf("failed to setup NAT port mapping: %v", err)
+
+		return
+	}
+
+	m.mappingLock.Lock()
+	m.mapping = mapping
+	m.mappingLock.Unlock()
+
+	m.renewLoop(ctx, gateway)
+
+	select {
+	case cleanupCtx := <-m.stopCtx:
+		// block the Start while cleaned up gracefully
+		m.cleanup(cleanupCtx, gateway)
+	default:
+		// return Start immediately and cleanup in background
+		cleanupCtx, cleanupCancel := context.WithTimeout(context.Background(), 10*time.Second)
+		go func() {
+			defer cleanupCancel()
+			m.cleanup(cleanupCtx, gateway)
+		}()
+	}
+}
+
+// GetMapping returns the current mapping if ready, nil otherwise
+func (m *Manager) GetMapping() *Mapping {
+	m.mappingLock.Lock()
+	defer m.mappingLock.Unlock()
+
+	if m.mapping == nil {
+		return nil
+	}
+
+	mapping := *m.mapping
+	return &mapping
+}
+
+// GracefullyStop cancels the manager and attempts to delete the port mapping.
+// After GracefullyStop returns, the manager cannot be restarted.
+func (m *Manager) GracefullyStop(ctx context.Context) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	if m.cancel == nil {
+		return nil
+	}
+
+	// Send cleanup context before cancelling, so Start picks it up after renewLoop exits.
+	m.startTearDown(ctx)
+
+	m.cancel()
+	m.cancel = nil
+
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-m.done:
+		return nil
+	}
+}
+
+func (m *Manager) setup(ctx context.Context) (nat.NAT, *Mapping, error) {
+	discoverCtx, discoverCancel := context.WithTimeout(ctx, discoveryTimeout)
+	defer discoverCancel()
+
+	gateway, err := discoverGateway(discoverCtx)
+	if err != nil {
+		log.Infof("NAT gateway discovery failed: %v (port forwarding disabled)", err)
+		return nil, nil, err
+	}
+
+	log.Infof("discovered NAT gateway: %s", gateway.Type())
+
+	mapping, err := m.createMapping(ctx, gateway)
+	if err != nil {
+		log.Warnf("failed to create port mapping: %v", err)
+		return nil, nil, err
+	}
+	return gateway, mapping, nil
+}
+
+func (m *Manager) createMapping(ctx context.Context, gateway nat.NAT) (*Mapping, error) {
+	ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
+	defer cancel()
+
+	externalPort, err := gateway.AddPortMapping(ctx, "udp", int(m.wgPort), mappingDescription, defaultMappingTTL)
+	if err != nil {
+		return nil, err
+	}
+
+	externalIP, err := gateway.GetExternalAddress()
+	if err != nil {
+		log.Debugf("failed to get external address: %v", err)
+	}
+
+	mapping := &Mapping{
+		Protocol:     "udp",
+		InternalPort: m.wgPort,
+		ExternalPort: uint16(externalPort),
+		ExternalIP:   externalIP,
+		NATType:      gateway.Type(),
+	}
+
+	log.Infof("created port mapping: %d -> %d via %s (external IP: %s)",
+		m.wgPort, externalPort, gateway.Type(), externalIP)
+	return mapping, nil
+}
+
+func (m *Manager) renewLoop(ctx context.Context, gateway nat.NAT) {
+	renewTicker := time.NewTicker(renewalInterval)
+	healthTicker := time.NewTicker(healthCheckInterval)
+	defer renewTicker.Stop()
+	defer healthTicker.Stop()
+
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-renewTicker.C:
+			if err := m.renewMapping(ctx, gateway); err != nil {
+				log.Warnf("failed to renew port mapping: %v", err)
+				continue
+			}
+		case <-healthTicker.C:
+			if m.checkHealthAndRecreate(ctx, gateway) {
+				renewTicker.Reset(renewalInterval)
+			}
+		}
+	}
+}
+
+func (m *Manager) checkHealthAndRecreate(ctx context.Context, gateway nat.NAT) bool {
+	if isHealthCheckDisabled() {
+		return false
+	}
+
+	m.mappingLock.Lock()
+	hasMapping := m.mapping != nil
+	m.mappingLock.Unlock()
+
+	if !hasMapping {
+		return false
+	}
+
+	pcpNAT, ok := gateway.(*pcp.NAT)
+	if !ok {
+		return false
+	}
+
+	ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
+	defer cancel()
+
+	epoch, serverRestarted, err := pcpNAT.CheckServerHealth(ctx)
+	if err != nil {
+		log.Debugf("PCP health check failed: %v", err)
+		return false
+	}
+
+	if serverRestarted {
+		log.Warnf("PCP server restart detected (epoch=%d), recreating port mapping", epoch)
+		if err := m.renewMapping(ctx, gateway); err != nil {
+			log.Errorf("failed to recreate port mapping after server restart: %v", err)
+			return false
+		}
+		return true
+	}
+
+	return false
+}
+
+func (m *Manager) renewMapping(ctx context.Context, gateway nat.NAT) error {
+	ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
+	defer cancel()
+
+	externalPort, err := gateway.AddPortMapping(ctx, m.mapping.Protocol, int(m.mapping.InternalPort), mappingDescription, defaultMappingTTL)
+	if err != nil {
+		return fmt.Errorf("add port mapping: %w", err)
+	}
+
+	if uint16(externalPort) != m.mapping.ExternalPort {
+		log.Warnf("external port changed on renewal: %d -> %d (candidate may be stale)", m.mapping.ExternalPort, externalPort)
+		m.mappingLock.Lock()
+		m.mapping.ExternalPort = uint16(externalPort)
+		m.mappingLock.Unlock()
+	}
+
+	log.Debugf("renewed port mapping: %d -> %d", m.mapping.InternalPort, m.mapping.ExternalPort)
+	return nil
+}
+
+func (m *Manager) cleanup(ctx context.Context, gateway nat.NAT) {
+	m.mappingLock.Lock()
+	mapping := m.mapping
+	m.mapping = nil
+	m.mappingLock.Unlock()
+
+	if mapping == nil {
+		return
+	}
+
+	if err := gateway.DeletePortMapping(ctx, mapping.Protocol, int(mapping.InternalPort)); err != nil {
+		log.Warnf("delete port mapping on stop: %v", err)
+		return
+	}
+
+	log.Infof("deleted port mapping for port %d", mapping.InternalPort)
+}
+
+func (m *Manager) startTearDown(ctx context.Context) {
+	select {
+	case m.stopCtx <- ctx:
+	default:
+	}
+}
+

client/internal/portforward/manager_js.go

@@ -0,0 +1,36 @@
+package portforward
+
+import (
+	"context"
+	"net"
+)
+
+// Mapping represents port mapping information.
+type Mapping struct {
+	Protocol     string
+	InternalPort uint16
+	ExternalPort uint16
+	ExternalIP   net.IP
+	NATType      string
+}
+
+// Manager is a stub for js/wasm builds where NAT-PMP/UPnP is not supported.
+type Manager struct{}
+
+// NewManager returns a stub manager for js/wasm builds.
+func NewManager() *Manager {
+	return &Manager{}
+}
+
+// Start is a no-op on js/wasm: NAT-PMP/UPnP is not available in browser environments.
+func (m *Manager) Start(context.Context, uint16) {
+	// no NAT traversal in wasm
+}
+
+// GracefullyStop is a no-op on js/wasm.
+func (m *Manager) GracefullyStop(context.Context) error { return nil }
+
+// GetMapping always returns nil on js/wasm.
+func (m *Manager) GetMapping() *Mapping {
+	return nil
+}

client/internal/portforward/manager_test.go

@@ -0,0 +1,159 @@
+//go:build !js
+
+package portforward
+
+import (
+	"context"
+	"net"
+	"testing"
+	"time"
+
+	"github.com/libp2p/go-nat"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+type mockNAT struct {
+	natType          string
+	deviceAddr       net.IP
+	externalAddr     net.IP
+	internalAddr     net.IP
+	mappings         map[int]int
+	addMappingErr    error
+	deleteMappingErr error
+}
+
+func newMockNAT() *mockNAT {
+	return &mockNAT{
+		natType:      "Mock-NAT",
+		deviceAddr:   net.ParseIP("192.168.1.1"),
+		externalAddr: net.ParseIP("203.0.113.50"),
+		internalAddr: net.ParseIP("192.168.1.100"),
+		mappings:     make(map[int]int),
+	}
+}
+
+func (m *mockNAT) Type() string {
+	return m.natType
+}
+
+func (m *mockNAT) GetDeviceAddress() (net.IP, error) {
+	return m.deviceAddr, nil
+}
+
+func (m *mockNAT) GetExternalAddress() (net.IP, error) {
+	return m.externalAddr, nil
+}
+
+func (m *mockNAT) GetInternalAddress() (net.IP, error) {
+	return m.internalAddr, nil
+}
+
+func (m *mockNAT) AddPortMapping(ctx context.Context, protocol string, internalPort int, description string, timeout time.Duration) (int, error) {
+	if m.addMappingErr != nil {
+		return 0, m.addMappingErr
+	}
+	externalPort := internalPort
+	m.mappings[internalPort] = externalPort
+	return externalPort, nil
+}
+
+func (m *mockNAT) DeletePortMapping(ctx context.Context, protocol string, internalPort int) error {
+	if m.deleteMappingErr != nil {
+		return m.deleteMappingErr
+	}
+	delete(m.mappings, internalPort)
+	return nil
+}
+
+func TestManager_CreateMapping(t *testing.T) {
+	m := NewManager()
+	m.wgPort = 51820
+
+	gateway := newMockNAT()
+	mapping, err := m.createMapping(context.Background(), gateway)
+	require.NoError(t, err)
+	require.NotNil(t, mapping)
+
+	assert.Equal(t, "udp", mapping.Protocol)
+	assert.Equal(t, uint16(51820), mapping.InternalPort)
+	assert.Equal(t, uint16(51820), mapping.ExternalPort)
+	assert.Equal(t, "Mock-NAT", mapping.NATType)
+	assert.Equal(t, net.ParseIP("203.0.113.50").To4(), mapping.ExternalIP.To4())
+}
+
+func TestManager_GetMapping_ReturnsNilWhenNotReady(t *testing.T) {
+	m := NewManager()
+	assert.Nil(t, m.GetMapping())
+}
+
+func TestManager_GetMapping_ReturnsCopy(t *testing.T) {
+	m := NewManager()
+	m.mapping = &Mapping{
+		Protocol:     "udp",
+		InternalPort: 51820,
+		ExternalPort: 51820,
+	}
+
+	mapping := m.GetMapping()
+	require.NotNil(t, mapping)
+	assert.Equal(t, uint16(51820), mapping.InternalPort)
+
+	// Mutating the returned copy should not affect the manager's mapping.
+	mapping.ExternalPort = 9999
+	assert.Equal(t, uint16(51820), m.GetMapping().ExternalPort)
+}
+
+func TestManager_Cleanup_DeletesMapping(t *testing.T) {
+	m := NewManager()
+	m.mapping = &Mapping{
+		Protocol:     "udp",
+		InternalPort: 51820,
+		ExternalPort: 51820,
+	}
+
+	gateway := newMockNAT()
+	// Seed the mock so we can verify deletion.
+	gateway.mappings[51820] = 51820
+
+	m.cleanup(context.Background(), gateway)
+
+	_, exists := gateway.mappings[51820]
+	assert.False(t, exists, "mapping should be deleted from gateway")
+	assert.Nil(t, m.GetMapping(), "in-memory mapping should be cleared")
+}
+
+func TestManager_Cleanup_NilMapping(t *testing.T) {
+	m := NewManager()
+	gateway := newMockNAT()
+
+	// Should not panic or call gateway.
+	m.cleanup(context.Background(), gateway)
+}
+
+func TestState_Cleanup(t *testing.T) {
+	origDiscover := discoverGateway
+	defer func() { discoverGateway = origDiscover }()
+
+	mockGateway := newMockNAT()
+	mockGateway.mappings[51820] = 51820
+	discoverGateway = func(ctx context.Context) (nat.NAT, error) {
+		return mockGateway, nil
+	}
+
+	state := &State{
+		Protocol:     "udp",
+		InternalPort: 51820,
+	}
+
+	err := state.Cleanup()
+	assert.NoError(t, err)
+
+	_, exists := mockGateway.mappings[51820]
+	assert.False(t, exists, "mapping should be deleted after cleanup")
+}
+
+func TestState_Name(t *testing.T) {
+	state := &State{}
+	assert.Equal(t, "port_forward_state", state.Name())
+}

client/internal/portforward/pcp/client.go

@@ -0,0 +1,408 @@
+package pcp
+
+import (
+	"context"
+	"crypto/rand"
+	"errors"
+	"fmt"
+	"net"
+	"net/netip"
+	"sync"
+	"time"
+
+	log "github.com/sirupsen/logrus"
+)
+
+const (
+	defaultTimeout     = 3 * time.Second
+	responseBufferSize = 128
+
+	// RFC 6887 Section 8.1.1 retry timing
+	initialRetryDelay = 3 * time.Second
+	maxRetryDelay     = 1024 * time.Second
+	maxRetries        = 4 // 3s + 6s + 12s + 24s = 45s total worst case
+)
+
+// Client is a PCP protocol client.
+// All methods are safe for concurrent use.
+type Client struct {
+	gateway netip.Addr
+	timeout time.Duration
+
+	mu sync.Mutex
+	// localIP caches the resolved local IP address.
+	localIP netip.Addr
+	// lastEpoch is the last observed server epoch value.
+	lastEpoch uint32
+	// epochTime tracks when lastEpoch was received for state loss detection.
+	epochTime time.Time
+	// externalIP caches the external IP from the last successful MAP response.
+	externalIP netip.Addr
+	// epochStateLost is set when epoch indicates server restart.
+	epochStateLost bool
+}
+
+// NewClient creates a new PCP client for the gateway at the given IP.
+func NewClient(gateway net.IP) *Client {
+	addr, ok := netip.AddrFromSlice(gateway)
+	if !ok {
+		log.Debugf("invalid gateway IP: %v", gateway)
+	}
+	return &Client{
+		gateway: addr.Unmap(),
+		timeout: defaultTimeout,
+	}
+}
+
+// NewClientWithTimeout creates a new PCP client with a custom timeout.
+func NewClientWithTimeout(gateway net.IP, timeout time.Duration) *Client {
+	addr, ok := netip.AddrFromSlice(gateway)
+	if !ok {
+		log.Debugf("invalid gateway IP: %v", gateway)
+	}
+	return &Client{
+		gateway: addr.Unmap(),
+		timeout: timeout,
+	}
+}
+
+// SetLocalIP sets the local IP address to use in PCP requests.
+func (c *Client) SetLocalIP(ip net.IP) {
+	addr, ok := netip.AddrFromSlice(ip)
+	if !ok {
+		log.Debugf("invalid local IP: %v", ip)
+	}
+	c.mu.Lock()
+	c.localIP = addr.Unmap()
+	c.mu.Unlock()
+}
+
+// Gateway returns the gateway IP address.
+func (c *Client) Gateway() net.IP {
+	return c.gateway.AsSlice()
+}
+
+// Announce sends a PCP ANNOUNCE request to discover PCP support.
+// Returns the server's epoch time on success.
+func (c *Client) Announce(ctx context.Context) (epoch uint32, err error) {
+	localIP, err := c.getLocalIP()
+	if err != nil {
+		return 0, fmt.Errorf("get local IP: %w", err)
+	}
+
+	req := buildAnnounceRequest(localIP)
+	resp, err := c.sendRequest(ctx, req)
+	if err != nil {
+		return 0, fmt.Errorf("send announce: %w", err)
+	}
+
+	parsed, err := parseResponse(resp)
+	if err != nil {
+		return 0, fmt.Errorf("parse announce response: %w", err)
+	}
+
+	if parsed.ResultCode != ResultSuccess {
+		return 0, fmt.Errorf("PCP ANNOUNCE failed: %s", ResultCodeString(parsed.ResultCode))
+	}
+
+	c.mu.Lock()
+	if c.updateEpochLocked(parsed.Epoch) {
+		log.Warnf("PCP server epoch indicates state loss - mappings may need refresh")
+	}
+	c.mu.Unlock()
+	return parsed.Epoch, nil
+}
+
+// AddPortMapping requests a port mapping from the PCP server.
+func (c *Client) AddPortMapping(ctx context.Context, protocol string, internalPort int, lifetime time.Duration) (*MapResponse, error) {
+	return c.addPortMappingWithHint(ctx, protocol, internalPort, internalPort, netip.Addr{}, lifetime)
+}
+
+// AddPortMappingWithHint requests a port mapping with suggested external port and IP.
+// Use lifetime <= 0 to delete a mapping.
+func (c *Client) AddPortMappingWithHint(ctx context.Context, protocol string, internalPort, suggestedExtPort int, suggestedExtIP net.IP, lifetime time.Duration) (*MapResponse, error) {
+	var extIP netip.Addr
+	if suggestedExtIP != nil {
+		var ok bool
+		extIP, ok = netip.AddrFromSlice(suggestedExtIP)
+		if !ok {
+			log.Debugf("invalid suggested external IP: %v", suggestedExtIP)
+		}
+		extIP = extIP.Unmap()
+	}
+	return c.addPortMappingWithHint(ctx, protocol, internalPort, suggestedExtPort, extIP, lifetime)
+}
+
+func (c *Client) addPortMappingWithHint(ctx context.Context, protocol string, internalPort, suggestedExtPort int, suggestedExtIP netip.Addr, lifetime time.Duration) (*MapResponse, error) {
+	localIP, err := c.getLocalIP()
+	if err != nil {
+		return nil, fmt.Errorf("get local IP: %w", err)
+	}
+
+	proto, err := protocolNumber(protocol)
+	if err != nil {
+		return nil, fmt.Errorf("parse protocol: %w", err)
+	}
+
+	var nonce [12]byte
+	if _, err := rand.Read(nonce[:]); err != nil {
+		return nil, fmt.Errorf("generate nonce: %w", err)
+	}
+
+	// Convert lifetime to seconds. Lifetime 0 means delete, so only apply
+	// default for positive durations that round to 0 seconds.
+	var lifetimeSec uint32
+	if lifetime > 0 {
+		lifetimeSec = uint32(lifetime.Seconds())
+		if lifetimeSec == 0 {
+			lifetimeSec = DefaultLifetime
+		}
+	}
+
+	req := buildMapRequest(localIP, nonce, proto, uint16(internalPort), uint16(suggestedExtPort), suggestedExtIP, lifetimeSec)
+
+	resp, err := c.sendRequest(ctx, req)
+	if err != nil {
+		return nil, fmt.Errorf("send map request: %w", err)
+	}
+
+	mapResp, err := parseMapResponse(resp)
+	if err != nil {
+		return nil, fmt.Errorf("parse map response: %w", err)
+	}
+
+	if mapResp.Nonce != nonce {
+		return nil, fmt.Errorf("nonce mismatch in response")
+	}
+
+	if mapResp.Protocol != proto {
+		return nil, fmt.Errorf("protocol mismatch: requested %d, got %d", proto, mapResp.Protocol)
+	}
+	if mapResp.InternalPort != uint16(internalPort) {
+		return nil, fmt.Errorf("internal port mismatch: requested %d, got %d", internalPort, mapResp.InternalPort)
+	}
+
+	if mapResp.ResultCode != ResultSuccess {
+		return nil, &Error{
+			Code:    mapResp.ResultCode,
+			Message: ResultCodeString(mapResp.ResultCode),
+		}
+	}
+
+	c.mu.Lock()
+	if c.updateEpochLocked(mapResp.Epoch) {
+		log.Warnf("PCP server epoch indicates state loss - mappings may need refresh")
+	}
+	c.cacheExternalIPLocked(mapResp.ExternalIP)
+	c.mu.Unlock()
+	return mapResp, nil
+}
+
+// DeletePortMapping removes a port mapping by requesting zero lifetime.
+func (c *Client) DeletePortMapping(ctx context.Context, protocol string, internalPort int) error {
+	if _, err := c.addPortMappingWithHint(ctx, protocol, internalPort, 0, netip.Addr{}, 0); err != nil {
+		var pcpErr *Error
+		if errors.As(err, &pcpErr) && pcpErr.Code == ResultNotAuthorized {
+			return nil
+		}
+		return fmt.Errorf("delete mapping: %w", err)
+	}
+	return nil
+}
+
+// GetExternalAddress returns the external IP address.
+// First checks for a cached value from previous MAP responses.
+// If not cached, creates a short-lived mapping to discover the external IP.
+func (c *Client) GetExternalAddress(ctx context.Context) (net.IP, error) {
+	c.mu.Lock()
+	if c.externalIP.IsValid() {
+		ip := c.externalIP.AsSlice()
+		c.mu.Unlock()
+		return ip, nil
+	}
+	c.mu.Unlock()
+
+	// Use an ephemeral port in the dynamic range (49152-65535).
+	// Port 0 is not valid with UDP/TCP protocols per RFC 6887.
+	ephemeralPort := 49152 + int(uint16(time.Now().UnixNano()))%(65535-49152)
+
+	// Use minimal lifetime (1 second) for discovery.
+	resp, err := c.AddPortMapping(ctx, "udp", ephemeralPort, time.Second)
+	if err != nil {
+		return nil, fmt.Errorf("create temporary mapping: %w", err)
+	}
+
+	if err := c.DeletePortMapping(ctx, "udp", ephemeralPort); err != nil {
+		log.Debugf("cleanup temporary PCP mapping: %v", err)
+	}
+
+	return resp.ExternalIP.AsSlice(), nil
+}
+
+// LastEpoch returns the last observed server epoch value.
+// A decrease in epoch indicates the server may have restarted and mappings may be lost.
+func (c *Client) LastEpoch() uint32 {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	return c.lastEpoch
+}
+
+// EpochStateLost returns true if epoch state loss was detected and clears the flag.
+func (c *Client) EpochStateLost() bool {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	lost := c.epochStateLost
+	c.epochStateLost = false
+	return lost
+}
+
+// updateEpoch updates the epoch tracking and detects potential state loss.
+// Returns true if state loss was detected (server likely restarted).
+// Caller must hold c.mu.
+func (c *Client) updateEpochLocked(newEpoch uint32) bool {
+	now := time.Now()
+	stateLost := false
+
+	// RFC 6887 Section 8.5: Detect invalid epoch indicating server state loss.
+	// client_delta = time since last response
+	// server_delta = epoch change since last response
+	// Invalid if: client_delta+2 < server_delta - server_delta/16
+	//         OR: server_delta+2 < client_delta - client_delta/16
+	// The +2 handles quantization, /16 (6.25%) handles clock drift.
+	if !c.epochTime.IsZero() && c.lastEpoch > 0 {
+		clientDelta := uint32(now.Sub(c.epochTime).Seconds())
+		serverDelta := newEpoch - c.lastEpoch
+
+		// Check for epoch going backwards or jumping unexpectedly.
+		// Subtraction is safe: serverDelta/16 is always <= serverDelta.
+		if clientDelta+2 < serverDelta-(serverDelta/16) ||
+			serverDelta+2 < clientDelta-(clientDelta/16) {
+			stateLost = true
+			c.epochStateLost = true
+		}
+	}
+
+	c.lastEpoch = newEpoch
+	c.epochTime = now
+	return stateLost
+}
+
+// cacheExternalIP stores the external IP from a successful MAP response.
+// Caller must hold c.mu.
+func (c *Client) cacheExternalIPLocked(ip netip.Addr) {
+	if ip.IsValid() && !ip.IsUnspecified() {
+		c.externalIP = ip
+	}
+}
+
+// sendRequest sends a PCP request with retries per RFC 6887 Section 8.1.1.
+func (c *Client) sendRequest(ctx context.Context, req []byte) ([]byte, error) {
+	addr := &net.UDPAddr{IP: c.gateway.AsSlice(), Port: Port}
+
+	var lastErr error
+	delay := initialRetryDelay
+
+	for range maxRetries {
+		resp, err := c.sendOnce(ctx, addr, req)
+		if err == nil {
+			return resp, nil
+		}
+		lastErr = err
+
+		if ctx.Err() != nil {
+			return nil, ctx.Err()
+		}
+
+		// RFC 6887 Section 8.1.1: RT = (1 + RAND) * MIN(2 * RTprev, MRT)
+		// RAND is random between -0.1 and +0.1
+		select {
+		case <-ctx.Done():
+			return nil, ctx.Err()
+		case <-time.After(retryDelayWithJitter(delay)):
+		}
+		delay = min(delay*2, maxRetryDelay)
+	}
+
+	return nil, fmt.Errorf("PCP request failed after %d retries: %w", maxRetries, lastErr)
+}
+
+// retryDelayWithJitter applies RFC 6887 jitter: multiply by (1 + RAND) where RAND is [-0.1, +0.1].
+func retryDelayWithJitter(d time.Duration) time.Duration {
+	var b [1]byte
+	_, _ = rand.Read(b[:])
+	// Convert byte to range [-0.1, +0.1]: (b/255 * 0.2) - 0.1
+	jitter := (float64(b[0])/255.0)*0.2 - 0.1
+	return time.Duration(float64(d) * (1 + jitter))
+}
+
+func (c *Client) sendOnce(ctx context.Context, addr *net.UDPAddr, req []byte) ([]byte, error) {
+	// Use ListenUDP instead of DialUDP to validate response source address per RFC 6887 §8.3.
+	conn, err := net.ListenUDP("udp", nil)
+	if err != nil {
+		return nil, fmt.Errorf("listen: %w", err)
+	}
+	defer func() {
+		if err := conn.Close(); err != nil {
+			log.Debugf("close UDP connection: %v", err)
+		}
+	}()
+
+	timeout := c.timeout
+	if deadline, ok := ctx.Deadline(); ok {
+		if remaining := time.Until(deadline); remaining < timeout {
+			timeout = remaining
+		}
+	}
+
+	if err := conn.SetDeadline(time.Now().Add(timeout)); err != nil {
+		return nil, fmt.Errorf("set deadline: %w", err)
+	}
+
+	if _, err := conn.WriteToUDP(req, addr); err != nil {
+		return nil, fmt.Errorf("write: %w", err)
+	}
+
+	resp := make([]byte, responseBufferSize)
+	n, from, err := conn.ReadFromUDP(resp)
+	if err != nil {
+		return nil, fmt.Errorf("read: %w", err)
+	}
+
+	// RFC 6887 §8.3: Validate response came from expected PCP server.
+	if !from.IP.Equal(addr.IP) {
+		return nil, fmt.Errorf("response from unexpected source %s (expected %s)", from.IP, addr.IP)
+	}
+
+	return resp[:n], nil
+}
+
+func (c *Client) getLocalIP() (netip.Addr, error) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	if !c.localIP.IsValid() {
+		return netip.Addr{}, fmt.Errorf("local IP not set for gateway %s", c.gateway)
+	}
+	return c.localIP, nil
+}
+
+func protocolNumber(protocol string) (uint8, error) {
+	switch protocol {
+	case "udp", "UDP":
+		return ProtoUDP, nil
+	case "tcp", "TCP":
+		return ProtoTCP, nil
+	default:
+		return 0, fmt.Errorf("unsupported protocol: %s", protocol)
+	}
+}
+
+// Error represents a PCP error response.
+type Error struct {
+	Code    uint8
+	Message string
+}
+
+func (e *Error) Error() string {
+	return fmt.Sprintf("PCP error: %s (%d)", e.Message, e.Code)
+}

client/internal/portforward/pcp/client_test.go

@@ -0,0 +1,187 @@
+package pcp
+
+import (
+	"context"
+	"net"
+	"net/netip"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestAddrConversion(t *testing.T) {
+	tests := []struct {
+		name string
+		addr netip.Addr
+	}{
+		{"IPv4", netip.MustParseAddr("192.168.1.100")},
+		{"IPv4 loopback", netip.MustParseAddr("127.0.0.1")},
+		{"IPv6", netip.MustParseAddr("2001:db8::1")},
+		{"IPv6 loopback", netip.MustParseAddr("::1")},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			b16 := addrTo16(tt.addr)
+
+			recovered := addrFrom16(b16)
+			assert.Equal(t, tt.addr, recovered, "address should round-trip")
+		})
+	}
+}
+
+func TestBuildAnnounceRequest(t *testing.T) {
+	clientIP := netip.MustParseAddr("192.168.1.100")
+	req := buildAnnounceRequest(clientIP)
+
+	require.Len(t, req, headerSize)
+	assert.Equal(t, byte(Version), req[0], "version")
+	assert.Equal(t, byte(OpAnnounce), req[1], "opcode")
+
+	// Check client IP is properly encoded as IPv4-mapped IPv6
+	assert.Equal(t, byte(0xff), req[18], "IPv4-mapped prefix byte 10")
+	assert.Equal(t, byte(0xff), req[19], "IPv4-mapped prefix byte 11")
+	assert.Equal(t, byte(192), req[20], "IP octet 1")
+	assert.Equal(t, byte(168), req[21], "IP octet 2")
+	assert.Equal(t, byte(1), req[22], "IP octet 3")
+	assert.Equal(t, byte(100), req[23], "IP octet 4")
+}
+
+func TestBuildMapRequest(t *testing.T) {
+	clientIP := netip.MustParseAddr("192.168.1.100")
+	nonce := [12]byte{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12}
+	req := buildMapRequest(clientIP, nonce, ProtoUDP, 51820, 51820, netip.Addr{}, 3600)
+
+	require.Len(t, req, mapRequestSize)
+	assert.Equal(t, byte(Version), req[0], "version")
+	assert.Equal(t, byte(OpMap), req[1], "opcode")
+
+	// Lifetime at bytes 4-7
+	assert.Equal(t, uint32(3600), (uint32(req[4])<<24)|(uint32(req[5])<<16)|(uint32(req[6])<<8)|uint32(req[7]), "lifetime")
+
+	// Nonce at bytes 24-35
+	assert.Equal(t, nonce[:], req[24:36], "nonce")
+
+	// Protocol at byte 36
+	assert.Equal(t, byte(ProtoUDP), req[36], "protocol")
+
+	// Internal port at bytes 40-41
+	assert.Equal(t, uint16(51820), (uint16(req[40])<<8)|uint16(req[41]), "internal port")
+
+	// External port at bytes 42-43
+	assert.Equal(t, uint16(51820), (uint16(req[42])<<8)|uint16(req[43]), "external port")
+}
+
+func TestParseResponse(t *testing.T) {
+	// Construct a valid ANNOUNCE response
+	resp := make([]byte, headerSize)
+	resp[0] = Version
+	resp[1] = OpAnnounce | OpReply
+	// Result code = 0 (success)
+	// Lifetime = 0
+	// Epoch = 12345
+	resp[8] = 0
+	resp[9] = 0
+	resp[10] = 0x30
+	resp[11] = 0x39
+
+	parsed, err := parseResponse(resp)
+	require.NoError(t, err)
+	assert.Equal(t, uint8(Version), parsed.Version)
+	assert.Equal(t, uint8(OpAnnounce|OpReply), parsed.Opcode)
+	assert.Equal(t, uint8(ResultSuccess), parsed.ResultCode)
+	assert.Equal(t, uint32(12345), parsed.Epoch)
+}
+
+func TestParseResponseErrors(t *testing.T) {
+	t.Run("too short", func(t *testing.T) {
+		_, err := parseResponse([]byte{1, 2, 3})
+		assert.Error(t, err)
+	})
+
+	t.Run("wrong version", func(t *testing.T) {
+		resp := make([]byte, headerSize)
+		resp[0] = 1 // Wrong version
+		resp[1] = OpReply
+		_, err := parseResponse(resp)
+		assert.Error(t, err)
+	})
+
+	t.Run("missing reply bit", func(t *testing.T) {
+		resp := make([]byte, headerSize)
+		resp[0] = Version
+		resp[1] = OpAnnounce // Missing OpReply bit
+		_, err := parseResponse(resp)
+		assert.Error(t, err)
+	})
+}
+
+func TestResultCodeString(t *testing.T) {
+	assert.Equal(t, "SUCCESS", ResultCodeString(ResultSuccess))
+	assert.Equal(t, "NOT_AUTHORIZED", ResultCodeString(ResultNotAuthorized))
+	assert.Equal(t, "ADDRESS_MISMATCH", ResultCodeString(ResultAddressMismatch))
+	assert.Contains(t, ResultCodeString(255), "UNKNOWN")
+}
+
+func TestProtocolNumber(t *testing.T) {
+	proto, err := protocolNumber("udp")
+	require.NoError(t, err)
+	assert.Equal(t, uint8(ProtoUDP), proto)
+
+	proto, err = protocolNumber("tcp")
+	require.NoError(t, err)
+	assert.Equal(t, uint8(ProtoTCP), proto)
+
+	proto, err = protocolNumber("UDP")
+	require.NoError(t, err)
+	assert.Equal(t, uint8(ProtoUDP), proto)
+
+	_, err = protocolNumber("icmp")
+	assert.Error(t, err)
+}
+
+func TestClientCreation(t *testing.T) {
+	gateway := netip.MustParseAddr("192.168.1.1").AsSlice()
+
+	client := NewClient(gateway)
+	assert.Equal(t, net.IP(gateway), client.Gateway())
+	assert.Equal(t, defaultTimeout, client.timeout)
+
+	clientWithTimeout := NewClientWithTimeout(gateway, 5*time.Second)
+	assert.Equal(t, 5*time.Second, clientWithTimeout.timeout)
+}
+
+func TestNATType(t *testing.T) {
+	n := NewNAT(netip.MustParseAddr("192.168.1.1").AsSlice(), netip.MustParseAddr("192.168.1.100").AsSlice())
+	assert.Equal(t, "PCP", n.Type())
+}
+
+// Integration test - skipped unless PCP_TEST_GATEWAY env is set
+func TestClientIntegration(t *testing.T) {
+	t.Skip("Integration test - run manually with PCP_TEST_GATEWAY=<gateway-ip>")
+
+	gateway := netip.MustParseAddr("10.0.1.1").AsSlice()   // Change to your test gateway
+	localIP := netip.MustParseAddr("10.0.1.100").AsSlice() // Change to your local IP
+
+	client := NewClient(gateway)
+	client.SetLocalIP(localIP)
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	// Test ANNOUNCE
+	epoch, err := client.Announce(ctx)
+	require.NoError(t, err)
+	t.Logf("Server epoch: %d", epoch)
+
+	// Test MAP
+	resp, err := client.AddPortMapping(ctx, "udp", 51820, 1*time.Hour)
+	require.NoError(t, err)
+	t.Logf("Mapping: internal=%d external=%d externalIP=%s",
+		resp.InternalPort, resp.ExternalPort, resp.ExternalIP)
+
+	// Cleanup
+	err = client.DeletePortMapping(ctx, "udp", 51820)
+	require.NoError(t, err)
+}

client/internal/portforward/pcp/nat.go

@@ -0,0 +1,209 @@
+package pcp
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"net/netip"
+	"sync"
+	"time"
+
+	log "github.com/sirupsen/logrus"
+
+	"github.com/libp2p/go-nat"
+	"github.com/libp2p/go-netroute"
+)
+
+var _ nat.NAT = (*NAT)(nil)
+
+// NAT implements the go-nat NAT interface using PCP.
+// Supports dual-stack (IPv4 and IPv6) when available.
+// All methods are safe for concurrent use.
+//
+// TODO: IPv6 pinholes use the local IPv6 address. If the address changes
+// (e.g., due to SLAAC rotation or network change), the pinhole becomes stale
+// and needs to be recreated with the new address.
+type NAT struct {
+	client *Client
+
+	mu sync.RWMutex
+	// client6 is the IPv6 PCP client, nil if IPv6 is unavailable.
+	client6 *Client
+	// localIP6 caches the local IPv6 address used for PCP requests.
+	localIP6 netip.Addr
+}
+
+// NewNAT creates a new NAT instance backed by PCP.
+func NewNAT(gateway, localIP net.IP) *NAT {
+	client := NewClient(gateway)
+	client.SetLocalIP(localIP)
+	return &NAT{
+		client: client,
+	}
+}
+
+// Type returns "PCP" as the NAT type.
+func (n *NAT) Type() string {
+	return "PCP"
+}
+
+// GetDeviceAddress returns the gateway IP address.
+func (n *NAT) GetDeviceAddress() (net.IP, error) {
+	return n.client.Gateway(), nil
+}
+
+// GetExternalAddress returns the external IP address.
+func (n *NAT) GetExternalAddress() (net.IP, error) {
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	return n.client.GetExternalAddress(ctx)
+}
+
+// GetInternalAddress returns the local IP address used to communicate with the gateway.
+func (n *NAT) GetInternalAddress() (net.IP, error) {
+	addr, err := n.client.getLocalIP()
+	if err != nil {
+		return nil, err
+	}
+	return addr.AsSlice(), nil
+}
+
+// AddPortMapping creates a port mapping on both IPv4 and IPv6 (if available).
+func (n *NAT) AddPortMapping(ctx context.Context, protocol string, internalPort int, _ string, timeout time.Duration) (int, error) {
+	resp, err := n.client.AddPortMapping(ctx, protocol, internalPort, timeout)
+	if err != nil {
+		return 0, fmt.Errorf("add mapping: %w", err)
+	}
+
+	n.mu.RLock()
+	client6 := n.client6
+	localIP6 := n.localIP6
+	n.mu.RUnlock()
+
+	if client6 == nil {
+		return int(resp.ExternalPort), nil
+	}
+
+	if _, err := client6.AddPortMapping(ctx, protocol, internalPort, timeout); err != nil {
+		log.Warnf("IPv6 PCP mapping failed (continuing with IPv4): %v", err)
+		return int(resp.ExternalPort), nil
+	}
+
+	log.Infof("created IPv6 PCP pinhole: %s:%d", localIP6, internalPort)
+	return int(resp.ExternalPort), nil
+}
+
+// DeletePortMapping removes a port mapping from both IPv4 and IPv6.
+func (n *NAT) DeletePortMapping(ctx context.Context, protocol string, internalPort int) error {
+	err := n.client.DeletePortMapping(ctx, protocol, internalPort)
+
+	n.mu.RLock()
+	client6 := n.client6
+	n.mu.RUnlock()
+
+	if client6 != nil {
+		if err6 := client6.DeletePortMapping(ctx, protocol, internalPort); err6 != nil {
+			log.Warnf("IPv6 PCP delete mapping failed: %v", err6)
+		}
+	}
+
+	if err != nil {
+		return fmt.Errorf("delete mapping: %w", err)
+	}
+	return nil
+}
+
+// CheckServerHealth sends an ANNOUNCE to verify the server is still responsive.
+// Returns the current epoch and whether the server may have restarted (epoch state loss detected).
+func (n *NAT) CheckServerHealth(ctx context.Context) (epoch uint32, serverRestarted bool, err error) {
+	epoch, err = n.client.Announce(ctx)
+	if err != nil {
+		return 0, false, fmt.Errorf("announce: %w", err)
+	}
+	return epoch, n.client.EpochStateLost(), nil
+}
+
+// DiscoverPCP attempts to discover a PCP-capable gateway.
+// Returns a NAT interface if PCP is supported, or an error otherwise.
+// Discovers both IPv4 and IPv6 gateways when available.
+func DiscoverPCP(ctx context.Context) (nat.NAT, error) {
+	gateway, localIP, err := getDefaultGateway()
+	if err != nil {
+		return nil, fmt.Errorf("get default gateway: %w", err)
+	}
+
+	client := NewClient(gateway)
+	client.SetLocalIP(localIP)
+	if _, err := client.Announce(ctx); err != nil {
+		return nil, fmt.Errorf("PCP announce: %w", err)
+	}
+
+	result := &NAT{client: client}
+	discoverIPv6(ctx, result)
+
+	return result, nil
+}
+
+func discoverIPv6(ctx context.Context, result *NAT) {
+	gateway6, localIP6, err := getDefaultGateway6()
+	if err != nil {
+		log.Debugf("IPv6 gateway discovery failed: %v", err)
+		return
+	}
+
+	client6 := NewClient(gateway6)
+	client6.SetLocalIP(localIP6)
+	if _, err := client6.Announce(ctx); err != nil {
+		log.Debugf("PCP IPv6 announce failed: %v", err)
+		return
+	}
+
+	addr, ok := netip.AddrFromSlice(localIP6)
+	if !ok {
+		log.Debugf("invalid IPv6 local IP: %v", localIP6)
+		return
+	}
+	result.mu.Lock()
+	result.client6 = client6
+	result.localIP6 = addr
+	result.mu.Unlock()
+	log.Debugf("PCP IPv6 gateway discovered: %s (local: %s)", gateway6, localIP6)
+}
+
+// getDefaultGateway returns the default IPv4 gateway and local IP using the system routing table.
+func getDefaultGateway() (gateway net.IP, localIP net.IP, err error) {
+	router, err := netroute.New()
+	if err != nil {
+		return nil, nil, err
+	}
+
+	_, gateway, localIP, err = router.Route(net.IPv4zero)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	if gateway == nil {
+		return nil, nil, nat.ErrNoNATFound
+	}
+
+	return gateway, localIP, nil
+}
+
+// getDefaultGateway6 returns the default IPv6 gateway IP address using the system routing table.
+func getDefaultGateway6() (gateway net.IP, localIP net.IP, err error) {
+	router, err := netroute.New()
+	if err != nil {
+		return nil, nil, err
+	}
+
+	_, gateway, localIP, err = router.Route(net.IPv6zero)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	if gateway == nil {
+		return nil, nil, nat.ErrNoNATFound
+	}
+
+	return gateway, localIP, nil
+}

client/internal/portforward/pcp/protocol.go

@@ -0,0 +1,225 @@
+// Package pcp implements the Port Control Protocol (RFC 6887).
+//
+// # Implemented Features
+//
+//   - ANNOUNCE opcode: Discovers PCP server support
+//   - MAP opcode: Creates/deletes port mappings (IPv4 NAT) and firewall pinholes (IPv6)
+//   - Dual-stack: Simultaneous IPv4 and IPv6 support via separate clients
+//   - Nonce validation: Prevents response spoofing
+//   - Epoch tracking: Detects server restarts per Section 8.5
+//   - RFC-compliant retry timing: 3s initial, exponential backoff to 1024s max (Section 8.1.1)
+//
+// # Not Implemented
+//
+//   - PEER opcode: For outbound peer connections (not needed for inbound NAT traversal)
+//   - THIRD_PARTY option: For managing mappings on behalf of other devices
+//   - PREFER_FAILURE option: Requires exact external port or fail (IPv4 NAT only, not needed for IPv6 pinholing)
+//   - FILTER option: To restrict remote peer addresses
+//
+// These optional features are omitted because the primary use case is simple
+// port forwarding for WireGuard, which only requires MAP with default behavior.
+package pcp
+
+import (
+	"encoding/binary"
+	"fmt"
+	"net/netip"
+)
+
+const (
+	// Version is the PCP protocol version (RFC 6887).
+	Version = 2
+
+	// Port is the standard PCP server port.
+	Port = 5351
+
+	// DefaultLifetime is the default requested mapping lifetime in seconds.
+	DefaultLifetime = 7200 // 2 hours
+
+	// Header sizes
+	headerSize     = 24
+	mapPayloadSize = 36
+	mapRequestSize = headerSize + mapPayloadSize // 60 bytes
+)
+
+// Opcodes
+const (
+	OpAnnounce = 0
+	OpMap      = 1
+	OpPeer     = 2
+	OpReply    = 0x80 // OR'd with opcode in responses
+)
+
+// Protocol numbers for MAP requests
+const (
+	ProtoUDP = 17
+	ProtoTCP = 6
+)
+
+// Result codes (RFC 6887 Section 7.4)
+const (
+	ResultSuccess              = 0
+	ResultUnsuppVersion        = 1
+	ResultNotAuthorized        = 2
+	ResultMalformedRequest     = 3
+	ResultUnsuppOpcode         = 4
+	ResultUnsuppOption         = 5
+	ResultMalformedOption      = 6
+	ResultNetworkFailure       = 7
+	ResultNoResources          = 8
+	ResultUnsuppProtocol       = 9
+	ResultUserExQuota          = 10
+	ResultCannotProvideExt     = 11
+	ResultAddressMismatch      = 12
+	ResultExcessiveRemotePeers = 13
+)
+
+// ResultCodeString returns a human-readable string for a result code.
+func ResultCodeString(code uint8) string {
+	switch code {
+	case ResultSuccess:
+		return "SUCCESS"
+	case ResultUnsuppVersion:
+		return "UNSUPP_VERSION"
+	case ResultNotAuthorized:
+		return "NOT_AUTHORIZED"
+	case ResultMalformedRequest:
+		return "MALFORMED_REQUEST"
+	case ResultUnsuppOpcode:
+		return "UNSUPP_OPCODE"
+	case ResultUnsuppOption:
+		return "UNSUPP_OPTION"
+	case ResultMalformedOption:
+		return "MALFORMED_OPTION"
+	case ResultNetworkFailure:
+		return "NETWORK_FAILURE"
+	case ResultNoResources:
+		return "NO_RESOURCES"
+	case ResultUnsuppProtocol:
+		return "UNSUPP_PROTOCOL"
+	case ResultUserExQuota:
+		return "USER_EX_QUOTA"
+	case ResultCannotProvideExt:
+		return "CANNOT_PROVIDE_EXTERNAL"
+	case ResultAddressMismatch:
+		return "ADDRESS_MISMATCH"
+	case ResultExcessiveRemotePeers:
+		return "EXCESSIVE_REMOTE_PEERS"
+	default:
+		return fmt.Sprintf("UNKNOWN(%d)", code)
+	}
+}
+
+// Response represents a parsed PCP response header.
+type Response struct {
+	Version    uint8
+	Opcode     uint8
+	ResultCode uint8
+	Lifetime   uint32
+	Epoch      uint32
+}
+
+// MapResponse contains the full response to a MAP request.
+type MapResponse struct {
+	Response
+	Nonce        [12]byte
+	Protocol     uint8
+	InternalPort uint16
+	ExternalPort uint16
+	ExternalIP   netip.Addr
+}
+
+// addrTo16 converts an address to its 16-byte IPv4-mapped IPv6 representation.
+func addrTo16(addr netip.Addr) [16]byte {
+	if addr.Is4() {
+		return netip.AddrFrom4(addr.As4()).As16()
+	}
+	return addr.As16()
+}
+
+// addrFrom16 extracts an address from a 16-byte representation, unmapping IPv4.
+func addrFrom16(b [16]byte) netip.Addr {
+	return netip.AddrFrom16(b).Unmap()
+}
+
+// buildAnnounceRequest creates a PCP ANNOUNCE request packet.
+func buildAnnounceRequest(clientIP netip.Addr) []byte {
+	req := make([]byte, headerSize)
+	req[0] = Version
+	req[1] = OpAnnounce
+	mapped := addrTo16(clientIP)
+	copy(req[8:24], mapped[:])
+	return req
+}
+
+// buildMapRequest creates a PCP MAP request packet.
+func buildMapRequest(clientIP netip.Addr, nonce [12]byte, protocol uint8, internalPort, suggestedExtPort uint16, suggestedExtIP netip.Addr, lifetime uint32) []byte {
+	req := make([]byte, mapRequestSize)
+
+	// Header
+	req[0] = Version
+	req[1] = OpMap
+	binary.BigEndian.PutUint32(req[4:8], lifetime)
+	mapped := addrTo16(clientIP)
+	copy(req[8:24], mapped[:])
+
+	// MAP payload
+	copy(req[24:36], nonce[:])
+	req[36] = protocol
+	binary.BigEndian.PutUint16(req[40:42], internalPort)
+	binary.BigEndian.PutUint16(req[42:44], suggestedExtPort)
+	if suggestedExtIP.IsValid() {
+		extMapped := addrTo16(suggestedExtIP)
+		copy(req[44:60], extMapped[:])
+	}
+
+	return req
+}
+
+// parseResponse parses the common PCP response header.
+func parseResponse(data []byte) (*Response, error) {
+	if len(data) < headerSize {
+		return nil, fmt.Errorf("response too short: %d bytes", len(data))
+	}
+
+	resp := &Response{
+		Version:    data[0],
+		Opcode:     data[1],
+		ResultCode: data[3], // Byte 2 is reserved, byte 3 is result code (RFC 6887 §7.2)
+		Lifetime:   binary.BigEndian.Uint32(data[4:8]),
+		Epoch:      binary.BigEndian.Uint32(data[8:12]),
+	}
+
+	if resp.Version != Version {
+		return nil, fmt.Errorf("unsupported PCP version: %d", resp.Version)
+	}
+
+	if resp.Opcode&OpReply == 0 {
+		return nil, fmt.Errorf("response missing reply bit: opcode=0x%02x", resp.Opcode)
+	}
+
+	return resp, nil
+}
+
+// parseMapResponse parses a complete MAP response.
+func parseMapResponse(data []byte) (*MapResponse, error) {
+	if len(data) < mapRequestSize {
+		return nil, fmt.Errorf("MAP response too short: %d bytes", len(data))
+	}
+
+	resp, err := parseResponse(data)
+	if err != nil {
+		return nil, fmt.Errorf("parse header: %w", err)
+	}
+
+	mapResp := &MapResponse{
+		Response:     *resp,
+		Protocol:     data[36],
+		InternalPort: binary.BigEndian.Uint16(data[40:42]),
+		ExternalPort: binary.BigEndian.Uint16(data[42:44]),
+		ExternalIP:   addrFrom16([16]byte(data[44:60])),
+	}
+	copy(mapResp.Nonce[:], data[24:36])
+
+	return mapResp, nil
+}

client/internal/portforward/state.go

@@ -0,0 +1,63 @@
+//go:build !js
+
+package portforward
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/libp2p/go-nat"
+	log "github.com/sirupsen/logrus"
+
+	"github.com/netbirdio/netbird/client/internal/portforward/pcp"
+)
+
+// discoverGateway is the function used for NAT gateway discovery.
+// It can be replaced in tests to avoid real network operations.
+// Tries PCP first, then falls back to NAT-PMP/UPnP.
+var discoverGateway = defaultDiscoverGateway
+
+func defaultDiscoverGateway(ctx context.Context) (nat.NAT, error) {
+	pcpGateway, err := pcp.DiscoverPCP(ctx)
+	if err == nil {
+		return pcpGateway, nil
+	}
+	log.Debugf("PCP discovery failed: %v, trying NAT-PMP/UPnP", err)
+
+	return nat.DiscoverGateway(ctx)
+}
+
+// State is persisted only for crash recovery cleanup
+type State struct {
+	InternalPort uint16 `json:"internal_port,omitempty"`
+	Protocol     string `json:"protocol,omitempty"`
+}
+
+func (s *State) Name() string {
+	return "port_forward_state"
+}
+
+// Cleanup implements statemanager.CleanableState for crash recovery
+func (s *State) Cleanup() error {
+	if s.InternalPort == 0 {
+		return nil
+	}
+
+	log.Infof("cleaning up stale port mapping for port %d", s.InternalPort)
+
+	ctx, cancel := context.WithTimeout(context.Background(), discoveryTimeout)
+	defer cancel()
+
+	gateway, err := discoverGateway(ctx)
+	if err != nil {
+		// Discovery failure is not an error - gateway may not exist
+		log.Debugf("cleanup: no gateway found: %v", err)
+		return nil
+	}
+
+	if err := gateway.DeletePortMapping(ctx, s.Protocol, int(s.InternalPort)); err != nil {
+		return fmt.Errorf("delete port mapping: %w", err)
+	}
+
+	return nil
+}

client/internal/profilemanager/config.go

@@ -198,7 +198,7 @@ func getConfigDirForUser(username string) (string, error) {
 
 	configDir := filepath.Join(DefaultConfigPathDir, username)
 	if _, err := os.Stat(configDir); os.IsNotExist(err) {
-		if err := os.MkdirAll(configDir, 0600); err != nil {
+		if err := os.MkdirAll(configDir, 0700); err != nil {
 			return "", err
 		}
 	}
@@ -206,9 +206,15 @@ func getConfigDirForUser(username string) (string, error) {
 	return configDir, nil
 }
 
-func fileExists(path string) bool {
+func fileExists(path string) (bool, error) {
 	_, err := os.Stat(path)
-	return !os.IsNotExist(err)
+	if err == nil {
+		return true, nil
+	}
+	if os.IsNotExist(err) {
+		return false, nil
+	}
+	return false, err
 }
 
 // createNewConfig creates a new config generating a new Wireguard key and saving to file
@@ -635,7 +641,11 @@ func isPreSharedKeyHidden(preSharedKey *string) bool {
 
 // UpdateConfig update existing configuration according to input configuration and return with the configuration
 func UpdateConfig(input ConfigInput) (*Config, error) {
-	if !fileExists(input.ConfigPath) {
+	configExists, err := fileExists(input.ConfigPath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to check if config file exists: %w", err)
+	}
+	if !configExists {
 		return nil, fmt.Errorf("config file %s does not exist", input.ConfigPath)
 	}
 
@@ -644,7 +654,11 @@ func UpdateConfig(input ConfigInput) (*Config, error) {
 
 // UpdateOrCreateConfig reads existing config or generates a new one
 func UpdateOrCreateConfig(input ConfigInput) (*Config, error) {
-	if !fileExists(input.ConfigPath) {
+	configExists, err := fileExists(input.ConfigPath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to check if config file exists: %w", err)
+	}
+	if !configExists {
 		log.Infof("generating new config %s", input.ConfigPath)
 		cfg, err := createNewConfig(input)
 		if err != nil {
@@ -657,7 +671,7 @@ func UpdateOrCreateConfig(input ConfigInput) (*Config, error) {
 	if isPreSharedKeyHidden(input.PreSharedKey) {
 		input.PreSharedKey = nil
 	}
-	err := util.EnforcePermission(input.ConfigPath)
+	err = util.EnforcePermission(input.ConfigPath)
 	if err != nil {
 		log.Errorf("failed to enforce permission on config dir: %v", err)
 	}
@@ -784,7 +798,12 @@ func ReadConfig(configPath string) (*Config, error) {
 
 // ReadConfig read config file and return with Config. If it is not exists create a new with default values
 func readConfig(configPath string, createIfMissing bool) (*Config, error) {
-	if fileExists(configPath) {
+	configExists, err := fileExists(configPath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to check if config file exists: %w", err)
+	}
+
+	if configExists {
 		err := util.EnforcePermission(configPath)
 		if err != nil {
 			log.Errorf("failed to enforce permission on config dir: %v", err)
@@ -831,7 +850,11 @@ func DirectWriteOutConfig(path string, config *Config) error {
 // DirectUpdateOrCreateConfig is like UpdateOrCreateConfig but uses direct (non-atomic) writes.
 // Use this on platforms where atomic writes are blocked (e.g., tvOS sandbox).
 func DirectUpdateOrCreateConfig(input ConfigInput) (*Config, error) {
-	if !fileExists(input.ConfigPath) {
+	configExists, err := fileExists(input.ConfigPath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to check if config file exists: %w", err)
+	}
+	if !configExists {
 		log.Infof("generating new config %s", input.ConfigPath)
 		cfg, err := createNewConfig(input)
 		if err != nil {

client/internal/profilemanager/service.go

@@ -256,7 +256,11 @@ func (s *ServiceManager) AddProfile(profileName, username string) error {
 	}
 
 	profPath := filepath.Join(configDir, profileName+".json")
-	if fileExists(profPath) {
+	profileExists, err := fileExists(profPath)
+	if err != nil {
+		return fmt.Errorf("failed to check if profile exists: %w", err)
+	}
+	if profileExists {
 		return ErrProfileAlreadyExists
 	}
 
@@ -285,7 +289,11 @@ func (s *ServiceManager) RemoveProfile(profileName, username string) error {
 		return fmt.Errorf("cannot remove profile with reserved name: %s", defaultProfileName)
 	}
 	profPath := filepath.Join(configDir, profileName+".json")
-	if !fileExists(profPath) {
+	profileExists, err := fileExists(profPath)
+	if err != nil {
+		return fmt.Errorf("failed to check if profile exists: %w", err)
+	}
+	if !profileExists {
 		return ErrProfileNotFound
 	}
 

client/internal/profilemanager/state.go

@@ -20,7 +20,11 @@ func (pm *ProfileManager) GetProfileState(profileName string) (*ProfileState, er
 	}
 
 	stateFile := filepath.Join(configDir, profileName+".state.json")
-	if !fileExists(stateFile) {
+	stateFileExists, err := fileExists(stateFile)
+	if err != nil {
+		return nil, fmt.Errorf("failed to check if profile state file exists: %w", err)
+	}
+	if !stateFileExists {
 		return nil, errors.New("profile state file does not exist")
 	}
 

client/internal/routemanager/client/client.go

@@ -263,8 +263,14 @@ func (w *Watcher) watchPeerStatusChanges(ctx context.Context, peerKey string, pe
 		case <-closer:
 			return
 		case routerStates := <-subscription.Events():
-			peerStateUpdate <- routerStates
-			log.Debugf("triggered route state update for Peer: %s", peerKey)
+			select {
+			case peerStateUpdate <- routerStates:
+				log.Debugf("triggered route state update for Peer: %s", peerKey)
+			case <-ctx.Done():
+				return
+			case <-closer:
+				return
+			}
 		}
 	}
 }

client/internal/sleep/handler/handler.go

@@ -0,0 +1,80 @@
+package handler
+
+import (
+	"context"
+	"sync"
+
+	log "github.com/sirupsen/logrus"
+
+	"github.com/netbirdio/netbird/client/internal"
+)
+
+type Agent interface {
+	Up(ctx context.Context) error
+	Down(ctx context.Context) error
+	Status() (internal.StatusType, error)
+}
+
+type SleepHandler struct {
+	agent Agent
+
+	mu sync.Mutex
+	// sleepTriggeredDown indicates whether the sleep handler triggered the last client down, to avoid unnecessary up on wake
+	sleepTriggeredDown bool
+}
+
+func New(agent Agent) *SleepHandler {
+	return &SleepHandler{
+		agent: agent,
+	}
+}
+
+func (s *SleepHandler) HandleWakeUp(ctx context.Context) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if !s.sleepTriggeredDown {
+		log.Info("skipping up because wasn't sleep down")
+		return nil
+	}
+
+	// avoid other wakeup runs if sleep didn't make the computer sleep
+	s.sleepTriggeredDown = false
+
+	log.Info("running up after wake up")
+	err := s.agent.Up(ctx)
+	if err != nil {
+		log.Errorf("running up failed: %v", err)
+		return err
+	}
+
+	log.Info("running up command executed successfully")
+	return nil
+}
+
+func (s *SleepHandler) HandleSleep(ctx context.Context) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	status, err := s.agent.Status()
+	if err != nil {
+		return err
+	}
+
+	if status != internal.StatusConnecting && status != internal.StatusConnected {
+		log.Infof("skipping setting the agent down because status is %s", status)
+		return nil
+	}
+
+	log.Info("running down after system started sleeping")
+
+	if err = s.agent.Down(ctx); err != nil {
+		log.Errorf("running down failed: %v", err)
+		return err
+	}
+
+	s.sleepTriggeredDown = true
+
+	log.Info("running down executed successfully")
+	return nil
+}

client/internal/sleep/handler/handler_test.go

@@ -0,0 +1,153 @@
+package handler
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/netbirdio/netbird/client/internal"
+)
+
+type mockAgent struct {
+	upErr     error
+	downErr   error
+	statusErr error
+	status    internal.StatusType
+	upCalls   int
+}
+
+func (m *mockAgent) Up(_ context.Context) error {
+	m.upCalls++
+	return m.upErr
+}
+
+func (m *mockAgent) Down(_ context.Context) error {
+	return m.downErr
+}
+
+func (m *mockAgent) Status() (internal.StatusType, error) {
+	return m.status, m.statusErr
+}
+
+func newHandler(status internal.StatusType) (*SleepHandler, *mockAgent) {
+	agent := &mockAgent{status: status}
+	return New(agent), agent
+}
+
+func TestHandleWakeUp_SkipsWhenFlagFalse(t *testing.T) {
+	h, agent := newHandler(internal.StatusIdle)
+
+	err := h.HandleWakeUp(context.Background())
+
+	require.NoError(t, err)
+	assert.Equal(t, 0, agent.upCalls, "Up should not be called when flag is false")
+}
+
+func TestHandleWakeUp_ResetsFlagBeforeUp(t *testing.T) {
+	h, _ := newHandler(internal.StatusIdle)
+	h.sleepTriggeredDown = true
+
+	// Even if Up fails, flag should be reset
+	_ = h.HandleWakeUp(context.Background())
+
+	assert.False(t, h.sleepTriggeredDown, "flag must be reset before calling Up")
+}
+
+func TestHandleWakeUp_CallsUpWhenFlagSet(t *testing.T) {
+	h, agent := newHandler(internal.StatusIdle)
+	h.sleepTriggeredDown = true
+
+	err := h.HandleWakeUp(context.Background())
+
+	require.NoError(t, err)
+	assert.Equal(t, 1, agent.upCalls)
+	assert.False(t, h.sleepTriggeredDown)
+}
+
+func TestHandleWakeUp_ReturnsErrorFromUp(t *testing.T) {
+	h, agent := newHandler(internal.StatusIdle)
+	h.sleepTriggeredDown = true
+	agent.upErr = errors.New("up failed")
+
+	err := h.HandleWakeUp(context.Background())
+
+	assert.ErrorIs(t, err, agent.upErr)
+	assert.False(t, h.sleepTriggeredDown, "flag should still be reset even when Up fails")
+}
+
+func TestHandleWakeUp_SecondCallIsNoOp(t *testing.T) {
+	h, agent := newHandler(internal.StatusIdle)
+	h.sleepTriggeredDown = true
+
+	_ = h.HandleWakeUp(context.Background())
+	err := h.HandleWakeUp(context.Background())
+
+	require.NoError(t, err)
+	assert.Equal(t, 1, agent.upCalls, "second wakeup should be no-op")
+}
+
+func TestHandleSleep_SkipsForNonActiveStates(t *testing.T) {
+	tests := []struct {
+		name   string
+		status internal.StatusType
+	}{
+		{"Idle", internal.StatusIdle},
+		{"NeedsLogin", internal.StatusNeedsLogin},
+		{"LoginFailed", internal.StatusLoginFailed},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			h, _ := newHandler(tt.status)
+
+			err := h.HandleSleep(context.Background())
+
+			require.NoError(t, err)
+			assert.False(t, h.sleepTriggeredDown)
+		})
+	}
+}
+
+func TestHandleSleep_ProceedsForActiveStates(t *testing.T) {
+	tests := []struct {
+		name   string
+		status internal.StatusType
+	}{
+		{"Connecting", internal.StatusConnecting},
+		{"Connected", internal.StatusConnected},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			h, _ := newHandler(tt.status)
+
+			err := h.HandleSleep(context.Background())
+
+			require.NoError(t, err)
+			assert.True(t, h.sleepTriggeredDown)
+		})
+	}
+}
+
+func TestHandleSleep_ReturnsErrorFromStatus(t *testing.T) {
+	agent := &mockAgent{statusErr: errors.New("status error")}
+	h := New(agent)
+
+	err := h.HandleSleep(context.Background())
+
+	assert.ErrorIs(t, err, agent.statusErr)
+	assert.False(t, h.sleepTriggeredDown)
+}
+
+func TestHandleSleep_ReturnsErrorFromDown(t *testing.T) {
+	agent := &mockAgent{status: internal.StatusConnected, downErr: errors.New("down failed")}
+	h := New(agent)
+
+	err := h.HandleSleep(context.Background())
+
+	assert.ErrorIs(t, err, agent.downErr)
+	assert.False(t, h.sleepTriggeredDown, "flag should not be set when Down fails")
+}

client/internal/updatemanager/manager_test.go

@@ -1,214 +0,0 @@
-//go:build windows || darwin
-
-package updatemanager
-
-import (
-	"context"
-	"fmt"
-	"path"
-	"testing"
-	"time"
-
-	v "github.com/hashicorp/go-version"
-
-	"github.com/netbirdio/netbird/client/internal/peer"
-	"github.com/netbirdio/netbird/client/internal/statemanager"
-)
-
-type versionUpdateMock struct {
-	latestVersion *v.Version
-	onUpdate      func()
-}
-
-func (v versionUpdateMock) StopWatch() {}
-
-func (v versionUpdateMock) SetDaemonVersion(newVersion string) bool {
-	return false
-}
-
-func (v *versionUpdateMock) SetOnUpdateListener(updateFn func()) {
-	v.onUpdate = updateFn
-}
-
-func (v versionUpdateMock) LatestVersion() *v.Version {
-	return v.latestVersion
-}
-
-func (v versionUpdateMock) StartFetcher() {}
-
-func Test_LatestVersion(t *testing.T) {
-	testMatrix := []struct {
-		name                 string
-		daemonVersion        string
-		initialLatestVersion *v.Version
-		latestVersion        *v.Version
-		shouldUpdateInit     bool
-		shouldUpdateLater    bool
-	}{
-		{
-			name:                 "Should only trigger update once due to time between triggers being < 5 Minutes",
-			daemonVersion:        "1.0.0",
-			initialLatestVersion: v.Must(v.NewSemver("1.0.1")),
-			latestVersion:        v.Must(v.NewSemver("1.0.2")),
-			shouldUpdateInit:     true,
-			shouldUpdateLater:    false,
-		},
-		{
-			name:                 "Shouldn't update initially, but should update as soon as latest version is fetched",
-			daemonVersion:        "1.0.0",
-			initialLatestVersion: nil,
-			latestVersion:        v.Must(v.NewSemver("1.0.1")),
-			shouldUpdateInit:     false,
-			shouldUpdateLater:    true,
-		},
-	}
-
-	for idx, c := range testMatrix {
-		mockUpdate := &versionUpdateMock{latestVersion: c.initialLatestVersion}
-		tmpFile := path.Join(t.TempDir(), fmt.Sprintf("update-test-%d.json", idx))
-		m, _ := newManager(peer.NewRecorder(""), statemanager.New(tmpFile))
-		m.update = mockUpdate
-
-		targetVersionChan := make(chan string, 1)
-
-		m.triggerUpdateFn = func(ctx context.Context, targetVersion string) error {
-			targetVersionChan <- targetVersion
-			return nil
-		}
-		m.currentVersion = c.daemonVersion
-		m.Start(context.Background())
-		m.SetVersion("latest")
-		var triggeredInit bool
-		select {
-		case targetVersion := <-targetVersionChan:
-			if targetVersion != c.initialLatestVersion.String() {
-				t.Errorf("%s: Initial update version mismatch, expected %v, got %v", c.name, c.initialLatestVersion.String(), targetVersion)
-			}
-			triggeredInit = true
-		case <-time.After(10 * time.Millisecond):
-			triggeredInit = false
-		}
-		if triggeredInit != c.shouldUpdateInit {
-			t.Errorf("%s: Initial update trigger mismatch, expected %v, got %v", c.name, c.shouldUpdateInit, triggeredInit)
-		}
-
-		mockUpdate.latestVersion = c.latestVersion
-		mockUpdate.onUpdate()
-
-		var triggeredLater bool
-		select {
-		case targetVersion := <-targetVersionChan:
-			if targetVersion != c.latestVersion.String() {
-				t.Errorf("%s: Update version mismatch, expected %v, got %v", c.name, c.latestVersion.String(), targetVersion)
-			}
-			triggeredLater = true
-		case <-time.After(10 * time.Millisecond):
-			triggeredLater = false
-		}
-		if triggeredLater != c.shouldUpdateLater {
-			t.Errorf("%s: Update trigger mismatch, expected %v, got %v", c.name, c.shouldUpdateLater, triggeredLater)
-		}
-
-		m.Stop()
-	}
-}
-
-func Test_HandleUpdate(t *testing.T) {
-	testMatrix := []struct {
-		name            string
-		daemonVersion   string
-		latestVersion   *v.Version
-		expectedVersion string
-		shouldUpdate    bool
-	}{
-		{
-			name:            "Update to a specific version should update regardless of if latestVersion is available yet",
-			daemonVersion:   "0.55.0",
-			latestVersion:   nil,
-			expectedVersion: "0.56.0",
-			shouldUpdate:    true,
-		},
-		{
-			name:            "Update to specific version should not update if version matches",
-			daemonVersion:   "0.55.0",
-			latestVersion:   nil,
-			expectedVersion: "0.55.0",
-			shouldUpdate:    false,
-		},
-		{
-			name:            "Update to specific version should not update if current version is newer",
-			daemonVersion:   "0.55.0",
-			latestVersion:   nil,
-			expectedVersion: "0.54.0",
-			shouldUpdate:    false,
-		},
-		{
-			name:            "Update to latest version should update if latest is newer",
-			daemonVersion:   "0.55.0",
-			latestVersion:   v.Must(v.NewSemver("0.56.0")),
-			expectedVersion: "latest",
-			shouldUpdate:    true,
-		},
-		{
-			name:            "Update to latest version should not update if latest == current",
-			daemonVersion:   "0.56.0",
-			latestVersion:   v.Must(v.NewSemver("0.56.0")),
-			expectedVersion: "latest",
-			shouldUpdate:    false,
-		},
-		{
-			name:            "Should not update if daemon version is invalid",
-			daemonVersion:   "development",
-			latestVersion:   v.Must(v.NewSemver("1.0.0")),
-			expectedVersion: "latest",
-			shouldUpdate:    false,
-		},
-		{
-			name:            "Should not update if expecting latest and latest version is unavailable",
-			daemonVersion:   "0.55.0",
-			latestVersion:   nil,
-			expectedVersion: "latest",
-			shouldUpdate:    false,
-		},
-		{
-			name:            "Should not update if expected version is invalid",
-			daemonVersion:   "0.55.0",
-			latestVersion:   nil,
-			expectedVersion: "development",
-			shouldUpdate:    false,
-		},
-	}
-	for idx, c := range testMatrix {
-		tmpFile := path.Join(t.TempDir(), fmt.Sprintf("update-test-%d.json", idx))
-		m, _ := newManager(peer.NewRecorder(""), statemanager.New(tmpFile))
-		m.update = &versionUpdateMock{latestVersion: c.latestVersion}
-		targetVersionChan := make(chan string, 1)
-
-		m.triggerUpdateFn = func(ctx context.Context, targetVersion string) error {
-			targetVersionChan <- targetVersion
-			return nil
-		}
-
-		m.currentVersion = c.daemonVersion
-		m.Start(context.Background())
-		m.SetVersion(c.expectedVersion)
-
-		var updateTriggered bool
-		select {
-		case targetVersion := <-targetVersionChan:
-			if c.expectedVersion == "latest" && targetVersion != c.latestVersion.String() {
-				t.Errorf("%s: Update version mismatch, expected %v, got %v", c.name, c.latestVersion.String(), targetVersion)
-			} else if c.expectedVersion != "latest" && targetVersion != c.expectedVersion {
-				t.Errorf("%s: Update version mismatch, expected %v, got %v", c.name, c.expectedVersion, targetVersion)
-			}
-			updateTriggered = true
-		case <-time.After(10 * time.Millisecond):
-			updateTriggered = false
-		}
-
-		if updateTriggered != c.shouldUpdate {
-			t.Errorf("%s: Update trigger mismatch, expected %v, got %v", c.name, c.shouldUpdate, updateTriggered)
-		}
-		m.Stop()
-	}
-}

client/internal/updatemanager/manager_unsupported.go

@@ -1,39 +0,0 @@
-//go:build !windows && !darwin
-
-package updatemanager
-
-import (
-	"context"
-	"fmt"
-
-	"github.com/netbirdio/netbird/client/internal/peer"
-	"github.com/netbirdio/netbird/client/internal/statemanager"
-)
-
-// Manager is a no-op stub for unsupported platforms
-type Manager struct{}
-
-// NewManager returns a no-op manager for unsupported platforms
-func NewManager(statusRecorder *peer.Status, stateManager *statemanager.Manager) (*Manager, error) {
-	return nil, fmt.Errorf("update manager is not supported on this platform")
-}
-
-// CheckUpdateSuccess is a no-op on unsupported platforms
-func (m *Manager) CheckUpdateSuccess(ctx context.Context) {
-	// no-op
-}
-
-// Start is a no-op on unsupported platforms
-func (m *Manager) Start(ctx context.Context) {
-	// no-op
-}
-
-// SetVersion is a no-op on unsupported platforms
-func (m *Manager) SetVersion(expectedVersion string) {
-	// no-op
-}
-
-// Stop is a no-op on unsupported platforms
-func (m *Manager) Stop() {
-	// no-op
-}

client/internal/updater/doc.go

@@ -1,4 +1,4 @@
-// Package updatemanager provides automatic update management for the NetBird client.
+// Package updater provides automatic update management for the NetBird client.
 // It monitors for new versions, handles update triggers from management server directives,
 // and orchestrates the download and installation of client updates.
 //
@@ -32,4 +32,4 @@
 //
 // This enables verification of successful updates and appropriate user notification
 // after the client restarts with the new version.
-package updatemanager
+package updater

client/internal/updater/installer/installer_common.go

@@ -16,8 +16,8 @@ import (
 	goversion "github.com/hashicorp/go-version"
 	log "github.com/sirupsen/logrus"
 
-	"github.com/netbirdio/netbird/client/internal/updatemanager/downloader"
-	"github.com/netbirdio/netbird/client/internal/updatemanager/reposign"
+	"github.com/netbirdio/netbird/client/internal/updater/downloader"
+	"github.com/netbirdio/netbird/client/internal/updater/reposign"
 )
 
 type Installer struct {

client/internal/updater/installer/result.go

@@ -203,7 +203,10 @@ func (rh *ResultHandler) write(result Result) error {
 
 func (rh *ResultHandler) cleanup() error {
 	err := os.Remove(rh.resultFile)
-	if err != nil && !os.IsNotExist(err) {
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil
+		}
 		return err
 	}
 	log.Debugf("delete installer result file: %s", rh.resultFile)

client/internal/updater/manager.go

@@ -1,12 +1,9 @@
-//go:build windows || darwin
-
-package updatemanager
+package updater
 
 import (
 	"context"
 	"errors"
 	"fmt"
-	"runtime"
 	"sync"
 	"time"
 
@@ -15,7 +12,7 @@ import (
 
 	"github.com/netbirdio/netbird/client/internal/peer"
 	"github.com/netbirdio/netbird/client/internal/statemanager"
-	"github.com/netbirdio/netbird/client/internal/updatemanager/installer"
+	"github.com/netbirdio/netbird/client/internal/updater/installer"
 	cProto "github.com/netbirdio/netbird/client/proto"
 	"github.com/netbirdio/netbird/version"
 )
@@ -41,6 +38,9 @@ type Manager struct {
 	statusRecorder *peer.Status
 	stateManager   *statemanager.Manager
 
+	downloadOnly bool // true when no enforcement from management; notifies UI to download latest
+	forceUpdate  bool // true when management sets AlwaysUpdate; skips UI interaction and installs directly
+
 	lastTrigger    time.Time
 	mgmUpdateChan  chan struct{}
 	updateChannel  chan struct{}
@@ -53,37 +53,38 @@ type Manager struct {
 	expectedVersion       *v.Version
 	updateToLatestVersion bool
 
-	// updateMutex protect update and expectedVersion fields
+	pendingVersion *v.Version
+
+	// updateMutex protects update, expectedVersion, updateToLatestVersion,
+	// downloadOnly, forceUpdate, pendingVersion, and lastTrigger fields
 	updateMutex sync.Mutex
 
-	triggerUpdateFn func(context.Context, string) error
+	// installMutex and installing guard against concurrent installation attempts
+	installMutex sync.Mutex
+	installing   bool
+
+	// protect to start the service multiple times
+	mu sync.Mutex
+
+	autoUpdateSupported func() bool
 }
 
-func NewManager(statusRecorder *peer.Status, stateManager *statemanager.Manager) (*Manager, error) {
-	if runtime.GOOS == "darwin" {
-		isBrew := !installer.TypeOfInstaller(context.Background()).Downloadable()
-		if isBrew {
-			log.Warnf("auto-update disabled on Home Brew installation")
-			return nil, fmt.Errorf("auto-update not supported on Home Brew installation yet")
-		}
-	}
-	return newManager(statusRecorder, stateManager)
-}
-
-func newManager(statusRecorder *peer.Status, stateManager *statemanager.Manager) (*Manager, error) {
+// NewManager creates a new update manager. The manager is single-use: once Stop() is called, it cannot be restarted.
+func NewManager(statusRecorder *peer.Status, stateManager *statemanager.Manager) *Manager {
 	manager := &Manager{
-		statusRecorder: statusRecorder,
-		stateManager:   stateManager,
-		mgmUpdateChan:  make(chan struct{}, 1),
-		updateChannel:  make(chan struct{}, 1),
-		currentVersion: version.NetbirdVersion(),
-		update:         version.NewUpdate("nb/client"),
+		statusRecorder:      statusRecorder,
+		stateManager:        stateManager,
+		mgmUpdateChan:       make(chan struct{}, 1),
+		updateChannel:       make(chan struct{}, 1),
+		currentVersion:      version.NetbirdVersion(),
+		update:              version.NewUpdate("nb/client"),
+		downloadOnly:        true,
+		autoUpdateSupported: isAutoUpdateSupported,
 	}
-	manager.triggerUpdateFn = manager.triggerUpdate
 
 	stateManager.RegisterState(&UpdateState{})
 
-	return manager, nil
+	return manager
 }
 
 // CheckUpdateSuccess checks if the update was successful and send a notification.
@@ -124,8 +125,10 @@ func (m *Manager) CheckUpdateSuccess(ctx context.Context) {
 }
 
 func (m *Manager) Start(ctx context.Context) {
+	log.Infof("starting update manager")
+	m.mu.Lock()
+	defer m.mu.Unlock()
 	if m.cancel != nil {
-		log.Errorf("Manager already started")
 		return
 	}
 
@@ -142,13 +145,32 @@ func (m *Manager) Start(ctx context.Context) {
 	m.cancel = cancel
 
 	m.wg.Add(1)
-	go m.updateLoop(ctx)
+	go func() {
+		defer m.wg.Done()
+		m.updateLoop(ctx)
+	}()
 }
 
-func (m *Manager) SetVersion(expectedVersion string) {
-	log.Infof("set expected agent version for upgrade: %s", expectedVersion)
-	if m.cancel == nil {
-		log.Errorf("manager not started")
+func (m *Manager) SetDownloadOnly() {
+	m.updateMutex.Lock()
+	m.downloadOnly = true
+	m.forceUpdate = false
+	m.expectedVersion = nil
+	m.updateToLatestVersion = false
+	m.lastTrigger = time.Time{}
+	m.updateMutex.Unlock()
+
+	select {
+	case m.mgmUpdateChan <- struct{}{}:
+	default:
+	}
+}
+
+func (m *Manager) SetVersion(expectedVersion string, forceUpdate bool) {
+	log.Infof("expected version changed to %s, force update: %t", expectedVersion, forceUpdate)
+
+	if !m.autoUpdateSupported() {
+		log.Warnf("auto-update not supported on this platform")
 		return
 	}
 
@@ -159,6 +181,7 @@ func (m *Manager) SetVersion(expectedVersion string) {
 		log.Errorf("empty expected version provided")
 		m.expectedVersion = nil
 		m.updateToLatestVersion = false
+		m.downloadOnly = true
 		return
 	}
 
@@ -178,12 +201,97 @@ func (m *Manager) SetVersion(expectedVersion string) {
 		m.updateToLatestVersion = false
 	}
 
+	m.lastTrigger = time.Time{}
+	m.downloadOnly = false
+	m.forceUpdate = forceUpdate
+
 	select {
 	case m.mgmUpdateChan <- struct{}{}:
 	default:
 	}
 }
 
+// Install triggers the installation of the pending version. It is called when the user clicks the install button in the UI.
+func (m *Manager) Install(ctx context.Context) error {
+	if !m.autoUpdateSupported() {
+		return fmt.Errorf("auto-update not supported on this platform")
+	}
+
+	m.updateMutex.Lock()
+	pending := m.pendingVersion
+	m.updateMutex.Unlock()
+
+	if pending == nil {
+		return fmt.Errorf("no pending version to install")
+	}
+
+	return m.tryInstall(ctx, pending)
+}
+
+// tryInstall ensures only one installation runs at a time. Concurrent callers
+// receive an error immediately rather than queuing behind a running install.
+func (m *Manager) tryInstall(ctx context.Context, targetVersion *v.Version) error {
+	m.installMutex.Lock()
+	if m.installing {
+		m.installMutex.Unlock()
+		return fmt.Errorf("installation already in progress")
+	}
+	m.installing = true
+	m.installMutex.Unlock()
+
+	defer func() {
+		m.installMutex.Lock()
+		m.installing = false
+		m.installMutex.Unlock()
+	}()
+
+	return m.install(ctx, targetVersion)
+}
+
+// NotifyUI re-publishes the current update state to a newly connected UI client.
+// Only needed for download-only mode where the latest version is already cached
+// NotifyUI re-publishes the current update state so a newly connected UI gets the info.
+func (m *Manager) NotifyUI() {
+	m.updateMutex.Lock()
+	if m.update == nil {
+		m.updateMutex.Unlock()
+		return
+	}
+	downloadOnly := m.downloadOnly
+	pendingVersion := m.pendingVersion
+	latestVersion := m.update.LatestVersion()
+	m.updateMutex.Unlock()
+
+	if downloadOnly {
+		if latestVersion == nil {
+			return
+		}
+		currentVersion, err := v.NewVersion(m.currentVersion)
+		if err != nil || currentVersion.GreaterThanOrEqual(latestVersion) {
+			return
+		}
+		m.statusRecorder.PublishEvent(
+			cProto.SystemEvent_INFO,
+			cProto.SystemEvent_SYSTEM,
+			"New version available",
+			"",
+			map[string]string{"new_version_available": latestVersion.String()},
+		)
+		return
+	}
+
+	if pendingVersion != nil {
+		m.statusRecorder.PublishEvent(
+			cProto.SystemEvent_INFO,
+			cProto.SystemEvent_SYSTEM,
+			"New version available",
+			"",
+			map[string]string{"new_version_available": pendingVersion.String(), "enforced": "true"},
+		)
+	}
+}
+
+// Stop is not used at the moment because it fully depends on the daemon. In a future refactor it may make sense to use it.
 func (m *Manager) Stop() {
 	if m.cancel == nil {
 		return
@@ -214,8 +322,6 @@ func (m *Manager) onContextCancel() {
 }
 
 func (m *Manager) updateLoop(ctx context.Context) {
-	defer m.wg.Done()
-
 	for {
 		select {
 		case <-ctx.Done():
@@ -239,55 +345,89 @@ func (m *Manager) handleUpdate(ctx context.Context) {
 		return
 	}
 
-	expectedVersion := m.expectedVersion
-	useLatest := m.updateToLatestVersion
+	downloadOnly := m.downloadOnly
+	forceUpdate := m.forceUpdate
 	curLatestVersion := m.update.LatestVersion()
-	m.updateMutex.Unlock()
 
 	switch {
-	// Resolve "latest" to actual version
-	case useLatest:
+	// Download-only mode or resolve "latest" to actual version
+	case downloadOnly, m.updateToLatestVersion:
 		if curLatestVersion == nil {
 			log.Tracef("latest version not fetched yet")
+			m.updateMutex.Unlock()
 			return
 		}
 		updateVersion = curLatestVersion
-	// Update to specific version
-	case expectedVersion != nil:
-		updateVersion = expectedVersion
+	// Install to specific version
+	case m.expectedVersion != nil:
+		updateVersion = m.expectedVersion
 	default:
 		log.Debugf("no expected version information set")
+		m.updateMutex.Unlock()
 		return
 	}
 
 	log.Debugf("checking update option, current version: %s, target version: %s", m.currentVersion, updateVersion)
-	if !m.shouldUpdate(updateVersion) {
+	if !m.shouldUpdate(updateVersion, forceUpdate) {
+		m.updateMutex.Unlock()
 		return
 	}
 
 	m.lastTrigger = time.Now()
-	log.Infof("Auto-update triggered, current version: %s, target version: %s", m.currentVersion, updateVersion)
-	m.statusRecorder.PublishEvent(
-		cProto.SystemEvent_CRITICAL,
-		cProto.SystemEvent_SYSTEM,
-		"Automatically updating client",
-		"Your client version is older than auto-update version set in Management, updating client now.",
-		nil,
-	)
+	log.Infof("new version available: %s", updateVersion)
+
+	if !downloadOnly && !forceUpdate {
+		m.pendingVersion = updateVersion
+	}
+	m.updateMutex.Unlock()
+
+	if downloadOnly {
+		m.statusRecorder.PublishEvent(
+			cProto.SystemEvent_INFO,
+			cProto.SystemEvent_SYSTEM,
+			"New version available",
+			"",
+			map[string]string{"new_version_available": updateVersion.String()},
+		)
+		return
+	}
+
+	if forceUpdate {
+		if err := m.tryInstall(ctx, updateVersion); err != nil {
+			log.Errorf("force update failed: %v", err)
+		}
+		return
+	}
 
+	m.statusRecorder.PublishEvent(
+		cProto.SystemEvent_INFO,
+		cProto.SystemEvent_SYSTEM,
+		"New version available",
+		"",
+		map[string]string{"new_version_available": updateVersion.String(), "enforced": "true"},
+	)
+}
+
+func (m *Manager) install(ctx context.Context, pendingVersion *v.Version) error {
+	m.statusRecorder.PublishEvent(
+		cProto.SystemEvent_CRITICAL,
+		cProto.SystemEvent_SYSTEM,
+		"Updating client",
+		"Installing update now.",
+		nil,
+	)
 	m.statusRecorder.PublishEvent(
 		cProto.SystemEvent_CRITICAL,
 		cProto.SystemEvent_SYSTEM,
 		"",
 		"",
-		map[string]string{"progress_window": "show", "version": updateVersion.String()},
+		map[string]string{"progress_window": "show", "version": pendingVersion.String()},
 	)
 
 	updateState := UpdateState{
 		PreUpdateVersion: m.currentVersion,
-		TargetVersion:    updateVersion.String(),
+		TargetVersion:    pendingVersion.String(),
 	}
-
 	if err := m.stateManager.UpdateState(updateState); err != nil {
 		log.Warnf("failed to update state: %v", err)
 	} else {
@@ -296,8 +436,9 @@ func (m *Manager) handleUpdate(ctx context.Context) {
 		}
 	}
 
-	if err := m.triggerUpdateFn(ctx, updateVersion.String()); err != nil {
-		log.Errorf("Error triggering auto-update: %v", err)
+	inst := installer.New()
+	if err := inst.RunInstallation(ctx, pendingVersion.String()); err != nil {
+		log.Errorf("error triggering update: %v", err)
 		m.statusRecorder.PublishEvent(
 			cProto.SystemEvent_ERROR,
 			cProto.SystemEvent_SYSTEM,
@@ -305,7 +446,9 @@ func (m *Manager) handleUpdate(ctx context.Context) {
 			fmt.Sprintf("Auto-update failed: %v", err),
 			nil,
 		)
+		return err
 	}
+	return nil
 }
 
 // loadAndDeleteUpdateState loads the update state, deletes it from storage, and returns it.
@@ -339,7 +482,7 @@ func (m *Manager) loadAndDeleteUpdateState(ctx context.Context) (*UpdateState, e
 	return updateState, nil
 }
 
-func (m *Manager) shouldUpdate(updateVersion *v.Version) bool {
+func (m *Manager) shouldUpdate(updateVersion *v.Version, forceUpdate bool) bool {
 	if m.currentVersion == developmentVersion {
 		log.Debugf("skipping auto-update, running development version")
 		return false
@@ -354,8 +497,8 @@ func (m *Manager) shouldUpdate(updateVersion *v.Version) bool {
 		return false
 	}
 
-	if time.Since(m.lastTrigger) < 5*time.Minute {
-		log.Debugf("skipping auto-update, last update was %s ago", time.Since(m.lastTrigger))
+	if forceUpdate && time.Since(m.lastTrigger) < 3*time.Minute {
+		log.Infof("skipping auto-update, last update was %s ago", time.Since(m.lastTrigger))
 		return false
 	}
 
@@ -367,8 +510,3 @@ func (m *Manager) lastResultErrReason() string {
 	result := installer.NewResultHandler(inst.TempDir())
 	return result.GetErrorResultReason()
 }
-
-func (m *Manager) triggerUpdate(ctx context.Context, targetVersion string) error {
-	inst := installer.New()
-	return inst.RunInstallation(ctx, targetVersion)
-}

client/internal/updater/manager_linux_test.go

@@ -0,0 +1,111 @@
+//go:build !windows && !darwin
+
+package updater
+
+import (
+	"context"
+	"fmt"
+	"path"
+	"testing"
+	"time"
+
+	v "github.com/hashicorp/go-version"
+
+	"github.com/netbirdio/netbird/client/internal/peer"
+	"github.com/netbirdio/netbird/client/internal/statemanager"
+)
+
+// On Linux, only Mode 1 (downloadOnly) is supported.
+// SetVersion is a no-op because auto-update installation is not supported.
+
+func Test_LatestVersion_Linux(t *testing.T) {
+	testMatrix := []struct {
+		name                 string
+		daemonVersion        string
+		initialLatestVersion *v.Version
+		latestVersion        *v.Version
+		shouldUpdateInit     bool
+		shouldUpdateLater    bool
+	}{
+		{
+			name:                 "Should notify again when a newer version arrives even within 5 minutes",
+			daemonVersion:        "1.0.0",
+			initialLatestVersion: v.Must(v.NewSemver("1.0.1")),
+			latestVersion:        v.Must(v.NewSemver("1.0.2")),
+			shouldUpdateInit:     true,
+			shouldUpdateLater:    true,
+		},
+		{
+			name:                 "Shouldn't notify initially, but should notify as soon as latest version is fetched",
+			daemonVersion:        "1.0.0",
+			initialLatestVersion: nil,
+			latestVersion:        v.Must(v.NewSemver("1.0.1")),
+			shouldUpdateInit:     false,
+			shouldUpdateLater:    true,
+		},
+	}
+
+	for idx, c := range testMatrix {
+		mockUpdate := &versionUpdateMock{latestVersion: c.initialLatestVersion}
+		tmpFile := path.Join(t.TempDir(), fmt.Sprintf("update-test-%d.json", idx))
+		recorder := peer.NewRecorder("")
+		sub := recorder.SubscribeToEvents()
+		defer recorder.UnsubscribeFromEvents(sub)
+
+		m := NewManager(recorder, statemanager.New(tmpFile))
+		m.update = mockUpdate
+		m.currentVersion = c.daemonVersion
+		m.Start(context.Background())
+		m.SetDownloadOnly()
+
+		ver, enforced := waitForUpdateEvent(sub, 500*time.Millisecond)
+		triggeredInit := ver != ""
+		if enforced {
+			t.Errorf("%s: Linux Mode 1 must never have enforced metadata", c.name)
+		}
+		if triggeredInit != c.shouldUpdateInit {
+			t.Errorf("%s: Initial notify mismatch, expected %v, got %v", c.name, c.shouldUpdateInit, triggeredInit)
+		}
+		if triggeredInit && c.initialLatestVersion != nil && ver != c.initialLatestVersion.String() {
+			t.Errorf("%s: Initial version mismatch, expected %v, got %v", c.name, c.initialLatestVersion.String(), ver)
+		}
+
+		mockUpdate.latestVersion = c.latestVersion
+		mockUpdate.onUpdate()
+
+		ver, enforced = waitForUpdateEvent(sub, 500*time.Millisecond)
+		triggeredLater := ver != ""
+		if enforced {
+			t.Errorf("%s: Linux Mode 1 must never have enforced metadata", c.name)
+		}
+		if triggeredLater != c.shouldUpdateLater {
+			t.Errorf("%s: Later notify mismatch, expected %v, got %v", c.name, c.shouldUpdateLater, triggeredLater)
+		}
+		if triggeredLater && c.latestVersion != nil && ver != c.latestVersion.String() {
+			t.Errorf("%s: Later version mismatch, expected %v, got %v", c.name, c.latestVersion.String(), ver)
+		}
+
+		m.Stop()
+	}
+}
+
+func Test_SetVersion_NoOp_Linux(t *testing.T) {
+	// On Linux, SetVersion should be a no-op — no events fired
+	tmpFile := path.Join(t.TempDir(), "update-test-noop.json")
+	recorder := peer.NewRecorder("")
+	sub := recorder.SubscribeToEvents()
+	defer recorder.UnsubscribeFromEvents(sub)
+
+	m := NewManager(recorder, statemanager.New(tmpFile))
+	m.update = &versionUpdateMock{latestVersion: v.Must(v.NewSemver("1.0.1"))}
+	m.currentVersion = "1.0.0"
+	m.Start(context.Background())
+	m.SetVersion("1.0.1", false)
+
+	ver, _ := waitForUpdateEvent(sub, 500*time.Millisecond)
+	if ver != "" {
+		t.Errorf("SetVersion should be a no-op on Linux, but got event with version %s", ver)
+	}
+
+	m.Stop()
+}

client/internal/updater/manager_test.go

@@ -0,0 +1,227 @@
+//go:build windows || darwin
+
+package updater
+
+import (
+	"context"
+	"fmt"
+	"path"
+	"testing"
+	"time"
+
+	v "github.com/hashicorp/go-version"
+
+	"github.com/netbirdio/netbird/client/internal/peer"
+	"github.com/netbirdio/netbird/client/internal/statemanager"
+	cProto "github.com/netbirdio/netbird/client/proto"
+)
+
+func Test_LatestVersion(t *testing.T) {
+	testMatrix := []struct {
+		name                 string
+		daemonVersion        string
+		initialLatestVersion *v.Version
+		latestVersion        *v.Version
+		shouldUpdateInit     bool
+		shouldUpdateLater    bool
+	}{
+		{
+			name:                 "Should notify again when a newer version arrives even within 5 minutes",
+			daemonVersion:        "1.0.0",
+			initialLatestVersion: v.Must(v.NewSemver("1.0.1")),
+			latestVersion:        v.Must(v.NewSemver("1.0.2")),
+			shouldUpdateInit:     true,
+			shouldUpdateLater:    true,
+		},
+		{
+			name:                 "Shouldn't update initially, but should update as soon as latest version is fetched",
+			daemonVersion:        "1.0.0",
+			initialLatestVersion: nil,
+			latestVersion:        v.Must(v.NewSemver("1.0.1")),
+			shouldUpdateInit:     false,
+			shouldUpdateLater:    true,
+		},
+	}
+
+	for idx, c := range testMatrix {
+		mockUpdate := &versionUpdateMock{latestVersion: c.initialLatestVersion}
+		tmpFile := path.Join(t.TempDir(), fmt.Sprintf("update-test-%d.json", idx))
+		recorder := peer.NewRecorder("")
+		sub := recorder.SubscribeToEvents()
+		defer recorder.UnsubscribeFromEvents(sub)
+
+		m := NewManager(recorder, statemanager.New(tmpFile))
+		m.update = mockUpdate
+		m.currentVersion = c.daemonVersion
+		m.autoUpdateSupported = func() bool { return true }
+		m.Start(context.Background())
+		m.SetVersion("latest", false)
+
+		ver, _ := waitForUpdateEvent(sub, 500*time.Millisecond)
+		triggeredInit := ver != ""
+		if triggeredInit != c.shouldUpdateInit {
+			t.Errorf("%s: Initial update trigger mismatch, expected %v, got %v", c.name, c.shouldUpdateInit, triggeredInit)
+		}
+		if triggeredInit && c.initialLatestVersion != nil && ver != c.initialLatestVersion.String() {
+			t.Errorf("%s: Initial update version mismatch, expected %v, got %v", c.name, c.initialLatestVersion.String(), ver)
+		}
+
+		mockUpdate.latestVersion = c.latestVersion
+		mockUpdate.onUpdate()
+
+		ver, _ = waitForUpdateEvent(sub, 500*time.Millisecond)
+		triggeredLater := ver != ""
+		if triggeredLater != c.shouldUpdateLater {
+			t.Errorf("%s: Later update trigger mismatch, expected %v, got %v", c.name, c.shouldUpdateLater, triggeredLater)
+		}
+		if triggeredLater && c.latestVersion != nil && ver != c.latestVersion.String() {
+			t.Errorf("%s: Later update version mismatch, expected %v, got %v", c.name, c.latestVersion.String(), ver)
+		}
+
+		m.Stop()
+	}
+}
+
+func Test_HandleUpdate(t *testing.T) {
+	testMatrix := []struct {
+		name            string
+		daemonVersion   string
+		latestVersion   *v.Version
+		expectedVersion string
+		shouldUpdate    bool
+	}{
+		{
+			name:            "Install to a specific version should update regardless of if latestVersion is available yet",
+			daemonVersion:   "0.55.0",
+			latestVersion:   nil,
+			expectedVersion: "0.56.0",
+			shouldUpdate:    true,
+		},
+		{
+			name:            "Install to specific version should not update if version matches",
+			daemonVersion:   "0.55.0",
+			latestVersion:   nil,
+			expectedVersion: "0.55.0",
+			shouldUpdate:    false,
+		},
+		{
+			name:            "Install to specific version should not update if current version is newer",
+			daemonVersion:   "0.55.0",
+			latestVersion:   nil,
+			expectedVersion: "0.54.0",
+			shouldUpdate:    false,
+		},
+		{
+			name:            "Install to latest version should update if latest is newer",
+			daemonVersion:   "0.55.0",
+			latestVersion:   v.Must(v.NewSemver("0.56.0")),
+			expectedVersion: "latest",
+			shouldUpdate:    true,
+		},
+		{
+			name:            "Install to latest version should not update if latest == current",
+			daemonVersion:   "0.56.0",
+			latestVersion:   v.Must(v.NewSemver("0.56.0")),
+			expectedVersion: "latest",
+			shouldUpdate:    false,
+		},
+		{
+			name:            "Should not update if daemon version is invalid",
+			daemonVersion:   "development",
+			latestVersion:   v.Must(v.NewSemver("1.0.0")),
+			expectedVersion: "latest",
+			shouldUpdate:    false,
+		},
+		{
+			name:            "Should not update if expecting latest and latest version is unavailable",
+			daemonVersion:   "0.55.0",
+			latestVersion:   nil,
+			expectedVersion: "latest",
+			shouldUpdate:    false,
+		},
+		{
+			name:            "Should not update if expected version is invalid",
+			daemonVersion:   "0.55.0",
+			latestVersion:   nil,
+			expectedVersion: "development",
+			shouldUpdate:    false,
+		},
+	}
+	for idx, c := range testMatrix {
+		tmpFile := path.Join(t.TempDir(), fmt.Sprintf("update-test-%d.json", idx))
+		recorder := peer.NewRecorder("")
+		sub := recorder.SubscribeToEvents()
+		defer recorder.UnsubscribeFromEvents(sub)
+
+		m := NewManager(recorder, statemanager.New(tmpFile))
+		m.update = &versionUpdateMock{latestVersion: c.latestVersion}
+		m.currentVersion = c.daemonVersion
+		m.autoUpdateSupported = func() bool { return true }
+		m.Start(context.Background())
+		m.SetVersion(c.expectedVersion, false)
+
+		ver, _ := waitForUpdateEvent(sub, 500*time.Millisecond)
+		updateTriggered := ver != ""
+
+		if updateTriggered {
+			if c.expectedVersion == "latest" && c.latestVersion != nil && ver != c.latestVersion.String() {
+				t.Errorf("%s: Version mismatch, expected %v, got %v", c.name, c.latestVersion.String(), ver)
+			} else if c.expectedVersion != "latest" && c.expectedVersion != "development" && ver != c.expectedVersion {
+				t.Errorf("%s: Version mismatch, expected %v, got %v", c.name, c.expectedVersion, ver)
+			}
+		}
+
+		if updateTriggered != c.shouldUpdate {
+			t.Errorf("%s: Update trigger mismatch, expected %v, got %v", c.name, c.shouldUpdate, updateTriggered)
+		}
+		m.Stop()
+	}
+}
+
+func Test_EnforcedMetadata(t *testing.T) {
+	// Mode 1 (downloadOnly): no enforced metadata
+	tmpFile := path.Join(t.TempDir(), "update-test-mode1.json")
+	recorder := peer.NewRecorder("")
+	sub := recorder.SubscribeToEvents()
+	defer recorder.UnsubscribeFromEvents(sub)
+
+	m := NewManager(recorder, statemanager.New(tmpFile))
+	m.update = &versionUpdateMock{latestVersion: v.Must(v.NewSemver("1.0.1"))}
+	m.currentVersion = "1.0.0"
+	m.Start(context.Background())
+	m.SetDownloadOnly()
+
+	ver, enforced := waitForUpdateEvent(sub, 500*time.Millisecond)
+	if ver == "" {
+		t.Fatal("Mode 1: expected new_version_available event")
+	}
+	if enforced {
+		t.Error("Mode 1: expected no enforced metadata")
+	}
+	m.Stop()
+
+	// Mode 2 (enforced, forceUpdate=false): enforced metadata present, no auto-install
+	tmpFile2 := path.Join(t.TempDir(), "update-test-mode2.json")
+	recorder2 := peer.NewRecorder("")
+	sub2 := recorder2.SubscribeToEvents()
+	defer recorder2.UnsubscribeFromEvents(sub2)
+
+	m2 := NewManager(recorder2, statemanager.New(tmpFile2))
+	m2.update = &versionUpdateMock{latestVersion: nil}
+	m2.currentVersion = "1.0.0"
+	m2.autoUpdateSupported = func() bool { return true }
+	m2.Start(context.Background())
+	m2.SetVersion("1.0.1", false)
+
+	ver, enforced2 := waitForUpdateEvent(sub2, 500*time.Millisecond)
+	if ver == "" {
+		t.Fatal("Mode 2: expected new_version_available event")
+	}
+	if !enforced2 {
+		t.Error("Mode 2: expected enforced metadata")
+	}
+	m2.Stop()
+}
+
+// ensure the proto import is used
+var _ = cProto.SystemEvent_INFO

client/internal/updater/manager_test_helpers_test.go

@@ -0,0 +1,56 @@
+package updater
+
+import (
+	"strconv"
+	"time"
+
+	v "github.com/hashicorp/go-version"
+
+	"github.com/netbirdio/netbird/client/internal/peer"
+)
+
+type versionUpdateMock struct {
+	latestVersion *v.Version
+	onUpdate      func()
+}
+
+func (m versionUpdateMock) StopWatch() {}
+
+func (m versionUpdateMock) SetDaemonVersion(newVersion string) bool {
+	return false
+}
+
+func (m *versionUpdateMock) SetOnUpdateListener(updateFn func()) {
+	m.onUpdate = updateFn
+}
+
+func (m versionUpdateMock) LatestVersion() *v.Version {
+	return m.latestVersion
+}
+
+func (m versionUpdateMock) StartFetcher() {}
+
+// waitForUpdateEvent waits for a new_version_available event, returns the version string or "" on timeout.
+func waitForUpdateEvent(sub *peer.EventSubscription, timeout time.Duration) (version string, enforced bool) {
+	timer := time.NewTimer(timeout)
+	defer timer.Stop()
+	for {
+		select {
+		case event, ok := <-sub.Events():
+			if !ok {
+				return "", false
+			}
+			if val, ok := event.Metadata["new_version_available"]; ok {
+				enforced := false
+				if raw, ok := event.Metadata["enforced"]; ok {
+					if parsed, err := strconv.ParseBool(raw); err == nil {
+						enforced = parsed
+					}
+				}
+				return val, enforced
+			}
+		case <-timer.C:
+			return "", false
+		}
+	}
+}