Merge branch 'main' into embedded-vnc

shared/context/keys.go

@@ -3,6 +3,8 @@ package context
 const (
 	RequestIDKey = "requestID"
 	AccountIDKey = "accountID"
+	RoleKey      = "role"
 	UserIDKey    = "userID"
 	PeerIDKey    = "peerID"
+	UserAgentKey = "userAgent"
 )

shared/management/client/client.go

@@ -16,6 +16,10 @@ type Client interface {
 	Job(ctx context.Context, msgHandler func(msg *proto.JobRequest) *proto.JobResponse) error
 	Register(setupKey string, jwtToken string, sysInfo *system.Info, sshKey []byte, dnsLabels domain.List) (*proto.LoginResponse, error)
 	Login(sysInfo *system.Info, sshKey []byte, dnsLabels domain.List) (*proto.LoginResponse, error)
+	// ExtendAuthSession refreshes the peer's SSO session deadline using a fresh JWT.
+	// Returns the new absolute deadline; zero time when the server reports the peer
+	// is not eligible for session extension.
+	ExtendAuthSession(sysInfo *system.Info, jwtToken string) (*proto.ExtendAuthSessionResponse, error)
 	GetDeviceAuthorizationFlow() (*proto.DeviceAuthorizationFlow, error)
 	GetPKCEAuthorizationFlow() (*proto.PKCEAuthorizationFlow, error)
 	GetNetworkMap(sysInfo *system.Info) (*proto.NetworkMap, error)

shared/management/client/client_test.go

@@ -17,8 +17,8 @@ import (
 	"google.golang.org/grpc/codes"
 	"google.golang.org/grpc/status"
 
-	"github.com/netbirdio/management-integrations/integrations"
 	ephemeral_manager "github.com/netbirdio/netbird/management/internals/modules/peers/ephemeral/manager"
+	"github.com/netbirdio/netbird/management/server/integrations/integrated_validator/validator"
 
 	"github.com/netbirdio/netbird/management/internals/controllers/network_map/controller"
 	"github.com/netbirdio/netbird/management/internals/controllers/network_map/update_channel"
@@ -89,7 +89,7 @@ func startManagement(t *testing.T) (*grpc.Server, net.Listener) {
 			gomock.Any(),
 			gomock.Any(),
 		).
-		Return(true, nil).
+		Return(true, context.Background(), nil).
 		AnyTimes()
 
 	peersManger := peers.NewManager(store, permissionsManagerMock)
@@ -103,7 +103,7 @@ func startManagement(t *testing.T) (*grpc.Server, net.Listener) {
 		t.Fatal(err)
 	}
 
-	ia, _ := integrations.NewIntegratedValidator(ctx, peersManger, settingsManagerMock, eventStore, cacheStore)
+	ia, _ := validator.NewIntegratedValidator(ctx, peersManger, settingsManagerMock, eventStore, cacheStore)
 
 	metrics, err := telemetry.NewDefaultAppMetrics(ctx)
 	require.NoError(t, err)

shared/management/client/grpc.go

@@ -607,6 +607,61 @@ func (c *GrpcClient) Login(sysInfo *system.Info, pubSSHKey []byte, dnsLabels dom
 	return c.login(&proto.LoginRequest{Meta: infoToMetaData(sysInfo), PeerKeys: keys, DnsLabels: dnsLabels.ToPunycodeList()})
 }
 
+// ExtendAuthSession refreshes the peer's SSO session deadline on the management
+// server using a freshly issued JWT. The tunnel is untouched: no network map
+// sync, no peer reconnect. Returns the new absolute UTC deadline (zero time
+// when the server reports the field empty).
+func (c *GrpcClient) ExtendAuthSession(sysInfo *system.Info, jwtToken string) (*proto.ExtendAuthSessionResponse, error) {
+	if !c.ready() {
+		return nil, errors.New(errMsgNoMgmtConnection)
+	}
+
+	serverKey, err := c.getServerPublicKey()
+	if err != nil {
+		return nil, err
+	}
+
+	reqBody, err := encryption.EncryptMessage(*serverKey, c.key, &proto.ExtendAuthSessionRequest{
+		JwtToken: jwtToken,
+		Meta:     infoToMetaData(sysInfo),
+	})
+	if err != nil {
+		log.Errorf("failed to encrypt extend auth session message: %s", err)
+		return nil, err
+	}
+
+	var resp *proto.EncryptedMessage
+	operation := func() error {
+		mgmCtx, cancel := context.WithTimeout(context.Background(), ConnectTimeout)
+		defer cancel()
+
+		var err error
+		resp, err = c.realClient.ExtendAuthSession(mgmCtx, &proto.EncryptedMessage{
+			WgPubKey: c.key.PublicKey().String(),
+			Body:     reqBody,
+		})
+		if err != nil {
+			if s, ok := gstatus.FromError(err); ok && s.Code() == codes.Canceled {
+				return err
+			}
+			return backoff.Permanent(err)
+		}
+		return nil
+	}
+
+	if err := backoff.Retry(operation, nbgrpc.Backoff(c.ctx)); err != nil {
+		log.Errorf("failed to extend auth session on Management Service: %v", err)
+		return nil, err
+	}
+
+	out := &proto.ExtendAuthSessionResponse{}
+	if err := encryption.DecryptMessage(*serverKey, c.key, resp.Body, out); err != nil {
+		log.Errorf("failed to decrypt extend auth session response: %s", err)
+		return nil, err
+	}
+	return out, nil
+}
+
 // GetDeviceAuthorizationFlow returns a device authorization flow information.
 // It also takes care of encrypting and decrypting messages.
 func (c *GrpcClient) GetDeviceAuthorizationFlow() (*proto.DeviceAuthorizationFlow, error) {

shared/management/client/mock.go

@@ -14,6 +14,7 @@ type MockClient struct {
 	SyncFunc                       func(ctx context.Context, sysInfo *system.Info, msgHandler func(msg *proto.SyncResponse) error) error
 	RegisterFunc                   func(setupKey string, jwtToken string, info *system.Info, sshKey []byte, dnsLabels domain.List) (*proto.LoginResponse, error)
 	LoginFunc                      func(info *system.Info, sshKey []byte, dnsLabels domain.List) (*proto.LoginResponse, error)
+	ExtendAuthSessionFunc          func(info *system.Info, jwtToken string) (*proto.ExtendAuthSessionResponse, error)
 	GetDeviceAuthorizationFlowFunc func() (*proto.DeviceAuthorizationFlow, error)
 	GetPKCEAuthorizationFlowFunc   func() (*proto.PKCEAuthorizationFlow, error)
 	GetServerURLFunc               func() string
@@ -65,6 +66,13 @@ func (m *MockClient) Login(info *system.Info, sshKey []byte, dnsLabels domain.Li
 	return m.LoginFunc(info, sshKey, dnsLabels)
 }
 
+func (m *MockClient) ExtendAuthSession(info *system.Info, jwtToken string) (*proto.ExtendAuthSessionResponse, error) {
+	if m.ExtendAuthSessionFunc == nil {
+		return nil, nil
+	}
+	return m.ExtendAuthSessionFunc(info, jwtToken)
+}
+
 func (m *MockClient) GetDeviceAuthorizationFlow() (*proto.DeviceAuthorizationFlow, error) {
 	if m.GetDeviceAuthorizationFlowFunc == nil {
 		return nil, nil

shared/management/client/rest/client.go

@@ -143,6 +143,10 @@ type Client struct {
 
 	// ReverseProxyDomains NetBird reverse proxy domains APIs
 	ReverseProxyDomains *ReverseProxyDomainsAPI
+
+	// ReverseProxyTokens account-scoped proxy access tokens used to register
+	// self-hosted (bring-your-own-proxy) `netbird proxy` instances.
+	ReverseProxyTokens *ReverseProxyTokensAPI
 }
 
 // New initialize new Client instance using PAT token
@@ -204,6 +208,7 @@ func (c *Client) initialize() {
 	c.ReverseProxyServices = &ReverseProxyServicesAPI{c}
 	c.ReverseProxyClusters = &ReverseProxyClustersAPI{c}
 	c.ReverseProxyDomains = &ReverseProxyDomainsAPI{c}
+	c.ReverseProxyTokens = &ReverseProxyTokensAPI{c}
 }
 
 // NewRequest creates and executes new management API request

shared/management/client/rest/reverse_proxy_clusters.go

@@ -2,6 +2,8 @@ package rest
 
 import (
 	"context"
+	"errors"
+	"net/url"
 
 	"github.com/netbirdio/netbird/shared/management/http/api"
 )
@@ -11,7 +13,10 @@ type ReverseProxyClustersAPI struct {
 	c *Client
 }
 
-// List lists all available proxy clusters
+// List lists all available proxy clusters. Each cluster is enriched with the
+// capability flags reported by its connected proxies (supports_custom_ports,
+// supports_crowdsec, private, etc.), so callers can render UX gates without
+// a follow-up round-trip.
 func (a *ReverseProxyClustersAPI) List(ctx context.Context) ([]api.ProxyCluster, error) {
 	resp, err := a.c.NewRequest(ctx, "GET", "/api/reverse-proxies/clusters", nil, nil)
 	if err != nil {
@@ -23,3 +28,24 @@ func (a *ReverseProxyClustersAPI) List(ctx context.Context) ([]api.ProxyCluster,
 	ret, err := parseResponse[[]api.ProxyCluster](resp)
 	return ret, err
 }
+
+// Delete removes every self-hosted (BYOP) proxy registration for the given
+// cluster address owned by the calling account. Shared clusters operated by
+// NetBird cannot be deleted via this endpoint; the server returns 404 / 400
+// for cluster addresses the account does not own.
+func (a *ReverseProxyClustersAPI) Delete(ctx context.Context, clusterAddress string) error {
+	// Guard against the empty input: url.PathEscape("") returns "" which
+	// would collapse the request URL onto the collection endpoint and
+	// silently delete nothing (or 405 depending on routing).
+	if clusterAddress == "" {
+		return errors.New("clusterAddress is required")
+	}
+	resp, err := a.c.NewRequest(ctx, "DELETE", "/api/reverse-proxies/clusters/"+url.PathEscape(clusterAddress), nil, nil)
+	if err != nil {
+		return err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	return nil
+}

shared/management/client/rest/reverse_proxy_clusters_test.go

@@ -0,0 +1,104 @@
+//go:build integration
+
+package rest_test
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/netbirdio/netbird/shared/management/client/rest"
+	"github.com/netbirdio/netbird/shared/management/http/api"
+	"github.com/netbirdio/netbird/shared/management/http/util"
+)
+
+func boolPtr(b bool) *bool { return &b }
+
+var testCluster = api.ProxyCluster{
+	Id:                  "cluster-1",
+	Address:             "proxy.netbird.local",
+	Type:                "shared",
+	Online:              true,
+	ConnectedProxies:    2,
+	SupportsCustomPorts: boolPtr(true),
+	RequireSubdomain:    boolPtr(false),
+	SupportsCrowdsec:    boolPtr(false),
+	Private:             boolPtr(true),
+}
+
+func TestReverseProxyClusters_List_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/reverse-proxies/clusters", func(w http.ResponseWriter, r *http.Request) {
+			assert.Equal(t, "GET", r.Method, "List must use GET")
+			retBytes, _ := json.Marshal([]api.ProxyCluster{testCluster})
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.ReverseProxyClusters.List(context.Background())
+		require.NoError(t, err)
+		require.Len(t, ret, 1)
+		assert.Equal(t, testCluster.Id, ret[0].Id)
+		assert.Equal(t, testCluster.Address, ret[0].Address)
+		require.NotNil(t, ret[0].Private, "private capability must round-trip through the client")
+		assert.True(t, *ret[0].Private, "private capability must reflect the server value")
+	})
+}
+
+func TestReverseProxyClusters_List_Err(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/reverse-proxies/clusters", func(w http.ResponseWriter, r *http.Request) {
+			retBytes, _ := json.Marshal(util.ErrorResponse{Message: "No", Code: 500})
+			w.WriteHeader(500)
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.ReverseProxyClusters.List(context.Background())
+		assert.Error(t, err)
+		assert.Empty(t, ret)
+	})
+}
+
+func TestReverseProxyClusters_Delete_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		// PathEscape on "proxy.netbird.local" leaves it intact; the route mux
+		// matches the unescaped form. Sanity-check both the method and that
+		// path-escaping doesn't double-encode the dotted address.
+		mux.HandleFunc("/api/reverse-proxies/clusters/proxy.netbird.local", func(w http.ResponseWriter, r *http.Request) {
+			assert.Equal(t, "DELETE", r.Method, "Delete must use DELETE")
+			w.WriteHeader(200)
+		})
+		err := c.ReverseProxyClusters.Delete(context.Background(), "proxy.netbird.local")
+		require.NoError(t, err)
+	})
+}
+
+func TestReverseProxyClusters_Delete_Err(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/reverse-proxies/clusters/proxy.netbird.local", func(w http.ResponseWriter, r *http.Request) {
+			retBytes, _ := json.Marshal(util.ErrorResponse{Message: "Not found", Code: 404})
+			w.WriteHeader(404)
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		err := c.ReverseProxyClusters.Delete(context.Background(), "proxy.netbird.local")
+		assert.Error(t, err)
+	})
+}
+
+// TestReverseProxyClusters_Delete_EmptyAddress guards against an empty
+// clusterAddress reaching the wire — that would collapse the URL onto
+// the collection endpoint instead of a specific cluster. The client
+// must short-circuit with a typed error before any request is issued.
+func TestReverseProxyClusters_Delete_EmptyAddress(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/reverse-proxies/clusters/", func(http.ResponseWriter, *http.Request) {
+			t.Fatal("empty clusterAddress must be rejected client-side; no request should reach the server")
+		})
+		err := c.ReverseProxyClusters.Delete(context.Background(), "")
+		assert.Error(t, err, "empty clusterAddress must surface as an error")
+	})
+}

shared/management/client/rest/reverse_proxy_services_test.go

@@ -116,8 +116,8 @@ func TestReverseProxyServices_Create_200(t *testing.T) {
 			Name:    "test-service",
 			Domain:  "test.example.com",
 			Enabled: true,
-			Auth:    api.ServiceAuthConfig{},
-			Targets: []api.ServiceTarget{testServiceTarget},
+			Auth:    &api.ServiceAuthConfig{},
+			Targets: &[]api.ServiceTarget{testServiceTarget},
 		})
 		require.NoError(t, err)
 		assert.Equal(t, testService.Id, ret.Id)
@@ -136,8 +136,8 @@ func TestReverseProxyServices_Create_Err(t *testing.T) {
 			Name:    "test-service",
 			Domain:  "test.example.com",
 			Enabled: true,
-			Auth:    api.ServiceAuthConfig{},
-			Targets: []api.ServiceTarget{testServiceTarget},
+			Auth:    &api.ServiceAuthConfig{},
+			Targets: &[]api.ServiceTarget{testServiceTarget},
 		})
 		assert.Error(t, err)
 		assert.Equal(t, "No", err.Error())
@@ -154,8 +154,9 @@ func TestReverseProxyServices_Create_WithPerTargetOptions(t *testing.T) {
 			var req api.ServiceRequest
 			require.NoError(t, json.Unmarshal(reqBytes, &req))
 
-			require.Len(t, req.Targets, 1)
-			target := req.Targets[0]
+			require.NotNil(t, req.Targets, "targets must be set on the request")
+			require.Len(t, *req.Targets, 1)
+			target := (*req.Targets)[0]
 			require.NotNil(t, target.Options, "options should be present")
 			opts := target.Options
 			require.NotNil(t, opts.SkipTlsVerify, "skip_tls_verify should be present")
@@ -177,8 +178,8 @@ func TestReverseProxyServices_Create_WithPerTargetOptions(t *testing.T) {
 			Name:    "test-service",
 			Domain:  "test.example.com",
 			Enabled: true,
-			Auth:    api.ServiceAuthConfig{},
-			Targets: []api.ServiceTarget{
+			Auth:    &api.ServiceAuthConfig{},
+			Targets: &[]api.ServiceTarget{
 				{
 					TargetId:   "peer-123",
 					TargetType: "peer",
@@ -216,8 +217,8 @@ func TestReverseProxyServices_Update_200(t *testing.T) {
 			Name:    "updated-service",
 			Domain:  "test.example.com",
 			Enabled: true,
-			Auth:    api.ServiceAuthConfig{},
-			Targets: []api.ServiceTarget{testServiceTarget},
+			Auth:    &api.ServiceAuthConfig{},
+			Targets: &[]api.ServiceTarget{testServiceTarget},
 		})
 		require.NoError(t, err)
 		assert.Equal(t, testService.Id, ret.Id)
@@ -236,8 +237,8 @@ func TestReverseProxyServices_Update_Err(t *testing.T) {
 			Name:    "updated-service",
 			Domain:  "test.example.com",
 			Enabled: true,
-			Auth:    api.ServiceAuthConfig{},
-			Targets: []api.ServiceTarget{testServiceTarget},
+			Auth:    &api.ServiceAuthConfig{},
+			Targets: &[]api.ServiceTarget{testServiceTarget},
 		})
 		assert.Error(t, err)
 		assert.Equal(t, "No", err.Error())

shared/management/client/rest/reverse_proxy_tokens.go

@@ -0,0 +1,79 @@
+package rest
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"net/url"
+
+	"github.com/netbirdio/netbird/shared/management/http/api"
+)
+
+// ReverseProxyTokensAPI exposes the account-scoped proxy access tokens that
+// self-hosted (bring-your-own-proxy) deployments use to register a
+// `netbird proxy` instance with management. Tokens are bound to the
+// calling account; revoking a token disconnects every proxy that
+// authenticated with it.
+type ReverseProxyTokensAPI struct {
+	c *Client
+}
+
+// List returns every proxy token the calling account has minted, including
+// already-revoked entries. The plain token is never returned — only the
+// metadata (id, name, created_at, last_used, revoked).
+func (a *ReverseProxyTokensAPI) List(ctx context.Context) ([]api.ProxyToken, error) {
+	resp, err := a.c.NewRequest(ctx, "GET", "/api/reverse-proxies/proxy-tokens", nil, nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	ret, err := parseResponse[[]api.ProxyToken](resp)
+	return ret, err
+}
+
+// Create mints a fresh account-scoped proxy token. The returned
+// ProxyTokenCreated.PlainToken is shown only once — callers must persist
+// it immediately. Subsequent reads will only expose the token metadata,
+// not the secret material.
+func (a *ReverseProxyTokensAPI) Create(ctx context.Context, request api.ProxyTokenRequest) (*api.ProxyTokenCreated, error) {
+	requestBytes, err := json.Marshal(request)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := a.c.NewRequest(ctx, "POST", "/api/reverse-proxies/proxy-tokens", bytes.NewReader(requestBytes), nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	ret, err := parseResponse[api.ProxyTokenCreated](resp)
+	if err != nil {
+		return nil, err
+	}
+	return &ret, nil
+}
+
+// Delete revokes a previously-issued proxy token by ID. Revoked tokens
+// remain in List output (with revoked=true) so operators can audit which
+// credentials existed; the plain secret can no longer authenticate any
+// new proxy registration.
+func (a *ReverseProxyTokensAPI) Delete(ctx context.Context, tokenID string) error {
+	// Guard against the empty input: url.PathEscape("") returns "" which
+	// would collapse the request URL onto the collection endpoint and
+	// silently delete nothing (or 405 depending on routing).
+	if tokenID == "" {
+		return errors.New("tokenID is required")
+	}
+	resp, err := a.c.NewRequest(ctx, "DELETE", "/api/reverse-proxies/proxy-tokens/"+url.PathEscape(tokenID), nil, nil)
+	if err != nil {
+		return err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	return nil
+}

shared/management/client/rest/reverse_proxy_tokens_test.go

@@ -0,0 +1,144 @@
+//go:build integration
+
+package rest_test
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/netbirdio/netbird/shared/management/client/rest"
+	"github.com/netbirdio/netbird/shared/management/http/api"
+	"github.com/netbirdio/netbird/shared/management/http/util"
+)
+
+func intPtr(v int) *int { return &v }
+
+var testProxyToken = api.ProxyToken{
+	Id:        "tok-1",
+	Name:      "ci-runner",
+	CreatedAt: time.Date(2026, 5, 21, 9, 0, 0, 0, time.UTC),
+	Revoked:   false,
+}
+
+var testProxyTokenCreated = api.ProxyTokenCreated{
+	Id:         "tok-1",
+	Name:       "ci-runner",
+	CreatedAt:  time.Date(2026, 5, 21, 9, 0, 0, 0, time.UTC),
+	PlainToken: "nbproxy_abcdef0123456789",
+	Revoked:    false,
+}
+
+func TestReverseProxyTokens_List_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/reverse-proxies/proxy-tokens", func(w http.ResponseWriter, r *http.Request) {
+			assert.Equal(t, "GET", r.Method, "List must use GET")
+			retBytes, _ := json.Marshal([]api.ProxyToken{testProxyToken})
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.ReverseProxyTokens.List(context.Background())
+		require.NoError(t, err)
+		require.Len(t, ret, 1)
+		assert.Equal(t, testProxyToken.Id, ret[0].Id)
+		assert.Equal(t, testProxyToken.Name, ret[0].Name)
+	})
+}
+
+func TestReverseProxyTokens_List_Err(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/reverse-proxies/proxy-tokens", func(w http.ResponseWriter, r *http.Request) {
+			retBytes, _ := json.Marshal(util.ErrorResponse{Message: "No", Code: 500})
+			w.WriteHeader(500)
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.ReverseProxyTokens.List(context.Background())
+		assert.Error(t, err)
+		assert.Empty(t, ret)
+	})
+}
+
+func TestReverseProxyTokens_Create_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/reverse-proxies/proxy-tokens", func(w http.ResponseWriter, r *http.Request) {
+			assert.Equal(t, "POST", r.Method, "Create must use POST")
+			body, err := io.ReadAll(r.Body)
+			require.NoError(t, err)
+			var req api.ProxyTokenRequest
+			require.NoError(t, json.Unmarshal(body, &req), "server must receive a valid ProxyTokenRequest body")
+			assert.Equal(t, "ci-runner", req.Name, "name must round-trip through the client")
+			require.NotNil(t, req.ExpiresIn, "expires_in must be sent when provided")
+			assert.Equal(t, 3600, *req.ExpiresIn, "expires_in value must round-trip unchanged")
+
+			retBytes, _ := json.Marshal(testProxyTokenCreated)
+			_, err = w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.ReverseProxyTokens.Create(context.Background(), api.ProxyTokenRequest{
+			Name:      "ci-runner",
+			ExpiresIn: intPtr(3600),
+		})
+		require.NoError(t, err)
+		assert.Equal(t, testProxyTokenCreated.Id, ret.Id)
+		assert.Equal(t, testProxyTokenCreated.PlainToken, ret.PlainToken,
+			"PlainToken must be returned to the caller — it's the one-shot secret")
+	})
+}
+
+func TestReverseProxyTokens_Create_Err(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/reverse-proxies/proxy-tokens", func(w http.ResponseWriter, r *http.Request) {
+			retBytes, _ := json.Marshal(util.ErrorResponse{Message: "Bad", Code: 400})
+			w.WriteHeader(400)
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.ReverseProxyTokens.Create(context.Background(), api.ProxyTokenRequest{Name: ""})
+		assert.Error(t, err)
+		assert.Nil(t, ret)
+	})
+}
+
+func TestReverseProxyTokens_Delete_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/reverse-proxies/proxy-tokens/tok-1", func(w http.ResponseWriter, r *http.Request) {
+			assert.Equal(t, "DELETE", r.Method, "Delete must use DELETE")
+			w.WriteHeader(200)
+		})
+		err := c.ReverseProxyTokens.Delete(context.Background(), "tok-1")
+		require.NoError(t, err)
+	})
+}
+
+func TestReverseProxyTokens_Delete_Err(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/reverse-proxies/proxy-tokens/tok-1", func(w http.ResponseWriter, r *http.Request) {
+			retBytes, _ := json.Marshal(util.ErrorResponse{Message: "Not found", Code: 404})
+			w.WriteHeader(404)
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		err := c.ReverseProxyTokens.Delete(context.Background(), "tok-1")
+		assert.Error(t, err)
+	})
+}
+
+// TestReverseProxyTokens_Delete_EmptyID guards against an empty tokenID
+// reaching the wire — url.PathEscape("") would collapse the URL onto
+// the collection endpoint.
+func TestReverseProxyTokens_Delete_EmptyID(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/reverse-proxies/proxy-tokens/", func(http.ResponseWriter, *http.Request) {
+			t.Fatal("empty tokenID must be rejected client-side; no request should reach the server")
+		})
+		err := c.ReverseProxyTokens.Delete(context.Background(), "")
+		assert.Error(t, err, "empty tokenID must surface as an error")
+	})
+}

shared/management/http/api/openapi.yml

@@ -3080,6 +3080,17 @@ components:
           $ref: '#/components/schemas/AccessRestrictions'
         meta:
           $ref: '#/components/schemas/ServiceMeta'
+        private:
+          type: boolean
+          description: When true, the service is NetBird-only — its target points at a proxy cluster, inbound peers authenticate via their WireGuard tunnel identity (no OIDC), and an ACL policy is auto-generated from access_groups to the cluster's proxy-peer group. Requires mode=http.
+          default: false
+          example: false
+        access_groups:
+          type: array
+          items:
+            type: string
+          description: NetBird group IDs whose peers may reach this private service over the tunnel. Required when private=true; ignored otherwise. Mutually exclusive with bearer auth (SSO).
+          example: ["group-engineering"]
       required:
         - id
         - name
@@ -3088,6 +3099,24 @@ components:
         - enabled
         - auth
         - meta
+      allOf:
+        # When private=true, access_groups must be present and non-empty,
+        # and the service mode must be "http". The bearer-auth mutex is
+        # enforced at the service-validation layer
+        # (validatePrivateRequirements) because it sits in a nested
+        # ServiceAuthConfig and isn't cleanly expressible here.
+        - if:
+            required: [private]
+            properties:
+              private:
+                const: true
+          then:
+            required: [access_groups]
+            properties:
+              access_groups:
+                minItems: 1
+              mode:
+                const: http
     ServiceMeta:
       type: object
       properties:
@@ -3160,10 +3189,38 @@ components:
           $ref: '#/components/schemas/ServiceAuthConfig'
         access_restrictions:
           $ref: '#/components/schemas/AccessRestrictions'
+        private:
+          type: boolean
+          description: When true, the service is NetBird-only — its target points at a proxy cluster, inbound peers authenticate via their WireGuard tunnel identity (no OIDC), and an ACL policy is auto-generated from access_groups to the cluster's proxy-peer group. Requires mode=http.
+          default: false
+          example: false
+        access_groups:
+          type: array
+          items:
+            type: string
+          description: NetBird group IDs whose peers may reach this private service over the tunnel. Required when private=true; ignored otherwise. Mutually exclusive with bearer auth (SSO).
+          example: ["group-engineering"]
       required:
         - name
         - domain
         - enabled
+      allOf:
+        # Mirror of the Service conditional: when private=true the
+        # request must carry a non-empty access_groups list and the
+        # mode must be "http". The bearer-auth mutex is enforced at the
+        # service-validation layer (validatePrivateRequirements).
+        - if:
+            required: [private]
+            properties:
+              private:
+                const: true
+          then:
+            required: [access_groups]
+            properties:
+              access_groups:
+                minItems: 1
+              mode:
+                const: http
     ServiceTargetOptions:
       type: object
       properties:
@@ -3198,6 +3255,15 @@ components:
           type: string
           description: Idle timeout before a UDP session is reaped, as a Go duration string (e.g. "30s", "2m").
           example: "2m"
+        direct_upstream:
+          type: boolean
+          description: |
+            When true, the proxy dials this target via the host's network stack
+            instead of through its embedded NetBird client. Use for upstreams
+            reachable without WireGuard (public APIs, LAN services, localhost
+            sidecars).
+          default: false
+          example: false
     ServiceTarget:
       type: object
       properties:
@@ -3208,7 +3274,7 @@ components:
         target_type:
           type: string
           description: Target type
-          enum: [peer, host, domain, subnet]
+          enum: [peer, host, domain, subnet, cluster]
           example: "subnet"
         path:
           type: string
@@ -3452,6 +3518,10 @@ components:
           type: boolean
           description: Whether all active proxies in the cluster have CrowdSec configured
           example: false
+        private:
+          type: boolean
+          description: True when at least one connected proxy in this cluster is running embedded in a netbird client (`netbird proxy`) and serving over a WireGuard tunnel. Lets the dashboard distinguish per-peer / private clusters from centralised ones.
+          example: false
       required:
         - id
         - address
@@ -3507,6 +3577,10 @@ components:
           type: boolean
           description: Whether the proxy cluster has CrowdSec configured
           example: false
+        supports_private:
+          type: boolean
+          description: Whether the proxy cluster supports private (NetBird-only) services. True when at least one connected proxy in the cluster runs embedded in a netbird client.
+          example: false
       required:
         - id
         - domain
@@ -5046,31 +5120,63 @@ components:
   responses:
     not_found:
       description: Resource not found
+      headers:
+        X-Request-Id:
+          $ref: '#/components/headers/X-Request-Id'
       content: { }
     validation_failed_simple:
       description: Validation failed
+      headers:
+        X-Request-Id:
+          $ref: '#/components/headers/X-Request-Id'
       content: { }
     bad_request:
       description: Bad Request
+      headers:
+        X-Request-Id:
+          $ref: '#/components/headers/X-Request-Id'
       content: { }
     internal_error:
       description: Internal Server Error
+      headers:
+        X-Request-Id:
+          $ref: '#/components/headers/X-Request-Id'
       content: { }
     validation_failed:
       description: Validation failed
+      headers:
+        X-Request-Id:
+          $ref: '#/components/headers/X-Request-Id'
       content: { }
     forbidden:
       description: Forbidden
+      headers:
+        X-Request-Id:
+          $ref: '#/components/headers/X-Request-Id'
       content: { }
     requires_authentication:
       description: Requires authentication
+      headers:
+        X-Request-Id:
+          $ref: '#/components/headers/X-Request-Id'
       content: { }
     conflict:
       description: Conflict
+      headers:
+        X-Request-Id:
+          $ref: '#/components/headers/X-Request-Id'
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/ErrorResponse'
+  headers:
+    X-Request-Id:
+      description: |
+        Unique identifier assigned to the request by the server and set on every
+        response. Useful for correlating client requests with server-side logs.
+      schema:
+        type: string
+        example: cot7r4n3l3vh3qj4qveg
   securitySchemes:
     BearerAuth:
       type: http

shared/management/http/api/types.gen.go

@@ -1063,15 +1063,18 @@ func (e ServiceTargetProtocol) Valid() bool {
 
 // Defines values for ServiceTargetTargetType.
 const (
-	ServiceTargetTargetTypeDomain ServiceTargetTargetType = "domain"
-	ServiceTargetTargetTypeHost   ServiceTargetTargetType = "host"
-	ServiceTargetTargetTypePeer   ServiceTargetTargetType = "peer"
-	ServiceTargetTargetTypeSubnet ServiceTargetTargetType = "subnet"
+	ServiceTargetTargetTypeCluster ServiceTargetTargetType = "cluster"
+	ServiceTargetTargetTypeDomain  ServiceTargetTargetType = "domain"
+	ServiceTargetTargetTypeHost    ServiceTargetTargetType = "host"
+	ServiceTargetTargetTypePeer    ServiceTargetTargetType = "peer"
+	ServiceTargetTargetTypeSubnet  ServiceTargetTargetType = "subnet"
 )
 
 // Valid indicates whether the value is a known member of the ServiceTargetTargetType enum.
 func (e ServiceTargetTargetType) Valid() bool {
 	switch e {
+	case ServiceTargetTargetTypeCluster:
+		return true
 	case ServiceTargetTargetTypeDomain:
 		return true
 	case ServiceTargetTargetTypeHost:
@@ -3828,6 +3831,9 @@ type ProxyCluster struct {
 	// Online Whether at least one proxy in the cluster has heartbeated within the active window
 	Online bool `json:"online"`
 
+	// Private True when at least one connected proxy in this cluster is running embedded in a netbird client (`netbird proxy`) and serving over a WireGuard tunnel. Lets the dashboard distinguish per-peer / private clusters from centralised ones.
+	Private *bool `json:"private,omitempty"`
+
 	// RequireSubdomain Whether services on this cluster must include a subdomain label
 	RequireSubdomain *bool `json:"require_subdomain,omitempty"`
 
@@ -3905,6 +3911,9 @@ type ReverseProxyDomain struct {
 	// SupportsCustomPorts Whether the cluster supports binding arbitrary TCP/UDP ports
 	SupportsCustomPorts *bool `json:"supports_custom_ports,omitempty"`
 
+	// SupportsPrivate Whether the proxy cluster supports private (NetBird-only) services. True when at least one connected proxy in the cluster runs embedded in a netbird client.
+	SupportsPrivate *bool `json:"supports_private,omitempty"`
+
 	// TargetCluster The proxy cluster this domain is validated against (only for custom domains)
 	TargetCluster *string `json:"target_cluster,omitempty"`
 
@@ -4094,6 +4103,9 @@ type SentinelOneMatchAttributesNetworkStatus string
 
 // Service defines model for Service.
 type Service struct {
+	// AccessGroups NetBird group IDs whose peers may reach this private service over the tunnel. Required when private=true; ignored otherwise. Mutually exclusive with bearer auth (SSO).
+	AccessGroups *[]string `json:"access_groups,omitempty"`
+
 	// AccessRestrictions Connection-level access restrictions based on IP address or geography. Applies to both HTTP and L4 services.
 	AccessRestrictions *AccessRestrictions `json:"access_restrictions,omitempty"`
 	Auth               ServiceAuthConfig   `json:"auth"`
@@ -4123,6 +4135,9 @@ type Service struct {
 	// PortAutoAssigned Whether the listen port was auto-assigned
 	PortAutoAssigned *bool `json:"port_auto_assigned,omitempty"`
 
+	// Private When true, the service is NetBird-only — its target points at a proxy cluster, inbound peers authenticate via their WireGuard tunnel identity (no OIDC), and an ACL policy is auto-generated from access_groups to the cluster's proxy-peer group. Requires mode=http.
+	Private *bool `json:"private,omitempty"`
+
 	// ProxyCluster The proxy cluster handling this service (derived from domain)
 	ProxyCluster *string `json:"proxy_cluster,omitempty"`
 
@@ -4165,6 +4180,9 @@ type ServiceMetaStatus string
 
 // ServiceRequest defines model for ServiceRequest.
 type ServiceRequest struct {
+	// AccessGroups NetBird group IDs whose peers may reach this private service over the tunnel. Required when private=true; ignored otherwise. Mutually exclusive with bearer auth (SSO).
+	AccessGroups *[]string `json:"access_groups,omitempty"`
+
 	// AccessRestrictions Connection-level access restrictions based on IP address or geography. Applies to both HTTP and L4 services.
 	AccessRestrictions *AccessRestrictions `json:"access_restrictions,omitempty"`
 	Auth               *ServiceAuthConfig  `json:"auth,omitempty"`
@@ -4187,6 +4205,9 @@ type ServiceRequest struct {
 	// PassHostHeader When true, the original client Host header is passed through to the backend instead of being rewritten to the backend's address
 	PassHostHeader *bool `json:"pass_host_header,omitempty"`
 
+	// Private When true, the service is NetBird-only — its target points at a proxy cluster, inbound peers authenticate via their WireGuard tunnel identity (no OIDC), and an ACL policy is auto-generated from access_groups to the cluster's proxy-peer group. Requires mode=http.
+	Private *bool `json:"private,omitempty"`
+
 	// RewriteRedirects When true, Location headers in backend responses are rewritten to replace the backend address with the public-facing domain
 	RewriteRedirects *bool `json:"rewrite_redirects,omitempty"`
 
@@ -4233,6 +4254,12 @@ type ServiceTargetOptions struct {
 	// CustomHeaders Extra headers sent to the backend. Hop-by-hop and proxy-managed headers (Host, Connection, Transfer-Encoding, etc.) are rejected.
 	CustomHeaders *map[string]string `json:"custom_headers,omitempty"`
 
+	// DirectUpstream When true, the proxy dials this target via the host's network stack
+	// instead of through its embedded NetBird client. Use for upstreams
+	// reachable without WireGuard (public APIs, LAN services, localhost
+	// sidecars).
+	DirectUpstream *bool `json:"direct_upstream,omitempty"`
+
 	// PathRewrite Controls how the request path is rewritten before forwarding to the backend. Default strips the matched prefix. "preserve" keeps the full original request path.
 	PathRewrite *ServiceTargetOptionsPathRewrite `json:"path_rewrite,omitempty"`
 

shared/management/proto/management.proto

@@ -52,6 +52,14 @@ service ManagementService {
   // Executes a job on a target peer (e.g., debug bundle)
   rpc Job(stream EncryptedMessage) returns (stream EncryptedMessage) {}
 
+  // ExtendAuthSession refreshes the peer's session expiry deadline using a fresh JWT.
+  // Same JWT validation pipeline as Login (including jwt.UserID == peer.UserID check),
+  // but does not redo the network-map sync. Only valid for SSO-registered peers where
+  // login expiration is enabled. The tunnel remains up.
+  // EncryptedMessage of the request has a body of ExtendAuthSessionRequest.
+  // EncryptedMessage of the response has a body of ExtendAuthSessionResponse.
+  rpc ExtendAuthSession(EncryptedMessage) returns (EncryptedMessage) {}
+
   // CreateExpose creates a temporary reverse proxy service for a peer
   rpc CreateExpose(EncryptedMessage) returns (EncryptedMessage) {}
 
@@ -133,6 +141,15 @@ message SyncResponse {
 
   // Posture checks to be evaluated by client
   repeated Checks Checks = 6;
+
+  // 3-state session deadline. Carried on every Sync snapshot so admin-side
+  // changes propagate live without a client reconnect.
+  //   field unset (nil)        → snapshot carries no info; client keeps the
+  //                              deadline it already had
+  //   set, seconds=0 nanos=0   → explicit "expiry disabled" or peer is not
+  //                              SSO-registered; client clears its anchor
+  //   set, valid timestamp     → new absolute UTC deadline
+  google.protobuf.Timestamp sessionExpiresAt = 7;
 }
 
 message  SyncMetaRequest {
@@ -246,6 +263,31 @@ message LoginResponse {
   PeerConfig peerConfig = 2;
   // Posture checks to be evaluated by client
   repeated Checks Checks = 3;
+
+  // 3-state session deadline; same encoding as SyncResponse.sessionExpiresAt.
+  //   field unset (nil)        → no info; client keeps any deadline it had
+  //   set, seconds=0 nanos=0   → explicit "expiry disabled" / non-SSO peer
+  //   set, valid timestamp     → new absolute UTC deadline
+  google.protobuf.Timestamp sessionExpiresAt = 4;
+}
+
+// ExtendAuthSessionRequest carries a fresh JWT to refresh the peer's session deadline.
+// The encrypted body of an EncryptedMessage with this payload is sent to the
+// ExtendAuthSession RPC.
+message ExtendAuthSessionRequest {
+  // SSO token (must be a fresh, valid JWT for the peer's owning user)
+  string jwtToken = 1;
+  // Meta data of the peer (used for IdP user info refresh consistent with Login)
+  PeerSystemMeta meta = 2;
+}
+
+// ExtendAuthSessionResponse contains the refreshed session deadline.
+message ExtendAuthSessionResponse {
+  // 3-state session deadline; same encoding as SyncResponse.sessionExpiresAt.
+  // In practice ExtendAuthSession only succeeds for SSO peers with expiry
+  // enabled, so this carries a valid timestamp on the success path. The
+  // 3-state encoding is documented here for symmetry with Login/Sync.
+  google.protobuf.Timestamp sessionExpiresAt = 1;
 }
 
 message ServerKeyResponse {

shared/management/proto/management_grpc.pb.go

@@ -28,6 +28,7 @@ const (
 	ManagementService_SyncMeta_FullMethodName                   = "/management.ManagementService/SyncMeta"
 	ManagementService_Logout_FullMethodName                     = "/management.ManagementService/Logout"
 	ManagementService_Job_FullMethodName                        = "/management.ManagementService/Job"
+	ManagementService_ExtendAuthSession_FullMethodName          = "/management.ManagementService/ExtendAuthSession"
 	ManagementService_CreateExpose_FullMethodName               = "/management.ManagementService/CreateExpose"
 	ManagementService_RenewExpose_FullMethodName                = "/management.ManagementService/RenewExpose"
 	ManagementService_StopExpose_FullMethodName                 = "/management.ManagementService/StopExpose"
@@ -71,6 +72,13 @@ type ManagementServiceClient interface {
 	Logout(ctx context.Context, in *EncryptedMessage, opts ...grpc.CallOption) (*Empty, error)
 	// Executes a job on a target peer (e.g., debug bundle)
 	Job(ctx context.Context, opts ...grpc.CallOption) (grpc.BidiStreamingClient[EncryptedMessage, EncryptedMessage], error)
+	// ExtendAuthSession refreshes the peer's session expiry deadline using a fresh JWT.
+	// Same JWT validation pipeline as Login (including jwt.UserID == peer.UserID check),
+	// but does not redo the network-map sync. Only valid for SSO-registered peers where
+	// login expiration is enabled. The tunnel remains up.
+	// EncryptedMessage of the request has a body of ExtendAuthSessionRequest.
+	// EncryptedMessage of the response has a body of ExtendAuthSessionResponse.
+	ExtendAuthSession(ctx context.Context, in *EncryptedMessage, opts ...grpc.CallOption) (*EncryptedMessage, error)
 	// CreateExpose creates a temporary reverse proxy service for a peer
 	CreateExpose(ctx context.Context, in *EncryptedMessage, opts ...grpc.CallOption) (*EncryptedMessage, error)
 	// RenewExpose extends the TTL of an active expose session
@@ -189,6 +197,16 @@ func (c *managementServiceClient) Job(ctx context.Context, opts ...grpc.CallOpti
 // This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
 type ManagementService_JobClient = grpc.BidiStreamingClient[EncryptedMessage, EncryptedMessage]
 
+func (c *managementServiceClient) ExtendAuthSession(ctx context.Context, in *EncryptedMessage, opts ...grpc.CallOption) (*EncryptedMessage, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(EncryptedMessage)
+	err := c.cc.Invoke(ctx, ManagementService_ExtendAuthSession_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
 func (c *managementServiceClient) CreateExpose(ctx context.Context, in *EncryptedMessage, opts ...grpc.CallOption) (*EncryptedMessage, error) {
 	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
 	out := new(EncryptedMessage)
@@ -257,6 +275,13 @@ type ManagementServiceServer interface {
 	Logout(context.Context, *EncryptedMessage) (*Empty, error)
 	// Executes a job on a target peer (e.g., debug bundle)
 	Job(grpc.BidiStreamingServer[EncryptedMessage, EncryptedMessage]) error
+	// ExtendAuthSession refreshes the peer's session expiry deadline using a fresh JWT.
+	// Same JWT validation pipeline as Login (including jwt.UserID == peer.UserID check),
+	// but does not redo the network-map sync. Only valid for SSO-registered peers where
+	// login expiration is enabled. The tunnel remains up.
+	// EncryptedMessage of the request has a body of ExtendAuthSessionRequest.
+	// EncryptedMessage of the response has a body of ExtendAuthSessionResponse.
+	ExtendAuthSession(context.Context, *EncryptedMessage) (*EncryptedMessage, error)
 	// CreateExpose creates a temporary reverse proxy service for a peer
 	CreateExpose(context.Context, *EncryptedMessage) (*EncryptedMessage, error)
 	// RenewExpose extends the TTL of an active expose session
@@ -300,6 +325,9 @@ func (UnimplementedManagementServiceServer) Logout(context.Context, *EncryptedMe
 func (UnimplementedManagementServiceServer) Job(grpc.BidiStreamingServer[EncryptedMessage, EncryptedMessage]) error {
 	return status.Error(codes.Unimplemented, "method Job not implemented")
 }
+func (UnimplementedManagementServiceServer) ExtendAuthSession(context.Context, *EncryptedMessage) (*EncryptedMessage, error) {
+	return nil, status.Error(codes.Unimplemented, "method ExtendAuthSession not implemented")
+}
 func (UnimplementedManagementServiceServer) CreateExpose(context.Context, *EncryptedMessage) (*EncryptedMessage, error) {
 	return nil, status.Error(codes.Unimplemented, "method CreateExpose not implemented")
 }
@@ -474,6 +502,24 @@ func _ManagementService_Job_Handler(srv interface{}, stream grpc.ServerStream) e
 // This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
 type ManagementService_JobServer = grpc.BidiStreamingServer[EncryptedMessage, EncryptedMessage]
 
+func _ManagementService_ExtendAuthSession_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(EncryptedMessage)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(ManagementServiceServer).ExtendAuthSession(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: ManagementService_ExtendAuthSession_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(ManagementServiceServer).ExtendAuthSession(ctx, req.(*EncryptedMessage))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
 func _ManagementService_CreateExpose_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
 	in := new(EncryptedMessage)
 	if err := dec(in); err != nil {
@@ -563,6 +609,10 @@ var ManagementService_ServiceDesc = grpc.ServiceDesc{
 			MethodName: "Logout",
 			Handler:    _ManagementService_Logout_Handler,
 		},
+		{
+			MethodName: "ExtendAuthSession",
+			Handler:    _ManagementService_ExtendAuthSession_Handler,
+		},
 		{
 			MethodName: "CreateExpose",
 			Handler:    _ManagementService_CreateExpose_Handler,

shared/management/proto/proxy_service.proto

@@ -12,6 +12,15 @@ import "google/protobuf/timestamp.proto";
 service ProxyService {
   rpc GetMappingUpdate(GetMappingUpdateRequest) returns (stream GetMappingUpdateResponse);
 
+  // SyncMappings is a bidirectional stream that replaces GetMappingUpdate for
+  // new proxies. The proxy sends an initial SyncMappingsRequest to start the
+  // stream and then sends an ack after each batch is fully processed.
+  // Management waits for the ack before sending the next batch, providing
+  // application-level back-pressure during large initial syncs.
+  // Old proxies continue using GetMappingUpdate; old management servers
+  // return Unimplemented for this RPC and proxies fall back.
+  rpc SyncMappings(stream SyncMappingsRequest) returns (stream SyncMappingsResponse);
+
   rpc SendAccessLog(SendAccessLogRequest) returns (SendAccessLogResponse);
 
   rpc Authenticate(AuthenticateRequest) returns (AuthenticateResponse);
@@ -25,6 +34,15 @@ service ProxyService {
   // ValidateSession validates a session token and checks user access permissions.
   // Called by the proxy after receiving a session token from OIDC callback.
   rpc ValidateSession(ValidateSessionRequest) returns (ValidateSessionResponse);
+
+  // ValidateTunnelPeer resolves an inbound peer by its WireGuard tunnel IP and
+  // checks the resolved user's access against the service's access_groups.
+  // Acts as a fast-path equivalent of OIDC for requests originating on the
+  // netbird mesh: when the source IP maps to a known peer in the calling
+  // account and that peer is in the service's access_groups, the proxy can
+  // issue a session cookie without redirecting through the OIDC flow.
+  // Mirrors ValidateSession's response shape.
+  rpc ValidateTunnelPeer(ValidateTunnelPeerRequest) returns (ValidateTunnelPeerResponse);
 }
 
 // ProxyCapabilities describes what a proxy can handle.
@@ -36,6 +54,13 @@ message ProxyCapabilities {
   optional bool require_subdomain = 2;
   // Whether the proxy has CrowdSec configured and can enforce IP reputation checks.
   optional bool supports_crowdsec = 3;
+  // Whether the proxy is running embedded in the netbird client and serving
+  // exclusively over the WireGuard tunnel (i.e. `netbird proxy` rather than
+  // the standalone netbird-proxy binary). Surfaces upstream so dashboards can
+  // distinguish per-peer / private clusters from centralised ones.
+  optional bool private = 4;
+  // Whether the proxy enforces ProxyMapping.private (fails closed on ValidateTunnelPeer failure). Management MUST NOT stream private mappings to proxies that don't claim this.
+  optional bool supports_private_service = 5;
 }
 
 // GetMappingUpdateRequest is sent to initialise a mapping stream.
@@ -77,6 +102,11 @@ message PathTargetOptions {
   bool proxy_protocol = 5;
   // Idle timeout before a UDP session is reaped.
   google.protobuf.Duration session_idle_timeout = 6;
+  // When true, the proxy dials this target via the host's network stack
+  // instead of through the embedded NetBird client. Useful for upstreams
+  // reachable without WireGuard (public APIs, LAN services, localhost
+  // sidecars). Defaults to false — embedded client is the standard path.
+  bool direct_upstream = 7;
 }
 
 message PathMapping {
@@ -129,6 +159,8 @@ message ProxyMapping {
   // For L4/TLS: the port the proxy listens on.
   int32 listen_port = 11;
   AccessRestrictions access_restrictions = 12;
+  // NetBird-only: the proxy MUST call ValidateTunnelPeer and fail closed; operator auth schemes are bypassed.
+  bool private = 13;
 }
 
 // SendAccessLogRequest consists of one or more AccessLogs from a Proxy.
@@ -204,6 +236,25 @@ message SendStatusUpdateRequest {
   ProxyStatus status = 3;
   bool certificate_issued = 4;
   optional string error_message = 5;
+  // Per-account inbound listener state for the account that owns
+  // service_id. Populated only when --private is enabled and the
+  // embedded client for the account is up. Field numbers >=50 reserved
+  // for observability extensions.
+  optional ProxyInboundListener inbound_listener = 50;
+}
+
+// ProxyInboundListener describes a per-account inbound listener that the
+// proxy has bound on the embedded netstack of the account's WireGuard
+// client. Surfaced so dashboards can render "this account is reachable
+// at <tunnel_ip>:<https_port> on this proxy".
+message ProxyInboundListener {
+  // Tunnel IP the embedded netstack listens on. Same address other peers
+  // in the account see for the proxy peer.
+  string tunnel_ip = 1;
+  // TLS port served on tunnel_ip (auto-detected, default 443).
+  uint32 https_port = 2;
+  // Plain-HTTP port served on tunnel_ip (auto-detected, default 80).
+  uint32 http_port = 3;
 }
 
 // SendStatusUpdateResponse is intentionally empty to allow for future expansion
@@ -245,4 +296,83 @@ message ValidateSessionResponse {
   string user_id = 2;
   string user_email = 3;
   string denied_reason = 4;
+  // peer_group_ids carries the calling user's group memberships so the
+  // proxy can authorise policy-aware middlewares without an additional
+  // management round-trip.
+  repeated string peer_group_ids = 5;
+  // peer_group_names carries the human-readable display names for the
+  // ids in peer_group_ids, ordered identically (positional pairing).
+  // Stamped onto upstream requests as X-NetBird-Groups so downstream
+  // services can read names rather than opaque ids.
+  repeated string peer_group_names = 6;
 }
+
+// ValidateTunnelPeerRequest carries the inbound peer's tunnel IP and the
+// service domain whose group requirements should gate access. The calling
+// account is inferred from the proxy's gRPC metadata (ProxyToken).
+message ValidateTunnelPeerRequest {
+  string tunnel_ip = 1;
+  string domain = 2;
+}
+
+// ValidateTunnelPeerResponse mirrors ValidateSessionResponse plus a freshly
+// minted session_token: when valid is true, the proxy installs the token as
+// a session cookie so subsequent requests skip the management round-trip,
+// matching the OIDC flow's UX. denied_reason values:
+//   "peer_not_found" — no peer with that tunnel IP in the calling account
+//   "no_user"        — peer exists but is not bound to a user
+//   "service_not_found"
+//   "account_mismatch"
+//   "not_in_group"   — peer resolved but not in service.access_groups
+message ValidateTunnelPeerResponse {
+  bool valid = 1;
+  string user_id = 2;
+  string user_email = 3;
+  string denied_reason = 4;
+  // session_token is set only when valid is true. Same shape as the JWT
+  // the OIDC flow produces — proxy installs it via setSessionCookie so the
+  // tunnel fast-path is indistinguishable from OIDC for subsequent requests.
+  string session_token = 5;
+  // peer_group_ids carries the resolved peer's user group memberships so
+  // the proxy can authorise policy-aware middlewares without an additional
+  // management round-trip.
+  repeated string peer_group_ids = 6;
+  // peer_group_names carries the human-readable display names for the
+  // ids in peer_group_ids, ordered identically (positional pairing).
+  // Stamped onto upstream requests as X-NetBird-Groups so downstream
+  // services can read names rather than opaque ids.
+  repeated string peer_group_names = 7;
+}
+
+// SyncMappingsRequest is sent by the proxy on the bidirectional SyncMappings
+// stream. The first message MUST be an init; all subsequent messages MUST be
+// acks.
+message SyncMappingsRequest {
+  oneof msg {
+    SyncMappingsInit init = 1;
+    SyncMappingsAck ack = 2;
+  }
+}
+
+// SyncMappingsInit is the first message on the stream, carrying the same
+// identification fields as GetMappingUpdateRequest.
+message SyncMappingsInit {
+  string proxy_id = 1;
+  string version = 2;
+  google.protobuf.Timestamp started_at = 3;
+  string address = 4;
+  ProxyCapabilities capabilities = 5;
+}
+
+// SyncMappingsAck is sent by the proxy after it has fully processed a batch.
+// Management waits for this before sending the next batch.
+message SyncMappingsAck {}
+
+// SyncMappingsResponse is a batch of mappings sent by management.
+// Identical semantics to GetMappingUpdateResponse.
+message SyncMappingsResponse {
+  repeated ProxyMapping mapping = 1;
+  // initial_sync_complete is set on the last message of the initial snapshot.
+  bool initial_sync_complete = 2;
+}
+

shared/management/proto/proxy_service_grpc.pb.go

@@ -19,6 +19,14 @@ const _ = grpc.SupportPackageIsVersion7
 // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.
 type ProxyServiceClient interface {
 	GetMappingUpdate(ctx context.Context, in *GetMappingUpdateRequest, opts ...grpc.CallOption) (ProxyService_GetMappingUpdateClient, error)
+	// SyncMappings is a bidirectional stream that replaces GetMappingUpdate for
+	// new proxies. The proxy sends an initial SyncMappingsRequest to start the
+	// stream and then sends an ack after each batch is fully processed.
+	// Management waits for the ack before sending the next batch, providing
+	// application-level back-pressure during large initial syncs.
+	// Old proxies continue using GetMappingUpdate; old management servers
+	// return Unimplemented for this RPC and proxies fall back.
+	SyncMappings(ctx context.Context, opts ...grpc.CallOption) (ProxyService_SyncMappingsClient, error)
 	SendAccessLog(ctx context.Context, in *SendAccessLogRequest, opts ...grpc.CallOption) (*SendAccessLogResponse, error)
 	Authenticate(ctx context.Context, in *AuthenticateRequest, opts ...grpc.CallOption) (*AuthenticateResponse, error)
 	SendStatusUpdate(ctx context.Context, in *SendStatusUpdateRequest, opts ...grpc.CallOption) (*SendStatusUpdateResponse, error)
@@ -27,6 +35,14 @@ type ProxyServiceClient interface {
 	// ValidateSession validates a session token and checks user access permissions.
 	// Called by the proxy after receiving a session token from OIDC callback.
 	ValidateSession(ctx context.Context, in *ValidateSessionRequest, opts ...grpc.CallOption) (*ValidateSessionResponse, error)
+	// ValidateTunnelPeer resolves an inbound peer by its WireGuard tunnel IP and
+	// checks the resolved user's access against the service's access_groups.
+	// Acts as a fast-path equivalent of OIDC for requests originating on the
+	// netbird mesh: when the source IP maps to a known peer in the calling
+	// account and that peer is in the service's access_groups, the proxy can
+	// issue a session cookie without redirecting through the OIDC flow.
+	// Mirrors ValidateSession's response shape.
+	ValidateTunnelPeer(ctx context.Context, in *ValidateTunnelPeerRequest, opts ...grpc.CallOption) (*ValidateTunnelPeerResponse, error)
 }
 
 type proxyServiceClient struct {
@@ -69,6 +85,37 @@ func (x *proxyServiceGetMappingUpdateClient) Recv() (*GetMappingUpdateResponse,
 	return m, nil
 }
 
+func (c *proxyServiceClient) SyncMappings(ctx context.Context, opts ...grpc.CallOption) (ProxyService_SyncMappingsClient, error) {
+	stream, err := c.cc.NewStream(ctx, &ProxyService_ServiceDesc.Streams[1], "/management.ProxyService/SyncMappings", opts...)
+	if err != nil {
+		return nil, err
+	}
+	x := &proxyServiceSyncMappingsClient{stream}
+	return x, nil
+}
+
+type ProxyService_SyncMappingsClient interface {
+	Send(*SyncMappingsRequest) error
+	Recv() (*SyncMappingsResponse, error)
+	grpc.ClientStream
+}
+
+type proxyServiceSyncMappingsClient struct {
+	grpc.ClientStream
+}
+
+func (x *proxyServiceSyncMappingsClient) Send(m *SyncMappingsRequest) error {
+	return x.ClientStream.SendMsg(m)
+}
+
+func (x *proxyServiceSyncMappingsClient) Recv() (*SyncMappingsResponse, error) {
+	m := new(SyncMappingsResponse)
+	if err := x.ClientStream.RecvMsg(m); err != nil {
+		return nil, err
+	}
+	return m, nil
+}
+
 func (c *proxyServiceClient) SendAccessLog(ctx context.Context, in *SendAccessLogRequest, opts ...grpc.CallOption) (*SendAccessLogResponse, error) {
 	out := new(SendAccessLogResponse)
 	err := c.cc.Invoke(ctx, "/management.ProxyService/SendAccessLog", in, out, opts...)
@@ -123,11 +170,28 @@ func (c *proxyServiceClient) ValidateSession(ctx context.Context, in *ValidateSe
 	return out, nil
 }
 
+func (c *proxyServiceClient) ValidateTunnelPeer(ctx context.Context, in *ValidateTunnelPeerRequest, opts ...grpc.CallOption) (*ValidateTunnelPeerResponse, error) {
+	out := new(ValidateTunnelPeerResponse)
+	err := c.cc.Invoke(ctx, "/management.ProxyService/ValidateTunnelPeer", in, out, opts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
 // ProxyServiceServer is the server API for ProxyService service.
 // All implementations must embed UnimplementedProxyServiceServer
 // for forward compatibility
 type ProxyServiceServer interface {
 	GetMappingUpdate(*GetMappingUpdateRequest, ProxyService_GetMappingUpdateServer) error
+	// SyncMappings is a bidirectional stream that replaces GetMappingUpdate for
+	// new proxies. The proxy sends an initial SyncMappingsRequest to start the
+	// stream and then sends an ack after each batch is fully processed.
+	// Management waits for the ack before sending the next batch, providing
+	// application-level back-pressure during large initial syncs.
+	// Old proxies continue using GetMappingUpdate; old management servers
+	// return Unimplemented for this RPC and proxies fall back.
+	SyncMappings(ProxyService_SyncMappingsServer) error
 	SendAccessLog(context.Context, *SendAccessLogRequest) (*SendAccessLogResponse, error)
 	Authenticate(context.Context, *AuthenticateRequest) (*AuthenticateResponse, error)
 	SendStatusUpdate(context.Context, *SendStatusUpdateRequest) (*SendStatusUpdateResponse, error)
@@ -136,6 +200,14 @@ type ProxyServiceServer interface {
 	// ValidateSession validates a session token and checks user access permissions.
 	// Called by the proxy after receiving a session token from OIDC callback.
 	ValidateSession(context.Context, *ValidateSessionRequest) (*ValidateSessionResponse, error)
+	// ValidateTunnelPeer resolves an inbound peer by its WireGuard tunnel IP and
+	// checks the resolved user's access against the service's access_groups.
+	// Acts as a fast-path equivalent of OIDC for requests originating on the
+	// netbird mesh: when the source IP maps to a known peer in the calling
+	// account and that peer is in the service's access_groups, the proxy can
+	// issue a session cookie without redirecting through the OIDC flow.
+	// Mirrors ValidateSession's response shape.
+	ValidateTunnelPeer(context.Context, *ValidateTunnelPeerRequest) (*ValidateTunnelPeerResponse, error)
 	mustEmbedUnimplementedProxyServiceServer()
 }
 
@@ -146,6 +218,9 @@ type UnimplementedProxyServiceServer struct {
 func (UnimplementedProxyServiceServer) GetMappingUpdate(*GetMappingUpdateRequest, ProxyService_GetMappingUpdateServer) error {
 	return status.Errorf(codes.Unimplemented, "method GetMappingUpdate not implemented")
 }
+func (UnimplementedProxyServiceServer) SyncMappings(ProxyService_SyncMappingsServer) error {
+	return status.Errorf(codes.Unimplemented, "method SyncMappings not implemented")
+}
 func (UnimplementedProxyServiceServer) SendAccessLog(context.Context, *SendAccessLogRequest) (*SendAccessLogResponse, error) {
 	return nil, status.Errorf(codes.Unimplemented, "method SendAccessLog not implemented")
 }
@@ -164,6 +239,9 @@ func (UnimplementedProxyServiceServer) GetOIDCURL(context.Context, *GetOIDCURLRe
 func (UnimplementedProxyServiceServer) ValidateSession(context.Context, *ValidateSessionRequest) (*ValidateSessionResponse, error) {
 	return nil, status.Errorf(codes.Unimplemented, "method ValidateSession not implemented")
 }
+func (UnimplementedProxyServiceServer) ValidateTunnelPeer(context.Context, *ValidateTunnelPeerRequest) (*ValidateTunnelPeerResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method ValidateTunnelPeer not implemented")
+}
 func (UnimplementedProxyServiceServer) mustEmbedUnimplementedProxyServiceServer() {}
 
 // UnsafeProxyServiceServer may be embedded to opt out of forward compatibility for this service.
@@ -198,6 +276,32 @@ func (x *proxyServiceGetMappingUpdateServer) Send(m *GetMappingUpdateResponse) e
 	return x.ServerStream.SendMsg(m)
 }
 
+func _ProxyService_SyncMappings_Handler(srv interface{}, stream grpc.ServerStream) error {
+	return srv.(ProxyServiceServer).SyncMappings(&proxyServiceSyncMappingsServer{stream})
+}
+
+type ProxyService_SyncMappingsServer interface {
+	Send(*SyncMappingsResponse) error
+	Recv() (*SyncMappingsRequest, error)
+	grpc.ServerStream
+}
+
+type proxyServiceSyncMappingsServer struct {
+	grpc.ServerStream
+}
+
+func (x *proxyServiceSyncMappingsServer) Send(m *SyncMappingsResponse) error {
+	return x.ServerStream.SendMsg(m)
+}
+
+func (x *proxyServiceSyncMappingsServer) Recv() (*SyncMappingsRequest, error) {
+	m := new(SyncMappingsRequest)
+	if err := x.ServerStream.RecvMsg(m); err != nil {
+		return nil, err
+	}
+	return m, nil
+}
+
 func _ProxyService_SendAccessLog_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
 	in := new(SendAccessLogRequest)
 	if err := dec(in); err != nil {
@@ -306,6 +410,24 @@ func _ProxyService_ValidateSession_Handler(srv interface{}, ctx context.Context,
 	return interceptor(ctx, in, info, handler)
 }
 
+func _ProxyService_ValidateTunnelPeer_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(ValidateTunnelPeerRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(ProxyServiceServer).ValidateTunnelPeer(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: "/management.ProxyService/ValidateTunnelPeer",
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(ProxyServiceServer).ValidateTunnelPeer(ctx, req.(*ValidateTunnelPeerRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
 // ProxyService_ServiceDesc is the grpc.ServiceDesc for ProxyService service.
 // It's only intended for direct use with grpc.RegisterService,
 // and not to be introspected or modified (even as a copy)
@@ -337,6 +459,10 @@ var ProxyService_ServiceDesc = grpc.ServiceDesc{
 			MethodName: "ValidateSession",
 			Handler:    _ProxyService_ValidateSession_Handler,
 		},
+		{
+			MethodName: "ValidateTunnelPeer",
+			Handler:    _ProxyService_ValidateTunnelPeer_Handler,
+		},
 	},
 	Streams: []grpc.StreamDesc{
 		{
@@ -344,6 +470,12 @@ var ProxyService_ServiceDesc = grpc.ServiceDesc{
 			Handler:       _ProxyService_GetMappingUpdate_Handler,
 			ServerStreams: true,
 		},
+		{
+			StreamName:    "SyncMappings",
+			Handler:       _ProxyService_SyncMappings_Handler,
+			ServerStreams: true,
+			ClientStreams: true,
+		},
 	},
 	Metadata: "proxy_service.proto",
 }

shared/relay/client/client.go

@@ -9,12 +9,14 @@ import (
 	"net/url"
 	"strings"
 	"sync"
+	"sync/atomic"
 	"time"
 
 	log "github.com/sirupsen/logrus"
 
 	auth "github.com/netbirdio/netbird/shared/relay/auth/hmac"
 	"github.com/netbirdio/netbird/shared/relay/client/dialer"
+	netErr "github.com/netbirdio/netbird/shared/relay/client/dialer/net"
 	"github.com/netbirdio/netbird/shared/relay/healthcheck"
 	"github.com/netbirdio/netbird/shared/relay/messages"
 )
@@ -172,6 +174,19 @@ type Client struct {
 	stateSubscription *PeersStateSubscription
 
 	mtu uint16
+
+	// transportFallback, when set, records datagram-too-large failures so a
+	// datagram-sized transport is avoided on subsequent connects. Shared via
+	// the manager.
+	transportFallback *transportFallback
+	// datagramFallbackTriggered guards a single fallback per connection so a
+	// burst of oversized datagrams triggers one reconnect, not many.
+	datagramFallbackTriggered atomic.Bool
+}
+
+// SetTransportFallback wires the shared datagram-transport fallback tracker.
+func (c *Client) SetTransportFallback(tf *transportFallback) {
+	c.transportFallback = tf
 }
 
 // NewClient creates a new client for the relay server. The client is not connected to the server until the Connect
@@ -361,12 +376,13 @@ func (c *Client) Close() error {
 }
 
 func (c *Client) connect(ctx context.Context) (*RelayAddr, error) {
-	dialers := c.getDialers()
+	mode := transportModeFromEnv()
+	dialers := c.getDialers(mode)
 
 	var conn net.Conn
 	if c.serverIP.IsValid() {
 		var err error
-		conn, err = c.dialRaceDirect(ctx, dialers)
+		conn, err = c.dialRaceDirect(ctx, mode, dialers)
 		if err != nil {
 			c.log.Infof("dial via server IP %s failed, falling back to FQDN: %v", c.serverIP, err)
 			conn = nil
@@ -375,6 +391,9 @@ func (c *Client) connect(ctx context.Context) (*RelayAddr, error) {
 
 	if conn == nil {
 		rd := dialer.NewRaceDial(c.log, dialer.DefaultConnectionTimeout, c.connectionURL, dialers...)
+		if mode.sequential() {
+			rd.WithSequential()
+		}
 		var err error
 		conn, err = rd.Dial(ctx)
 		if err != nil {
@@ -382,6 +401,7 @@ func (c *Client) connect(ctx context.Context) (*RelayAddr, error) {
 		}
 	}
 	c.relayConn = conn
+	c.datagramFallbackTriggered.Store(false)
 
 	instanceURL, err := c.handShake(ctx)
 	if err != nil {
@@ -396,7 +416,7 @@ func (c *Client) connect(ctx context.Context) (*RelayAddr, error) {
 }
 
 // dialRaceDirect dials c.serverIP, preserving the original FQDN as the TLS ServerName for SNI.
-func (c *Client) dialRaceDirect(ctx context.Context, dialers []dialer.DialeFn) (net.Conn, error) {
+func (c *Client) dialRaceDirect(ctx context.Context, mode TransportMode, dialers []dialer.DialeFn) (net.Conn, error) {
 	directURL, serverName, err := substituteHost(c.connectionURL, c.serverIP)
 	if err != nil {
 		return nil, fmt.Errorf("substitute host: %w", err)
@@ -406,6 +426,9 @@ func (c *Client) dialRaceDirect(ctx context.Context, dialers []dialer.DialeFn) (
 
 	rd := dialer.NewRaceDial(c.log, dialer.DefaultConnectionTimeout, directURL, dialers...).
 		WithServerName(serverName)
+	if mode.sequential() {
+		rd.WithSequential()
+	}
 	return rd.Dial(ctx)
 }
 
@@ -631,13 +654,53 @@ func (c *Client) writeTo(containerRef *connContainer, dstID messages.PeerID, pay
 	}
 
 	// the write always return with 0 length because the underling does not support the size feedback.
-	_, err = c.relayConn.Write(msg)
+	conn := c.relayConn
+	_, err = conn.Write(msg)
 	if err != nil {
-		c.log.Errorf("failed to write transport message: %s", err)
+		if errors.Is(err, netErr.ErrDatagramTooLarge) {
+			c.onDatagramTooLarge(conn, err)
+		} else {
+			c.log.Errorf("failed to write transport message: %s", err)
+		}
 	}
 	return len(payload), err
 }
 
+// onDatagramTooLarge reacts to a datagram rejected as too large for the path.
+// When a non-datagram transport is available, it records a fallback for this
+// server and closes the connection so the reconnect avoids datagram-sized
+// transports. A single fallback is triggered per connection regardless of how
+// many oversized datagrams arrive. cause carries the datagram size and budget.
+func (c *Client) onDatagramTooLarge(conn net.Conn, cause error) {
+	// Handle one oversized datagram per connection; a burst triggers a single
+	// fallback (and a single log line), not many.
+	if !c.datagramFallbackTriggered.CompareAndSwap(false, true) {
+		return
+	}
+
+	// If the selected mode offers no non-datagram transport (e.g. pinned to a
+	// datagram-sized transport), reconnecting would just re-fail, so leave the
+	// connection up rather than loop.
+	if len(nonDatagramSized(c.baseDialers(transportModeFromEnv()))) == 0 {
+		c.log.Warnf("%s, but no non-datagram transport is available, not falling back", cause)
+		return
+	}
+
+	// Without the shared tracker a reconnect would just select the same
+	// transport again and re-fail, so leave the connection up rather than loop.
+	if c.transportFallback == nil {
+		c.log.Debugf("%s, but no transport fallback configured, leaving connection up", cause)
+		return
+	}
+
+	window := c.transportFallback.recordFailure(c.connectionURL)
+	c.log.Warnf("%s, avoiding datagram-sized transport for %s", cause, window)
+
+	if err := conn.Close(); err != nil {
+		c.log.Debugf("close relay connection for transport fallback: %s", err)
+	}
+}
+
 func (c *Client) listenForStopEvents(ctx context.Context, hc *healthcheck.Receiver, conn net.Conn, internalStopFlag *internalStopFlag) {
 	for {
 		select {

shared/relay/client/dialer/capability.go

@@ -0,0 +1,18 @@
+package dialer
+
+// DatagramSized is implemented by dialers whose connections carry each write in
+// a single datagram, so a write can be rejected when it exceeds the path's
+// datagram budget (e.g. QUIC). Transports without this capability (e.g.
+// WebSocket over TCP) impose no per-write size limit, so the relay client can
+// fall back to them when a datagram-sized transport rejects a write as too
+// large. The capability is advertised per dialer rather than hardcoded, so a
+// new transport only needs to declare whether it is datagram-sized.
+type DatagramSized interface {
+	DatagramSized()
+}
+
+// IsDatagramSized reports whether d produces datagram-sized connections.
+func IsDatagramSized(d DialeFn) bool {
+	_, ok := d.(DatagramSized)
+	return ok
+}

shared/relay/client/dialer/net/err.go

@@ -4,4 +4,9 @@ import "errors"
 
 var (
 	ErrClosedByServer = errors.New("closed by server")
+
+	// ErrDatagramTooLarge is returned when a transport message exceeds the
+	// QUIC datagram size the path to the relay can carry. The relay client
+	// treats it as a signal to fall back to a non-datagram transport.
+	ErrDatagramTooLarge = errors.New("datagram frame too large")
 )

shared/relay/client/dialer/quic/conn.go

@@ -8,7 +8,6 @@ import (
 	"time"
 
 	"github.com/quic-go/quic-go"
-	log "github.com/sirupsen/logrus"
 
 	netErr "github.com/netbirdio/netbird/shared/relay/client/dialer/net"
 )
@@ -52,11 +51,8 @@ func (c *Conn) Read(b []byte) (n int, err error) {
 }
 
 func (c *Conn) Write(b []byte) (int, error) {
-	err := c.session.SendDatagram(b)
-	if err != nil {
-		err = c.remoteCloseErrHandling(err)
-		log.Errorf("failed to write to QUIC stream: %v", err)
-		return 0, err
+	if err := c.session.SendDatagram(b); err != nil {
+		return 0, c.writeErrHandling(err, len(b))
 	}
 	return len(b), nil
 }
@@ -95,3 +91,15 @@ func (c *Conn) remoteCloseErrHandling(err error) error {
 	}
 	return err
 }
+
+// writeErrHandling normalizes SendDatagram errors. A datagram that exceeds the
+// path's QUIC packet budget is mapped to ErrDatagramTooLarge (annotated with the
+// datagram size and path budget) so the relay client can fall back to a
+// non-datagram transport.
+func (c *Conn) writeErrHandling(err error, size int) error {
+	var tooLarge *quic.DatagramTooLargeError
+	if errors.As(err, &tooLarge) {
+		return fmt.Errorf("%w: %d byte datagram over path budget %d", netErr.ErrDatagramTooLarge, size, tooLarge.MaxDatagramPayloadSize)
+	}
+	return c.remoteCloseErrHandling(err)
+}

shared/relay/client/dialer/quic/quic.go

@@ -9,6 +9,7 @@ import (
 	"time"
 
 	"github.com/quic-go/quic-go"
+	"github.com/quic-go/quic-go/logging"
 	log "github.com/sirupsen/logrus"
 
 	nbnet "github.com/netbirdio/netbird/client/net"
@@ -23,6 +24,12 @@ func (d Dialer) Protocol() string {
 	return Network
 }
 
+// DatagramSized marks QUIC as a datagram-sized transport: relay traffic is
+// carried in QUIC DATAGRAM frames, which must fit a single packet.
+func (d Dialer) DatagramSized() {
+	// Intentional marker method; presence is the capability signal.
+}
+
 func (d Dialer) Dial(ctx context.Context, address, serverName string) (net.Conn, error) {
 	quicURL, err := prepareURL(address)
 	if err != nil {
@@ -47,6 +54,7 @@ func (d Dialer) Dial(ctx context.Context, address, serverName string) (net.Conn,
 		MaxIdleTimeout:    4 * time.Minute,
 		EnableDatagrams:   true,
 		InitialPacketSize: nbRelay.QUICInitialPacketSize,
+		Tracer:            connectionTracer(quicURL),
 	}
 
 	udpConn, err := nbnet.ListenUDP("udp", &net.UDPAddr{Port: 0})
@@ -74,6 +82,28 @@ func (d Dialer) Dial(ctx context.Context, address, serverName string) (net.Conn,
 	return conn, nil
 }
 
+// connectionTracer returns a QUIC tracer that logs the DPLPMTUD result and the
+// reason a relay connection closed, so the path MTU settled on and teardown
+// cause are visible in logs. Lines carry the relay address as a structured
+// field, matching the rest of the relay client logging.
+func connectionTracer(addr string) func(context.Context, logging.Perspective, quic.ConnectionID) *logging.ConnectionTracer {
+	relayLog := log.WithField("relay", addr)
+	return func(context.Context, logging.Perspective, quic.ConnectionID) *logging.ConnectionTracer {
+		return &logging.ConnectionTracer{
+			UpdatedMTU: func(mtu logging.ByteCount, done bool) {
+				if done {
+					relayLog.Infof("QUIC path MTU settled at %d", mtu)
+					return
+				}
+				relayLog.Debugf("QUIC path MTU probing at %d", mtu)
+			},
+			ClosedConnection: func(err error) {
+				relayLog.Debugf("QUIC connection closed: %v", err)
+			},
+		}
+	}
+}
+
 func prepareURL(address string) (string, error) {
 	var host string
 	var defaultPort string

shared/relay/client/dialer/race_dialer.go

@@ -32,6 +32,7 @@ type RaceDial struct {
 	serverName        string
 	dialerFns         []DialeFn
 	connectionTimeout time.Duration
+	sequential        bool
 }
 
 func NewRaceDial(log *log.Entry, connectionTimeout time.Duration, serverURL string, dialerFns ...DialeFn) *RaceDial {
@@ -53,7 +54,21 @@ func (r *RaceDial) WithServerName(serverName string) *RaceDial {
 	return r
 }
 
+// WithSequential makes Dial try the dialers in order, falling back to the next
+// only when one fails to connect, instead of racing them concurrently.
+//
+// Mutates the receiver and is not safe for concurrent reconfiguration; a
+// RaceDial is intended to be constructed per dial and discarded.
+func (r *RaceDial) WithSequential() *RaceDial {
+	r.sequential = true
+	return r
+}
+
 func (r *RaceDial) Dial(ctx context.Context) (net.Conn, error) {
+	if r.sequential {
+		return r.dialSequential(ctx)
+	}
+
 	connChan := make(chan dialResult, len(r.dialerFns))
 	winnerConn := make(chan net.Conn, 1)
 	abortCtx, abort := context.WithCancel(ctx)
@@ -72,6 +87,30 @@ func (r *RaceDial) Dial(ctx context.Context) (net.Conn, error) {
 	return conn, nil
 }
 
+// dialSequential tries each dialer in order, returning the first connection and
+// falling back to the next on failure.
+func (r *RaceDial) dialSequential(ctx context.Context) (net.Conn, error) {
+	for _, dfn := range r.dialerFns {
+		if err := ctx.Err(); err != nil {
+			return nil, err
+		}
+		attemptCtx, cancel := context.WithTimeout(ctx, r.connectionTimeout)
+		r.log.Infof("dialing Relay server via %s", dfn.Protocol())
+		conn, err := dfn.Dial(attemptCtx, r.serverURL, r.serverName)
+		cancel()
+		if err != nil {
+			if errors.Is(err, context.Canceled) {
+				return nil, err
+			}
+			r.log.Errorf("failed to dial via %s: %s", dfn.Protocol(), err)
+			continue
+		}
+		r.log.Infof("successfully dialed via: %s", dfn.Protocol())
+		return conn, nil
+	}
+	return nil, errors.New("failed to dial to Relay server on any protocol")
+}
+
 func (r *RaceDial) dial(dfn DialeFn, abortCtx context.Context, connChan chan dialResult) {
 	ctx, cancel := context.WithTimeout(abortCtx, r.connectionTimeout)
 	defer cancel()

shared/relay/client/dialer/race_dialer_test.go

@@ -250,3 +250,66 @@ func TestRaceDialFirstSuccessfulDialerWins(t *testing.T) {
 		}
 	}
 }
+
+func TestRaceDialSequentialFallback(t *testing.T) {
+	logger := logrus.NewEntry(logrus.New())
+	serverURL := "test.server.com"
+
+	var firstDialed, secondDialed bool
+	preferred := &MockDialer{
+		protocolStr: "quic",
+		dialFunc: func(ctx context.Context, address string) (net.Conn, error) {
+			firstDialed = true
+			return nil, errors.New("quic unreachable")
+		},
+	}
+	fallbackConn := &MockConn{remoteAddr: &MockAddr{network: "ws"}}
+	fallback := &MockDialer{
+		protocolStr: "ws",
+		dialFunc: func(ctx context.Context, address string) (net.Conn, error) {
+			secondDialed = true
+			return fallbackConn, nil
+		},
+	}
+
+	rd := NewRaceDial(logger, DefaultConnectionTimeout, serverURL, preferred, fallback).WithSequential()
+	conn, err := rd.Dial(context.Background())
+	if err != nil {
+		t.Fatalf("expected fallback to succeed, got %v", err)
+	}
+	if conn != fallbackConn {
+		t.Errorf("expected fallback connection, got %v", conn)
+	}
+	if !firstDialed || !secondDialed {
+		t.Errorf("expected both dialers attempted in order, first=%v second=%v", firstDialed, secondDialed)
+	}
+}
+
+func TestRaceDialSequentialPreferredWins(t *testing.T) {
+	logger := logrus.NewEntry(logrus.New())
+	serverURL := "test.server.com"
+
+	preferredConn := &MockConn{remoteAddr: &MockAddr{network: "quic"}}
+	preferred := &MockDialer{
+		protocolStr: "quic",
+		dialFunc: func(ctx context.Context, address string) (net.Conn, error) {
+			return preferredConn, nil
+		},
+	}
+	fallback := &MockDialer{
+		protocolStr: "ws",
+		dialFunc: func(ctx context.Context, address string) (net.Conn, error) {
+			t.Errorf("fallback dialer must not be tried when preferred succeeds")
+			return nil, errors.New("should not happen")
+		},
+	}
+
+	rd := NewRaceDial(logger, DefaultConnectionTimeout, serverURL, preferred, fallback).WithSequential()
+	conn, err := rd.Dial(context.Background())
+	if err != nil {
+		t.Fatalf("expected preferred to succeed, got %v", err)
+	}
+	if conn != preferredConn {
+		t.Errorf("expected preferred connection, got %v", conn)
+	}
+}

shared/relay/client/dialers_generic.go

@@ -9,11 +9,42 @@ import (
 	"github.com/netbirdio/netbird/shared/relay/client/dialer/ws"
 )
 
-// getDialers returns the list of dialers to use for connecting to the relay server.
-func (c *Client) getDialers() []dialer.DialeFn {
-	if c.mtu > 0 && c.mtu > iface.DefaultMTU {
-		c.log.Infof("MTU %d exceeds default (%d), forcing WebSocket transport to avoid DATAGRAM frame size issues", c.mtu, iface.DefaultMTU)
-		return []dialer.DialeFn{ws.Dialer{}}
+// getDialers returns the ordered dialers for connecting to the relay server. It
+// applies the datagram fallback generically: if this server recently rejected a
+// datagram-sized transport, those dialers are dropped, leaving the rest.
+func (c *Client) getDialers(mode TransportMode) []dialer.DialeFn {
+	dialers := c.baseDialers(mode)
+
+	if c.transportFallback != nil && c.transportFallback.avoidDatagramSized(c.connectionURL) {
+		if filtered := nonDatagramSized(dialers); len(filtered) > 0 {
+			c.log.Infof("relay recently rejected a datagram-sized transport, avoiding it")
+			return filtered
+		}
 	}
-	return []dialer.DialeFn{quic.Dialer{}, ws.Dialer{}}
+	return dialers
+}
+
+// baseDialers returns the ordered dialers for the mode, before any datagram
+// fallback filtering. For racing modes (auto) the order is irrelevant; for
+// prefer modes the first entry is tried before falling back to the second.
+func (c *Client) baseDialers(mode TransportMode) []dialer.DialeFn {
+	switch mode {
+	case TransportModeWS:
+		c.log.Infof("%s=ws, using WebSocket transport", EnvRelayTransport)
+		return []dialer.DialeFn{ws.Dialer{}}
+	case TransportModeQUIC:
+		c.log.Infof("%s=quic, using QUIC transport", EnvRelayTransport)
+		return []dialer.DialeFn{quic.Dialer{}}
+	}
+
+	all := []dialer.DialeFn{quic.Dialer{}, ws.Dialer{}}
+	if mode == TransportModePreferWS {
+		all = []dialer.DialeFn{ws.Dialer{}, quic.Dialer{}}
+	}
+
+	if c.mtu > 0 && c.mtu > iface.DefaultMTU {
+		c.log.Infof("MTU %d exceeds default (%d), avoiding datagram-sized transports", c.mtu, iface.DefaultMTU)
+		return nonDatagramSized(all)
+	}
+	return all
 }

shared/relay/client/dialers_generic_test.go

@@ -0,0 +1,101 @@
+//go:build !js
+
+package client
+
+import (
+	"os"
+	"testing"
+
+	log "github.com/sirupsen/logrus"
+	"github.com/stretchr/testify/assert"
+
+	"github.com/netbirdio/netbird/client/iface"
+	"github.com/netbirdio/netbird/shared/relay/client/dialer"
+	netErr "github.com/netbirdio/netbird/shared/relay/client/dialer/net"
+	"github.com/netbirdio/netbird/shared/relay/client/dialer/quic"
+	"github.com/netbirdio/netbird/shared/relay/client/dialer/ws"
+)
+
+// TestDatagramSizedCapability locks the capability the generic fallback relies
+// on: QUIC is datagram-sized, WebSocket is not.
+func TestDatagramSizedCapability(t *testing.T) {
+	assert.True(t, dialer.IsDatagramSized(quic.Dialer{}), "QUIC must advertise datagram-sized")
+	assert.False(t, dialer.IsDatagramSized(ws.Dialer{}), "WebSocket must not advertise datagram-sized")
+}
+
+func protocols(dialers []dialer.DialeFn) []string {
+	out := make([]string, len(dialers))
+	for i, d := range dialers {
+		out[i] = d.Protocol()
+	}
+	return out
+}
+
+func TestGetDialers(t *testing.T) {
+	const url = "rels://relay.example:443"
+
+	tests := []struct {
+		name     string
+		mode     string
+		mtu      uint16
+		preferWS bool
+		want     []string
+	}{
+		{name: "auto races quic and ws", mode: "auto", mtu: iface.DefaultMTU, want: []string{"quic", "WS"}},
+		{name: "ws pinned", mode: "ws", mtu: iface.DefaultMTU, want: []string{"WS"}},
+		{name: "quic pinned", mode: "quic", mtu: iface.DefaultMTU, want: []string{"quic"}},
+		{name: "prefer-quic orders quic first", mode: "prefer-quic", mtu: iface.DefaultMTU, want: []string{"quic", "WS"}},
+		{name: "prefer-ws orders ws first", mode: "prefer-ws", mtu: iface.DefaultMTU, want: []string{"WS", "quic"}},
+		{name: "mtu above default forces ws", mode: "auto", mtu: iface.DefaultMTU + 100, want: []string{"WS"}},
+		{name: "sticky fallback forces ws in auto", mode: "auto", mtu: iface.DefaultMTU, preferWS: true, want: []string{"WS"}},
+		{name: "sticky fallback forces ws in prefer-quic", mode: "prefer-quic", mtu: iface.DefaultMTU, preferWS: true, want: []string{"WS"}},
+		{name: "quic pin overrides sticky fallback", mode: "quic", mtu: iface.DefaultMTU, preferWS: true, want: []string{"quic"}},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Setenv(EnvRelayTransport, tc.mode)
+			if tc.mode == "" {
+				os.Unsetenv(EnvRelayTransport)
+			}
+
+			tf := newTransportFallback()
+			if tc.preferWS {
+				tf.recordFailure(url)
+			}
+
+			c := &Client{
+				log:               log.WithField("test", t.Name()),
+				connectionURL:     url,
+				mtu:               tc.mtu,
+				transportFallback: tf,
+			}
+
+			assert.Equal(t, tc.want, protocols(c.getDialers(transportModeFromEnv())))
+		})
+	}
+}
+
+// TestStickyFallbackAfterDatagramTooLarge verifies the full chain: an oversized
+// datagram records a fallback that makes the next dial pick WebSocket, the way a
+// reconnect would after the connection is closed.
+func TestStickyFallbackAfterDatagramTooLarge(t *testing.T) {
+	const url = "rels://relay.example:443"
+	t.Setenv(EnvRelayTransport, string(TransportModeAuto))
+
+	c := &Client{
+		log:               log.WithField("test", t.Name()),
+		connectionURL:     url,
+		mtu:               iface.DefaultMTU,
+		transportFallback: newTransportFallback(),
+	}
+
+	// First dial races both transports.
+	assert.Equal(t, []string{"quic", "WS"}, protocols(c.getDialers(transportModeFromEnv())))
+
+	// An oversized datagram records the fallback for this server.
+	c.onDatagramTooLarge(&closeTrackingConn{}, netErr.ErrDatagramTooLarge)
+
+	// The reconnect now sticks to WebSocket.
+	assert.Equal(t, []string{"WS"}, protocols(c.getDialers(transportModeFromEnv())))
+}

shared/relay/client/dialers_js.go

@@ -7,7 +7,11 @@ import (
 	"github.com/netbirdio/netbird/shared/relay/client/dialer/ws"
 )
 
-func (c *Client) getDialers() []dialer.DialeFn {
+func (c *Client) getDialers(_ TransportMode) []dialer.DialeFn {
 	// JS/WASM build only uses WebSocket transport
 	return []dialer.DialeFn{ws.Dialer{}}
 }
+
+func (c *Client) baseDialers(_ TransportMode) []dialer.DialeFn {
+	return []dialer.DialeFn{ws.Dialer{}}
+}

shared/relay/client/manager.go

@@ -79,23 +79,30 @@ type Manager struct {
 
 	cleanupInterval      time.Duration
 	keepUnusedServerTime time.Duration
+
+	// transportFallback is shared across home and foreign relay clients so a
+	// datagram-too-large failure makes that server avoid datagram-sized transports across reconnects.
+	transportFallback *transportFallback
 }
 
 // NewManager creates a new manager instance.
 // The serverURL address can be empty. In this case, the manager will not serve.
 func NewManager(ctx context.Context, serverURLs []string, peerID string, mtu uint16, opts ...ManagerOption) *Manager {
 	tokenStore := &relayAuth.TokenStore{}
+	tf := newTransportFallback()
 
 	m := &Manager{
-		ctx:        ctx,
-		peerID:     peerID,
-		tokenStore: tokenStore,
-		mtu:        mtu,
+		ctx:               ctx,
+		peerID:            peerID,
+		tokenStore:        tokenStore,
+		mtu:               mtu,
+		transportFallback: tf,
 		serverPicker: &ServerPicker{
 			TokenStore:        tokenStore,
 			PeerID:            peerID,
 			MTU:               mtu,
 			ConnectionTimeout: defaultConnectionTimeout,
+			TransportFallback: tf,
 		},
 		relayClients:            make(map[string]*RelayTrack),
 		onDisconnectedListeners: make(map[string]*list.List),
@@ -287,6 +294,7 @@ func (m *Manager) openConnVia(ctx context.Context, serverAddress, peerKey string
 	m.relayClientsMutex.Unlock()
 
 	relayClient := NewClientWithServerIP(serverAddress, serverIP, m.tokenStore, m.peerID, m.mtu)
+	relayClient.SetTransportFallback(m.transportFallback)
 	err := relayClient.Connect(m.ctx)
 	if err != nil {
 		rt.err = err

shared/relay/client/picker.go

@@ -29,6 +29,7 @@ type ServerPicker struct {
 	PeerID            string
 	MTU               uint16
 	ConnectionTimeout time.Duration
+	TransportFallback *transportFallback
 }
 
 func (sp *ServerPicker) PickServer(parentCtx context.Context) (*Client, error) {
@@ -70,6 +71,7 @@ func (sp *ServerPicker) PickServer(parentCtx context.Context) (*Client, error) {
 func (sp *ServerPicker) startConnection(ctx context.Context, resultChan chan connResult, url string) {
 	log.Infof("try to connecting to relay server: %s", url)
 	relayClient := NewClient(url, sp.TokenStore, sp.PeerID, sp.MTU)
+	relayClient.SetTransportFallback(sp.TransportFallback)
 	err := relayClient.Connect(ctx)
 	resultChan <- connResult{
 		RelayClient: relayClient,

shared/relay/client/transport.go

@@ -0,0 +1,129 @@
+package client
+
+import (
+	"os"
+	"strings"
+	"sync"
+	"time"
+
+	log "github.com/sirupsen/logrus"
+
+	"github.com/netbirdio/netbird/shared/relay/client/dialer"
+)
+
+// EnvRelayTransport pins the relay transport. Valid values: "auto" (default,
+// race QUIC and WebSocket), "quic" (QUIC only), "ws" (WebSocket only),
+// "prefer-quic" / "prefer-ws" (try the preferred transport first, fall back to
+// the other only if it fails to connect; no race). The prefer modes trade a
+// slower connect when the preferred transport is blackholed for deterministic
+// transport selection.
+const EnvRelayTransport = "NB_RELAY_TRANSPORT"
+
+const (
+	// transportFallbackBase is the initial window a relay server avoids
+	// datagram-sized transports after a datagram is rejected as too large.
+	transportFallbackBase = 10 * time.Minute
+	// transportFallbackMax caps the pinned window when failures repeat.
+	transportFallbackMax = 60 * time.Minute
+)
+
+// TransportMode selects which relay dialers are used.
+type TransportMode string
+
+const (
+	TransportModeAuto       TransportMode = "auto"
+	TransportModeQUIC       TransportMode = "quic"
+	TransportModeWS         TransportMode = "ws"
+	TransportModePreferQUIC TransportMode = "prefer-quic"
+	TransportModePreferWS   TransportMode = "prefer-ws"
+)
+
+// transportModeFromEnv reads EnvRelayTransport, defaulting to auto for an empty
+// or unrecognized value.
+func transportModeFromEnv() TransportMode {
+	switch TransportMode(strings.ToLower(strings.TrimSpace(os.Getenv(EnvRelayTransport)))) {
+	case "", TransportModeAuto:
+		return TransportModeAuto
+	case TransportModeQUIC:
+		return TransportModeQUIC
+	case TransportModeWS:
+		return TransportModeWS
+	case TransportModePreferQUIC:
+		return TransportModePreferQUIC
+	case TransportModePreferWS:
+		return TransportModePreferWS
+	default:
+		log.Warnf("invalid %s value %q, using %q", EnvRelayTransport, os.Getenv(EnvRelayTransport), TransportModeAuto)
+		return TransportModeAuto
+	}
+}
+
+// sequential reports whether the mode tries dialers in order with fallback
+// instead of racing them concurrently.
+func (m TransportMode) sequential() bool {
+	return m == TransportModePreferQUIC || m == TransportModePreferWS
+}
+
+// transportFallback tracks relay servers that have rejected a datagram-sized
+// transport (a write too large for the path) and should temporarily avoid such
+// transports. It is shared across the relay manager so the preference survives
+// client recreation (foreign relay clients are evicted and rebuilt on
+// disconnect). Entries are keyed by server URL and expire after a window that
+// grows on repeated failures.
+type transportFallback struct {
+	mu      sync.Mutex
+	entries map[string]*fallbackEntry
+}
+
+type fallbackEntry struct {
+	until    time.Time
+	duration time.Duration
+}
+
+func newTransportFallback() *transportFallback {
+	return &transportFallback{entries: make(map[string]*fallbackEntry)}
+}
+
+// avoidDatagramSized reports whether serverURL is currently within a window
+// where datagram-sized transports should be avoided.
+func (f *transportFallback) avoidDatagramSized(serverURL string) bool {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	e := f.entries[serverURL]
+	return e != nil && time.Now().Before(e.until)
+}
+
+// recordFailure makes serverURL avoid datagram-sized transports for a window:
+// transportFallbackBase on the first failure, doubling up to transportFallbackMax
+// when a datagram transport fails again after a previous window expired. It
+// returns the active window duration.
+func (f *transportFallback) recordFailure(serverURL string) time.Duration {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+
+	now := time.Now()
+	e := f.entries[serverURL]
+	switch {
+	case e == nil:
+		e = &fallbackEntry{duration: transportFallbackBase}
+		f.entries[serverURL] = e
+	case now.Before(e.until):
+		return time.Until(e.until)
+	default:
+		e.duration = min(e.duration*2, transportFallbackMax)
+	}
+	e.until = now.Add(e.duration)
+	return e.duration
+}
+
+// nonDatagramSized returns the dialers from in that are not datagram-sized,
+// preserving order.
+func nonDatagramSized(in []dialer.DialeFn) []dialer.DialeFn {
+	out := make([]dialer.DialeFn, 0, len(in))
+	for _, d := range in {
+		if !dialer.IsDatagramSized(d) {
+			out = append(out, d)
+		}
+	}
+	return out
+}

shared/relay/client/transport_test.go

@@ -0,0 +1,140 @@
+package client
+
+import (
+	"net"
+	"os"
+	"testing"
+	"time"
+
+	log "github.com/sirupsen/logrus"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	netErr "github.com/netbirdio/netbird/shared/relay/client/dialer/net"
+)
+
+// closeTrackingConn records whether Close was called; only Close is exercised.
+type closeTrackingConn struct {
+	net.Conn
+	closed bool
+}
+
+func (c *closeTrackingConn) Close() error {
+	c.closed = true
+	return nil
+}
+
+func TestTransportModeFromEnv(t *testing.T) {
+	tests := []struct {
+		value string
+		want  TransportMode
+	}{
+		{"", TransportModeAuto},
+		{"auto", TransportModeAuto},
+		{"quic", TransportModeQUIC},
+		{"QUIC", TransportModeQUIC},
+		{"ws", TransportModeWS},
+		{" Ws ", TransportModeWS},
+		{"prefer-quic", TransportModePreferQUIC},
+		{"prefer-ws", TransportModePreferWS},
+		{"garbage", TransportModeAuto},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.value, func(t *testing.T) {
+			t.Setenv(EnvRelayTransport, tc.value)
+			if tc.value == "" {
+				os.Unsetenv(EnvRelayTransport)
+			}
+			assert.Equal(t, tc.want, transportModeFromEnv())
+		})
+	}
+}
+
+func TestTransportFallbackRecordAndExpiry(t *testing.T) {
+	const url = "rels://relay.example:443"
+	f := newTransportFallback()
+
+	assert.False(t, f.avoidDatagramSized(url), "no fallback recorded yet")
+
+	d := f.recordFailure(url)
+	assert.Equal(t, transportFallbackBase, d, "first failure pins for the base window")
+	assert.True(t, f.avoidDatagramSized(url), "datagram-sized transport avoided within the window")
+
+	// A second failure while still inside the window must not grow the window.
+	d = f.recordFailure(url)
+	assert.LessOrEqual(t, d, transportFallbackBase, "still within the active window")
+	require.NotNil(t, f.entries[url])
+	assert.Equal(t, transportFallbackBase, f.entries[url].duration, "duration unchanged inside window")
+
+	// Expire the window: datagram-sized transport allowed again.
+	f.entries[url].until = time.Now().Add(-time.Second)
+	assert.False(t, f.avoidDatagramSized(url), "window expired, datagram-sized transport allowed")
+}
+
+func TestTransportFallbackGrowsOnRepeat(t *testing.T) {
+	const url = "rels://relay.example:443"
+	f := newTransportFallback()
+
+	want := transportFallbackBase
+	for i := range 6 {
+		d := f.recordFailure(url)
+		assert.Equal(t, want, d, "window after %d expiries", i)
+
+		// expire the window so the next failure is treated as a repeat
+		f.entries[url].until = time.Now().Add(-time.Second)
+
+		want = min(want*2, transportFallbackMax)
+	}
+
+	assert.Equal(t, transportFallbackMax, f.entries[url].duration, "window caps at the max")
+}
+
+func TestOnDatagramTooLargeAuto(t *testing.T) {
+	const url = "rels://relay.example:443"
+	t.Setenv(EnvRelayTransport, string(TransportModeAuto))
+
+	tf := newTransportFallback()
+	c := &Client{
+		log:               log.WithField("test", t.Name()),
+		connectionURL:     url,
+		transportFallback: tf,
+	}
+	conn := &closeTrackingConn{}
+
+	c.onDatagramTooLarge(conn, netErr.ErrDatagramTooLarge)
+
+	assert.True(t, conn.closed, "connection closed to force reconnect")
+	assert.True(t, tf.avoidDatagramSized(url), "fallback recorded for the server")
+
+	// A second oversized datagram on the same connection must not re-close.
+	conn.closed = false
+	c.onDatagramTooLarge(conn, netErr.ErrDatagramTooLarge)
+	assert.False(t, conn.closed, "single fallback per connection")
+}
+
+func TestOnDatagramTooLargeQUICPinned(t *testing.T) {
+	const url = "rels://relay.example:443"
+	t.Setenv(EnvRelayTransport, string(TransportModeQUIC))
+
+	tf := newTransportFallback()
+	c := &Client{
+		log:               log.WithField("test", t.Name()),
+		connectionURL:     url,
+		transportFallback: tf,
+	}
+	conn := &closeTrackingConn{}
+
+	c.onDatagramTooLarge(conn, netErr.ErrDatagramTooLarge)
+
+	assert.False(t, conn.closed, "QUIC pin keeps the connection, no fallback redial")
+	assert.False(t, tf.avoidDatagramSized(url), "QUIC pin records no fallback")
+}
+
+func TestTransportFallbackPerServer(t *testing.T) {
+	f := newTransportFallback()
+	f.recordFailure("rels://a.example:443")
+
+	assert.True(t, f.avoidDatagramSized("rels://a.example:443"))
+	assert.False(t, f.avoidDatagramSized("rels://b.example:443"), "fallback is scoped to one server")
+}