[doc] Update Agent Network Readme (#6699)

* [client] Update gopsutil to v4 (#6688)
* [client] Fix hanging status command during relay dial (#6694)

---------

Co-authored-by: Maycon Santos <mlsmaycon@gmail.com>

agent-network/README.md

@@ -1,16 +1,47 @@
 # NetBird Agent Network
 
-Agent Network is NetBird's access control layer for AI agents and the people who run
-them. It gives every agent a real identity, tied to your identity provider (IdP), and
-governs what it can reach — the LLM APIs and AI gateways it can call, and the internal
-resources it can access. Traffic flows only over the encrypted NetBird tunnel, scoped by
-policy, with no API keys to leak.
+Agent Network is NetBird's access control layer for AI agents and the people who run them. 
+It gives every agent a real identity, tied to an identity provider (IdP), and governs what it can reach: LLM APIs and 
+AI gateways it can call, and the internal resources it can access. Traffic flows only over the encrypted NetBird tunnel, 
+scoped by policy, with no API keys or other credentials to leak. It also gives you control over cost and token usage.
 
-> **Beta.** Agent Network is open source and can be self-hosted on your own
-> infrastructure.
+Because every LLM request passes through an
+identity-aware proxy, you can:
+
+- **Set spending and rate limits** per agent, per user, or per team — with hard caps
+  that stop requests once a budget is reached.
+- **Restrict models and providers** so agents can only call approved (and cost-appropriate)
+  endpoints, keeping expensive models off-limits unless explicitly allowed.
+- **Attribute usage** by tracking token consumption and cost per identity, group, or cost center so every
+  request is tied back to the agent and person responsible.
+- **Reuse your existing AI gateway** — point the proxy at a gateway you already run,
+  keeping its routing and config in place while it adds identity on top, so you skip
+  API key distribution.
+
+https://github.com/user-attachments/assets/44d18286-d8ab-49f8-a457-98ccd66f3268
+
+> **Beta.** Agent Network is in beta, but it's stable and already running in
+> production environments. It's fully open source and can be self-hosted on your own
+> infrastructure, with no vendor lock-in and no data leaving your environment.
 
 ## How it works
 
+Say you have a simple use case: your Engineering or IT team needs access to Claude Code or Codex, and you want visibility into usage plus the ability to enforce budgets.
+How can you do that without creating a dedicated API key for every team?
+
+With Agent Network you get a private endpoint inside your network, for example: https://mirror.netbird.ai
+Teams configure their agents to point to that endpoint instead of using individual API keys directly. 
+
+This endpoint is only reachable when users are connected to your NetBird network and authenticated through your IdP. Otherwise, it is not accessible from the public internet.
+You can then use this private endpoint to configure your AI agents, whether that is Claude Code, Codex, or another tool.
+
+## Quickstart
+
+Full step-by-step setup:
+**https://docs.netbird.io/agent-network/quickstart**
+
+## Architecture 
+
 Agent Network is built on two existing NetBird capabilities:
 
 - **Overlay network** — the encrypted WireGuard mesh between peers.
@@ -22,6 +53,9 @@ LLM traffic is routed through the proxy's identity-aware pipeline, while interna
 resources (databases, internal APIs, self-hosted models) are reached directly over
 peer-to-peer WireGuard tunnels, governed by the same identities and access policies.
 
+<img width="4720" height="2218" alt="image" src="https://github.com/user-attachments/assets/1afa5da1-4b82-4f8a-a7a8-f417efadf1eb" />
+
+
 ## Where the code lives
 
 There is no separate "agent-network" service — it reuses the reverse-proxy and management

client/cmd/service.go

@@ -5,6 +5,7 @@ package cmd
 import (
 	"context"
 	"fmt"
+	"net/http"
 	"runtime"
 	"strings"
 	"sync"
@@ -22,15 +23,21 @@ var serviceCmd = &cobra.Command{
 	Short: "Manage the NetBird daemon service",
 }
 
+const defaultJSONSocket = "unix:///var/run/netbird-http.sock"
+
 var (
-	serviceName    string
-	serviceEnvVars []string
+	serviceName      string
+	serviceEnvVars   []string
+	jsonSocket       string
+	enableJSONSocket bool
 )
 
 type program struct {
 	ctx              context.Context
 	cancel           context.CancelFunc
 	serv             *grpc.Server
+	jsonServ         *http.Server
+	jsonServMu       sync.Mutex
 	serverInstance   *server.Server
 	serverInstanceMu sync.Mutex
 }
@@ -46,6 +53,8 @@ func init() {
 	serviceCmd.PersistentFlags().BoolVar(&updateSettingsDisabled, "disable-update-settings", false, "Disables update settings feature. If enabled, the client will not be able to change or edit any settings. To persist this setting, use: netbird service install --disable-update-settings")
 	serviceCmd.PersistentFlags().BoolVar(&captureEnabled, "enable-capture", false, "Enables packet capture via 'netbird debug capture'. To persist, use: netbird service install --enable-capture")
 	serviceCmd.PersistentFlags().BoolVar(&networksDisabled, "disable-networks", false, "Disables network selection. If enabled, the client will not allow listing, selecting, or deselecting networks. To persist, use: netbird service install --disable-networks")
+	serviceCmd.PersistentFlags().BoolVar(&enableJSONSocket, "enable-json-socket", false, "Enables the HTTP/JSON API socket served by grpc-gateway. To persist, use: netbird service install --enable-json-socket")
+	serviceCmd.PersistentFlags().StringVar(&jsonSocket, "json-socket", defaultJSONSocket, "HTTP/JSON API socket address [unix|tcp]://[path|host:port]. Requires --enable-json-socket to serve. To persist, use: netbird service install --enable-json-socket --json-socket")
 
 	rootCmd.PersistentFlags().StringVarP(&serviceName, "service", "s", defaultServiceName, "Netbird system service name")
 	serviceEnvDesc := `Sets extra environment variables for the service. ` +

client/cmd/service_controller.go

@@ -5,9 +5,6 @@ package cmd
 import (
 	"context"
 	"fmt"
-	"net"
-	"os"
-	"strings"
 	"time"
 
 	"github.com/kardianos/service"
@@ -22,41 +19,56 @@ import (
 	"github.com/netbirdio/netbird/util"
 )
 
+func validateJSONSocketFlags() error {
+	if serviceCmd.PersistentFlags().Changed("json-socket") && !enableJSONSocket {
+		return fmt.Errorf("--json-socket requires --enable-json-socket to configure the daemon JSON gateway")
+	}
+	return nil
+}
+
 func (p *program) Start(svc service.Service) error {
 	// Start should not block. Do the actual work async.
 	log.Info("starting NetBird service") //nolint
 
+	if err := validateJSONSocketFlags(); err != nil {
+		return err
+	}
+
 	// Collect static system and platform information
 	system.UpdateStaticInfoAsync()
 
 	// in any case, even if configuration does not exists we run daemon to serve CLI gRPC API.
 	p.serv = grpc.NewServer()
 
-	split := strings.Split(daemonAddr, "://")
-	switch split[0] {
-	case "unix":
-		// cleanup failed close
-		stat, err := os.Stat(split[1])
-		if err == nil && !stat.IsDir() {
-			if err := os.Remove(split[1]); err != nil {
-				log.Debugf("remove socket file: %v", err)
-			}
-		}
-	case "tcp":
-	default:
-		return fmt.Errorf("unsupported daemon address protocol: %v", split[0])
-	}
-
-	listen, err := net.Listen(split[0], split[1])
+	daemonListener, err := listenOnAddress(daemonAddr)
 	if err != nil {
 		return fmt.Errorf("listen daemon interface: %w", err)
 	}
-	go func() {
-		defer listen.Close()
 
-		if split[0] == "unix" {
-			if err := os.Chmod(split[1], 0666); err != nil {
-				log.Errorf("failed setting daemon permissions: %v", split[1])
+	var jsonListener *socketListener
+	if enableJSONSocket {
+		jsonListener, err = listenOnAddress(jsonSocket)
+		if err != nil {
+			_ = daemonListener.Close()
+			return fmt.Errorf("listen daemon JSON interface: %w", err)
+		}
+	} else {
+		removeStaleUnixSocketForAddress(jsonSocket)
+	}
+
+	go func() {
+		defer daemonListener.Close()
+		if jsonListener != nil {
+			defer jsonListener.Close()
+		}
+
+		if err := daemonListener.chmodUnixSocket("daemon"); err != nil {
+			log.Error(err)
+			return
+		}
+		if jsonListener != nil {
+			if err := jsonListener.chmodUnixSocket("daemon JSON"); err != nil {
+				log.Error(err)
 				return
 			}
 		}
@@ -71,8 +83,16 @@ func (p *program) Start(svc service.Service) error {
 		p.serverInstance = serverInstance
 		p.serverInstanceMu.Unlock()
 
-		log.Printf("started daemon server: %v", split[1])
-		if err := p.serv.Serve(listen); err != nil {
+		if jsonListener != nil {
+			if err := p.startJSONGateway(jsonListener, daemonAddr); err != nil {
+				log.Fatalf("failed to start daemon JSON server: %v", err)
+			}
+		} else {
+			log.Debug("daemon JSON socket disabled")
+		}
+
+		log.Printf("started daemon server: %v", daemonListener.address)
+		if err := p.serv.Serve(daemonListener.Listener); err != nil {
 			log.Errorf("failed to serve daemon requests: %v", err)
 		}
 	}()
@@ -92,6 +112,20 @@ func (p *program) Stop(srv service.Service) error {
 
 	p.cancel()
 
+	p.jsonServMu.Lock()
+	jsonServ := p.jsonServ
+	p.jsonServMu.Unlock()
+	if jsonServ != nil {
+		shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 2*time.Second)
+		if err := jsonServ.Shutdown(shutdownCtx); err != nil {
+			log.Errorf("failed to stop daemon JSON server gracefully: %v", err)
+			if err := jsonServ.Close(); err != nil {
+				log.Errorf("failed to close daemon JSON server: %v", err)
+			}
+		}
+		shutdownCancel()
+	}
+
 	if p.serv != nil {
 		p.serv.Stop()
 	}
@@ -148,6 +182,9 @@ var runCmd = &cobra.Command{
 		if err != nil {
 			return err
 		}
+		if err := validateJSONSocketFlags(); err != nil {
+			return err
+		}
 
 		return s.Run()
 	},
@@ -162,6 +199,9 @@ var startCmd = &cobra.Command{
 		if err != nil {
 			return err
 		}
+		if err := validateJSONSocketFlags(); err != nil {
+			return err
+		}
 
 		if err := s.Start(); err != nil {
 			return fmt.Errorf("start service: %w", err)
@@ -198,6 +238,9 @@ var restartCmd = &cobra.Command{
 		if err != nil {
 			return err
 		}
+		if err := validateJSONSocketFlags(); err != nil {
+			return err
+		}
 
 		if err := s.Restart(); err != nil {
 			return fmt.Errorf("restart service: %w", err)

client/cmd/service_installer.go

@@ -67,6 +67,10 @@ func buildServiceArguments() []string {
 		args = append(args, "--disable-networks")
 	}
 
+	if enableJSONSocket {
+		args = append(args, "--enable-json-socket", "--json-socket", jsonSocket)
+	}
+
 	return args
 }
 
@@ -106,6 +110,10 @@ func configurePlatformSpecificSettings(svcConfig *service.Config) error {
 
 // Create fully configured service config for install/reconfigure
 func createServiceConfigForInstall() (*service.Config, error) {
+	if err := validateJSONSocketFlags(); err != nil {
+		return nil, err
+	}
+
 	svcConfig, err := newSVCConfig()
 	if err != nil {
 		return nil, fmt.Errorf("create service config: %w", err)

client/cmd/service_json_gateway.go

@@ -0,0 +1,52 @@
+//go:build !ios && !android
+
+package cmd
+
+import (
+	"context"
+	"errors"
+	"net"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/grpc-ecosystem/grpc-gateway/v2/runtime"
+	log "github.com/sirupsen/logrus"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/credentials/insecure"
+
+	"github.com/netbirdio/netbird/client/proto"
+)
+
+func grpcGatewayEndpoint(addr string) string {
+	return strings.TrimPrefix(addr, "tcp://")
+}
+
+func (p *program) startJSONGateway(jsonListener *socketListener, daemonEndpoint string) error {
+	mux := runtime.NewServeMux()
+	opts := []grpc.DialOption{grpc.WithTransportCredentials(insecure.NewCredentials())}
+	if err := proto.RegisterDaemonServiceHandlerFromEndpoint(p.ctx, mux, grpcGatewayEndpoint(daemonEndpoint), opts); err != nil {
+		return err
+	}
+
+	jsonServer := &http.Server{
+		Handler:           mux,
+		ReadHeaderTimeout: 5 * time.Second,
+		BaseContext: func(net.Listener) context.Context {
+			return p.ctx
+		},
+	}
+
+	p.jsonServMu.Lock()
+	p.jsonServ = jsonServer
+	p.jsonServMu.Unlock()
+
+	go func() {
+		log.Printf("started daemon JSON server: %v", jsonListener.address)
+		if err := jsonServer.Serve(jsonListener.Listener); err != nil && !errors.Is(err, http.ErrServerClosed) {
+			log.Errorf("failed to serve daemon JSON requests: %v", err)
+		}
+	}()
+
+	return nil
+}

client/cmd/service_json_socket_test.go

@@ -0,0 +1,176 @@
+//go:build !ios && !android
+
+package cmd
+
+import (
+	"net"
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func preserveJSONSocketTestState(t *testing.T) {
+	t.Helper()
+
+	origJSONSocket := jsonSocket
+	origEnableJSONSocket := enableJSONSocket
+	origChanged := map[string]bool{}
+	serviceCmd.PersistentFlags().VisitAll(func(flag *pflag.Flag) {
+		origChanged[flag.Name] = flag.Changed
+	})
+
+	t.Cleanup(func() {
+		jsonSocket = origJSONSocket
+		enableJSONSocket = origEnableJSONSocket
+		serviceCmd.PersistentFlags().VisitAll(func(flag *pflag.Flag) {
+			flag.Changed = origChanged[flag.Name]
+		})
+	})
+}
+
+func TestJSONSocketFlagsArePositiveEnableOnly(t *testing.T) {
+	assert.NotNil(t, serviceCmd.PersistentFlags().Lookup("enable-json-socket"))
+	assert.NotNil(t, serviceCmd.PersistentFlags().Lookup("json-socket"))
+	assert.Nil(t, serviceCmd.PersistentFlags().Lookup("disable-json-socket"))
+	assert.Equal(t, "false", serviceCmd.PersistentFlags().Lookup("enable-json-socket").DefValue)
+}
+
+func TestBuildServiceArgumentsDefaultDisablesJSONSocket(t *testing.T) {
+	preserveJSONSocketTestState(t)
+
+	enableJSONSocket = false
+	jsonSocket = "tcp://127.0.0.1:8080"
+
+	args := buildServiceArguments()
+
+	assert.NotContains(t, args, "--enable-json-socket")
+	assert.NotContains(t, args, "--json-socket")
+}
+
+func TestBuildServiceArgumentsIncludesJSONSocketWhenEnabled(t *testing.T) {
+	preserveJSONSocketTestState(t)
+
+	enableJSONSocket = true
+	jsonSocket = "tcp://127.0.0.1:8080"
+
+	args := buildServiceArguments()
+
+	enableIndex := indexOfArg(args, "--enable-json-socket")
+	jsonIndex := indexOfArg(args, "--json-socket")
+	require.NotEqual(t, -1, enableIndex)
+	require.NotEqual(t, -1, jsonIndex)
+	require.Less(t, enableIndex, jsonIndex)
+	require.Less(t, jsonIndex+1, len(args))
+	assert.Equal(t, "tcp://127.0.0.1:8080", args[jsonIndex+1])
+}
+
+func TestJSONSocketWithoutEnableValidation(t *testing.T) {
+	preserveJSONSocketTestState(t)
+
+	enableJSONSocket = false
+	require.NoError(t, serviceCmd.PersistentFlags().Set("json-socket", "tcp://127.0.0.1:8080"))
+
+	err := validateJSONSocketFlags()
+
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "--enable-json-socket")
+}
+
+func TestJSONSocketWithEnableValidation(t *testing.T) {
+	preserveJSONSocketTestState(t)
+
+	require.NoError(t, serviceCmd.PersistentFlags().Set("enable-json-socket", "true"))
+	require.NoError(t, serviceCmd.PersistentFlags().Set("json-socket", "tcp://127.0.0.1:8080"))
+
+	assert.NoError(t, validateJSONSocketFlags())
+}
+
+func TestJSONSocketServiceParamsPersistEnableAndAddress(t *testing.T) {
+	preserveJSONSocketTestState(t)
+	serviceCmd.PersistentFlags().VisitAll(func(flag *pflag.Flag) {
+		flag.Changed = false
+	})
+
+	enableJSONSocket = true
+	jsonSocket = "tcp://127.0.0.1:8080"
+
+	params := currentServiceParams()
+	require.True(t, params.EnableJSONSocket)
+	require.Equal(t, "tcp://127.0.0.1:8080", params.JSONSocket)
+
+	enableJSONSocket = false
+	jsonSocket = defaultJSONSocket
+	applyServiceParams(testServiceEnvCommand(), params)
+
+	assert.True(t, enableJSONSocket)
+	assert.Equal(t, "tcp://127.0.0.1:8080", jsonSocket)
+}
+
+func TestRemoveStaleUnixSocketDoesNotRemoveRegularFile(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "netbird-http.sock")
+	require.NoError(t, os.WriteFile(path, []byte("not a socket"), 0600))
+
+	removeStaleUnixSocket(path)
+
+	data, err := os.ReadFile(path)
+	require.NoError(t, err)
+	assert.Equal(t, []byte("not a socket"), data)
+}
+
+func TestRemoveStaleUnixSocketRemovesSocket(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("unix sockets are not available on Windows")
+	}
+
+	path := filepath.Join(t.TempDir(), "netbird-http.sock")
+	addr := &net.UnixAddr{Name: path, Net: "unix"}
+	listener, err := net.ListenUnix("unix", addr)
+	require.NoError(t, err)
+	listener.SetUnlinkOnClose(false)
+	require.NoError(t, listener.Close())
+
+	_, err = os.Lstat(path)
+	require.NoError(t, err, "test setup must leave a stale Unix socket path")
+
+	removeStaleUnixSocket(path)
+
+	_, err = os.Lstat(path)
+	assert.True(t, os.IsNotExist(err), "expected stale Unix socket to be removed, got %v", err)
+}
+
+func TestRemoveStaleUnixSocketDoesNotRemoveLiveSocket(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("unix sockets are not available on Windows")
+	}
+
+	path := filepath.Join(t.TempDir(), "netbird-http.sock")
+	listener, err := net.Listen("unix", path)
+	require.NoError(t, err)
+	defer listener.Close()
+
+	removeStaleUnixSocket(path)
+
+	_, err = os.Lstat(path)
+	assert.NoError(t, err, "expected live Unix socket to be preserved")
+}
+
+func testServiceEnvCommand() *cobra.Command {
+	cmd := &cobra.Command{}
+	cmd.Flags().StringSlice("service-env", nil, "")
+	return cmd
+}
+
+func indexOfArg(args []string, arg string) int {
+	for i, candidate := range args {
+		if candidate == arg {
+			return i
+		}
+	}
+	return -1
+}

client/cmd/service_params.go

@@ -23,6 +23,7 @@ const serviceParamsFile = "service.json"
 type serviceParams struct {
 	LogLevel              string            `json:"log_level"`
 	DaemonAddr            string            `json:"daemon_addr"`
+	JSONSocket            string            `json:"json_socket"`
 	ManagementURL         string            `json:"management_url,omitempty"`
 	ConfigPath            string            `json:"config_path,omitempty"`
 	LogFiles              []string          `json:"log_files,omitempty"`
@@ -30,6 +31,7 @@ type serviceParams struct {
 	DisableUpdateSettings bool              `json:"disable_update_settings,omitempty"`
 	EnableCapture         bool              `json:"enable_capture,omitempty"`
 	DisableNetworks       bool              `json:"disable_networks,omitempty"`
+	EnableJSONSocket      bool              `json:"enable_json_socket,omitempty"`
 	ServiceEnvVars        map[string]string `json:"service_env_vars,omitempty"`
 }
 
@@ -75,6 +77,7 @@ func currentServiceParams() *serviceParams {
 	params := &serviceParams{
 		LogLevel:              logLevel,
 		DaemonAddr:            daemonAddr,
+		JSONSocket:            jsonSocket,
 		ManagementURL:         managementURL,
 		ConfigPath:            configPath,
 		LogFiles:              logFiles,
@@ -82,6 +85,7 @@ func currentServiceParams() *serviceParams {
 		DisableUpdateSettings: updateSettingsDisabled,
 		EnableCapture:         captureEnabled,
 		DisableNetworks:       networksDisabled,
+		EnableJSONSocket:      enableJSONSocket,
 	}
 
 	if len(serviceEnvVars) > 0 {
@@ -113,9 +117,8 @@ func applyServiceParams(cmd *cobra.Command, params *serviceParams) {
 		return
 	}
 
-	// For fields with non-empty defaults (log-level, daemon-addr), keep the
-	// != "" guard so that an older service.json missing the field doesn't
-	// clobber the default with an empty string.
+	// For fields with non-empty defaults, keep the != "" guard so that an older
+	// service.json missing the field doesn't clobber the default with an empty string.
 	if !rootCmd.PersistentFlags().Changed("log-level") && params.LogLevel != "" {
 		logLevel = params.LogLevel
 	}
@@ -124,6 +127,14 @@ func applyServiceParams(cmd *cobra.Command, params *serviceParams) {
 		daemonAddr = params.DaemonAddr
 	}
 
+	if !serviceCmd.PersistentFlags().Changed("json-socket") && params.JSONSocket != "" {
+		jsonSocket = params.JSONSocket
+	}
+
+	if !serviceCmd.PersistentFlags().Changed("enable-json-socket") {
+		enableJSONSocket = params.EnableJSONSocket
+	}
+
 	// For optional fields where empty means "use default", always apply so
 	// that an explicit clear (--management-url "") persists across reinstalls.
 	if !rootCmd.PersistentFlags().Changed("management-url") {

client/cmd/service_params_test.go

@@ -41,6 +41,8 @@ func TestSaveAndLoadServiceParams(t *testing.T) {
 	params := &serviceParams{
 		LogLevel:              "debug",
 		DaemonAddr:            "unix:///var/run/netbird.sock",
+		JSONSocket:            "tcp://127.0.0.1:8080",
+		EnableJSONSocket:      true,
 		ManagementURL:         "https://my.server.com",
 		ConfigPath:            "/etc/netbird/config.json",
 		LogFiles:              []string{"/var/log/netbird/client.log", "console"},
@@ -63,6 +65,8 @@ func TestSaveAndLoadServiceParams(t *testing.T) {
 
 	assert.Equal(t, params.LogLevel, loaded.LogLevel)
 	assert.Equal(t, params.DaemonAddr, loaded.DaemonAddr)
+	assert.Equal(t, params.JSONSocket, loaded.JSONSocket)
+	assert.Equal(t, params.EnableJSONSocket, loaded.EnableJSONSocket)
 	assert.Equal(t, params.ManagementURL, loaded.ManagementURL)
 	assert.Equal(t, params.ConfigPath, loaded.ConfigPath)
 	assert.Equal(t, params.LogFiles, loaded.LogFiles)
@@ -101,6 +105,8 @@ func TestLoadServiceParams_InvalidJSON(t *testing.T) {
 func TestCurrentServiceParams(t *testing.T) {
 	origLogLevel := logLevel
 	origDaemonAddr := daemonAddr
+	origJSONSocket := jsonSocket
+	origEnableJSONSocket := enableJSONSocket
 	origManagementURL := managementURL
 	origConfigPath := configPath
 	origLogFiles := logFiles
@@ -110,6 +116,8 @@ func TestCurrentServiceParams(t *testing.T) {
 	t.Cleanup(func() {
 		logLevel = origLogLevel
 		daemonAddr = origDaemonAddr
+		jsonSocket = origJSONSocket
+		enableJSONSocket = origEnableJSONSocket
 		managementURL = origManagementURL
 		configPath = origConfigPath
 		logFiles = origLogFiles
@@ -120,6 +128,8 @@ func TestCurrentServiceParams(t *testing.T) {
 
 	logLevel = "trace"
 	daemonAddr = "tcp://127.0.0.1:9999"
+	jsonSocket = "tcp://127.0.0.1:8080"
+	enableJSONSocket = true
 	managementURL = "https://mgmt.example.com"
 	configPath = "/tmp/test-config.json"
 	logFiles = []string{"/tmp/test.log"}
@@ -131,6 +141,8 @@ func TestCurrentServiceParams(t *testing.T) {
 
 	assert.Equal(t, "trace", params.LogLevel)
 	assert.Equal(t, "tcp://127.0.0.1:9999", params.DaemonAddr)
+	assert.Equal(t, "tcp://127.0.0.1:8080", params.JSONSocket)
+	assert.True(t, params.EnableJSONSocket)
 	assert.Equal(t, "https://mgmt.example.com", params.ManagementURL)
 	assert.Equal(t, "/tmp/test-config.json", params.ConfigPath)
 	assert.Equal(t, []string{"/tmp/test.log"}, params.LogFiles)
@@ -142,6 +154,8 @@ func TestCurrentServiceParams(t *testing.T) {
 func TestApplyServiceParams_OnlyUnchangedFlags(t *testing.T) {
 	origLogLevel := logLevel
 	origDaemonAddr := daemonAddr
+	origJSONSocket := jsonSocket
+	origEnableJSONSocket := enableJSONSocket
 	origManagementURL := managementURL
 	origConfigPath := configPath
 	origLogFiles := logFiles
@@ -151,6 +165,8 @@ func TestApplyServiceParams_OnlyUnchangedFlags(t *testing.T) {
 	t.Cleanup(func() {
 		logLevel = origLogLevel
 		daemonAddr = origDaemonAddr
+		jsonSocket = origJSONSocket
+		enableJSONSocket = origEnableJSONSocket
 		managementURL = origManagementURL
 		configPath = origConfigPath
 		logFiles = origLogFiles
@@ -162,6 +178,8 @@ func TestApplyServiceParams_OnlyUnchangedFlags(t *testing.T) {
 	// Reset all flags to defaults.
 	logLevel = "info"
 	daemonAddr = "unix:///var/run/netbird.sock"
+	jsonSocket = defaultJSONSocket
+	enableJSONSocket = false
 	managementURL = ""
 	configPath = "/etc/netbird/config.json"
 	logFiles = []string{"/var/log/netbird/client.log"}
@@ -184,6 +202,8 @@ func TestApplyServiceParams_OnlyUnchangedFlags(t *testing.T) {
 	saved := &serviceParams{
 		LogLevel:              "debug",
 		DaemonAddr:            "tcp://127.0.0.1:5555",
+		JSONSocket:            "tcp://127.0.0.1:8080",
+		EnableJSONSocket:      true,
 		ManagementURL:         "https://saved.example.com",
 		ConfigPath:            "/saved/config.json",
 		LogFiles:              []string{"/saved/client.log"},
@@ -201,6 +221,8 @@ func TestApplyServiceParams_OnlyUnchangedFlags(t *testing.T) {
 
 	// All other fields were not Changed, so they should use saved values.
 	assert.Equal(t, "tcp://127.0.0.1:5555", daemonAddr)
+	assert.Equal(t, "tcp://127.0.0.1:8080", jsonSocket)
+	assert.True(t, enableJSONSocket)
 	assert.Equal(t, "https://saved.example.com", managementURL)
 	assert.Equal(t, "/saved/config.json", configPath)
 	assert.Equal(t, []string{"/saved/client.log"}, logFiles)
@@ -212,14 +234,17 @@ func TestApplyServiceParams_OnlyUnchangedFlags(t *testing.T) {
 func TestApplyServiceParams_BooleanRevertToFalse(t *testing.T) {
 	origProfilesDisabled := profilesDisabled
 	origUpdateSettingsDisabled := updateSettingsDisabled
+	origEnableJSONSocket := enableJSONSocket
 	t.Cleanup(func() {
 		profilesDisabled = origProfilesDisabled
 		updateSettingsDisabled = origUpdateSettingsDisabled
+		enableJSONSocket = origEnableJSONSocket
 	})
 
 	// Simulate current state where booleans are true (e.g. set by previous install).
 	profilesDisabled = true
 	updateSettingsDisabled = true
+	enableJSONSocket = true
 
 	// Reset Changed state so flags appear unset.
 	serviceCmd.PersistentFlags().VisitAll(func(f *pflag.Flag) {
@@ -238,6 +263,7 @@ func TestApplyServiceParams_BooleanRevertToFalse(t *testing.T) {
 
 	assert.False(t, profilesDisabled, "saved false should override current true")
 	assert.False(t, updateSettingsDisabled, "saved false should override current true")
+	assert.False(t, enableJSONSocket, "saved false should override current true")
 }
 
 func TestApplyServiceParams_ClearManagementURL(t *testing.T) {
@@ -530,6 +556,7 @@ func fieldToGlobalVar(field string) string {
 	m := map[string]string{
 		"LogLevel":              "logLevel",
 		"DaemonAddr":            "daemonAddr",
+		"JSONSocket":            "jsonSocket",
 		"ManagementURL":         "managementURL",
 		"ConfigPath":            "configPath",
 		"LogFiles":              "logFiles",
@@ -537,6 +564,7 @@ func fieldToGlobalVar(field string) string {
 		"DisableUpdateSettings": "updateSettingsDisabled",
 		"EnableCapture":         "captureEnabled",
 		"DisableNetworks":       "networksDisabled",
+		"EnableJSONSocket":      "enableJSONSocket",
 		"ServiceEnvVars":        "serviceEnvVars",
 	}
 	if v, ok := m[field]; ok {

client/cmd/service_socket.go

@@ -0,0 +1,111 @@
+//go:build !ios && !android
+
+package cmd
+
+import (
+	"errors"
+	"fmt"
+	"net"
+	"os"
+	"strings"
+	"syscall"
+	"time"
+
+	log "github.com/sirupsen/logrus"
+)
+
+type socketListener struct {
+	net.Listener
+	network string
+	address string
+}
+
+func listenOnAddress(addr string) (*socketListener, error) {
+	network, address, err := parseListenAddress(addr)
+	if err != nil {
+		return nil, err
+	}
+
+	if network == "unix" {
+		removeStaleUnixSocket(address)
+	}
+
+	listener, err := net.Listen(network, address)
+	if err != nil {
+		return nil, err
+	}
+
+	return &socketListener{Listener: listener, network: network, address: address}, nil
+}
+
+func parseListenAddress(addr string) (string, string, error) {
+	network, address, ok := strings.Cut(addr, "://")
+	if !ok || network == "" || address == "" {
+		return "", "", fmt.Errorf("address must be in [unix|tcp]://[path|host:port] format: %q", addr)
+	}
+
+	switch network {
+	case "unix", "tcp":
+		return network, address, nil
+	default:
+		return "", "", fmt.Errorf("unsupported daemon address protocol: %v", network)
+	}
+}
+
+func removeStaleUnixSocket(path string) {
+	stat, err := os.Lstat(path)
+	if err != nil {
+		if !os.IsNotExist(err) {
+			log.Debugf("stat socket file: %v", err)
+		}
+		return
+	}
+
+	if stat.Mode()&os.ModeSocket == 0 {
+		return
+	}
+
+	if !isStaleUnixSocket(path) {
+		return
+	}
+
+	if err := os.Remove(path); err != nil {
+		log.Debugf("remove socket file: %v", err)
+	}
+}
+
+func isStaleUnixSocket(path string) bool {
+	conn, err := net.DialTimeout("unix", path, 100*time.Millisecond)
+	if err == nil {
+		if closeErr := conn.Close(); closeErr != nil {
+			log.Debugf("close unix socket probe: %v", closeErr)
+		}
+		return false
+	}
+
+	if os.IsNotExist(err) || os.IsPermission(err) || os.IsTimeout(err) {
+		log.Debugf("not removing unix socket %s after probe error: %v", path, err)
+		return false
+	}
+
+	return errors.Is(err, syscall.ECONNREFUSED)
+}
+
+func removeStaleUnixSocketForAddress(addr string) {
+	network, address, err := parseListenAddress(addr)
+	if err != nil || network != "unix" {
+		return
+	}
+	removeStaleUnixSocket(address)
+}
+
+func (l *socketListener) chmodUnixSocket(description string) error {
+	if l == nil || l.network != "unix" {
+		return nil
+	}
+
+	if err := os.Chmod(l.address, 0666); err != nil {
+		return fmt.Errorf("failed setting %s permissions for %s: %w", description, l.address, err)
+	}
+	return nil
+}

client/proto/daemon_gateway_test.go

@@ -0,0 +1,80 @@
+package proto
+
+import (
+	"context"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	gatewayruntime "github.com/grpc-ecosystem/grpc-gateway/v2/runtime"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/credentials/insecure"
+	"google.golang.org/grpc/test/bufconn"
+)
+
+func TestGatewayServerRoutesCoverDaemonRPCs(t *testing.T) {
+	mux := gatewayruntime.NewServeMux()
+	if err := RegisterDaemonServiceHandlerServer(context.Background(), mux, UnimplementedDaemonServiceServer{}); err != nil {
+		t.Fatalf("register daemon gateway server handlers: %v", err)
+	}
+
+	assertAllDaemonGatewayRoutesRegistered(t, mux)
+}
+
+func TestGatewayClientRoutesCoverDaemonRPCs(t *testing.T) {
+	listener := bufconn.Listen(1024 * 1024)
+	server := grpc.NewServer()
+	RegisterDaemonServiceServer(server, UnimplementedDaemonServiceServer{})
+	go func() {
+		if err := server.Serve(listener); err != nil && err != grpc.ErrServerStopped {
+			t.Errorf("serve bufconn gRPC server: %v", err)
+		}
+	}()
+	t.Cleanup(func() {
+		server.Stop()
+		_ = listener.Close()
+	})
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	mux := gatewayruntime.NewServeMux()
+	opts := []grpc.DialOption{
+		grpc.WithContextDialer(func(context.Context, string) (net.Conn, error) {
+			return listener.Dial()
+		}),
+		grpc.WithTransportCredentials(insecure.NewCredentials()),
+	}
+	if err := RegisterDaemonServiceHandlerFromEndpoint(ctx, mux, "passthrough:///bufnet", opts); err != nil {
+		t.Fatalf("register daemon gateway client handlers: %v", err)
+	}
+
+	assertAllDaemonGatewayRoutesRegistered(t, mux)
+}
+
+func assertAllDaemonGatewayRoutesRegistered(t *testing.T, mux http.Handler) {
+	t.Helper()
+	for _, method := range DaemonService_ServiceDesc.Methods {
+		assertGatewayRouteRegistered(t, mux, method.MethodName)
+	}
+	for _, stream := range DaemonService_ServiceDesc.Streams {
+		assertGatewayRouteRegistered(t, mux, stream.StreamName)
+	}
+}
+
+func assertGatewayRouteRegistered(t *testing.T, mux http.Handler, methodName string) {
+	t.Helper()
+
+	path := "/daemon.DaemonService/" + methodName
+	req := httptest.NewRequest(http.MethodPost, path, strings.NewReader("{}"))
+	req.Header.Set("Content-Type", "application/json")
+	res := httptest.NewRecorder()
+
+	mux.ServeHTTP(res, req)
+
+	if res.Code == http.StatusNotFound {
+		t.Fatalf("gateway route for %s is not registered", methodName)
+	}
+}

client/proto/generate.sh

@@ -12,5 +12,11 @@ script_path=$(dirname "$(realpath "$0")")
 cd "$script_path"
 go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.36.6
 go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.6.1
-protoc -I ./ ./daemon.proto --go_out=../ --go-grpc_out=../ --experimental_allow_proto3_optional
+go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway@v2.26.3
+protoc -I ./ ./daemon.proto \
+  --go_out=../ \
+  --go-grpc_out=../ \
+  --grpc-gateway_out=../ \
+  --grpc-gateway_opt=generate_unbound_methods=true \
+  --experimental_allow_proto3_optional
 cd "$old_pwd"

client/system/process.go

@@ -7,7 +7,7 @@ import (
 	"os"
 	"slices"
 
-	"github.com/shirou/gopsutil/v3/process"
+	"github.com/shirou/gopsutil/v4/process"
 )
 
 // getRunningProcesses returns a list of running process paths. The context bounds the work:

client/system/process_test.go

@@ -4,7 +4,7 @@ import (
 	"context"
 	"testing"
 
-	"github.com/shirou/gopsutil/v3/process"
+	"github.com/shirou/gopsutil/v4/process"
 )
 
 func Benchmark_getRunningProcesses(b *testing.B) {

client/test/json-socket-docker.sh

@@ -0,0 +1,223 @@
+#!/usr/bin/env bash
+set -eEuo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: client/test/json-socket-docker.sh [tcp|unix|both]
+
+Builds the NetBird client Docker image from the local source tree, starts
+`netbird service run` in a container with --enable-json-socket, and verifies
+that the HTTP/JSON daemon gateway responds to Status requests.
+
+Modes:
+  tcp   Validate tcp://0.0.0.0:8080 via a published localhost port (default)
+  unix  Validate unix:///sock/netbird-http.sock via a bind-mounted socket dir
+  both  Run both validations
+
+Environment:
+  CONTAINER_RUNTIME  docker or podman. Auto-detected if unset.
+  IMAGE              Image tag to build. Default: netbird-json-socket-test:local
+  TARGETARCH         Go/Docker target arch. Default: `go env GOARCH`
+  PLATFORM           Docker platform. Default: linux/$TARGETARCH
+  WAIT_TIMEOUT       Seconds to wait for the JSON socket. Default: 30
+EOF
+}
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+MODE="${1:-tcp}"
+case "${MODE}" in
+  tcp|unix|both) ;;
+  *)
+    usage >&2
+    echo "invalid mode: ${MODE}" >&2
+    exit 2
+    ;;
+esac
+
+RUNTIME="${CONTAINER_RUNTIME:-}"
+if [[ -z "${RUNTIME}" ]]; then
+  if command -v docker >/dev/null 2>&1; then
+    RUNTIME=docker
+  elif command -v podman >/dev/null 2>&1; then
+    RUNTIME=podman
+  else
+    echo "docker or podman is required" >&2
+    exit 127
+  fi
+fi
+if ! command -v "${RUNTIME}" >/dev/null 2>&1; then
+  echo "container runtime not found: ${RUNTIME}" >&2
+  exit 127
+fi
+
+if ! command -v curl >/dev/null 2>&1; then
+  echo "curl is required" >&2
+  exit 127
+fi
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+IMAGE="${IMAGE:-netbird-json-socket-test:local}"
+TARGETARCH="${TARGETARCH:-$(go env GOARCH)}"
+PLATFORM="${PLATFORM:-linux/${TARGETARCH}}"
+WAIT_TIMEOUT="${WAIT_TIMEOUT:-30}"
+TMP_DIR="$(mktemp -d)"
+CONTAINERS=()
+
+cleanup() {
+  local status=$?
+  for container in "${CONTAINERS[@]:-}"; do
+    "${RUNTIME}" rm -f "${container}" >/dev/null 2>&1 || true
+  done
+  rm -rf "${TMP_DIR}"
+  exit "${status}"
+}
+trap cleanup EXIT
+
+build_image() {
+  echo "==> Building Linux ${TARGETARCH} netbird binary"
+  mkdir -p "${TMP_DIR}/context/client"
+  cp "${ROOT_DIR}/client/Dockerfile" "${TMP_DIR}/context/Dockerfile"
+  cp "${ROOT_DIR}/client/netbird-entrypoint.sh" "${TMP_DIR}/context/client/netbird-entrypoint.sh"
+
+  (cd "${ROOT_DIR}" && CGO_ENABLED=0 GOOS=linux GOARCH="${TARGETARCH}" go build -o "${TMP_DIR}/context/netbird" ./client)
+
+  echo "==> Building ${IMAGE} for ${PLATFORM}"
+  "${RUNTIME}" build \
+    --platform "${PLATFORM}" \
+    --build-arg NETBIRD_BINARY=netbird \
+    -t "${IMAGE}" \
+    -f "${TMP_DIR}/context/Dockerfile" \
+    "${TMP_DIR}/context"
+}
+
+pick_port() {
+  python3 - <<'PY'
+import socket
+sock = socket.socket()
+sock.bind(("127.0.0.1", 0))
+print(sock.getsockname()[1])
+sock.close()
+PY
+}
+
+assert_status_json() {
+  local response_file="$1"
+  if command -v python3 >/dev/null 2>&1; then
+    python3 - "${response_file}" <<'PY'
+import json
+import sys
+with open(sys.argv[1], encoding="utf-8") as fh:
+    data = json.load(fh)
+if not data.get("status"):
+    raise SystemExit("missing non-empty status field")
+if "daemonVersion" not in data:
+    raise SystemExit("missing daemonVersion field")
+print(f"status={data['status']} daemonVersion={data['daemonVersion']}")
+PY
+  else
+    grep -q '"status"' "${response_file}"
+    grep -q '"daemonVersion"' "${response_file}"
+    cat "${response_file}"
+  fi
+}
+
+container_logs() {
+  local container="$1"
+  echo "---- ${container} logs ----" >&2
+  "${RUNTIME}" logs "${container}" >&2 || true
+  echo "--------------------------" >&2
+}
+
+wait_for_http_status() {
+  local container="$1"
+  local response="${TMP_DIR}/${container}.json"
+  local curl_err="${TMP_DIR}/${container}.curl.err"
+  shift
+  local deadline=$((SECONDS + WAIT_TIMEOUT))
+
+  while (( SECONDS < deadline )); do
+    if curl -fsS "$@" \
+      -X POST \
+      -H 'Content-Type: application/json' \
+      -d '{}' \
+      -o "${response}" \
+      2>"${curl_err}"; then
+      assert_status_json "${response}"
+      return 0
+    fi
+
+    if ! "${RUNTIME}" ps --format '{{.Names}}' | grep -Fxq "${container}"; then
+      echo "container exited before JSON socket became ready" >&2
+      container_logs "${container}"
+      return 1
+    fi
+    sleep 1
+  done
+
+  echo "timed out waiting for JSON socket after ${WAIT_TIMEOUT}s" >&2
+  cat "${curl_err}" >&2 || true
+  container_logs "${container}"
+  return 1
+}
+
+run_netbird_container() {
+  local container="$1"
+  local json_socket="$2"
+  shift 2
+
+  CONTAINERS+=("${container}")
+  "${RUNTIME}" run --rm -d \
+    --name "${container}" \
+    -e NB_STATE_DIR=/tmp/netbird-state \
+    --entrypoint /usr/local/bin/netbird \
+    "$@" \
+    "${IMAGE}" \
+    --log-file console \
+    --daemon-addr unix:///tmp/netbird.sock \
+    service run \
+    --enable-json-socket \
+    --json-socket "${json_socket}" >/dev/null
+}
+
+run_tcp_test() {
+  local port container
+  port="$(pick_port)"
+  container="nb-json-socket-tcp-$RANDOM-$RANDOM"
+
+  echo "==> Validating TCP JSON socket on 127.0.0.1:${port}"
+  run_netbird_container "${container}" "tcp://0.0.0.0:8080" -p "127.0.0.1:${port}:8080"
+  wait_for_http_status "${container}" "http://127.0.0.1:${port}/daemon.DaemonService/Status"
+}
+
+run_unix_test() {
+  local sock_dir sock_path container
+  sock_dir="${TMP_DIR}/sock"
+  sock_path="${sock_dir}/netbird-http.sock"
+  container="nb-json-socket-unix-$RANDOM-$RANDOM"
+  mkdir -p "${sock_dir}"
+
+  echo "==> Validating Unix JSON socket at ${sock_path}"
+  run_netbird_container "${container}" "unix:///sock/netbird-http.sock" -v "${sock_dir}:/sock"
+  wait_for_http_status "${container}" --unix-socket "${sock_path}" "http://unix/daemon.DaemonService/Status"
+}
+
+build_image
+
+case "${MODE}" in
+  tcp)
+    run_tcp_test
+    ;;
+  unix)
+    run_unix_test
+    ;;
+  both)
+    run_tcp_test
+    run_unix_test
+    ;;
+esac
+
+echo "==> Docker JSON socket validation passed (${MODE})"

go.mod

@@ -66,6 +66,7 @@ require (
 	github.com/google/nftables v0.3.0
 	github.com/gopacket/gopacket v1.4.0
 	github.com/grpc-ecosystem/go-grpc-middleware/v2 v2.0.2-0.20240212192251-757544f21357
+	github.com/grpc-ecosystem/grpc-gateway/v2 v2.26.3
 	github.com/hashicorp/go-multierror v1.1.1
 	github.com/hashicorp/go-secure-stdlib/base62 v0.1.2
 	github.com/hashicorp/go-version v1.7.0
@@ -100,7 +101,7 @@ require (
 	github.com/quic-go/quic-go v0.55.0
 	github.com/redis/go-redis/v9 v9.7.3
 	github.com/rs/xid v1.3.0
-	github.com/shirou/gopsutil/v3 v3.24.4
+	github.com/shirou/gopsutil/v4 v4.25.8
 	github.com/skratchdot/open-golang v0.0.0-20200116055534-eef842397966
 	github.com/songgao/water v0.0.0-20200317203138-2b4b6d7c09d8
 	github.com/stretchr/testify v1.11.1
@@ -294,8 +295,6 @@ require (
 	github.com/prometheus/procfs v0.19.2 // indirect
 	github.com/russellhaering/goxmldsig v1.6.0 // indirect
 	github.com/ryanuber/go-glob v1.0.0 // indirect
-	github.com/shirou/gopsutil/v4 v4.25.8 // indirect
-	github.com/shoenig/go-m1cpu v0.2.1 // indirect
 	github.com/shopspring/decimal v1.4.0 // indirect
 	github.com/spf13/cast v1.10.0 // indirect
 	github.com/stretchr/objx v0.5.2 // indirect
@@ -318,6 +317,7 @@ require (
 	golang.org/x/text v0.37.0 // indirect
 	golang.org/x/tools v0.44.0 // indirect
 	golang.zx2c4.com/wintun v0.0.0-20230126152724-0fa3db229ce2 // indirect
+	google.golang.org/genproto/googleapis/api v0.0.0-20260319201613-d00831a3d3e7 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20260401024825-9d38bb4040a9 // indirect
 	gopkg.in/square/go-jose.v2 v2.6.0 // indirect
 	gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7 // indirect

go.sum

@@ -271,9 +271,7 @@ github.com/google/go-cmp v0.3.1/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMyw
 github.com/google/go-cmp v0.4.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
-github.com/google/go-cmp v0.5.6/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 github.com/google/go-cmp v0.5.8/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
-github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
@@ -417,7 +415,6 @@ github.com/libp2p/go-netroute v0.4.0 h1:sZZx9hyANYUx9PZyqcgE/E1GUG3iEtTZHUEvdtXT
 github.com/libp2p/go-netroute v0.4.0/go.mod h1:Nkd5ShYgSMS5MUKy/MU2T57xFoOKvvLR92Lic48LEyA=
 github.com/lrh3321/ipset-go v0.0.0-20250619021614-54a0a98ace81 h1:J56rFEfUTFT9j9CiRXhi1r8lUJ4W5idG3CiaBZGojNU=
 github.com/lrh3321/ipset-go v0.0.0-20250619021614-54a0a98ace81/go.mod h1:RD8ML/YdXctQ7qbcizZkw5mZ6l8Ogrl1dodBzVJduwI=
-github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0/go.mod h1:zJYVVT2jmtg6P3p1VtQj7WsuWi/y4VnjVBn7F8KPB3I=
 github.com/lufia/plan9stats v0.0.0-20240513124658-fba389f38bae h1:dIZY4ULFcto4tAFlj1FYZl8ztUZ13bdq+PLY+NOfbyI=
 github.com/lufia/plan9stats v0.0.0-20240513124658-fba389f38bae/go.mod h1:ilwx/Dta8jXAgpFYFvSWEMwxmbWXyiUHkd5FwyKhb5k=
 github.com/magiconair/properties v1.8.10 h1:s31yESBquKXCV9a/ScB3ESkOjUYYv+X0rg8SYxI99mE=
@@ -569,7 +566,6 @@ github.com/pkg/sftp v1.13.9/go.mod h1:OBN7bVXdstkFFN/gdnHPUb5TE8eb8G1Rp9wCItqjkk
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE=
 github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 h1:o4JXh1EVt9k/+g42oCprj/FisM4qX9L3sZB3upGN2ZU=
 github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE=
 github.com/pquerna/otp v1.5.0 h1:NMMR+WrmaqXU4EzdGJEE1aUUI0AMRzsp96fFFWNPwxs=
@@ -599,16 +595,8 @@ github.com/russellhaering/goxmldsig v1.6.0/go.mod h1:TrnaquDcYxWXfJrOjeMBTX4mLBe
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/ryanuber/go-glob v1.0.0 h1:iQh3xXAumdQ+4Ufa5b25cRpC5TYKlno6hsv6Cb3pkBk=
 github.com/ryanuber/go-glob v1.0.0/go.mod h1:807d1WSdnB0XRJzKNil9Om6lcp/3a0v4qIHxIXzX/Yc=
-github.com/shirou/gopsutil/v3 v3.24.4 h1:dEHgzZXt4LMNm+oYELpzl9YCqV65Yr/6SfrvgRBtXeU=
-github.com/shirou/gopsutil/v3 v3.24.4/go.mod h1:lTd2mdiOspcqLgAnr9/nGi71NkeMpWKdmhuxm9GusH8=
 github.com/shirou/gopsutil/v4 v4.25.8 h1:NnAsw9lN7587WHxjJA9ryDnqhJpFH6A+wagYWTOH970=
 github.com/shirou/gopsutil/v4 v4.25.8/go.mod h1:q9QdMmfAOVIw7a+eF86P7ISEU6ka+NLgkUxlopV4RwI=
-github.com/shoenig/go-m1cpu v0.1.6/go.mod h1:1JJMcUBvfNwpq05QDQVAnx3gUHr9IYF7GNg9SUEw2VQ=
-github.com/shoenig/go-m1cpu v0.2.1 h1:yqRB4fvOge2+FyRXFkXqsyMoqPazv14Yyy+iyccT2E4=
-github.com/shoenig/go-m1cpu v0.2.1/go.mod h1:KkDOw6m3ZJQAPHbrzkZki4hnx+pDRR1Lo+ldA56wD5w=
-github.com/shoenig/test v0.6.4/go.mod h1:byHiCGXqrVaflBLAMq/srcZIHynQPQgeyvkvXnjqq0k=
-github.com/shoenig/test v1.7.0 h1:eWcHtTXa6QLnBvm0jgEabMRN/uJ4DMV3M8xUGgRkZmk=
-github.com/shoenig/test v1.7.0/go.mod h1:UxJ6u/x2v/TNs/LoLxBNJRV9DiwBBKYxXSyczsBHFoI=
 github.com/shopspring/decimal v1.4.0 h1:bxl37RwXBklmTi0C79JfXCEBD1cqqHt0bbgBAGFp81k=
 github.com/shopspring/decimal v1.4.0/go.mod h1:gawqmDU56v4yIKSwfBSFip1HdCCXN8/+DMd9qYNcwME=
 github.com/sirupsen/logrus v1.9.4 h1:TsZE7l11zFCLZnZ+teH4Umoq5BhEIfIzfRDZ1Uzql2w=
@@ -640,7 +628,6 @@ github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
 github.com/stretchr/testify v1.8.3/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
-github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/testcontainers/testcontainers-go v0.37.0 h1:L2Qc0vkTw2EHWQ08djon0D2uw7Z/PtHS/QzZZ5Ra/hg=
@@ -659,10 +646,8 @@ github.com/ti-mo/netfilter v0.5.2 h1:CTjOwFuNNeZ9QPdRXt1MZFLFUf84cKtiQutNauHWd40
 github.com/ti-mo/netfilter v0.5.2/go.mod h1:Btx3AtFiOVdHReTDmP9AE+hlkOcvIy403u7BXXbWZKo=
 github.com/tinylib/msgp v1.6.3 h1:bCSxiTz386UTgyT1i0MSCvdbWjVW+8sG3PjkGsZQt4s=
 github.com/tinylib/msgp v1.6.3/go.mod h1:RSp0LW9oSxFut3KzESt5Voq4GVWyS+PSulT77roAqEA=
-github.com/tklauser/go-sysconf v0.3.12/go.mod h1:Ho14jnntGE1fpdOqQEEaiKRpvIavV0hSfmBq8nJbHYI=
 github.com/tklauser/go-sysconf v0.3.15 h1:VE89k0criAymJ/Os65CSn1IXaol+1wrsFHEB8Ol49K4=
 github.com/tklauser/go-sysconf v0.3.15/go.mod h1:Dmjwr6tYFIseJw7a3dRLJfsHAMXZ3nEnL/aZY+0IuI4=
-github.com/tklauser/numcpus v0.6.1/go.mod h1:1XfjsgE2zo8GVw7POkMbHENHzVg3GzmoZ9fESEdAacY=
 github.com/tklauser/numcpus v0.10.0 h1:18njr6LDBk1zuna922MgdjQuJFjrdppsZG60sHGfjso=
 github.com/tklauser/numcpus v0.10.0/go.mod h1:BiTKazU708GQTYF4mB+cmlpT2Is1gLk7XVuEeem8LsQ=
 github.com/ugorji/go v1.1.7/go.mod h1:kZn38zHttfInRq0xu/PH0az30d+z6vm202qpg1oXVMw=
@@ -834,7 +819,6 @@ golang.org/x/sys v0.11.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.12.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.16.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.17.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
-golang.org/x/sys v0.19.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.20.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI=

shared/relay/client/manager.go

@@ -30,11 +30,16 @@ type RelayTrack struct {
 	relayClient *Client
 	err         error
 	created     time.Time
+	// ready is closed once the dial started by openConnVia finishes (relayClient
+	// or err is set). Callers reusing a track wait on this instead of the track
+	// lock, so the dial never runs under rt.Lock.
+	ready chan struct{}
 }
 
 func NewRelayTrack() *RelayTrack {
 	return &RelayTrack{
 		created: time.Now(),
+		ready:   make(chan struct{}),
 	}
 }
 
@@ -326,34 +331,24 @@ func (m *Manager) openConnVia(ctx context.Context, serverAddress, peerKey string
 	// check if already has a connection to the desired relay server
 	m.relayClientsMutex.RLock()
 	rt, ok := m.relayClients[serverAddress]
-	if ok {
-		rt.RLock()
-		m.relayClientsMutex.RUnlock()
-		defer rt.RUnlock()
-		if rt.err != nil {
-			return nil, rt.err
-		}
-		return rt.relayClient.OpenConn(ctx, peerKey)
-	}
 	m.relayClientsMutex.RUnlock()
+	if ok {
+		return m.openConnOnTrack(ctx, rt, peerKey)
+	}
 
 	// if not, establish a new connection but check it again (because changed the lock type) before starting the
 	// connection
 	m.relayClientsMutex.Lock()
 	rt, ok = m.relayClients[serverAddress]
 	if ok {
-		rt.RLock()
 		m.relayClientsMutex.Unlock()
-		defer rt.RUnlock()
-		if rt.err != nil {
-			return nil, rt.err
-		}
-		return rt.relayClient.OpenConn(ctx, peerKey)
+		return m.openConnOnTrack(ctx, rt, peerKey)
 	}
 
-	// create a new relay client and store it in the relayClients map
+	// Publish the track and release the map lock BEFORE dialing, so the dial does
+	// not run under rt.Lock (which would block RelayStates and the cleanup loop
+	// for the full dial). Concurrent callers find this track and wait on rt.ready.
 	rt = NewRelayTrack()
-	rt.Lock()
 	m.relayClients[serverAddress] = rt
 	m.relayClientsMutex.Unlock()
 
@@ -361,8 +356,10 @@ func (m *Manager) openConnVia(ctx context.Context, serverAddress, peerKey string
 	relayClient.SetTransportFallback(m.transportFallback)
 	err := relayClient.Connect(m.ctx)
 	if err != nil {
+		rt.Lock()
 		rt.err = err
 		rt.Unlock()
+		close(rt.ready)
 		m.relayClientsMutex.Lock()
 		delete(m.relayClients, serverAddress)
 		m.relayClientsMutex.Unlock()
@@ -370,14 +367,34 @@ func (m *Manager) openConnVia(ctx context.Context, serverAddress, peerKey string
 	}
 	// if connection closed then delete the relay client from the list
 	relayClient.SetOnDisconnectListener(m.onServerDisconnected)
+	rt.Lock()
 	rt.relayClient = relayClient
 	rt.Unlock()
+	close(rt.ready)
 
-	conn, err := relayClient.OpenConn(ctx, peerKey)
-	if err != nil {
-		return nil, err
+	return relayClient.OpenConn(ctx, peerKey)
+}
+
+// openConnOnTrack opens a peer connection through an existing relay track,
+// waiting for the dial started by another openConnVia call to finish. It waits
+// on rt.ready rather than the track lock, so it neither holds nor contends the
+// track lock across the dial.
+func (m *Manager) openConnOnTrack(ctx context.Context, rt *RelayTrack, peerKey string) (net.Conn, error) {
+	select {
+	case <-rt.ready:
+	case <-ctx.Done():
+		return nil, ctx.Err()
 	}
-	return conn, nil
+
+	rt.RLock()
+	defer rt.RUnlock()
+	if rt.err != nil {
+		return nil, rt.err
+	}
+	if rt.relayClient == nil {
+		return nil, ErrRelayClientNotConnected
+	}
+	return rt.relayClient.OpenConn(ctx, peerKey)
 }
 
 func (m *Manager) onServerConnected() {
@@ -476,6 +493,13 @@ func (m *Manager) cleanUpUnusedRelays() {
 			continue
 		}
 
+		// dial still in progress (openConnVia publishes the track before Connect
+		// completes and no longer holds rt.Lock during it), nothing to clean up.
+		if rt.relayClient == nil {
+			rt.Unlock()
+			continue
+		}
+
 		if time.Since(rt.created) <= m.keepUnusedServerTime {
 			rt.Unlock()
 			continue

shared/relay/client/manager_cleanup_test.go

@@ -0,0 +1,60 @@
+package client
+
+import (
+	"context"
+	"net/netip"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+// TestCleanUpUnusedRelays_DoesNotBlockOnRealHangingDial drives a real, hanging foreign
+// relay dial and asserts cleanUpUnusedRelays does not stall behind it.
+func TestCleanUpUnusedRelays_DoesNotBlockOnRealHangingDial(t *testing.T) {
+	serverAddr := stallingRelayListener(t)
+
+	mCtx, mCancel := context.WithCancel(context.Background())
+	t.Cleanup(mCancel)
+
+	m := NewManager(mCtx, nil, "alice", 1280)
+
+	dialDone := make(chan struct{})
+	go func() {
+		defer close(dialDone)
+		_, _ = m.openConnVia(mCtx, serverAddr, "peerKey", netip.Addr{})
+	}()
+
+	// The track appears in the map once the dial is in flight.
+	require.Eventually(t, func() bool {
+		m.relayClientsMutex.RLock()
+		defer m.relayClientsMutex.RUnlock()
+		_, ok := m.relayClients[serverAddr]
+		return ok
+	}, 5*time.Second, 5*time.Millisecond, "relay dial did not start")
+
+	cleanupDone := make(chan struct{})
+	go func() {
+		defer close(cleanupDone)
+		m.cleanUpUnusedRelays()
+	}()
+
+	select {
+	case <-cleanupDone:
+	case <-time.After(2 * time.Second):
+		t.Fatal("cleanUpUnusedRelays blocked on an in-progress relay dial while holding the relay map lock")
+	}
+
+	m.relayClientsMutex.RLock()
+	_, stillTracked := m.relayClients[serverAddr]
+	m.relayClientsMutex.RUnlock()
+	require.True(t, stillTracked, "an in-progress relay dial must not be evicted by cleanup")
+
+	// Release the hanging dial so the goroutine can exit cleanly.
+	mCancel()
+	select {
+	case <-dialDone:
+	case <-time.After(5 * time.Second):
+		t.Fatal("openConnVia did not return after context cancellation")
+	}
+}

shared/relay/client/manager_relaystates_test.go

@@ -0,0 +1,91 @@
+package client
+
+import (
+	"context"
+	"net"
+	"net/netip"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+// stallingRelayListener accepts TCP connections and holds them open without ever
+// responding, so a relay handshake dialed against it blocks until its context is
+// cancelled. It returns the "rel://host:port" URL to dial.
+func stallingRelayListener(t *testing.T) string {
+	t.Helper()
+
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	require.NoError(t, err)
+
+	var mu sync.Mutex
+	var conns []net.Conn
+	go func() {
+		for {
+			c, err := ln.Accept()
+			if err != nil {
+				return
+			}
+			mu.Lock()
+			conns = append(conns, c)
+			mu.Unlock()
+		}
+	}()
+	t.Cleanup(func() {
+		_ = ln.Close()
+		mu.Lock()
+		for _, c := range conns {
+			_ = c.Close()
+		}
+		mu.Unlock()
+	})
+
+	return "rel://" + ln.Addr().String()
+}
+
+// TestRelayStates_DoesNotBlockOnRealHangingDial is a regression test for
+// RelayStates() called by a "status -d command" hanging behind an in-progress
+// relay dial.
+func TestRelayStates_DoesNotBlockOnRealHangingDial(t *testing.T) {
+	serverAddr := stallingRelayListener(t)
+
+	mCtx, mCancel := context.WithCancel(context.Background())
+	t.Cleanup(mCancel)
+
+	m := NewManager(mCtx, nil, "alice", 1280)
+
+	dialDone := make(chan struct{})
+	go func() {
+		defer close(dialDone)
+		_, _ = m.openConnVia(mCtx, serverAddr, "peerKey", netip.Addr{})
+	}()
+
+	require.Eventually(t, func() bool {
+		m.relayClientsMutex.RLock()
+		defer m.relayClientsMutex.RUnlock()
+		_, ok := m.relayClients[serverAddr]
+		return ok
+	}, 5*time.Second, 5*time.Millisecond, "relay dial did not start")
+
+	done := make(chan []RelayConnState, 1)
+	go func() {
+		done <- m.RelayStates()
+	}()
+
+	select {
+	case states := <-done:
+		require.Empty(t, states, "a relay still being dialed carries no state and must be omitted")
+	case <-time.After(2 * time.Second):
+		t.Fatal("RelayStates blocked on a foreign relay whose Connect() is in progress")
+	}
+
+	// Release the hanging dial so the goroutine can exit cleanly.
+	mCancel()
+	select {
+	case <-dialDone:
+	case <-time.After(5 * time.Second):
+		t.Fatal("openConnVia did not return after context cancellation")
+	}
+}