use API

(We now do AsyncStart + waitEstablishedOrDone, so everything is managed inside the
supervisor)

client/android/client.go

@@ -151,9 +151,9 @@ func (c *Client) Run(platformFiles PlatformFiles, urlOpener URLOpener, isAndroid
 
 	// todo do not throw error in case of cancelled context
 	ctx = internal.CtxInitState(ctx)
-	connectClient := internal.NewConnectClient(ctx, cfg, c.recorder)
+	connectClient := internal.NewConnectClient(ctx, c.recorder)
 	c.setState(cfg, cacheDir, connectClient)
-	return connectClient.RunOnAndroid(c.tunAdapter, c.iFaceDiscover, c.networkChangeListener, slices.Clone(dns.items), dnsReadyListener, stateFile, cacheDir)
+	return connectClient.RunOnAndroid(cfg, c.tunAdapter, c.iFaceDiscover, c.networkChangeListener, slices.Clone(dns.items), dnsReadyListener, stateFile, cacheDir)
 }
 
 // RunWithoutLogin we apply this type of run function when the backed has been started without UI (i.e. after reboot).
@@ -186,9 +186,9 @@ func (c *Client) RunWithoutLogin(platformFiles PlatformFiles, dns *DNSList, dnsR
 
 	// todo do not throw error in case of cancelled context
 	ctx = internal.CtxInitState(ctx)
-	connectClient := internal.NewConnectClient(ctx, cfg, c.recorder)
+	connectClient := internal.NewConnectClient(ctx, c.recorder)
 	c.setState(cfg, cacheDir, connectClient)
-	return connectClient.RunOnAndroid(c.tunAdapter, c.iFaceDiscover, c.networkChangeListener, slices.Clone(dns.items), dnsReadyListener, stateFile, cacheDir)
+	return connectClient.RunOnAndroid(cfg, c.tunAdapter, c.iFaceDiscover, c.networkChangeListener, slices.Clone(dns.items), dnsReadyListener, stateFile, cacheDir)
 }
 
 // Stop the internal client and free the resources

client/cmd/root.go

@@ -20,6 +20,7 @@ import (
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 	"google.golang.org/grpc"
+	"google.golang.org/grpc/connectivity"
 	"google.golang.org/grpc/credentials/insecure"
 
 	daddr "github.com/netbirdio/netbird/client/internal/daemonaddr"
@@ -261,17 +262,46 @@ func FlagNameToEnvVar(cmdFlag string, prefix string) string {
 	return prefix + upper
 }
 
-// DialClientGRPCServer returns client connection to the daemon server.
+// DialClientGRPCServer returns client connection to the daemon server. It waits
+// (up to the timeout) for the daemon to become reachable so an `up` issued right
+// after `service start` tolerates the startup race. Instead of grpc's blocking
+// dial — whose raw "transport failed" retry warnings are silenced by the logger
+// config — we drive the wait ourselves and emit one clean line per failed attempt.
 func DialClientGRPCServer(ctx context.Context, addr string) (*grpc.ClientConn, error) {
 	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
 	defer cancel()
 
-	return grpc.DialContext(
+	conn, err := grpc.DialContext(
 		ctx,
 		strings.TrimPrefix(addr, "tcp://"),
 		grpc.WithTransportCredentials(insecure.NewCredentials()),
-		grpc.WithBlock(),
 	)
+	if err != nil {
+		return nil, err
+	}
+
+	conn.Connect()
+	for {
+		state := conn.GetState()
+		if state == connectivity.Ready {
+			return conn, nil
+		}
+		// Log only once the connection has actually failed — not during the
+		// brief Idle/Connecting phase on a healthy daemon (avoids a spurious
+		// line + wait when the daemon is already up).
+		if state == connectivity.TransientFailure {
+			log.Infof("waiting for the netbird daemon to become available at %s...", addr)
+		}
+		// Wake on the next state change, but at least every second so a stuck
+		// TransientFailure re-logs at a steady cadence until the timeout.
+		waitCtx, waitCancel := context.WithTimeout(ctx, time.Second)
+		conn.WaitForStateChange(waitCtx, state)
+		waitCancel()
+		if ctx.Err() != nil {
+			_ = conn.Close()
+			return nil, fmt.Errorf("daemon not reachable at %s: %w", addr, ctx.Err())
+		}
+	}
 }
 
 // WithBackOff execute function in backoff cycle.

client/cmd/up.go

@@ -201,10 +201,10 @@ func runInForegroundMode(ctx context.Context, cmd *cobra.Command, activeProf *pr
 	r := peer.NewRecorder(config.ManagementURL.String())
 	r.GetFullStatus()
 
-	connectClient := internal.NewConnectClient(ctx, config, r)
+	connectClient := internal.NewConnectClient(ctx, r)
 	SetupDebugHandler(ctx, config, r, connectClient, "")
 
-	return connectClient.Run(nil, util.FindFirstLogPath(logFiles))
+	return connectClient.Run(config, nil, util.FindFirstLogPath(logFiles))
 }
 
 func runInDaemonMode(ctx context.Context, cmd *cobra.Command, pm *profilemanager.ProfileManager, activeProf *profilemanager.Profile, profileSwitched bool) error {

client/embed/embed.go

@@ -264,32 +264,24 @@ func (c *Client) Start(startCtx context.Context) error {
 	if err, _ := authClient.Login(ctx, c.setupKey, c.jwtToken); err != nil {
 		return fmt.Errorf("login: %w", err)
 	}
-	client := internal.NewConnectClient(ctx, c.config, c.recorder)
+	client := internal.NewConnectClient(ctx, c.recorder)
 	client.SetSyncResponsePersistence(true)
 
-	// either startup error (permanent backoff err) or nil err (successful engine up)
+	// The supervisor owns the run; we wait until it is established, ends with a
+	// startup error (permanent backoff err), or startCtx expires.
 	// TODO: make after-startup backoff err available
-	run := make(chan struct{})
-	clientErr := make(chan error, 1)
-	go func() {
-		if err := client.Run(run, ""); err != nil {
-			clientErr <- err
-		}
-	}()
+	client.RunAsync(c.config, nil)
 
-	select {
-	case <-startCtx.Done():
-		// Cancel the client context before stopping: Engine.Start blocks on the
-		// signal stream while holding the engine mutex and only unblocks on
-		// cancellation. Stopping first would deadlock on that mutex.
+	if err := client.WaitEstablishedOrDone(startCtx); err != nil {
+		// Either startCtx expired while connecting, or the run ended before it
+		// established. Cancel the client context before stopping: Engine.Start
+		// blocks on the signal stream while holding the engine mutex and only
+		// unblocks on cancellation. Stopping first would deadlock on that mutex.
 		cancel()
 		if stopErr := client.Stop(); stopErr != nil {
-			return fmt.Errorf("stop error after context done. Stop error: %w. Context done: %w", stopErr, startCtx.Err())
+			return fmt.Errorf("stop error after startup failure. Stop error: %w. Startup: %w", stopErr, err)
 		}
-		return startCtx.Err()
-	case err := <-clientErr:
 		return fmt.Errorf("startup: %w", err)
-	case <-run:
 	}
 
 	c.connect = client

client/internal/connect.go

@@ -18,6 +18,7 @@ import (
 
 	"golang.zx2c4.com/wireguard/wgctrl/wgtypes"
 	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/metadata"
 	gstatus "google.golang.org/grpc/status"
 
 	"github.com/netbirdio/netbird/client/iface/wgaddr"
@@ -48,13 +49,23 @@ import (
 	"github.com/netbirdio/netbird/version"
 )
 
-// androidRunOverride is set on Android to inject mobile dependencies
-// when using embed.Client (which calls Run() with empty MobileDependency).
-var androidRunOverride func(c *ConnectClient, runningChan chan struct{}, logPath string) error
+// androidMobileDep is set on Android to inject the MobileDependency for runs
+// started through the generic entry points (Run/RunAsync, e.g. embed.Client).
+// nil on other platforms, where the dependency is empty.
+var androidMobileDep func(config *profilemanager.Config) MobileDependency
+
+// mobileDependency returns the MobileDependency for a run started via the
+// generic entry points. On Android the androidMobileDep provider supplies
+// platform stubs (or real implementations); elsewhere it is empty.
+func (c *ConnectClient) mobileDependency(config *profilemanager.Config) MobileDependency {
+	if androidMobileDep != nil {
+		return androidMobileDep(config)
+	}
+	return MobileDependency{}
+}
 
 type ConnectClient struct {
 	ctx            context.Context
-	config         *profilemanager.Config
 	statusRecorder *peer.Status
 
 	engine        *Engine
@@ -63,35 +74,62 @@ type ConnectClient struct {
 	updateManager *updater.Manager
 
 	persistSyncResponse bool
+
+	// sup serializes all start/stop requests so two lifecycle operations can
+	// never overlap. See connect_lifecycle.go.
+	sup *supervisor
 }
 
 func NewConnectClient(
 	ctx context.Context,
-	config *profilemanager.Config,
 	statusRecorder *peer.Status,
 ) *ConnectClient {
-	return &ConnectClient{
+	c := &ConnectClient{
 		ctx:            ctx,
-		config:         config,
 		statusRecorder: statusRecorder,
 		engineMutex:    sync.Mutex{},
 	}
+	c.sup = newSupervisor(ctx, c.run)
+	return c
 }
 
 func (c *ConnectClient) SetUpdateManager(um *updater.Manager) {
 	c.updateManager = um
 }
 
-// Run with main logic.
-func (c *ConnectClient) Run(runningChan chan struct{}, logPath string) error {
-	if androidRunOverride != nil {
-		return androidRunOverride(c, runningChan, logPath)
-	}
-	return c.run(MobileDependency{}, runningChan, logPath)
+// Run with main logic. md carries optional gRPC metadata (e.g. the UI
+// user-agent) to forward to the management/signal services; nil when none.
+func (c *ConnectClient) Run(config *profilemanager.Config, md metadata.MD, logPath string) error {
+	return c.sup.start(config, md, c.mobileDependency(config), logPath)
+}
+
+// RunAsync starts a client run without blocking. Used by the daemon and embed,
+// which drive the lifecycle through the supervisor rather than blocking on Run;
+// they then wait for the outcome via WaitEstablishedOrDone. The run's lifecycle
+// channels are created and owned by the supervisor — callers never hold them.
+func (c *ConnectClient) RunAsync(config *profilemanager.Config, md metadata.MD) {
+	c.sup.startAsync(config, md, c.mobileDependency(config), "", nil)
+}
+
+// Restart atomically stops any in-flight run and starts a fresh one with the
+// given config. The stop+start happens as a single supervisor operation, so no
+// other lifecycle request can interleave between them — used for explicit
+// restarts (e.g. an MDM policy change) that must not expose a "stopped" window.
+func (c *ConnectClient) Restart(config *profilemanager.Config, md metadata.MD) {
+	c.sup.restartAsync(config, md, c.mobileDependency(config), "")
+}
+
+// WaitEstablishedOrDone blocks until the in-flight run becomes established (nil),
+// ends before that (the run error, or a sentinel on a clean stop), or ctx is
+// cancelled. Returns errNoRunInFlight if no run is in flight. Wraps the wait on
+// the supervisor-owned channels so callers never touch them directly.
+func (c *ConnectClient) WaitEstablishedOrDone(ctx context.Context) error {
+	return c.sup.waitEstablishedOrDone(ctx)
 }
 
 // RunOnAndroid with main logic on mobile system
 func (c *ConnectClient) RunOnAndroid(
+	config *profilemanager.Config,
 	tunAdapter device.TunAdapter,
 	iFaceDiscover stdnet.ExternalIFaceDiscover,
 	networkChangeListener listener.NetworkChangeListener,
@@ -110,10 +148,11 @@ func (c *ConnectClient) RunOnAndroid(
 		StateFilePath:         stateFilePath,
 		TempDir:               cacheDir,
 	}
-	return c.run(mobileDependency, nil, "")
+	return c.sup.start(config, nil, mobileDependency, "")
 }
 
 func (c *ConnectClient) RunOniOS(
+	config *profilemanager.Config,
 	fileDescriptor int32,
 	networkChangeListener listener.NetworkChangeListener,
 	dnsManager dns.IosDnsManager,
@@ -131,10 +170,12 @@ func (c *ConnectClient) RunOniOS(
 		StateFilePath:         stateFilePath,
 		TempDir:               cacheDir,
 	}
-	return c.run(mobileDependency, nil, logFilePath)
+	return c.sup.start(config, nil, mobileDependency, logFilePath)
 }
 
-func (c *ConnectClient) run(mobileDependency MobileDependency, runningChan chan struct{}, logPath string) error {
+// run executes a single client run. runCtx is owned by the supervisor: cancelling
+// it tears the run down (it is the parent of the per-attempt engine context).
+func (c *ConnectClient) run(runCtx context.Context, config *profilemanager.Config, mobileDependency MobileDependency, connEstablishedChan chan struct{}, logPath string) error {
 	defer func() {
 		if r := recover(); r != nil {
 			rec := c.statusRecorder
@@ -198,18 +239,18 @@ func (c *ConnectClient) run(mobileDependency MobileDependency, runningChan chan
 	}()
 
 	wrapErr := state.Wrap
-	myPrivateKey, err := wgtypes.ParseKey(c.config.PrivateKey)
+	myPrivateKey, err := wgtypes.ParseKey(config.PrivateKey)
 	if err != nil {
-		log.Errorf("failed parsing Wireguard key %s: [%s]", c.config.PrivateKey, err.Error())
+		log.Errorf("failed parsing Wireguard key %s: [%s]", config.PrivateKey, err.Error())
 		return wrapErr(err)
 	}
 
 	var mgmTlsEnabled bool
-	if c.config.ManagementURL.Scheme == "https" {
+	if config.ManagementURL.Scheme == "https" {
 		mgmTlsEnabled = true
 	}
 
-	publicSSHKey, err := ssh.GeneratePublicKey([]byte(c.config.SSHKey))
+	publicSSHKey, err := ssh.GeneratePublicKey([]byte(config.SSHKey))
 	if err != nil {
 		return err
 	}
@@ -243,13 +284,13 @@ func (c *ConnectClient) run(mobileDependency MobileDependency, runningChan chan
 	defer c.statusRecorder.ClientStop()
 	operation := func() error {
 		// if context cancelled we not start new backoff cycle
-		if c.ctx.Err() != nil {
+		if runCtx.Err() != nil {
 			return nil
 		}
 
 		state.Set(StatusConnecting)
 
-		engineCtx, cancel := context.WithCancel(c.ctx)
+		engineCtx, cancel := context.WithCancel(runCtx)
 		defer func() {
 			_, err := state.Status()
 			c.statusRecorder.MarkManagementDisconnected(err)
@@ -257,8 +298,8 @@ func (c *ConnectClient) run(mobileDependency MobileDependency, runningChan chan
 			cancel()
 		}()
 
-		log.Debugf("connecting to the Management service %s", c.config.ManagementURL.Host)
-		mgmClient, err := mgm.NewClient(engineCtx, c.config.ManagementURL.Host, myPrivateKey, mgmTlsEnabled)
+		log.Debugf("connecting to the Management service %s", config.ManagementURL.Host)
+		mgmClient, err := mgm.NewClient(engineCtx, config.ManagementURL.Host, myPrivateKey, mgmTlsEnabled)
 		if err != nil {
 			return wrapErr(gstatus.Errorf(codes.FailedPrecondition, "failed connecting to Management Service : %s", err))
 		}
@@ -275,7 +316,7 @@ func (c *ConnectClient) run(mobileDependency MobileDependency, runningChan chan
 		}
 		c.clientMetrics.UpdateAgentInfo(agentInfo, myPrivateKey.PublicKey().String())
 
-		log.Debugf("connected to the Management service %s", c.config.ManagementURL.Host)
+		log.Debugf("connected to the Management service %s", config.ManagementURL.Host)
 		defer func() {
 			if err = mgmClient.Close(); err != nil {
 				log.Warnf("failed to close the Management service client %v", err)
@@ -284,13 +325,14 @@ func (c *ConnectClient) run(mobileDependency MobileDependency, runningChan chan
 
 		// connect (just a connection, no stream yet) and login to Management Service to get an initial global Netbird config
 		loginStarted := time.Now()
-		loginResp, err := loginToManagement(engineCtx, mgmClient, publicSSHKey, c.config)
+		loginResp, err := loginToManagement(engineCtx, mgmClient, publicSSHKey, config)
 		if err != nil {
 			c.clientMetrics.RecordLoginDuration(engineCtx, time.Since(loginStarted), false)
 			log.Debug(err)
 			if s, ok := gstatus.FromError(err); ok && (s.Code() == codes.PermissionDenied) {
 				state.Set(StatusNeedsLogin)
-				_ = c.Stop()
+				// No teardown needed: login fails before the engine is started
+				// (engine.Start is below), so there is nothing running to stop.
 				return backoff.Permanent(wrapErr(err)) // unrecoverable error
 			}
 			return wrapErr(err)
@@ -344,7 +386,7 @@ func (c *ConnectClient) run(mobileDependency MobileDependency, runningChan chan
 		}
 		peerConfig := loginResp.GetPeerConfig()
 
-		engineConfig, err := createEngineConfig(myPrivateKey, c.config, peerConfig, logPath)
+		engineConfig, err := createEngineConfig(myPrivateKey, config, peerConfig, logPath)
 		if err != nil {
 			log.Error(err)
 			return wrapErr(err)
@@ -388,7 +430,7 @@ func (c *ConnectClient) run(mobileDependency MobileDependency, runningChan chan
 		c.engine = engine
 		c.engineMutex.Unlock()
 
-		if err := engine.Start(loginResp.GetNetbirdConfig(), c.config.ManagementURL); err != nil {
+		if err := engine.Start(loginResp.GetNetbirdConfig(), config.ManagementURL); err != nil {
 			log.Errorf("error while starting Netbird Connection Engine: %s", err)
 			return wrapErr(err)
 		}
@@ -396,12 +438,13 @@ func (c *ConnectClient) run(mobileDependency MobileDependency, runningChan chan
 		log.Infof("Netbird engine started, the IP is: %s", peerConfig.GetAddress())
 		state.Set(StatusConnected)
 
-		if runningChan != nil {
-			select {
-			case <-runningChan:
-			default:
-				close(runningChan)
-			}
+		// The supervisor owns connEstablishedChan and it is always present. Guard
+		// against a double close: operation re-runs on ErrResetConnection retries
+		// within the same run, and the channel is closed only on the first connect.
+		select {
+		case <-connEstablishedChan:
+		default:
+			close(connEstablishedChan)
 		}
 
 		<-engineCtx.Done()
@@ -410,14 +453,12 @@ func (c *ConnectClient) run(mobileDependency MobileDependency, runningChan chan
 		c.engine = nil
 		c.engineMutex.Unlock()
 
-		// todo: consider to remove this condition. Is not thread safe.
-		// We should always call Stop(), but we need to verify that it is idempotent
-		if engine.wgInterface != nil {
-			log.Infof("ensuring %s is removed, Netbird engine context cancelled", engine.wgInterface.Name())
-
-			if err := engine.Stop(); err != nil {
-				log.Errorf("Failed to stop engine: %v", err)
-			}
+		// Always tear the engine down once its context is cancelled. engine.Stop
+		// is nil-guarded per component, so calling it unconditionally is safe and
+		// avoids both the data race on engine.wgInterface and skipping teardown
+		// when the interface was never brought up (e.g. a mid-start failure).
+		if err := engine.Stop(); err != nil {
+			log.Errorf("Failed to stop engine: %v", err)
 		}
 		c.statusRecorder.ClientTeardown()
 
@@ -437,8 +478,9 @@ func (c *ConnectClient) run(mobileDependency MobileDependency, runningChan chan
 	if err != nil {
 		log.Debugf("exiting client retry loop due to unrecoverable error: %s", err)
 		if s, ok := gstatus.FromError(err); ok && (s.Code() == codes.PermissionDenied) {
+			// Login failed permanently: the engine was never started, so there
+			// is nothing to tear down — just record that a login is needed.
 			state.Set(StatusNeedsLogin)
-			_ = c.Stop()
 		}
 		return err
 	}
@@ -459,6 +501,22 @@ func parseRelayInfo(loginResp *mgmProto.LoginResponse) ([]string, *hmac.Token) {
 	return relayCfg.GetUrls(), token
 }
 
+// ConnectionRunning reports whether a connection run is currently in flight
+// (connecting, connected, or reconnecting). Answered by the supervisor via a
+// serialized query, so it settles behind an in-flight stop. Distinct from
+// ServiceRunning, which reports whether the service itself is alive.
+func (c *ConnectClient) ConnectionRunning() bool {
+	return c.sup.isRunning()
+}
+
+// ServiceRunning reports whether the client's lifecycle supervisor is alive and
+// able to accept start/stop commands — i.e. its context has not been cancelled
+// (the daemon is not shutting down). Independent of whether a connection run is
+// up (that is ConnectionRunning).
+func (c *ConnectClient) ServiceRunning() bool {
+	return c.sup.ctx.Err() == nil
+}
+
 func (c *ConnectClient) Engine() *Engine {
 	if c == nil {
 		return nil
@@ -515,14 +573,10 @@ func (c *ConnectClient) Status() StatusType {
 	return status
 }
 
+// Stop serializes a stop request through the lifecycle supervisor and blocks
+// until the in-flight run is fully torn down.
 func (c *ConnectClient) Stop() error {
-	engine := c.Engine()
-	if engine != nil {
-		if err := engine.Stop(); err != nil {
-			return fmt.Errorf("stop engine: %w", err)
-		}
-	}
-	return nil
+	return c.sup.stop()
 }
 
 // SetSyncResponsePersistence enables or disables sync response persistence.

client/internal/connect_android_default.go

@@ -7,6 +7,7 @@ import (
 
 	"github.com/netbirdio/netbird/client/internal/dns"
 	"github.com/netbirdio/netbird/client/internal/listener"
+	"github.com/netbirdio/netbird/client/internal/profilemanager"
 	"github.com/netbirdio/netbird/client/internal/stdnet"
 )
 
@@ -59,19 +60,17 @@ var _ listener.NetworkChangeListener = noopNetworkChangeListener{}
 var _ dns.ReadyListener = noopDnsReadyListener{}
 
 func init() {
-	// Wire up the default override so embed.Client.Start() works on Android
-	// with netstack mode. Provides complete no-op stubs for all mobile
+	// Wire up the default MobileDependency provider so embed.Client.Start() works
+	// on Android with netstack mode. Provides complete no-op stubs for all mobile
 	// dependencies so the engine's existing Android code paths work unchanged.
-	// Applications that need P2P ICE or real DNS should replace this by
-	// setting androidRunOverride before calling Start().
-	androidRunOverride = func(c *ConnectClient, runningChan chan struct{}, logPath string) error {
-		return c.runOnAndroidEmbed(
+	// Applications that need P2P ICE or real DNS should replace this by setting
+	// androidMobileDep before calling Start().
+	androidMobileDep = func(config *profilemanager.Config) MobileDependency {
+		return mobileDependencyForEmbed(
 			noopIFaceDiscover{},
 			noopNetworkChangeListener{},
 			[]netip.AddrPort{},
 			noopDnsReadyListener{},
-			runningChan,
-			logPath,
 		)
 	}
 }

client/internal/connect_android_embed.go

@@ -10,23 +10,18 @@ import (
 	"github.com/netbirdio/netbird/client/internal/stdnet"
 )
 
-// runOnAndroidEmbed is like RunOnAndroid but accepts a runningChan
-// so embed.Client.Start() can detect when the engine is ready.
-// It provides complete MobileDependency so the engine's existing
-// Android code paths work unchanged.
-func (c *ConnectClient) runOnAndroidEmbed(
+// mobileDependencyForEmbed builds the MobileDependency used by embed.Client on
+// Android so the engine's existing Android code paths work unchanged.
+func mobileDependencyForEmbed(
 	iFaceDiscover stdnet.ExternalIFaceDiscover,
 	networkChangeListener listener.NetworkChangeListener,
 	dnsAddresses []netip.AddrPort,
 	dnsReadyListener dns.ReadyListener,
-	runningChan chan struct{},
-	logPath string,
-) error {
-	mobileDependency := MobileDependency{
+) MobileDependency {
+	return MobileDependency{
 		IFaceDiscover:         iFaceDiscover,
 		NetworkChangeListener: networkChangeListener,
 		HostDNSAddresses:      dnsAddresses,
 		DnsReadyListener:      dnsReadyListener,
 	}
-	return c.run(mobileDependency, runningChan, logPath)
 }

client/internal/connect_lifecycle.go

@@ -0,0 +1,362 @@
+package internal
+
+import (
+	"context"
+	"errors"
+
+	"google.golang.org/grpc/metadata"
+
+	"github.com/netbirdio/netbird/client/internal/profilemanager"
+)
+
+// errAlreadyRunning is returned when a start is requested while a run is already
+// in flight.
+var errAlreadyRunning = errors.New("client is already running")
+
+// errNoRunInFlight is returned by waitEstablishedOrDone when no run is active.
+var errNoRunInFlight = errors.New("no connection run in flight")
+
+// errStoppedBeforeEstablished is returned when a run ended (cleanly) before the
+// connection was established.
+var errStoppedBeforeEstablished = errors.New("run stopped before the connection was established")
+
+// lifecycleOp is a serialized lifecycle operation processed by the supervisor.
+type lifecycleOp int
+
+const (
+	opStart lifecycleOp = iota
+	opStop
+	opRestart
+	opStatus
+	opWaitEstablished
+)
+
+// lifecycleCmd is a single lifecycle request handed to the supervisor goroutine.
+// They all flow through the same cmdCh so they are strictly ordered (FIFO) with
+// respect to each other.
+type lifecycleCmd struct {
+	op        lifecycleOp
+	config    *profilemanager.Config
+	md        metadata.MD
+	mobileDep MobileDependency
+	logPath   string
+
+	// done is the caller's notification channel (nil for fire-and-forget). Its
+	// meaning depends on op:
+	//   - opStart: receives the run's end result when the run terminates, or
+	//     errAlreadyRunning immediately if a run is already in flight.
+	//   - opStop: receives nil once the in-flight run has fully unwound.
+	//   - opWaitEstablished: receives the wait outcome (see waitEstablishedOrDone).
+	done chan error
+
+	reply   chan bool       // opStatus only: receives whether a run is in flight
+	waitCtx context.Context // opWaitEstablished only: the waiter's cancellation context
+}
+
+// runState holds the lifecycle channels of a single in-flight run, owned by the
+// loop goroutine. It never escapes the supervisor as an API; the only readers
+// are the per-wait goroutines the loop spawns for opWaitEstablished.
+//
+// connEstablishedChan is closed by the run once the connection is established.
+// The supervisor creates and owns it — callers no longer supply it; they observe
+// it through waitEstablishedOrDone. ended is closed (broadcast) when the run
+// terminates, so any number of waiters can observe it; err is the run's end
+// result, valid only after ended is closed.
+type runState struct {
+	connEstablishedChan chan struct{} // closed by the run on established
+	ended               chan struct{} // closed by finishRun when the run terminates
+	err                 error         // run end result, valid after ended is closed
+}
+
+// runEndResult is sent by the run goroutine to the supervisor when a run ends,
+// whether on its own (error / external context cancellation) or because of a Stop.
+type runEndResult struct {
+	err error
+}
+
+// runFunc executes a single client run bound to the supervisor-owned context,
+// with the config supplied by the start request.
+type runFunc func(ctx context.Context, config *profilemanager.Config, mobileDep MobileDependency, connEstablishedChan chan struct{}, logPath string) error
+
+// supervisor serializes start/stop of a single client run. Every request goes
+// through cmdCh and is handled one at a time by the loop goroutine, so two
+// lifecycle operations can never overlap and their order is preserved (FIFO).
+// The loop goroutine is the sole owner of curStart/runCancel, so that state
+// needs no locking. The loop exits when the parent context is cancelled.
+type supervisor struct {
+	ctx      context.Context
+	run      runFunc
+	cmdCh    chan lifecycleCmd
+	runEnded chan runEndResult
+
+	// owned exclusively by the loop goroutine. curStart is the in-flight start
+	// command (nil = idle); its done channel is notified when the run ends.
+	// curRun holds that run's lifecycle channels; runCancel cancels it.
+	curStart  *lifecycleCmd
+	curRun    *runState
+	runCancel context.CancelFunc
+}
+
+func newSupervisor(ctx context.Context, run runFunc) *supervisor {
+	s := &supervisor{
+		ctx:      ctx,
+		run:      run,
+		cmdCh:    make(chan lifecycleCmd, 16),
+		runEnded: make(chan runEndResult, 1),
+	}
+	go s.loop()
+	return s
+}
+
+func (s *supervisor) loop() {
+	for {
+		select {
+		case <-s.ctx.Done():
+			s.shutdown()
+			return
+		case cmd := <-s.cmdCh:
+			switch cmd.op {
+			case opStart:
+				s.handleStart(cmd)
+			case opStop:
+				s.handleStop(cmd)
+			case opRestart:
+				s.handleRestart(cmd)
+			case opStatus:
+				cmd.reply <- (s.isRunningInternal())
+			case opWaitEstablished:
+				s.handleWaitEstablished(cmd)
+			}
+		case res := <-s.runEnded:
+			// Run ended on its own, without an explicit Stop.
+			s.finishRun(res.err)
+		}
+	}
+}
+
+func (s *supervisor) handleStart(cmd lifecycleCmd) {
+	if s.isRunningInternal() {
+		notify(cmd.done, errAlreadyRunning)
+		return
+	}
+
+	runCtx, cancel := context.WithCancel(s.ctx)
+	if cmd.md != nil {
+		// Carry caller-supplied gRPC metadata (e.g. UI user-agent) into the run
+		// context so the engine's management/signal calls forward it. The cancel
+		// still drives runCtx (metadata wrapping preserves cancellation).
+		runCtx = metadata.NewOutgoingContext(runCtx, cmd.md)
+	}
+	s.runCancel = cancel
+	s.curStart = &cmd
+	s.curRun = &runState{connEstablishedChan: make(chan struct{}), ended: make(chan struct{})}
+
+	go func(ctx context.Context, cfg *profilemanager.Config, m MobileDependency, established chan struct{}, lp string) {
+		err := s.run(ctx, cfg, m, established, lp)
+		s.runEnded <- runEndResult{err: err}
+	}(runCtx, cmd.config, cmd.mobileDep, s.curRun.connEstablishedChan, cmd.logPath)
+}
+
+func (s *supervisor) handleStop(cmd lifecycleCmd) {
+	if !s.isRunningInternal() {
+		notify(cmd.done, nil)
+		return
+	}
+	s.stopCurrentRun()
+	notify(cmd.done, nil)
+}
+
+// handleRestart tears down any in-flight run and starts a fresh one in a single
+// loop turn. No other command can interleave between the stop and the start
+// (the loop is single-threaded), so the swap is atomic without relying on any
+// daemon-side lock — that is what an explicit restart (e.g. MDM config change)
+// needs to avoid a window where the client is observably stopped.
+func (s *supervisor) handleRestart(cmd lifecycleCmd) {
+	if s.isRunningInternal() {
+		s.stopCurrentRun()
+	}
+	s.handleStart(cmd)
+}
+
+// stopCurrentRun cancels the in-flight run and blocks the supervisor until it
+// has fully unwound, so the next action starts from a clean slate. The run
+// goroutine reports completion via runEnded. Caller must hold an in-flight run
+// (curStart != nil).
+func (s *supervisor) stopCurrentRun() {
+	s.runCancel()
+	res := <-s.runEnded
+	s.finishRun(res.err)
+}
+
+// finishRun resets lifecycle state after a run terminates and hands the run
+// error back to whoever asked to be notified of the start.
+func (s *supervisor) finishRun(err error) {
+	s.runCancel = nil
+	if s.isRunningInternal() {
+		// Publish the result to the broadcast channel before nil-ing curRun, so
+		// any opWaitEstablished goroutines blocked on ended observe err.
+		s.curRun.err = err
+		close(s.curRun.ended)
+		s.curRun = nil
+
+		notify(s.curStart.done, err)
+		s.curStart = nil
+	}
+}
+
+// handleWaitEstablished answers an opWaitEstablished request. The select itself
+// runs in a spawned goroutine on the run's channels so it never blocks the loop;
+// the loop only snapshots the in-flight run's channels (which it owns) here.
+func (s *supervisor) handleWaitEstablished(cmd lifecycleCmd) {
+	caller := cmd.done
+	if !s.isRunningInternal() {
+		notify(caller, errNoRunInFlight)
+		return
+	}
+	rs := s.curRun
+	established := rs.connEstablishedChan
+	ctx := cmd.waitCtx
+	go func() {
+		select {
+		case <-established:
+			notify(caller, nil)
+		case <-rs.ended:
+			if rs.err != nil {
+				notify(caller, rs.err)
+				return
+			}
+			notify(caller, errStoppedBeforeEstablished)
+		case <-ctx.Done():
+			notify(caller, ctx.Err())
+		}
+	}()
+}
+
+// shutdown tears down the in-flight run when the parent context is cancelled,
+// then fails any still-queued commands so their callers never hang.
+func (s *supervisor) shutdown() {
+	if s.runCancel != nil {
+		s.runCancel()
+		res := <-s.runEnded
+		s.finishRun(res.err)
+	}
+	for {
+		select {
+		case cmd := <-s.cmdCh:
+			notify(cmd.done, s.ctx.Err())
+		default:
+			return
+		}
+	}
+}
+
+// startAsync enqueues a start without blocking. If done is non-nil it receives
+// the run's end result (or errAlreadyRunning on rejection, or the context error
+// on shutdown).
+func (s *supervisor) startAsync(config *profilemanager.Config, md metadata.MD, mobileDep MobileDependency, logPath string, done chan error) {
+	cmd := lifecycleCmd{op: opStart, config: config, md: md, mobileDep: mobileDep, logPath: logPath, done: done}
+	select {
+	case s.cmdCh <- cmd:
+	case <-s.ctx.Done():
+		notify(done, s.ctx.Err())
+	}
+}
+
+// restartAsync enqueues an atomic stop+start without blocking. The supervisor
+// tears down any in-flight run and starts a fresh one with the supplied config
+// in a single loop turn (see handleRestart). Fire-and-forget: the new run owns
+// its lifecycle channels, observed via waitEstablishedOrDone.
+func (s *supervisor) restartAsync(config *profilemanager.Config, md metadata.MD, mobileDep MobileDependency, logPath string) {
+	cmd := lifecycleCmd{op: opRestart, config: config, md: md, mobileDep: mobileDep, logPath: logPath}
+	select {
+	case s.cmdCh <- cmd:
+	case <-s.ctx.Done():
+	}
+}
+
+// start enqueues a start and blocks until the run terminates, preserving the
+// blocking contract of the legacy Run entry points.
+func (s *supervisor) start(config *profilemanager.Config, md metadata.MD, mobileDep MobileDependency, logPath string) error {
+	done := make(chan error, 1)
+	s.startAsync(config, md, mobileDep, logPath, done)
+	select {
+	case err := <-done:
+		return err
+	case <-s.ctx.Done():
+		return s.ctx.Err()
+	}
+}
+
+// isRunning asks the loop whether a run is in flight. The query is serialized
+// with start/stop, so during a stop it waits for the teardown to settle and
+// then reports the final state — never a transient "half-stopped".
+func (s *supervisor) isRunning() bool {
+	reply := make(chan bool, 1)
+	select {
+	case s.cmdCh <- lifecycleCmd{op: opStatus, reply: reply}:
+	case <-s.ctx.Done():
+		return false
+	}
+	select {
+	case r := <-reply:
+		return r
+	case <-s.ctx.Done():
+		return false
+	}
+}
+
+func (s *supervisor) isRunningInternal() bool {
+	return s.curStart != nil
+}
+
+// waitEstablishedOrDone blocks until the in-flight run becomes established
+// (returns nil) or ends before that (returns the run error, or
+// errStoppedBeforeEstablished on a clean stop), or ctx is cancelled. Returns
+// errNoRunInFlight if no run is in flight. The wait is performed by a goroutine
+// spawned inside the loop (see handleWaitEstablished); the run's channels never
+// leave the supervisor.
+func (s *supervisor) waitEstablishedOrDone(ctx context.Context) error {
+	reply := make(chan error, 1)
+	select {
+	case s.cmdCh <- lifecycleCmd{op: opWaitEstablished, waitCtx: ctx, done: reply}:
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-s.ctx.Done():
+		return s.ctx.Err()
+	}
+	select {
+	case err := <-reply:
+		return err
+	case <-s.ctx.Done():
+		return s.ctx.Err()
+	}
+}
+
+// stop enqueues a stop and blocks until the in-flight run is fully torn down.
+func (s *supervisor) stop() error {
+	done := make(chan error, 1)
+	select {
+	case s.cmdCh <- lifecycleCmd{op: opStop, done: done}:
+	case <-s.ctx.Done():
+		return s.ctx.Err()
+	}
+	select {
+	case err := <-done:
+		return err
+	case <-s.ctx.Done():
+		return s.ctx.Err()
+	}
+}
+
+// notify sends on a caller-supplied channel without blocking. The channel is
+// expected to be buffered (cap 1); a nil channel means the caller did not ask
+// to be notified.
+func notify(ch chan error, err error) {
+	if ch == nil {
+		return
+	}
+	select {
+	case ch <- err:
+	default:
+	}
+}

client/internal/engine.go

@@ -22,6 +22,8 @@ import (
 	log "github.com/sirupsen/logrus"
 	"golang.zx2c4.com/wireguard/tun/netstack"
 	"golang.zx2c4.com/wireguard/wgctrl/wgtypes"
+	"google.golang.org/grpc/codes"
+	gstatus "google.golang.org/grpc/status"
 
 	nberrors "github.com/netbirdio/netbird/client/errors"
 	"github.com/netbirdio/netbird/client/firewall"
@@ -1125,6 +1127,20 @@ func (e *Engine) hasIPv6Changed(conf *mgmProto.PeerConfig) bool {
 	return !current.HasIPv6() || current.IPv6 != prefix.Addr() || current.IPv6Net != prefix.Masked()
 }
 
+// wrapDisconnectError classifies a receive-loop failure before the run is torn
+// down. An auth rejection (PermissionDenied/Unauthenticated) means the session
+// needs re-login and retrying is futile, so mark it terminal (NeedsLogin) — run()
+// then exits on its own instead of spinning the backoff. Any other failure is a
+// recoverable connection reset that the backoff should retry.
+func (e *Engine) wrapDisconnectError(err error) {
+	state := CtxGetState(e.ctx)
+	if s, ok := gstatus.FromError(err); ok && (s.Code() == codes.PermissionDenied || s.Code() == codes.Unauthenticated) {
+		state.Set(StatusNeedsLogin)
+		return
+	}
+	_ = state.Wrap(ErrResetConnection)
+}
+
 func (e *Engine) receiveJobEvents() {
 	e.jobExecutorWG.Add(1)
 	go func() {
@@ -1151,9 +1167,9 @@ func (e *Engine) receiveJobEvents() {
 			}
 		})
 		if err != nil {
-			// happens if management is unavailable for a long time.
-			// We want to cancel the operation of the whole client
-			_ = CtxGetState(e.ctx).Wrap(ErrResetConnection)
+			// happens if management is unavailable for a long time, or rejects
+			// us (auth). wrapDisconnectError decides retry vs needs-login.
+			e.wrapDisconnectError(err)
 			e.clientCancel()
 			return
 		}
@@ -1235,9 +1251,9 @@ func (e *Engine) receiveManagementEvents() {
 
 		err = e.mgmClient.Sync(e.ctx, info, e.handleSync)
 		if err != nil {
-			// happens if management is unavailable for a long time.
-			// We want to cancel the operation of the whole client
-			_ = CtxGetState(e.ctx).Wrap(ErrResetConnection)
+			// happens if management is unavailable for a long time, or rejects
+			// us (auth). wrapDisconnectError decides retry vs needs-login.
+			e.wrapDisconnectError(err)
 			e.clientCancel()
 			return
 		}
@@ -1761,9 +1777,9 @@ func (e *Engine) receiveSignalEvents() {
 			return nil
 		})
 		if err != nil {
-			// happens if signal is unavailable for a long time.
-			// We want to cancel the operation of the whole client
-			_ = CtxGetState(e.ctx).Wrap(ErrResetConnection)
+			// happens if signal is unavailable for a long time, or rejects us
+			// (auth). wrapDisconnectError decides retry vs needs-login.
+			e.wrapDisconnectError(err)
 			e.clientCancel()
 			return
 		}

client/ios/NetBirdSDK/client.go

@@ -171,13 +171,13 @@ func (c *Client) Run(fd int32, interfaceName string, envList *EnvList) error {
 	c.onHostDnsFn = func([]string) {}
 	cfg.WgIface = interfaceName
 
-	connectClient := internal.NewConnectClient(ctx, cfg, c.recorder)
+	connectClient := internal.NewConnectClient(ctx, c.recorder)
 	c.setState(cfg, connectClient)
 	// Persist the latest sync response so DebugBundle can include the network
 	// map. On iOS this is backed by disk to keep it out of the constrained
 	// process memory (see the syncstore package).
 	connectClient.SetSyncResponsePersistence(true)
-	return connectClient.RunOniOS(fd, c.networkChangeListener, c.dnsManager, c.stateFile, c.cacheDir, c.logFilePath)
+	return connectClient.RunOniOS(cfg, fd, c.networkChangeListener, c.dnsManager, c.stateFile, c.cacheDir, c.logFilePath)
 }
 
 // Stop the internal client and free the resources

client/server/capture.go

@@ -344,9 +344,6 @@ func (s *Server) clearCaptureIfOwner(sess *capture.Session, engine *internal.Eng
 }
 
 func (s *Server) getCaptureEngineLocked() (*internal.Engine, error) {
-	if s.connectClient == nil {
-		return nil, status.Error(codes.FailedPrecondition, "client not connected")
-	}
 	engine := s.connectClient.Engine()
 	if engine == nil {
 		return nil, status.Error(codes.FailedPrecondition, "engine not initialized")

client/server/debug.go

@@ -5,7 +5,6 @@ package server
 import (
 	"bytes"
 	"context"
-	"errors"
 	"fmt"
 	"runtime/pprof"
 
@@ -28,11 +27,9 @@ func (s *Server) DebugBundle(_ context.Context, req *proto.DebugBundleRequest) (
 	}
 
 	var clientMetrics debug.MetricsExporter
-	if s.connectClient != nil {
-		if engine := s.connectClient.Engine(); engine != nil {
-			if cm := engine.GetClientMetrics(); cm != nil {
-				clientMetrics = cm
-			}
+	if engine := s.connectClient.Engine(); engine != nil {
+		if cm := engine.GetClientMetrics(); cm != nil {
+			clientMetrics = cm
 		}
 	}
 
@@ -48,13 +45,10 @@ func (s *Server) DebugBundle(_ context.Context, req *proto.DebugBundleRequest) (
 	defer s.cleanupBundleCapture()
 
 	var refreshStatus func()
-	if s.connectClient != nil {
-		engine := s.connectClient.Engine()
-		if engine != nil {
-			refreshStatus = func() {
-				log.Debug("refreshing system health status for debug bundle")
-				engine.RunHealthProbes(true)
-			}
+	if engine := s.connectClient.Engine(); engine != nil {
+		refreshStatus = func() {
+			log.Debug("refreshing system health status for debug bundle")
+			engine.RunHealthProbes(true)
 		}
 	}
 
@@ -118,9 +112,7 @@ func (s *Server) SetLogLevel(_ context.Context, req *proto.SetLogLevelRequest) (
 
 	log.SetLevel(level)
 
-	if s.connectClient != nil {
-		s.connectClient.SetLogLevel(level)
-	}
+	s.connectClient.SetLogLevel(level)
 
 	log.Infof("Log level set to %s", level.String())
 
@@ -134,20 +126,13 @@ func (s *Server) SetSyncResponsePersistence(_ context.Context, req *proto.SetSyn
 
 	enabled := req.GetEnabled()
 	s.persistSyncResponse = enabled
-	if s.connectClient != nil {
-		s.connectClient.SetSyncResponsePersistence(enabled)
-	}
+	s.connectClient.SetSyncResponsePersistence(enabled)
 
 	return &proto.SetSyncResponsePersistenceResponse{}, nil
 }
 
 func (s *Server) getLatestSyncResponse() (*mgmProto.SyncResponse, error) {
-	cClient := s.connectClient
-	if cClient == nil {
-		return nil, errors.New("connect client is not initialized")
-	}
-
-	return cClient.GetLatestSyncResponse()
+	return s.connectClient.GetLatestSyncResponse()
 }
 
 // StartCPUProfile starts CPU profiling in the daemon.

client/server/mdm.go

@@ -3,7 +3,6 @@ package server
 import (
 	"context"
 	"fmt"
-	"time"
 
 	log "github.com/sirupsen/logrus"
 	"google.golang.org/grpc/codes"
@@ -39,12 +38,11 @@ type conflictCheck struct {
 // OS-native managed-config store reports a diff vs the last observation.
 //
 // Restart sequence:
-//  1. Cancel the active engine context (terminates connectWithRetryRuns).
-//  2. Wait briefly for that goroutine to exit (giveUpChan is closed on exit).
-//  3. Re-resolve Config from disk + MDM policy (Config.apply re-runs
+//  1. Stop the in-flight run via the supervisor (blocks until fully torn down).
+//  2. Re-resolve Config from disk + MDM policy (Config.apply re-runs
 //     applyMDMPolicy with the freshly loaded Policy).
-//  4. Spawn a fresh connectWithRetryRuns with the new context and config.
-//  5. Broadcast a SystemEvent so any GUI / CLI subscriber (SubscribeEvents
+//  3. Start a fresh run with the new config.
+//  4. Broadcast a SystemEvent so any GUI / CLI subscriber (SubscribeEvents
 //     RPC) can refresh its cached config view without polling.
 //
 // The callback runs in the ticker's own goroutine. Ticker has already
@@ -52,39 +50,24 @@ type conflictCheck struct {
 func (s *Server) onMDMPolicyChange(_, _ *mdm.Policy) error {
 	log.Warn("MDM policy changed; restarting engine to apply new configuration")
 
-	// Hold s.mutex for the entire restart sequence (cancel + quiescence
-	// wait + re-spawn). Any concurrent Up/Down/Status arriving while
-	// MDM is restarting blocks on the Lock until we are done — they
-	// then observe the post-restart state coherently. This is safe
-	// because the connectWithRetryRuns goroutine no longer acquires
-	// s.mutex in its defer (intent vs. goroutine-alive concerns are
-	// fully separated; see the connectionGoroutineRunning helper).
+	// Hold s.mutex for the entire restart sequence (stop + re-start). Any
+	// concurrent Up/Down/Status arriving while MDM is restarting blocks on the
+	// Lock until we are done — they then observe the post-restart state coherently.
 	s.mutex.Lock()
 	defer s.mutex.Unlock()
 
-	if !s.clientRunning {
-		// The client is not running, so there's no engine to restart.
+	if !s.connectClient.ConnectionRunning() {
+		// No run in flight, so there's no engine to restart.
 		return nil
 	}
+
+	// Cancel daemon-side login/status activities tied to the old run; the run
+	// itself is torn down atomically by the supervisor inside Restart (see
+	// restartEngineForMDMLocked), which stops and re-starts in one operation.
 	if s.actCancel != nil {
 		s.actCancel()
 	}
 
-	// Wait for previous connectWithRetryRuns to exit so we don't end up
-	// with two goroutines fighting over the same status recorder + engine.
-	// The teardown engages a fan-out of engine goroutines (peer workers,
-	// signal handler, route manager, ...). close(clientGiveUpChan)
-	// happens in the function-scope defer of connectWithRetryRuns, on
-	// every exit path (ctx cancel, backoff exhausted, panic) — see the
-	// defer in server.go.
-	if s.clientGiveUpChan != nil {
-		select {
-		case <-s.clientGiveUpChan:
-		case <-time.After(10 * time.Second):
-			return fmt.Errorf("failed to restart the engine due to timeout")
-		}
-	}
-
 	if err := s.restartEngineForMDMLocked(); err != nil {
 		log.Errorf("MDM restart failed: %v", err)
 		return err
@@ -131,14 +114,13 @@ func (s *Server) publishConfigChangedEvent(source string) {
 }
 
 // restartEngineForMDMLocked re-resolves the active profile config
-// (re-running applyMDMPolicy via Config.apply) and re-spawns
-// connectWithRetryRuns. Mirrors the tail of Server.Start so a runtime
-// MDM change behaves identically to a fresh boot under the new policy.
+// (re-running applyMDMPolicy via Config.apply) and starts a fresh run.
+// Mirrors the tail of Server.Start so a runtime MDM change behaves
+// identically to a fresh boot under the new policy.
 //
 // MUST be called with s.mutex held — onMDMPolicyChange holds the lock
-// for the entire restart sequence (cancel + quiescence wait + re-spawn)
-// so concurrent Up/Down/Status RPCs observe a coherent post-restart
-// state.
+// for the entire restart sequence so concurrent Up/Down/Status RPCs
+// observe a coherent post-restart state.
 func (s *Server) restartEngineForMDMLocked() error {
 	activeProf, err := s.profileManager.GetActiveProfileState()
 	if err != nil {
@@ -154,13 +136,13 @@ func (s *Server) restartEngineForMDMLocked() error {
 	s.statusRecorder.UpdateRosenpass(config.RosenpassEnabled, config.RosenpassPermissive)
 	s.statusRecorder.UpdateLazyConnection(config.LazyConnectionEnabled)
 
-	ctx, cancel := context.WithCancel(s.rootCtx)
+	_, cancel := context.WithCancel(s.rootCtx)
 	s.actCancel = cancel
-	s.clientRunning = true
-	s.clientRunningChan = make(chan struct{})
-	s.clientGiveUpChan = make(chan struct{})
-	log.Info("MDM restart: spawning connectWithRetryRuns with re-resolved config")
-	go s.connectWithRetryRuns(ctx, config, s.statusRecorder, s.clientRunningChan, s.clientGiveUpChan)
+	log.Info("MDM restart: atomically restarting the run with re-resolved config")
+	// MDM restart has no incoming RPC metadata; fire and forget. Restart is a
+	// single supervisor op (atomic stop+start), so there is no observable
+	// "stopped" window between tearing down the old run and starting the new.
+	s.connectClient.Restart(config, nil)
 	s.publishConfigChangedEvent("mdm")
 	return nil
 }

client/server/network.go

@@ -34,10 +34,6 @@ func (s *Server) ListNetworks(context.Context, *proto.ListNetworksRequest) (*pro
 		return nil, gstatus.Errorf(codes.Unavailable, errNetworksDisabled)
 	}
 
-	if s.connectClient == nil {
-		return nil, fmt.Errorf("not connected")
-	}
-
 	engine := s.connectClient.Engine()
 	if engine == nil {
 		return nil, fmt.Errorf("not connected")
@@ -147,10 +143,6 @@ func (s *Server) SelectNetworks(_ context.Context, req *proto.SelectNetworksRequ
 		return nil, gstatus.Errorf(codes.Unavailable, errNetworksDisabled)
 	}
 
-	if s.connectClient == nil {
-		return nil, fmt.Errorf("not connected")
-	}
-
 	engine := s.connectClient.Engine()
 	if engine == nil {
 		return nil, fmt.Errorf("not connected")
@@ -199,10 +191,6 @@ func (s *Server) DeselectNetworks(_ context.Context, req *proto.SelectNetworksRe
 		return nil, gstatus.Errorf(codes.Unavailable, errNetworksDisabled)
 	}
 
-	if s.connectClient == nil {
-		return nil, fmt.Errorf("not connected")
-	}
-
 	engine := s.connectClient.Engine()
 	if engine == nil {
 		return nil, fmt.Errorf("not connected")

client/server/server.go

@@ -8,12 +8,10 @@ import (
 	"os"
 	"os/exec"
 	"runtime"
-	"strconv"
 	"sync"
 	"sync/atomic"
 	"time"
 
-	"github.com/cenkalti/backoff/v4"
 	log "github.com/sirupsen/logrus"
 	"golang.zx2c4.com/wireguard/wgctrl/wgtypes"
 	"google.golang.org/grpc/codes"
@@ -39,15 +37,7 @@ import (
 )
 
 const (
-	probeThreshold          = time.Second * 5
-	retryInitialIntervalVar = "NB_CONN_RETRY_INTERVAL_TIME"
-	maxRetryIntervalVar     = "NB_CONN_MAX_RETRY_INTERVAL_TIME"
-	maxRetryTimeVar         = "NB_CONN_MAX_RETRY_TIME_TIME"
-	retryMultiplierVar      = "NB_CONN_RETRY_MULTIPLIER"
-	defaultInitialRetryTime = 30 * time.Minute
-	defaultMaxRetryInterval = 60 * time.Minute
-	defaultMaxRetryTime     = 14 * 24 * time.Hour
-	defaultRetryMultiplier  = 1.7
+	probeThreshold = time.Second * 5
 
 	// JWT token cache TTL for the client daemon (disabled by default)
 	defaultJWTCacheTTL = 0
@@ -72,15 +62,8 @@ type Server struct {
 	mutex  sync.Mutex
 	config *profilemanager.Config
 	proto.UnimplementedDaemonServiceServer
-	// clientRunning tracks "the daemon wants to be connected" — set true by
-	// Start / Up, cleared by Down / Logout. Persists across retry
-	// loops, signal disconnects, and ErrResetConnection cycles. NOT
-	// changed by connectWithRetryRuns goroutine exit — for that
-	// (goroutine-still-alive) check, see connectionGoroutineRunning() which
-	// derives from clientGiveUpChan close state. Protected by s.mutex.
-	clientRunning     bool
-	clientRunningChan chan struct{}
-	clientGiveUpChan  chan struct{} // closed when connectWithRetryRuns goroutine exits
+	// Run state (in-flight? established/done channels?) is owned entirely by the
+	// supervisor inside connectClient — the daemon keeps no per-run fields.
 
 	connectClient *internal.ConnectClient
 
@@ -136,6 +119,13 @@ func New(ctx context.Context, logFile string, configFile string, profilesDisable
 		networksDisabled:       networksDisabled,
 		jwtCache:               newJWTCache(),
 	}
+	// The ConnectClient is daemon-lifetime: build it exactly once, here. Its
+	// supervisor lives as long as the daemon; Up/Down/MDM and reconnects all
+	// drive this same instance. updateManager isn't ready yet (created in
+	// Start) and is injected there via SetUpdateManager.
+	s.connectClient = internal.NewConnectClient(ctx, s.statusRecorder)
+	s.connectClient.SetSyncResponsePersistence(s.persistSyncResponse)
+
 	agent := &serverAgent{s}
 	s.sleepHandler = sleephandler.New(agent)
 	s.startSleepDetector()
@@ -147,7 +137,7 @@ func (s *Server) Start() error {
 	s.mutex.Lock()
 	defer s.mutex.Unlock()
 
-	if s.clientRunning {
+	if s.connectClient.ConnectionRunning() {
 		return nil
 	}
 
@@ -165,6 +155,7 @@ func (s *Server) Start() error {
 		stateMgr := statemanager.New(s.profileManager.GetStatePath())
 		s.updateManager = updater.NewManager(s.statusRecorder, stateMgr)
 		s.updateManager.CheckUpdateSuccess(s.rootCtx)
+		s.connectClient.SetUpdateManager(s.updateManager)
 	}
 
 	// MDM policy reload ticker: every minute the desktop daemon re-reads
@@ -190,7 +181,9 @@ func (s *Server) Start() error {
 		return nil
 	}
 
-	ctx, cancel := context.WithCancel(s.rootCtx)
+	// actCancel cancels in-flight foreground operations (login/status); the run
+	// itself is owned by the supervisor and stopped via Stop, not this cancel.
+	_, cancel := context.WithCancel(s.rootCtx)
 	s.actCancel = cancel
 
 	// copy old default config
@@ -232,99 +225,14 @@ func (s *Server) Start() error {
 		return nil
 	}
 
-	s.clientRunning = true
-	s.clientRunningChan = make(chan struct{})
-	s.clientGiveUpChan = make(chan struct{})
-	go s.connectWithRetryRuns(ctx, config, s.statusRecorder, s.clientRunningChan, s.clientGiveUpChan)
+	// Boot autoconnect: no incoming RPC metadata. The supervisor runs the
+	// client and reconnects internally; we just fire and forget (the run owns
+	// its established/done channels).
+	s.connectClient.RunAsync(config, nil)
 	s.publishConfigChangedEvent("startup")
 	return nil
 }
 
-// connectWithRetryRuns runs the client connection with a backoff strategy where we retry the operation as additional
-// mechanism to keep the client connected even when the connection is lost.
-// we cancel retry if the client receive a stop or down command, or if disable auto connect is configured.
-//
-// The goroutine's exit is signalled to the daemon via close(giveUpChan)
-// — placed in the function-scope defer so every return path (panic,
-// DisableAutoConnect early-exit, backoff exhausted, ctx cancel) closes
-// it. Callers that need to observe "is the goroutine still alive?" use
-// Server.connectionGoroutineRunning() which non-blockingly checks the close state
-// of clientGiveUpChan. The defer does NOT touch s.mutex; the daemon's
-// "intent" (clientRunning) is maintained by the RPC handlers, not by this
-// goroutine.
-func (s *Server) connectWithRetryRuns(ctx context.Context, profileConfig *profilemanager.Config, statusRecorder *peer.Status, runningChan chan struct{}, giveUpChan chan struct{}) {
-	defer func() {
-		if giveUpChan != nil {
-			close(giveUpChan)
-		}
-	}()
-
-	if s.config.DisableAutoConnect {
-		if err := s.connect(ctx, s.config, s.statusRecorder, runningChan); err != nil {
-			log.Debugf("run client connection exited with error: %v", err)
-		}
-		log.Tracef("client connection exited")
-		return
-	}
-
-	backOff := getConnectWithBackoff(ctx)
-	go func() {
-		t := time.NewTicker(24 * time.Hour)
-		for {
-			select {
-			case <-ctx.Done():
-				t.Stop()
-				return
-			case <-t.C:
-				mgmtState := statusRecorder.GetManagementState()
-				signalState := statusRecorder.GetSignalState()
-				if mgmtState.Connected && signalState.Connected {
-					log.Tracef("resetting status")
-					backOff.Reset()
-				} else {
-					log.Tracef("not resetting status: mgmt: %v, signal: %v", mgmtState.Connected, signalState.Connected)
-				}
-			}
-		}
-	}()
-
-	runOperation := func() error {
-		err := s.connect(ctx, profileConfig, statusRecorder, runningChan)
-		if err != nil {
-			log.Debugf("run client connection exited with error: %v. Will retry in the background", err)
-			return err
-		}
-
-		log.Tracef("client connection exited gracefully, do not need to retry")
-		return nil
-	}
-
-	if err := backoff.Retry(runOperation, backOff); err != nil {
-		log.Errorf("operation failed: %v", err)
-	}
-	// giveUpChan is closed by the function-scope defer.
-}
-
-// connectionGoroutineRunning reports whether the connectWithRetryRuns goroutine is
-// still running. Returns false when no goroutine has ever been started
-// AND when the most recent one has already closed clientGiveUpChan on
-// exit (whether due to ctx cancel, DisableAutoConnect single-shot
-// completion, or backoff retry exhaustion).
-//
-// MUST be called with s.mutex held — accesses s.clientGiveUpChan which
-// is written by Start/Up under the same lock.
-func (s *Server) connectionGoroutineRunning() bool {
-	if s.clientGiveUpChan == nil {
-		return false
-	}
-	select {
-	case <-s.clientGiveUpChan:
-		return false
-	default:
-		return true
-	}
-}
-
 // loginAttempt attempts to login using the provided information. it returns a status in case something fails
 func (s *Server) loginAttempt(ctx context.Context, setupKey, jwtToken string) (internal.StatusType, error) {
 	authClient, err := auth.NewAuth(ctx, s.config.PrivateKey, s.config.ManagementURL, s.config)
@@ -720,13 +628,22 @@ func (s *Server) WaitSSOLogin(callerCtx context.Context, msg *proto.WaitSSOLogin
 // Up starts engine work in the daemon.
 func (s *Server) Up(callerCtx context.Context, msg *proto.UpRequest) (*proto.UpResponse, error) {
 	s.mutex.Lock()
-	// clientRunning is the daemon-intent flag (set by previous Up/Start, cleared
-	// by Down). connectionGoroutineRunning() reports whether the previous retry-loop
-	// goroutine is still trying. When intent is up AND goroutine is alive,
-	// the existing engine is on the job — just wait for it. When intent
-	// is up but the goroutine has given up (backoff exhausted) OR when
-	// intent is down, fall through to spawn a fresh retry loop.
-	if s.clientRunning && s.connectionGoroutineRunning() {
+
+	// The client (and its supervisor) is built once in New(), so a nil here
+	// never happens in production — Up is only reachable after New() has run and
+	// the gRPC server is serving. The real case this guards is the daemon
+	// SHUTTING DOWN: rootCtx is cancelled, the supervisor is no longer accepting
+	// commands, so ServiceRunning() is false even though the client exists. Bail
+	// loud instead of enqueuing a run that will never start. (nil only happens in
+	// tests that build a Server without New(); ServiceRunning is nil-safe.)
+	if !s.connectClient.ServiceRunning() {
+		s.mutex.Unlock()
+		return nil, fmt.Errorf("service is not running, start the netbird service for 'up' to take effect")
+	}
+
+	// If a connection run is already in flight, the existing engine is on the
+	// job — just wait for it. Otherwise fall through to start a fresh run.
+	if s.connectClient.ConnectionRunning() {
 		state := internal.CtxGetState(s.rootCtx)
 		status, err := state.Status()
 		if err != nil {
@@ -764,14 +681,14 @@ func (s *Server) Up(callerCtx context.Context, msg *proto.UpRequest) (*proto.UpR
 	if s.actCancel != nil {
 		s.actCancel()
 	}
-	ctx, cancel := context.WithCancel(s.rootCtx)
-	md, ok := metadata.FromIncomingContext(callerCtx)
-	if ok {
-		ctx = metadata.NewOutgoingContext(ctx, md)
-	}
-
+	// actCancel cancels in-flight foreground ops (login/status); the run is
+	// owned by the supervisor and stopped via Stop, not this cancel.
+	_, cancel := context.WithCancel(s.rootCtx)
 	s.actCancel = cancel
 
+	// Forward the caller's gRPC metadata (e.g. UI user-agent) into the run.
+	md, _ := metadata.FromIncomingContext(callerCtx)
+
 	if s.config == nil {
 		s.mutex.Unlock()
 		return nil, fmt.Errorf("config is not defined, please call login command first")
@@ -812,35 +729,26 @@ func (s *Server) Up(callerCtx context.Context, msg *proto.UpRequest) (*proto.UpR
 	s.statusRecorder.UpdateManagementAddress(s.config.ManagementURL.String())
 	s.statusRecorder.UpdateRosenpass(s.config.RosenpassEnabled, s.config.RosenpassPermissive)
 
-	s.clientRunning = true
-	s.clientRunningChan = make(chan struct{})
-	s.clientGiveUpChan = make(chan struct{})
-
-	go s.connectWithRetryRuns(ctx, s.config, s.statusRecorder, s.clientRunningChan, s.clientGiveUpChan)
+	s.connectClient.RunAsync(s.config, md)
 	s.publishConfigChangedEvent("up_rpc")
 
 	s.mutex.Unlock()
 	return s.waitForUp(callerCtx)
 }
 
-// todo: handle potential race conditions
+// waitForUp blocks until the in-flight run becomes established (success) or ends
+// before that (failure). The wait is owned by the supervisor (via the client) —
+// the daemon holds no per-run state here.
 func (s *Server) waitForUp(callerCtx context.Context) (*proto.UpResponse, error) {
 	timeoutCtx, cancel := context.WithTimeout(callerCtx, 50*time.Second)
 	defer cancel()
 
-	select {
-	case <-s.clientGiveUpChan:
-		return nil, fmt.Errorf("client gave up to connect")
-	case <-s.clientRunningChan:
-		s.isSessionActive.Store(true)
-		return &proto.UpResponse{}, nil
-	case <-callerCtx.Done():
-		log.Debug("context done, stopping the wait for engine to become ready")
-		return nil, callerCtx.Err()
-	case <-timeoutCtx.Done():
-		log.Debug("up is timed out, stopping the wait for engine to become ready")
-		return nil, timeoutCtx.Err()
+	if err := s.connectClient.WaitEstablishedOrDone(timeoutCtx); err != nil {
+		log.Debugf("waiting for the connection to be established failed: %v", err)
+		return nil, fmt.Errorf("connection not established: %w", err)
 	}
+	s.isSessionActive.Store(true)
+	return &proto.UpResponse{}, nil
 }
 
 // resolveProfileHandle resolves a wire-level profile handle (display
@@ -935,11 +843,11 @@ func (s *Server) SwitchProfile(callerCtx context.Context, msg *proto.SwitchProfi
 // Down engine work in the daemon.
 func (s *Server) Down(ctx context.Context, _ *proto.DownRequest) (*proto.DownResponse, error) {
 	s.mutex.Lock()
+	defer s.mutex.Unlock()
 
-	giveUpChan := s.clientGiveUpChan
-
+	// cleanupConnection stops the run through the supervisor, which blocks until
+	// the run has fully unwound — no separate goroutine-quiescence wait needed.
 	if err := s.cleanupConnection(); err != nil {
-		s.mutex.Unlock()
 		// todo review to update the status in case any type of error
 		log.Errorf("failed to shut down properly: %v", err)
 		return nil, err
@@ -948,20 +856,6 @@ func (s *Server) Down(ctx context.Context, _ *proto.DownRequest) (*proto.DownRes
 	state := internal.CtxGetState(s.rootCtx)
 	state.Set(internal.StatusIdle)
 
-	s.mutex.Unlock()
-
-	// Wait for the connectWithRetryRuns goroutine to finish with a short timeout.
-	// This prevents the goroutine from setting ErrResetConnection after Down() returns.
-	// The giveUpChan is closed at the end of connectWithRetryRuns.
-	if giveUpChan != nil {
-		select {
-		case <-giveUpChan:
-			log.Debugf("client goroutine finished successfully")
-		case <-time.After(5 * time.Second):
-			log.Warnf("timeout waiting for client goroutine to finish, proceeding anyway")
-		}
-	}
-
 	return &proto.DownResponse{}, nil
 }
 
@@ -972,34 +866,19 @@ func (s *Server) cleanupConnection() error {
 		return ErrServiceNotUp
 	}
 
-	// Daemon intent flips to "down" — all callers (Down RPC,
-	// Logout RPC handlers) tear down the connection because the user
-	// explicitly asked for it. MDM restart does NOT go through this
-	// path, so its clientRunning stays true.
-	s.clientRunning = false
-
-	// Capture the engine reference before cancelling the context.
-	// After actCancel(), the connectWithRetryRuns goroutine wakes up
-	// and sets connectClient.engine = nil, causing connectClient.Stop()
-	// to skip the engine shutdown entirely.
-	var engine *internal.Engine
-	if s.connectClient != nil {
-		engine = s.connectClient.Engine()
+	// Tear the client down through the lifecycle supervisor BEFORE cancelling
+	// the retry context. Stop serializes on the supervisor queue and blocks
+	// until the in-flight run has fully unwound (a clean, synchronous teardown).
+	// It must run before actCancel: cancelling the context first would make
+	// Stop observe a dead context and return early without waiting.
+	if err := s.connectClient.Stop(); err != nil {
+		return err
 	}
 
+	// Stop the retry goroutine so it does not start a fresh run. The client
+	// itself is daemon-lifetime and intentionally kept (a later Up reuses it).
 	s.actCancel()
 
-	if s.connectClient == nil {
-		return nil
-	}
-
-	if engine != nil {
-		if err := engine.Stop(); err != nil {
-			return err
-		}
-	}
-
-	s.connectClient = nil
 	s.isSessionActive.Store(false)
 
 	log.Infof("service is down")
@@ -1134,7 +1013,7 @@ func (s *Server) validateProfileOperation(id profilemanager.ID, allowActiveProfi
 
 func (s *Server) logoutFromProfile(ctx context.Context, profile *profilemanager.Profile) error {
 	activeProf, err := s.profileManager.GetActiveProfileState()
-	if err == nil && activeProf.ID == profile.ID && s.connectClient != nil {
+	if err == nil && activeProf.ID == profile.ID && s.connectClient.ConnectionRunning() {
 		return s.sendLogoutRequest(ctx)
 	}
 
@@ -1180,48 +1059,13 @@ func (s *Server) Status(
 	ctx context.Context,
 	msg *proto.StatusRequest,
 ) (*proto.StatusResponse, error) {
-	s.mutex.Lock()
-	// Only wait if the retry-loop goroutine is alive and making
-	// progress. clientRunning=true with connectionGoroutineRunning=false means the
-	// backoff has given up — there is nothing to wait for; let the
-	// caller observe the failed status directly.
-	alive := s.connectionGoroutineRunning()
-	s.mutex.Unlock()
-
-	if msg.WaitForReady != nil && *msg.WaitForReady && alive {
-		state := internal.CtxGetState(s.rootCtx)
-		status, err := state.Status()
-		if err != nil {
-			return nil, err
-		}
-
-		if status != internal.StatusIdle && status != internal.StatusConnected && status != internal.StatusConnecting {
-			s.actCancel()
-		}
-
-		ticker := time.NewTicker(1 * time.Second)
-		defer ticker.Stop()
-	loop:
-		for {
-			select {
-			case <-s.clientGiveUpChan:
-				ticker.Stop()
-				break loop
-			case <-s.clientRunningChan:
-				ticker.Stop()
-				break loop
-			case <-ticker.C:
-				status, err := state.Status()
-				if err != nil {
-					continue
-				}
-				if status != internal.StatusIdle && status != internal.StatusConnected && status != internal.StatusConnecting {
-					s.actCancel()
-				}
-				continue
-			case <-ctx.Done():
-				return nil, ctx.Err()
-			}
+	// A run that hits a terminal auth failure now exits on its own (engine marks
+	// NeedsLogin), so we no longer poll-and-cancel: we wait for the in-flight run
+	// to become established or to end. With no run in flight this returns
+	// immediately (errNoRunInFlight); either way we then report the status below.
+	if msg.WaitForReady != nil && *msg.WaitForReady {
+		if err := s.connectClient.WaitEstablishedOrDone(ctx); err != nil && ctx.Err() != nil {
+			return nil, ctx.Err()
 		}
 	}
 
@@ -1259,10 +1103,6 @@ func (s *Server) getSSHServerState() *proto.SSHServerState {
 	connectClient := s.connectClient
 	s.mutex.Unlock()
 
-	if connectClient == nil {
-		return nil
-	}
-
 	engine := connectClient.Engine()
 	if engine == nil {
 		return nil
@@ -1300,10 +1140,6 @@ func (s *Server) GetPeerSSHHostKey(
 	statusRecorder := s.statusRecorder
 	s.mutex.Unlock()
 
-	if connectClient == nil {
-		return nil, errors.New("client not initialized")
-	}
-
 	engine := connectClient.Engine()
 	if engine == nil {
 		return nil, errors.New("engine not started")
@@ -1470,17 +1306,13 @@ func (s *Server) WaitJWTToken(
 // ExposeService exposes a local port via the NetBird reverse proxy.
 func (s *Server) ExposeService(req *proto.ExposeServiceRequest, srv proto.DaemonService_ExposeServiceServer) error {
 	s.mutex.Lock()
-	if !s.clientRunning {
+	if !s.connectClient.ConnectionRunning() {
 		s.mutex.Unlock()
 		return gstatus.Errorf(codes.FailedPrecondition, "client is not running, run 'netbird up' first")
 	}
 	connectClient := s.connectClient
 	s.mutex.Unlock()
 
-	if connectClient == nil {
-		return gstatus.Errorf(codes.FailedPrecondition, "client not initialized")
-	}
-
 	engine := connectClient.Engine()
 	if engine == nil {
 		return gstatus.Errorf(codes.FailedPrecondition, "engine not initialized")
@@ -1534,10 +1366,6 @@ func isUnixRunningDesktop() bool {
 }
 
 func (s *Server) runProbes(waitForProbeResult bool) {
-	if s.connectClient == nil {
-		return
-	}
-
 	engine := s.connectClient.Engine()
 	if engine == nil {
 		return
@@ -1816,22 +1644,6 @@ func (s *Server) GetFeatures(ctx context.Context, msg *proto.GetFeaturesRequest)
 	return features, nil
 }
 
-func (s *Server) connect(ctx context.Context, config *profilemanager.Config, statusRecorder *peer.Status, runningChan chan struct{}) error {
-	log.Tracef("running client connection")
-	client := internal.NewConnectClient(ctx, config, statusRecorder)
-	client.SetUpdateManager(s.updateManager)
-	client.SetSyncResponsePersistence(s.persistSyncResponse)
-
-	s.mutex.Lock()
-	s.connectClient = client
-	s.mutex.Unlock()
-
-	if err := client.Run(runningChan, s.logFile); err != nil {
-		return err
-	}
-	return nil
-}
-
 // MDM authority: when the platform-native MDM source sets a kill switch
 // key (regardless of true/false value), that value wins. The CLI flag
 // supplied at service install time is the fallback used only when the
@@ -1893,45 +1705,6 @@ func (s *Server) onSessionExpire() {
 	}
 }
 
-// getConnectWithBackoff returns a backoff with exponential backoff strategy for connection retries
-func getConnectWithBackoff(ctx context.Context) backoff.BackOff {
-	initialInterval := parseEnvDuration(retryInitialIntervalVar, defaultInitialRetryTime)
-	maxInterval := parseEnvDuration(maxRetryIntervalVar, defaultMaxRetryInterval)
-	maxElapsedTime := parseEnvDuration(maxRetryTimeVar, defaultMaxRetryTime)
-	multiplier := defaultRetryMultiplier
-
-	if envValue := os.Getenv(retryMultiplierVar); envValue != "" {
-		// parse the multiplier from the environment variable string value to float64
-		value, err := strconv.ParseFloat(envValue, 64)
-		if err != nil {
-			log.Warnf("unable to parse environment variable %s: %s. using default: %f", retryMultiplierVar, envValue, multiplier)
-		} else {
-			multiplier = value
-		}
-	}
-
-	return backoff.WithContext(&backoff.ExponentialBackOff{
-		InitialInterval:     initialInterval,
-		RandomizationFactor: 1,
-		Multiplier:          multiplier,
-		MaxInterval:         maxInterval,
-		MaxElapsedTime:      maxElapsedTime, // 14 days
-		Stop:                backoff.Stop,
-		Clock:               backoff.SystemClock,
-	}, ctx)
-}
-
-// parseEnvDuration parses the environment variable and returns the duration
-func parseEnvDuration(envVar string, defaultDuration time.Duration) time.Duration {
-	if envValue := os.Getenv(envVar); envValue != "" {
-		if duration, err := time.ParseDuration(envValue); err == nil {
-			return duration
-		}
-		log.Warnf("unable to parse environment variable %s: %s. using default: %s", envVar, envValue, defaultDuration)
-	}
-	return defaultDuration
-}
-
 // sendTerminalNotification sends a terminal notification message
 // to inform the user that the NetBird connection session has expired.
 func sendTerminalNotification() error {

client/server/server_connect_test.go

@@ -15,14 +15,19 @@ import (
 )
 
 func newTestServer() *Server {
-	return &Server{
-		rootCtx:        context.Background(),
+	ctx := context.Background()
+	s := &Server{
+		rootCtx:        ctx,
 		statusRecorder: peer.NewRecorder(""),
 	}
+	// Honor the production invariant: the daemon-lifetime client always exists
+	// (built in New). Server methods rely on s.connectClient being non-nil.
+	s.connectClient = internal.NewConnectClient(ctx, s.statusRecorder)
+	return s
 }
 
 func newDummyConnectClient(ctx context.Context) *internal.ConnectClient {
-	return internal.NewConnectClient(ctx, nil, nil)
+	return internal.NewConnectClient(ctx, nil)
 }
 
 // TestConnectSetsClientWithMutex validates that connect() sets s.connectClient
@@ -87,41 +92,36 @@ func TestConcurrentConnectClientAccess(t *testing.T) {
 	assert.Equal(t, 50, nilCount+setCount, "all goroutines should complete without panic")
 }
 
-// TestCleanupConnection_ClearsConnectClient validates that cleanupConnection
-// properly nils out connectClient.
-func TestCleanupConnection_ClearsConnectClient(t *testing.T) {
+// TestCleanupConnection_KeepsClientStopsRunning validates that cleanupConnection
+// clears the daemon "up" intent but KEEPS the daemon-lifetime ConnectClient
+// (it is reused across Up/Down; only the run is stopped).
+func TestCleanupConnection_KeepsClientStopsRunning(t *testing.T) {
 	s := newTestServer()
 	_, cancel := context.WithCancel(context.Background())
 	s.actCancel = cancel
 
-	s.connectClient = newDummyConnectClient(context.Background())
-	s.clientRunning = true
-
 	err := s.cleanupConnection()
 	require.NoError(t, err)
 
-	assert.Nil(t, s.connectClient, "connectClient should be nil after cleanup")
-	assert.False(t, s.clientRunning, "clientRunning should be cleared after cleanup (intent = down)")
+	assert.NotNil(t, s.connectClient, "connectClient is daemon-lifetime and must persist after cleanup")
+	assert.False(t, s.connectClient.ConnectionRunning(), "no run should be in flight after cleanup")
 }
 
-// TestCleanState_NilConnectClient validates that CleanState doesn't panic
-// when connectClient is nil.
-func TestCleanState_NilConnectClient(t *testing.T) {
+// TestCleanState_NotConnected validates that CleanState doesn't panic when no
+// connection run is in flight.
+func TestCleanState_NotConnected(t *testing.T) {
 	s := newTestServer()
-	s.connectClient = nil
-	s.profileManager = nil // will cause error if it tries to proceed past the nil check
+	s.profileManager = nil // will cause error if it tries to proceed
 
-	// Should not panic — the nil check should prevent calling Status() on nil
 	assert.NotPanics(t, func() {
 		_, _ = s.CleanState(context.Background(), &proto.CleanStateRequest{All: true})
 	})
 }
 
-// TestDeleteState_NilConnectClient validates that DeleteState doesn't panic
-// when connectClient is nil.
-func TestDeleteState_NilConnectClient(t *testing.T) {
+// TestDeleteState_NotConnected validates that DeleteState doesn't panic when no
+// connection run is in flight.
+func TestDeleteState_NotConnected(t *testing.T) {
 	s := newTestServer()
-	s.connectClient = nil
 	s.profileManager = nil
 
 	assert.NotPanics(t, func() {
@@ -129,60 +129,6 @@ func TestDeleteState_NilConnectClient(t *testing.T) {
 	})
 }
 
-// TestDownThenUp_StaleRunningChan documents the known state issue where
-// clientRunningChan from a previous connection is already closed, causing
-// waitForUp() to return immediately on reconnect.
-func TestDownThenUp_StaleRunningChan(t *testing.T) {
-	s := newTestServer()
-
-	// Simulate state after a successful connection
-	s.clientRunning = true
-	s.clientRunningChan = make(chan struct{})
-	close(s.clientRunningChan) // closed when engine started
-	s.clientGiveUpChan = make(chan struct{})
-	s.connectClient = newDummyConnectClient(context.Background())
-
-	_, cancel := context.WithCancel(context.Background())
-	s.actCancel = cancel
-
-	// Simulate Down(): cleanupConnection sets connectClient = nil and
-	// flips clientRunning to false (intent = down). The connectionGoroutineRunning state
-	// remains independent of intent — derived from clientGiveUpChan.
-	s.mutex.Lock()
-	err := s.cleanupConnection()
-	s.mutex.Unlock()
-	require.NoError(t, err)
-
-	// After cleanup: connectClient is nil, clientRunning is false (intent
-	// cleared by cleanupConnection), connectionGoroutineRunning may still be true
-	// (goroutine teardown is independent of the intent flag).
-	s.mutex.Lock()
-	assert.Nil(t, s.connectClient, "connectClient should be nil after cleanup")
-	assert.False(t, s.clientRunning, "clientRunning should be cleared by cleanupConnection (intent = down)")
-	s.mutex.Unlock()
-
-	// waitForUp() returns immediately due to stale closed clientRunningChan
-	ctx, ctxCancel := context.WithTimeout(context.Background(), 2*time.Second)
-	defer ctxCancel()
-
-	waitDone := make(chan error, 1)
-	go func() {
-		_, err := s.waitForUp(ctx)
-		waitDone <- err
-	}()
-
-	select {
-	case err := <-waitDone:
-		assert.NoError(t, err, "waitForUp returns success on stale channel")
-		// But connectClient is still nil — this is the stale state issue
-		s.mutex.Lock()
-		assert.Nil(t, s.connectClient, "connectClient is nil despite waitForUp success")
-		s.mutex.Unlock()
-	case <-time.After(1 * time.Second):
-		t.Fatal("waitForUp should have returned immediately due to stale closed channel")
-	}
-}
-
 // TestConnectClient_EngineNilOnFreshClient validates that a newly created
 // ConnectClient has nil Engine (before Run is called).
 func TestConnectClient_EngineNilOnFreshClient(t *testing.T) {

client/server/server_test.go

@@ -31,7 +31,6 @@ import (
 	"google.golang.org/grpc/keepalive"
 
 	"github.com/netbirdio/netbird/client/internal"
-	"github.com/netbirdio/netbird/client/internal/peer"
 	"github.com/netbirdio/netbird/client/internal/profilemanager"
 	daemonProto "github.com/netbirdio/netbird/client/proto"
 	"github.com/netbirdio/netbird/management/server"
@@ -61,65 +60,6 @@ var (
 	}
 )
 
-// TestConnectWithRetryRuns checks that the connectWithRetry function runs and runs the retries according to the times specified via environment variables
-// we will use a management server started via to simulate the server and capture the number of retries
-func TestConnectWithRetryRuns(t *testing.T) {
-	// start the signal server
-	_, signalAddr, err := startSignal(t)
-	if err != nil {
-		t.Fatalf("failed to start signal server: %v", err)
-	}
-
-	counter := 0
-	// start the management server
-	_, mgmtAddr, err := startManagement(t, signalAddr, &counter)
-	if err != nil {
-		t.Fatalf("failed to start management server: %v", err)
-	}
-
-	ctx := internal.CtxInitState(context.Background())
-
-	ctx, cancel := context.WithDeadline(ctx, time.Now().Add(30*time.Second))
-	defer cancel()
-	// create new server
-	ic := profilemanager.ConfigInput{
-		ManagementURL: "http://" + mgmtAddr,
-		ConfigPath:    t.TempDir() + "/test-profile.json",
-	}
-
-	config, err := profilemanager.UpdateOrCreateConfig(ic)
-	if err != nil {
-		t.Fatalf("failed to create config: %v", err)
-	}
-
-	currUser, err := user.Current()
-	require.NoError(t, err)
-
-	pm := profilemanager.ServiceManager{}
-	err = pm.SetActiveProfileState(&profilemanager.ActiveProfileState{
-		ID:       "test-profile",
-		Username: currUser.Username,
-	})
-	if err != nil {
-		t.Fatalf("failed to set active profile state: %v", err)
-	}
-
-	s := New(ctx, "debug", "", false, false, false, false)
-
-	s.config = config
-
-	s.statusRecorder = peer.NewRecorder(config.ManagementURL.String())
-	t.Setenv(retryInitialIntervalVar, "1s")
-	t.Setenv(maxRetryIntervalVar, "2s")
-	t.Setenv(maxRetryTimeVar, "5s")
-	t.Setenv(retryMultiplierVar, "1")
-
-	s.connectWithRetryRuns(ctx, config, s.statusRecorder, nil, nil)
-	if counter < 3 {
-		t.Fatalf("expected counter > 2, got %d", counter)
-	}
-}
-
 func TestServer_Up(t *testing.T) {
 	tempDir := t.TempDir()
 	origDefaultProfileDir := profilemanager.DefaultConfigPathDir

client/server/state.go

@@ -9,7 +9,6 @@ import (
 	"google.golang.org/grpc/status"
 
 	nberrors "github.com/netbirdio/netbird/client/errors"
-	"github.com/netbirdio/netbird/client/internal"
 	"github.com/netbirdio/netbird/client/internal/routemanager/systemops"
 	"github.com/netbirdio/netbird/client/internal/statemanager"
 	"github.com/netbirdio/netbird/client/proto"
@@ -38,7 +37,7 @@ func (s *Server) ListStates(_ context.Context, _ *proto.ListStatesRequest) (*pro
 
 // CleanState handles cleaning of states (performing cleanup operations)
 func (s *Server) CleanState(ctx context.Context, req *proto.CleanStateRequest) (*proto.CleanStateResponse, error) {
-	if s.connectClient != nil && (s.connectClient.Status() == internal.StatusConnected || s.connectClient.Status() == internal.StatusConnecting) {
+	if s.connectClient.ConnectionRunning() {
 		return nil, status.Errorf(codes.FailedPrecondition, "cannot clean state while connecting or connected, run 'netbird down' first.")
 	}
 
@@ -81,7 +80,7 @@ func (s *Server) CleanState(ctx context.Context, req *proto.CleanStateRequest) (
 
 // DeleteState handles deletion of states without cleanup
 func (s *Server) DeleteState(ctx context.Context, req *proto.DeleteStateRequest) (*proto.DeleteStateResponse, error) {
-	if s.connectClient != nil && (s.connectClient.Status() == internal.StatusConnected || s.connectClient.Status() == internal.StatusConnecting) {
+	if s.connectClient.ConnectionRunning() {
 		return nil, status.Errorf(codes.FailedPrecondition, "cannot clean state while connecting or connected, run 'netbird down' first.")
 	}
 

client/server/trace.go

@@ -62,10 +62,6 @@ func (s *Server) TracePacket(_ context.Context, req *proto.TracePacketRequest) (
 }
 
 func (s *Server) getPacketTracer() (packetTracer, *internal.Engine, error) {
-	if s.connectClient == nil {
-		return nil, nil, fmt.Errorf("connect client not initialized")
-	}
-
 	engine := s.connectClient.Engine()
 	if engine == nil {
 		return nil, nil, fmt.Errorf("engine not initialized")

docker/build-env/README.md

@@ -0,0 +1,56 @@
+# Build environments
+
+Dockerfiles that pin the same toolchain CI uses, so a developer can
+reproduce a CI build locally without installing platform SDKs on their
+workstation. The version pins in each `Dockerfile` must stay in lockstep
+with `.github/workflows/`.
+
+## `android/`
+
+Mirrors `.github/workflows/mobile-build-validation.yml` (`android_build`
+job). Carries Go 1.25.5, Adopt JDK 11, Android cmdline-tools 8512546,
+NDK 23.1.7779620 and gomobile pinned at the CI commit. Use it to
+produce `netbird.aar` from `./client/android`:
+
+```bash
+docker build -t netbird/build-android docker/build-env/android
+docker run --rm -v "$PWD:/src" -w /src netbird/build-android \
+    gomobile bind \
+    -o netbird.aar \
+    -javapkg=io.netbird.gomobile \
+    -ldflags="-checklinkname=0 \
+              -X golang.zx2c4.com/wireguard/ipc.socketDirectory=/data/data/io.netbird.client/cache/wireguard \
+              -X github.com/netbirdio/netbird/version.version=local" \
+    ./client/android
+```
+
+To build the full Android APK, bind-mount the `android-client` repo as
+well and run its own `./gradlew assembleDebug` from inside the
+container (the gradle wrapper ships with `android-client`).
+
+## `windows-cross/`
+
+Cross-compiles Windows binaries from Linux using `mingw-w64`. Lets you
+verify that `GOOS=windows go build ./...` compiles cleanly without
+needing a Windows VM. Cannot run Windows tests — the `golang-test-windows`
+CI job executes on a native `windows-latest` runner with wintun.dll
+and PsExec, neither of which lives under Linux containers.
+
+```bash
+docker build -t netbird/build-windows docker/build-env/windows-cross
+docker run --rm -v "$PWD:/src" -w /src netbird/build-windows \
+    bash -c 'GOOS=windows GOARCH=amd64 go build ./...'
+```
+
+## What is NOT here
+
+- **iOS / macOS**: cannot legally run macOS in Docker (Apple EULA),
+  and Xcode is not redistributable. The `ios_build` CI job uses a
+  `macos-latest` GitHub runner; locally you need a real Mac.
+
+- **Native Windows tests**: see note above. The Linux+mingw image
+  builds, it does not execute Windows-host code paths
+  (registry, wintun, services, PsExec workflows).
+
+When CI version pins change, update the corresponding `ARG` lines in
+the Dockerfiles and the README's table of versions.

docker/build-env/android/Dockerfile

@@ -0,0 +1,86 @@
+# Android build environment.
+#
+# Mirrors the toolchain pinned by .github/workflows/mobile-build-validation.yml
+# so a `gomobile bind` against ./client/android in this image produces the
+# same netbird.aar that CI builds.
+#
+# Tooling versions (must stay in sync with the CI workflow):
+#   - Ubuntu 22.04 (matches the ubuntu-latest GitHub runner)
+#   - Go 1.25.5 (matches go.mod)
+#   - Adopt JDK 11 (matches actions/setup-java@v3 java-version: 11, distribution: adopt)
+#   - Android SDK cmdline-tools 8512546
+#   - Android NDK 23.1.7779620
+#   - gomobile commit v0.0.0-20251113184115-a159579294ab
+#
+# Usage (from the netbird repo root):
+#
+#   docker build -t netbird/build-android docker/build-env/android
+#
+#   # bind the netbird checkout in and run the same gomobile command CI runs
+#   docker run --rm -v "$PWD:/src" -w /src netbird/build-android \
+#       gomobile bind \
+#       -o netbird.aar \
+#       -javapkg=io.netbird.gomobile \
+#       -ldflags="-checklinkname=0 \
+#                 -X golang.zx2c4.com/wireguard/ipc.socketDirectory=/data/data/io.netbird.client/cache/wireguard \
+#                 -X github.com/netbirdio/netbird/version.version=local" \
+#       ./client/android
+#
+# To build the full APK, mount the android-client repo too and run
+# `./gradlew assembleDebug` from /android-client (this image carries
+# gradle's prerequisites JDK + Android SDK but not the gradle wrapper —
+# that ships with android-client).
+
+FROM ubuntu:22.04
+
+ARG DEBIAN_FRONTEND=noninteractive
+
+# Versions — bump in lockstep with .github/workflows/mobile-build-validation.yml.
+ARG GO_VERSION=1.25.5
+ARG ANDROID_CMDLINE_TOOLS_VERSION=8512546
+ARG ANDROID_NDK_VERSION=23.1.7779620
+ARG GOMOBILE_VERSION=v0.0.0-20251113184115-a159579294ab
+
+ENV ANDROID_HOME=/opt/android-sdk
+ENV ANDROID_NDK_HOME=${ANDROID_HOME}/ndk/${ANDROID_NDK_VERSION}
+ENV JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
+ENV GOPATH=/go
+ENV GOTOOLCHAIN=local
+ENV CGO_ENABLED=0
+ENV PATH=${GOPATH}/bin:/usr/local/go/bin:${ANDROID_HOME}/cmdline-tools/latest/bin:${ANDROID_HOME}/platform-tools:${JAVA_HOME}/bin:${PATH}
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        ca-certificates \
+        curl \
+        unzip \
+        git \
+        openjdk-11-jdk-headless \
+        build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Go (matches go.mod). actions/setup-go fetches the same tarball.
+RUN curl -fsSL "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz" \
+        | tar -C /usr/local -xz \
+    && go version
+
+# Install Android SDK command-line tools, accept licenses, install NDK.
+RUN mkdir -p "${ANDROID_HOME}/cmdline-tools" \
+    && curl -fsSL -o /tmp/cmdline.zip \
+        "https://dl.google.com/android/repository/commandlinetools-linux-${ANDROID_CMDLINE_TOOLS_VERSION}_latest.zip" \
+    && unzip -q /tmp/cmdline.zip -d "${ANDROID_HOME}/cmdline-tools" \
+    && mv "${ANDROID_HOME}/cmdline-tools/cmdline-tools" "${ANDROID_HOME}/cmdline-tools/latest" \
+    && rm /tmp/cmdline.zip \
+    && yes | sdkmanager --licenses > /dev/null \
+    && sdkmanager --install "ndk;${ANDROID_NDK_VERSION}" "platform-tools" > /dev/null
+
+# Install gomobile at the same commit CI pins. Don't run `gomobile init` here:
+# `init` resolves the NDK at runtime, do it on the first bind in the mounted
+# workspace so the cache lands on the host volume.
+RUN GOBIN=/usr/local/bin go install "golang.org/x/mobile/cmd/gomobile@${GOMOBILE_VERSION}" \
+    && gomobile version
+
+WORKDIR /src
+
+# Default entrypoint is a plain shell so the image is composable: callers pass
+# the full gomobile / gradle command they want to run.
+CMD ["/bin/bash"]

docker/build-env/windows-cross/Dockerfile

@@ -0,0 +1,63 @@
+# Windows-cross build environment.
+#
+# Cross-compiles Windows .exe targets from a Linux container using
+# mingw-w64. Mirrors the toolchain set used by
+# .github/workflows/golang-test-windows.yml insofar as that is possible
+# without a Windows kernel.
+#
+# IMPORTANT — what this image CAN do:
+#   - `GOOS=windows go build ./...` to validate that Windows builds compile
+#   - CGO Windows cross-compile via x86_64-w64-mingw32-gcc when CGO_ENABLED=1
+#     (matches CI's choco-installed mingw-w64)
+#
+# IMPORTANT — what this image CANNOT do:
+#   - Run Windows binaries (no Windows kernel under Docker on Linux).
+#   - Replicate the CI's `go test` runs which execute on a real
+#     windows-latest runner (wintun.dll, PsExec, registry, etc.).
+#     Use the CI for that or a native Windows VM.
+#
+# Usage (from the netbird repo root):
+#
+#   docker build -t netbird/build-windows docker/build-env/windows-cross
+#
+#   # Cross-compile a static client (.exe) from Linux:
+#   docker run --rm -v "$PWD:/src" -w /src netbird/build-windows \
+#       bash -c 'CGO_ENABLED=1 GOOS=windows GOARCH=amd64 \
+#           CC=x86_64-w64-mingw32-gcc CXX=x86_64-w64-mingw32-g++ \
+#           go build -o netbird.exe ./client'
+#
+#   # Just validate that everything *compiles* on Windows (no CGO):
+#   docker run --rm -v "$PWD:/src" -w /src netbird/build-windows \
+#       bash -c 'GOOS=windows GOARCH=amd64 go build ./...'
+#
+# Tooling versions (keep in sync with go.mod and any future explicit pin
+# documented in golang-test-windows.yml):
+#   - Ubuntu 22.04
+#   - Go 1.25.5 (matches go.mod)
+#   - mingw-w64 (Ubuntu package — pin further if drift becomes a problem)
+
+FROM ubuntu:22.04
+
+ARG DEBIAN_FRONTEND=noninteractive
+ARG GO_VERSION=1.25.5
+
+ENV GOPATH=/go
+ENV GOTOOLCHAIN=local
+ENV PATH=${GOPATH}/bin:/usr/local/go/bin:${PATH}
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        ca-certificates \
+        curl \
+        git \
+        build-essential \
+        mingw-w64 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Go (matches go.mod).
+RUN curl -fsSL "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz" \
+        | tar -C /usr/local -xz \
+    && go version
+
+WORKDIR /src
+
+CMD ["/bin/bash"]

util/log.go

@@ -140,7 +140,12 @@ func newRotatedOutput(logPath string) io.Writer {
 func setGRPCLibLogger(logger *log.Logger) {
 	logOut := logger.Writer()
 	if os.Getenv("GRPC_GO_LOG_SEVERITY_LEVEL") != "info" {
-		grpclog.SetLoggerV2(grpclog.NewLoggerV2(io.Discard, logOut, logOut))
+		// Discard grpc info AND warning logs by default — the warning stream is
+		// dominated by benign connection-retry noise ("addrConn.createTransport
+		// failed", "transport is closing") that surfaces e.g. when the CLI dials
+		// a daemon that is still starting or already gone. Errors are kept. Set
+		// GRPC_GO_LOG_SEVERITY_LEVEL=info to get the full verbose grpc logging.
+		grpclog.SetLoggerV2(grpclog.NewLoggerV2(io.Discard, io.Discard, logOut))
 		return
 	}