Merge main into embedded-vnc

# Conflicts: # client/internal/engine.go
2026-09-12 01:39:07 +02:00 · 2026-08-06 10:50:48 +02:00
parent 6781cd74bb 40ac64bb4e
commit 4b9f167401
87 changed files with 4492 additions and 626 deletions
@@ -22,7 +22,6 @@ type Client interface {
 	ExtendAuthSession(sysInfo *system.Info, jwtToken string) (*proto.ExtendAuthSessionResponse, error)
 	GetDeviceAuthorizationFlow() (*proto.DeviceAuthorizationFlow, error)
 	GetPKCEAuthorizationFlow() (*proto.PKCEAuthorizationFlow, error)
-	GetNetworkMap(sysInfo *system.Info) (*proto.NetworkMap, error)
 	GetServerURL() string
 	// IsHealthy returns the current connection status without blocking.
 	// Used by the engine to monitor connectivity in the background.
@@ -436,49 +436,6 @@ func (c *GrpcClient) handleSyncStream(ctx context.Context, serverPubKey wgtypes.
 	return nil
 }

-// GetNetworkMap return with the network map
-func (c *GrpcClient) GetNetworkMap(sysInfo *system.Info) (*proto.NetworkMap, error) {
-	serverPubKey, err := c.getServerPublicKey()
-	if err != nil {
-		log.Debugf("failed getting Management Service public key: %s", err)
-		return nil, err
-	}
-
-	ctx, cancelStream := context.WithCancel(c.ctx)
-	defer cancelStream()
-	stream, err := c.connectToSyncStream(ctx, *serverPubKey, sysInfo)
-	if err != nil {
-		log.Debugf("failed to open Management Service stream: %s", err)
-		return nil, err
-	}
-	defer func() {
-		_ = stream.CloseSend()
-	}()
-
-	update, err := stream.Recv()
-	if err == io.EOF {
-		log.Debugf("Management stream has been closed by server: %s", err)
-		return nil, err
-	}
-	if err != nil {
-		log.Debugf("disconnected from Management Service sync stream: %v", err)
-		return nil, err
-	}
-
-	decryptedResp := &proto.SyncResponse{}
-	err = encryption.DecryptMessage(*serverPubKey, c.key, update.Body, decryptedResp)
-	if err != nil {
-		log.Errorf("failed decrypting update message from Management Service: %s", err)
-		return nil, err
-	}
-
-	if decryptedResp.GetNetworkMap() == nil {
-		return nil, fmt.Errorf("invalid msg, required network map")
-	}
-
-	return decryptedResp.GetNetworkMap(), nil
-}
-
 func (c *GrpcClient) connectToSyncStream(ctx context.Context, serverPubKey wgtypes.Key, sysInfo *system.Info) (proto.ManagementService_SyncClient, error) {
 	req := &proto.SyncRequest{Meta: infoToMetaData(sysInfo)}

@@ -94,11 +94,6 @@ func (m *MockClient) HealthCheck() error {
 	return m.HealthCheckFunc()
 }

-// GetNetworkMap mock implementation of GetNetworkMap from Client interface.
-func (m *MockClient) GetNetworkMap(_ *system.Info) (*proto.NetworkMap, error) {
-	return nil, nil
-}
-
 // GetServerURL mock implementation of GetServerURL from mgm.Client interface
 func (m *MockClient) GetServerURL() string {
 	if m.GetServerURLFunc == nil {
@@ -0,0 +1,381 @@
+package rest
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+
+	"github.com/netbirdio/netbird/shared/management/http/api"
+)
+
+// AgentNetworkAPI APIs for the Agent Network (AI/LLM gateway), do not use directly
+// see more: https://docs.netbird.io/api/resources/agent-network
+type AgentNetworkAPI struct {
+	c *Client
+}
+
+// ListCatalogProviders lists the catalog of supported upstream AI providers
+// (openai_api, anthropic_api, bedrock_api, ...) with their default models and
+// pricing, used to prefill provider create forms.
+func (a *AgentNetworkAPI) ListCatalogProviders(ctx context.Context) ([]api.AgentNetworkCatalogProvider, error) {
+	resp, err := a.c.NewRequest(ctx, "GET", "/api/agent-network/catalog/providers", nil, nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	ret, err := parseResponse[[]api.AgentNetworkCatalogProvider](resp)
+	return ret, err
+}
+
+// ListProviders lists all Agent Network providers
+func (a *AgentNetworkAPI) ListProviders(ctx context.Context) ([]api.AgentNetworkProvider, error) {
+	resp, err := a.c.NewRequest(ctx, "GET", "/api/agent-network/providers", nil, nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	ret, err := parseResponse[[]api.AgentNetworkProvider](resp)
+	return ret, err
+}
+
+// GetProvider gets Agent Network provider info
+func (a *AgentNetworkAPI) GetProvider(ctx context.Context, providerID string) (*api.AgentNetworkProvider, error) {
+	resp, err := a.c.NewRequest(ctx, "GET", "/api/agent-network/providers/"+providerID, nil, nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	ret, err := parseResponse[api.AgentNetworkProvider](resp)
+	return &ret, err
+}
+
+// CreateProvider creates a new Agent Network provider. Set
+// request.BootstrapCluster on the account's first provider to bootstrap the
+// per-account gateway endpoint (alternatively bootstrap via UpdateSettings
+// with a cluster).
+func (a *AgentNetworkAPI) CreateProvider(ctx context.Context, request api.PostApiAgentNetworkProvidersJSONRequestBody) (*api.AgentNetworkProvider, error) {
+	requestBytes, err := json.Marshal(request)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := a.c.NewRequest(ctx, "POST", "/api/agent-network/providers", bytes.NewReader(requestBytes), nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	ret, err := parseResponse[api.AgentNetworkProvider](resp)
+	return &ret, err
+}
+
+// UpdateProvider updates an Agent Network provider. The request replaces the
+// provider's mutable state; only an omitted api_key keeps the stored key
+// (secrets are never required to round-trip).
+func (a *AgentNetworkAPI) UpdateProvider(ctx context.Context, providerID string, request api.PutApiAgentNetworkProvidersProviderIdJSONRequestBody) (*api.AgentNetworkProvider, error) {
+	requestBytes, err := json.Marshal(request)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := a.c.NewRequest(ctx, "PUT", "/api/agent-network/providers/"+providerID, bytes.NewReader(requestBytes), nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	ret, err := parseResponse[api.AgentNetworkProvider](resp)
+	return &ret, err
+}
+
+// DeleteProvider deletes an Agent Network provider. Fails while any policy
+// still references the provider — detach it first.
+func (a *AgentNetworkAPI) DeleteProvider(ctx context.Context, providerID string) error {
+	resp, err := a.c.NewRequest(ctx, "DELETE", "/api/agent-network/providers/"+providerID, nil, nil)
+	if err != nil {
+		return err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+
+	return nil
+}
+
+// ListPolicies lists all Agent Network policies
+func (a *AgentNetworkAPI) ListPolicies(ctx context.Context) ([]api.AgentNetworkPolicy, error) {
+	resp, err := a.c.NewRequest(ctx, "GET", "/api/agent-network/policies", nil, nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	ret, err := parseResponse[[]api.AgentNetworkPolicy](resp)
+	return ret, err
+}
+
+// GetPolicy gets Agent Network policy info
+func (a *AgentNetworkAPI) GetPolicy(ctx context.Context, policyID string) (*api.AgentNetworkPolicy, error) {
+	resp, err := a.c.NewRequest(ctx, "GET", "/api/agent-network/policies/"+policyID, nil, nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	ret, err := parseResponse[api.AgentNetworkPolicy](resp)
+	return &ret, err
+}
+
+// CreatePolicy creates a new Agent Network policy
+func (a *AgentNetworkAPI) CreatePolicy(ctx context.Context, request api.PostApiAgentNetworkPoliciesJSONRequestBody) (*api.AgentNetworkPolicy, error) {
+	requestBytes, err := json.Marshal(request)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := a.c.NewRequest(ctx, "POST", "/api/agent-network/policies", bytes.NewReader(requestBytes), nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	ret, err := parseResponse[api.AgentNetworkPolicy](resp)
+	return &ret, err
+}
+
+// UpdatePolicy updates an Agent Network policy
+func (a *AgentNetworkAPI) UpdatePolicy(ctx context.Context, policyID string, request api.PutApiAgentNetworkPoliciesPolicyIdJSONRequestBody) (*api.AgentNetworkPolicy, error) {
+	requestBytes, err := json.Marshal(request)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := a.c.NewRequest(ctx, "PUT", "/api/agent-network/policies/"+policyID, bytes.NewReader(requestBytes), nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	ret, err := parseResponse[api.AgentNetworkPolicy](resp)
+	return &ret, err
+}
+
+// DeletePolicy deletes an Agent Network policy
+func (a *AgentNetworkAPI) DeletePolicy(ctx context.Context, policyID string) error {
+	resp, err := a.c.NewRequest(ctx, "DELETE", "/api/agent-network/policies/"+policyID, nil, nil)
+	if err != nil {
+		return err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+
+	return nil
+}
+
+// ListGuardrails lists all Agent Network guardrails
+func (a *AgentNetworkAPI) ListGuardrails(ctx context.Context) ([]api.AgentNetworkGuardrail, error) {
+	resp, err := a.c.NewRequest(ctx, "GET", "/api/agent-network/guardrails", nil, nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	ret, err := parseResponse[[]api.AgentNetworkGuardrail](resp)
+	return ret, err
+}
+
+// GetGuardrail gets Agent Network guardrail info
+func (a *AgentNetworkAPI) GetGuardrail(ctx context.Context, guardrailID string) (*api.AgentNetworkGuardrail, error) {
+	resp, err := a.c.NewRequest(ctx, "GET", "/api/agent-network/guardrails/"+guardrailID, nil, nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	ret, err := parseResponse[api.AgentNetworkGuardrail](resp)
+	return &ret, err
+}
+
+// CreateGuardrail creates a new Agent Network guardrail
+func (a *AgentNetworkAPI) CreateGuardrail(ctx context.Context, request api.PostApiAgentNetworkGuardrailsJSONRequestBody) (*api.AgentNetworkGuardrail, error) {
+	requestBytes, err := json.Marshal(request)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := a.c.NewRequest(ctx, "POST", "/api/agent-network/guardrails", bytes.NewReader(requestBytes), nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	ret, err := parseResponse[api.AgentNetworkGuardrail](resp)
+	return &ret, err
+}
+
+// UpdateGuardrail updates an Agent Network guardrail
+func (a *AgentNetworkAPI) UpdateGuardrail(ctx context.Context, guardrailID string, request api.PutApiAgentNetworkGuardrailsGuardrailIdJSONRequestBody) (*api.AgentNetworkGuardrail, error) {
+	requestBytes, err := json.Marshal(request)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := a.c.NewRequest(ctx, "PUT", "/api/agent-network/guardrails/"+guardrailID, bytes.NewReader(requestBytes), nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	ret, err := parseResponse[api.AgentNetworkGuardrail](resp)
+	return &ret, err
+}
+
+// DeleteGuardrail deletes an Agent Network guardrail
+func (a *AgentNetworkAPI) DeleteGuardrail(ctx context.Context, guardrailID string) error {
+	resp, err := a.c.NewRequest(ctx, "DELETE", "/api/agent-network/guardrails/"+guardrailID, nil, nil)
+	if err != nil {
+		return err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+
+	return nil
+}
+
+// ListBudgetRules lists all account-level Agent Network budget rules
+func (a *AgentNetworkAPI) ListBudgetRules(ctx context.Context) ([]api.AgentNetworkBudgetRule, error) {
+	resp, err := a.c.NewRequest(ctx, "GET", "/api/agent-network/budget-rules", nil, nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	ret, err := parseResponse[[]api.AgentNetworkBudgetRule](resp)
+	return ret, err
+}
+
+// GetBudgetRule gets Agent Network budget rule info
+func (a *AgentNetworkAPI) GetBudgetRule(ctx context.Context, ruleID string) (*api.AgentNetworkBudgetRule, error) {
+	resp, err := a.c.NewRequest(ctx, "GET", "/api/agent-network/budget-rules/"+ruleID, nil, nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	ret, err := parseResponse[api.AgentNetworkBudgetRule](resp)
+	return &ret, err
+}
+
+// CreateBudgetRule creates a new Agent Network budget rule
+func (a *AgentNetworkAPI) CreateBudgetRule(ctx context.Context, request api.PostApiAgentNetworkBudgetRulesJSONRequestBody) (*api.AgentNetworkBudgetRule, error) {
+	requestBytes, err := json.Marshal(request)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := a.c.NewRequest(ctx, "POST", "/api/agent-network/budget-rules", bytes.NewReader(requestBytes), nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	ret, err := parseResponse[api.AgentNetworkBudgetRule](resp)
+	return &ret, err
+}
+
+// UpdateBudgetRule updates an Agent Network budget rule
+func (a *AgentNetworkAPI) UpdateBudgetRule(ctx context.Context, ruleID string, request api.PutApiAgentNetworkBudgetRulesRuleIdJSONRequestBody) (*api.AgentNetworkBudgetRule, error) {
+	requestBytes, err := json.Marshal(request)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := a.c.NewRequest(ctx, "PUT", "/api/agent-network/budget-rules/"+ruleID, bytes.NewReader(requestBytes), nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	ret, err := parseResponse[api.AgentNetworkBudgetRule](resp)
+	return &ret, err
+}
+
+// DeleteBudgetRule deletes an Agent Network budget rule
+func (a *AgentNetworkAPI) DeleteBudgetRule(ctx context.Context, ruleID string) error {
+	resp, err := a.c.NewRequest(ctx, "DELETE", "/api/agent-network/budget-rules/"+ruleID, nil, nil)
+	if err != nil {
+		return err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+
+	return nil
+}
+
+// GetSettings gets the account's Agent Network gateway settings (cluster,
+// subdomain, endpoint, collection toggles). An account that has not been
+// bootstrapped yet — via UpdateSettings with a cluster, or by creating the
+// first provider with bootstrap_cluster set — reads as the defaults with an
+// empty Cluster, Subdomain and Endpoint. Management servers prior to that
+// contract answered 200 with a JSON null body instead; that legacy shape is
+// translated to an APIError matchable via IsNotFound rather than fabricating
+// defaults the server never stated.
+func (a *AgentNetworkAPI) GetSettings(ctx context.Context) (*api.AgentNetworkSettings, error) {
+	resp, err := a.c.NewRequest(ctx, "GET", "/api/agent-network/settings", nil, nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, err
+	}
+	if trimmed := bytes.TrimSpace(body); len(trimmed) == 0 || bytes.Equal(trimmed, []byte("null")) {
+		return nil, &APIError{StatusCode: http.StatusNotFound, Message: "agent network settings not found"}
+	}
+	var ret api.AgentNetworkSettings
+	if err := json.Unmarshal(body, &ret); err != nil {
+		return nil, err
+	}
+	return &ret, nil
+}
+
+// UpdateSettings updates the account's Agent Network settings; the request
+// replaces every mutable field (collection toggles and retention). Setting
+// request.Cluster bootstraps the settings row when the account does not have
+// one yet; on a bootstrapped account it must match the assigned cluster (or
+// be nil) and any other value is rejected — the cluster is immutable.
+func (a *AgentNetworkAPI) UpdateSettings(ctx context.Context, request api.PutApiAgentNetworkSettingsJSONRequestBody) (*api.AgentNetworkSettings, error) {
+	requestBytes, err := json.Marshal(request)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := a.c.NewRequest(ctx, "PUT", "/api/agent-network/settings", bytes.NewReader(requestBytes), nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	ret, err := parseResponse[api.AgentNetworkSettings](resp)
+	return &ret, err
+}
@@ -0,0 +1,497 @@
+//go:build integration
+
+package rest_test
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/netbirdio/netbird/shared/management/client/rest"
+	"github.com/netbirdio/netbird/shared/management/http/api"
+	"github.com/netbirdio/netbird/shared/management/http/util"
+)
+
+var (
+	testAgentNetworkProvider = api.AgentNetworkProvider{
+		Id:          "ainp_test",
+		ProviderId:  "openai_api",
+		Name:        "OpenAI",
+		UpstreamUrl: "https://api.openai.com",
+		Models:      []api.AgentNetworkProviderModel{},
+		Enabled:     true,
+	}
+
+	testAgentNetworkPolicy = api.AgentNetworkPolicy{
+		Id:                     "ainpol_test",
+		Name:                   "Engineering → OpenAI",
+		Enabled:                true,
+		SourceGroups:           []string{"grp-eng"},
+		DestinationProviderIds: []string{"ainp_test"},
+	}
+
+	testAgentNetworkGuardrail = api.AgentNetworkGuardrail{
+		Id:   "aingr_test",
+		Name: "No secrets",
+	}
+
+	testAgentNetworkBudgetRule = api.AgentNetworkBudgetRule{
+		Id:      "ainbud_test",
+		Name:    "Org monthly ceiling",
+		Enabled: true,
+	}
+
+	testAgentNetworkSettings = api.AgentNetworkSettings{
+		Cluster:                "eu.proxy.netbird.io",
+		Subdomain:              "violet",
+		Endpoint:               "violet.eu.proxy.netbird.io",
+		EnableLogCollection:    true,
+		AccessLogRetentionDays: ptr(30),
+	}
+)
+
+func TestAgentNetwork_ListCatalogProviders_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/catalog/providers", func(w http.ResponseWriter, r *http.Request) {
+			retBytes, _ := json.Marshal([]api.AgentNetworkCatalogProvider{{Id: "openai_api", Name: "OpenAI"}})
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.AgentNetwork.ListCatalogProviders(context.Background())
+		require.NoError(t, err)
+		assert.Len(t, ret, 1)
+		assert.Equal(t, "openai_api", ret[0].Id)
+	})
+}
+
+func TestAgentNetwork_ListProviders_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/providers", func(w http.ResponseWriter, r *http.Request) {
+			retBytes, _ := json.Marshal([]api.AgentNetworkProvider{testAgentNetworkProvider})
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.AgentNetwork.ListProviders(context.Background())
+		require.NoError(t, err)
+		assert.Len(t, ret, 1)
+		assert.Equal(t, testAgentNetworkProvider, ret[0])
+	})
+}
+
+func TestAgentNetwork_GetProvider_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/providers/ainp_test", func(w http.ResponseWriter, r *http.Request) {
+			assert.Equal(t, "GET", r.Method)
+			retBytes, _ := json.Marshal(testAgentNetworkProvider)
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.AgentNetwork.GetProvider(context.Background(), "ainp_test")
+		require.NoError(t, err)
+		assert.Equal(t, testAgentNetworkProvider, *ret)
+	})
+}
+
+func TestAgentNetwork_GetProvider_Err(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/providers/ainp_test", func(w http.ResponseWriter, r *http.Request) {
+			retBytes, _ := json.Marshal(util.ErrorResponse{Message: "not found", Code: 404})
+			w.WriteHeader(404)
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		_, err := c.AgentNetwork.GetProvider(context.Background(), "ainp_test")
+		require.Error(t, err)
+		assert.True(t, rest.IsNotFound(err), "a 404 must be matchable via IsNotFound")
+	})
+}
+
+func TestAgentNetwork_CreateProvider_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/providers", func(w http.ResponseWriter, r *http.Request) {
+			assert.Equal(t, "POST", r.Method)
+			reqBytes, err := io.ReadAll(r.Body)
+			require.NoError(t, err)
+			var req api.PostApiAgentNetworkProvidersJSONRequestBody
+			require.NoError(t, json.Unmarshal(reqBytes, &req))
+			assert.Equal(t, "OpenAI", req.Name)
+			require.NotNil(t, req.BootstrapCluster)
+			assert.Equal(t, "eu.proxy.netbird.io", *req.BootstrapCluster)
+			retBytes, _ := json.Marshal(testAgentNetworkProvider)
+			_, err = w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.AgentNetwork.CreateProvider(context.Background(), api.PostApiAgentNetworkProvidersJSONRequestBody{
+			ProviderId:       "openai_api",
+			Name:             "OpenAI",
+			UpstreamUrl:      "https://api.openai.com",
+			ApiKey:           ptr("sk-test"),
+			BootstrapCluster: ptr("eu.proxy.netbird.io"),
+		})
+		require.NoError(t, err)
+		assert.Equal(t, testAgentNetworkProvider, *ret)
+	})
+}
+
+func TestAgentNetwork_UpdateProvider_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/providers/ainp_test", func(w http.ResponseWriter, r *http.Request) {
+			assert.Equal(t, "PUT", r.Method)
+			reqBytes, err := io.ReadAll(r.Body)
+			require.NoError(t, err)
+			// Omitted optional fields must be absent from the wire (not
+			// zero-valued) so the server-side merge preserves them.
+			assert.NotContains(t, string(reqBytes), "api_key")
+			assert.NotContains(t, string(reqBytes), "models")
+			retBytes, _ := json.Marshal(testAgentNetworkProvider)
+			_, err = w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.AgentNetwork.UpdateProvider(context.Background(), "ainp_test", api.PutApiAgentNetworkProvidersProviderIdJSONRequestBody{
+			ProviderId:  "openai_api",
+			Name:        "OpenAI",
+			UpstreamUrl: "https://api.openai.com",
+		})
+		require.NoError(t, err)
+		assert.Equal(t, testAgentNetworkProvider, *ret)
+	})
+}
+
+func TestAgentNetwork_DeleteProvider_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/providers/ainp_test", func(w http.ResponseWriter, r *http.Request) {
+			assert.Equal(t, "DELETE", r.Method)
+			_, err := w.Write([]byte("{}"))
+			require.NoError(t, err)
+		})
+		err := c.AgentNetwork.DeleteProvider(context.Background(), "ainp_test")
+		require.NoError(t, err)
+	})
+}
+
+func TestAgentNetwork_ListPolicies_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/policies", func(w http.ResponseWriter, r *http.Request) {
+			retBytes, _ := json.Marshal([]api.AgentNetworkPolicy{testAgentNetworkPolicy})
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.AgentNetwork.ListPolicies(context.Background())
+		require.NoError(t, err)
+		assert.Len(t, ret, 1)
+		assert.Equal(t, testAgentNetworkPolicy, ret[0])
+	})
+}
+
+func TestAgentNetwork_GetPolicy_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/policies/ainpol_test", func(w http.ResponseWriter, r *http.Request) {
+			retBytes, _ := json.Marshal(testAgentNetworkPolicy)
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.AgentNetwork.GetPolicy(context.Background(), "ainpol_test")
+		require.NoError(t, err)
+		assert.Equal(t, testAgentNetworkPolicy, *ret)
+	})
+}
+
+func TestAgentNetwork_CreatePolicy_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/policies", func(w http.ResponseWriter, r *http.Request) {
+			assert.Equal(t, "POST", r.Method)
+			retBytes, _ := json.Marshal(testAgentNetworkPolicy)
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.AgentNetwork.CreatePolicy(context.Background(), api.PostApiAgentNetworkPoliciesJSONRequestBody{
+			Name:                   "Engineering → OpenAI",
+			SourceGroups:           []string{"grp-eng"},
+			DestinationProviderIds: []string{"ainp_test"},
+		})
+		require.NoError(t, err)
+		assert.Equal(t, testAgentNetworkPolicy, *ret)
+	})
+}
+
+func TestAgentNetwork_UpdatePolicy_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/policies/ainpol_test", func(w http.ResponseWriter, r *http.Request) {
+			assert.Equal(t, "PUT", r.Method)
+			retBytes, _ := json.Marshal(testAgentNetworkPolicy)
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.AgentNetwork.UpdatePolicy(context.Background(), "ainpol_test", api.PutApiAgentNetworkPoliciesPolicyIdJSONRequestBody{
+			Name:                   "Engineering → OpenAI",
+			SourceGroups:           []string{"grp-eng"},
+			DestinationProviderIds: []string{"ainp_test"},
+		})
+		require.NoError(t, err)
+		assert.Equal(t, testAgentNetworkPolicy, *ret)
+	})
+}
+
+func TestAgentNetwork_DeletePolicy_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/policies/ainpol_test", func(w http.ResponseWriter, r *http.Request) {
+			assert.Equal(t, "DELETE", r.Method)
+			_, err := w.Write([]byte("{}"))
+			require.NoError(t, err)
+		})
+		err := c.AgentNetwork.DeletePolicy(context.Background(), "ainpol_test")
+		require.NoError(t, err)
+	})
+}
+
+func TestAgentNetwork_ListGuardrails_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/guardrails", func(w http.ResponseWriter, r *http.Request) {
+			retBytes, _ := json.Marshal([]api.AgentNetworkGuardrail{testAgentNetworkGuardrail})
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.AgentNetwork.ListGuardrails(context.Background())
+		require.NoError(t, err)
+		assert.Len(t, ret, 1)
+		assert.Equal(t, testAgentNetworkGuardrail, ret[0])
+	})
+}
+
+func TestAgentNetwork_GetGuardrail_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/guardrails/aingr_test", func(w http.ResponseWriter, r *http.Request) {
+			retBytes, _ := json.Marshal(testAgentNetworkGuardrail)
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.AgentNetwork.GetGuardrail(context.Background(), "aingr_test")
+		require.NoError(t, err)
+		assert.Equal(t, testAgentNetworkGuardrail, *ret)
+	})
+}
+
+func TestAgentNetwork_CreateGuardrail_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/guardrails", func(w http.ResponseWriter, r *http.Request) {
+			assert.Equal(t, "POST", r.Method)
+			retBytes, _ := json.Marshal(testAgentNetworkGuardrail)
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.AgentNetwork.CreateGuardrail(context.Background(), api.PostApiAgentNetworkGuardrailsJSONRequestBody{
+			Name: "No secrets",
+		})
+		require.NoError(t, err)
+		assert.Equal(t, testAgentNetworkGuardrail, *ret)
+	})
+}
+
+func TestAgentNetwork_UpdateGuardrail_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/guardrails/aingr_test", func(w http.ResponseWriter, r *http.Request) {
+			assert.Equal(t, "PUT", r.Method)
+			retBytes, _ := json.Marshal(testAgentNetworkGuardrail)
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.AgentNetwork.UpdateGuardrail(context.Background(), "aingr_test", api.PutApiAgentNetworkGuardrailsGuardrailIdJSONRequestBody{
+			Name: "No secrets",
+		})
+		require.NoError(t, err)
+		assert.Equal(t, testAgentNetworkGuardrail, *ret)
+	})
+}
+
+func TestAgentNetwork_DeleteGuardrail_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/guardrails/aingr_test", func(w http.ResponseWriter, r *http.Request) {
+			assert.Equal(t, "DELETE", r.Method)
+			_, err := w.Write([]byte("{}"))
+			require.NoError(t, err)
+		})
+		err := c.AgentNetwork.DeleteGuardrail(context.Background(), "aingr_test")
+		require.NoError(t, err)
+	})
+}
+
+func TestAgentNetwork_ListBudgetRules_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/budget-rules", func(w http.ResponseWriter, r *http.Request) {
+			retBytes, _ := json.Marshal([]api.AgentNetworkBudgetRule{testAgentNetworkBudgetRule})
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.AgentNetwork.ListBudgetRules(context.Background())
+		require.NoError(t, err)
+		assert.Len(t, ret, 1)
+		assert.Equal(t, testAgentNetworkBudgetRule, ret[0])
+	})
+}
+
+func TestAgentNetwork_GetBudgetRule_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/budget-rules/ainbud_test", func(w http.ResponseWriter, r *http.Request) {
+			retBytes, _ := json.Marshal(testAgentNetworkBudgetRule)
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.AgentNetwork.GetBudgetRule(context.Background(), "ainbud_test")
+		require.NoError(t, err)
+		assert.Equal(t, testAgentNetworkBudgetRule, *ret)
+	})
+}
+
+func TestAgentNetwork_CreateBudgetRule_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/budget-rules", func(w http.ResponseWriter, r *http.Request) {
+			assert.Equal(t, "POST", r.Method)
+			retBytes, _ := json.Marshal(testAgentNetworkBudgetRule)
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.AgentNetwork.CreateBudgetRule(context.Background(), api.PostApiAgentNetworkBudgetRulesJSONRequestBody{
+			Name: "Org monthly ceiling",
+		})
+		require.NoError(t, err)
+		assert.Equal(t, testAgentNetworkBudgetRule, *ret)
+	})
+}
+
+func TestAgentNetwork_UpdateBudgetRule_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/budget-rules/ainbud_test", func(w http.ResponseWriter, r *http.Request) {
+			assert.Equal(t, "PUT", r.Method)
+			retBytes, _ := json.Marshal(testAgentNetworkBudgetRule)
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.AgentNetwork.UpdateBudgetRule(context.Background(), "ainbud_test", api.PutApiAgentNetworkBudgetRulesRuleIdJSONRequestBody{
+			Name: "Org monthly ceiling",
+		})
+		require.NoError(t, err)
+		assert.Equal(t, testAgentNetworkBudgetRule, *ret)
+	})
+}
+
+func TestAgentNetwork_DeleteBudgetRule_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/budget-rules/ainbud_test", func(w http.ResponseWriter, r *http.Request) {
+			assert.Equal(t, "DELETE", r.Method)
+			_, err := w.Write([]byte("{}"))
+			require.NoError(t, err)
+		})
+		err := c.AgentNetwork.DeleteBudgetRule(context.Background(), "ainbud_test")
+		require.NoError(t, err)
+	})
+}
+
+func TestAgentNetwork_GetSettings_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/settings", func(w http.ResponseWriter, r *http.Request) {
+			retBytes, _ := json.Marshal(testAgentNetworkSettings)
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.AgentNetwork.GetSettings(context.Background())
+		require.NoError(t, err)
+		assert.Equal(t, testAgentNetworkSettings, *ret)
+	})
+}
+
+// TestAgentNetwork_GetSettings_UnbootstrappedDefaults pins the settings-read
+// contract: an unbootstrapped account answers 200 with the defaults and empty
+// cluster/subdomain/endpoint, which the client passes through untouched.
+func TestAgentNetwork_GetSettings_UnbootstrappedDefaults(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/settings", func(w http.ResponseWriter, r *http.Request) {
+			retBytes, _ := json.Marshal(api.AgentNetworkSettings{
+				EnableLogCollection:    true,
+				AccessLogRetentionDays: ptr(30),
+			})
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.AgentNetwork.GetSettings(context.Background())
+		require.NoError(t, err)
+		assert.Empty(t, ret.Endpoint, "empty endpoint is the not-bootstrapped signal")
+		assert.True(t, ret.EnableLogCollection, "defaults must pass through")
+	})
+}
+
+func TestAgentNetwork_GetSettings_Err(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/settings", func(w http.ResponseWriter, r *http.Request) {
+			retBytes, _ := json.Marshal(util.ErrorResponse{Message: "no", Code: 403})
+			w.WriteHeader(403)
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		_, err := c.AgentNetwork.GetSettings(context.Background())
+		require.Error(t, err)
+		assert.Equal(t, "no", err.Error())
+	})
+}
+
+// TestAgentNetwork_GetSettings_LegacyNullBody pins the compatibility shim for
+// management servers that answered 200 with a JSON null body before the
+// defaults contract: the client translates that shape into an IsNotFound
+// error instead of returning a bogus zero-valued settings object or
+// fabricating defaults the server never stated.
+func TestAgentNetwork_GetSettings_LegacyNullBody(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/settings", func(w http.ResponseWriter, r *http.Request) {
+			_, err := w.Write([]byte("null"))
+			require.NoError(t, err)
+		})
+		ret, err := c.AgentNetwork.GetSettings(context.Background())
+		require.Error(t, err)
+		assert.Nil(t, ret)
+		assert.True(t, rest.IsNotFound(err), "the legacy 200+null shape must surface as IsNotFound")
+	})
+}
+
+func TestAgentNetwork_UpdateSettings_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/settings", func(w http.ResponseWriter, r *http.Request) {
+			assert.Equal(t, "PUT", r.Method)
+			reqBytes, err := io.ReadAll(r.Body)
+			require.NoError(t, err)
+			var req api.PutApiAgentNetworkSettingsJSONRequestBody
+			require.NoError(t, json.Unmarshal(reqBytes, &req))
+			require.NotNil(t, req.Cluster, "bootstrap cluster must be on the wire")
+			assert.Equal(t, "eu.proxy.netbird.io", *req.Cluster)
+			assert.True(t, req.EnableLogCollection)
+			retBytes, _ := json.Marshal(testAgentNetworkSettings)
+			_, err = w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.AgentNetwork.UpdateSettings(context.Background(), api.PutApiAgentNetworkSettingsJSONRequestBody{
+			Cluster:             ptr("eu.proxy.netbird.io"),
+			EnableLogCollection: true,
+		})
+		require.NoError(t, err)
+		assert.Equal(t, testAgentNetworkSettings, *ret)
+	})
+}
+
+func TestAgentNetwork_UpdateSettings_Err(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/settings", func(w http.ResponseWriter, r *http.Request) {
+			retBytes, _ := json.Marshal(util.ErrorResponse{Message: "cluster is immutable once assigned (current: eu.proxy.netbird.io)", Code: 422})
+			w.WriteHeader(422)
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		_, err := c.AgentNetwork.UpdateSettings(context.Background(), api.PutApiAgentNetworkSettingsJSONRequestBody{
+			Cluster: ptr("us.proxy.netbird.io"),
+		})
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "immutable")
+	})
+}
@@ -147,6 +147,10 @@ type Client struct {
 	// ReverseProxyTokens account-scoped proxy access tokens used to register
 	// self-hosted (bring-your-own-proxy) `netbird proxy` instances.
 	ReverseProxyTokens *ReverseProxyTokensAPI
+
+	// AgentNetwork NetBird Agent Network (AI/LLM gateway) APIs: catalog,
+	// providers, policies, guardrails, budget rules and account settings.
+	AgentNetwork *AgentNetworkAPI
 }

 // New initialize new Client instance using PAT token
@@ -209,6 +213,7 @@ func (c *Client) initialize() {
 	c.ReverseProxyClusters = &ReverseProxyClustersAPI{c}
 	c.ReverseProxyDomains = &ReverseProxyDomainsAPI{c}
 	c.ReverseProxyTokens = &ReverseProxyTokensAPI{c}
+	c.AgentNetwork = &AgentNetworkAPI{c}
 }

 // NewRequest creates and executes new management API request
@@ -5162,12 +5162,12 @@ components:
        identity_header_user_id:
          type: string
          description: |
-            Wire header name the proxy stamps with the caller's display identity (user email or peer name) when the catalog entry's HeaderPair is `customizable`. Empty disables stamping for this dimension. Ignored when the catalog entry has a fixed HeaderPair (e.g. LiteLLM, Portkey). Used today by Bifrost: typical values are `x-bf-lh-netbird_user_id` (always-on log metadata) or `x-bf-dim-netbird_user_id` (Prometheus / OTEL — requires the label to be pre-declared in the gateway's `client.prometheus_labels` config).
+            Wire header name the proxy stamps with the caller's display identity (user email or peer name) when the catalog entry's HeaderPair is `customizable`. Always present in responses; empty disables stamping for this dimension. Ignored when the catalog entry has a fixed HeaderPair (e.g. LiteLLM, Portkey). Used today by Bifrost: typical values are `x-bf-lh-netbird_user_id` (always-on log metadata) or `x-bf-dim-netbird_user_id` (Prometheus / OTEL — requires the label to be pre-declared in the gateway's `client.prometheus_labels` config).
          example: "x-bf-dim-netbird_user_id"
        identity_header_groups:
          type: string
          description: |
-            Wire header name the proxy stamps with the caller's NetBird groups as a comma-separated list (sorted) when the catalog entry's HeaderPair is `customizable`. Empty disables stamping for this dimension. Same per-catalog semantics as `identity_header_user_id`.
+            Wire header name the proxy stamps with the caller's NetBird groups as a comma-separated list (sorted) when the catalog entry's HeaderPair is `customizable`. Always present in responses; empty disables stamping for this dimension. Same per-catalog semantics as `identity_header_user_id`.
          example: "x-bf-dim-netbird_groups"
        enabled:
          type: boolean
@@ -5199,6 +5199,8 @@ components:
        - name
        - upstream_url
        - models
+        - identity_header_user_id
+        - identity_header_groups
        - enabled
        - skip_tls_verification
        - metadata_disabled
@@ -5235,7 +5237,7 @@ components:
        extra_values:
          type: object
          description: |
-            Operator-typed values for catalog-declared extra headers (see AgentNetworkProvider.extra_values). When present on a request, the whole map replaces the stored values. Empty strings drop the corresponding key.
+            Operator-typed values for catalog-declared extra headers (see AgentNetworkProvider.extra_values). The request's map replaces the stored values; empty strings drop the corresponding key.
          additionalProperties:
            type: string
          example:
@@ -5243,12 +5245,12 @@ components:
        identity_header_user_id:
          type: string
          description: |
-            Wire header name for the caller's display identity. See AgentNetworkProvider.identity_header_user_id. When omitted on a request, the stored value is left unchanged; pass an empty string explicitly to clear it (which disables stamping for this dimension).
+            Wire header name for the caller's display identity. See AgentNetworkProvider.identity_header_user_id. Empty or omitted disables stamping for this dimension.
          example: "x-bf-dim-netbird_user_id"
        identity_header_groups:
          type: string
          description: |
-            Wire header name for the caller's groups CSV. See AgentNetworkProvider.identity_header_groups. Same omit / empty semantics as `identity_header_user_id`.
+            Wire header name for the caller's groups CSV. See AgentNetworkProvider.identity_header_groups. Same semantics as `identity_header_user_id`.
          example: "x-bf-dim-netbird_groups"
        enabled:
          type: boolean
@@ -5256,11 +5258,11 @@ components:
          example: true
        skip_tls_verification:
          type: boolean
-          description: Skip upstream TLS certificate verification when the proxy dials this provider's URL. For self-hosted / internal gateways behind a private or self-signed certificate. Defaults to false. When omitted on update, the stored value is left unchanged.
+          description: Skip upstream TLS certificate verification when the proxy dials this provider's URL. For self-hosted / internal gateways behind a private or self-signed certificate. Defaults to false.
          example: false
        metadata_disabled:
          type: boolean
-          description: Disable identity metadata injection (the caller's user + authorizing group) for this provider. Defaults to false (metadata is injected). When omitted on update, the stored value is left unchanged.
+          description: Disable identity metadata injection (the caller's user + authorizing group) for this provider. Defaults to false (metadata is injected).
          example: false
      required:
        - provider_id
@@ -6204,19 +6206,19 @@ components:
        - cache_cost_usd
    AgentNetworkSettings:
      type: object
-      description: Per-account Agent Network gateway settings. One row per account; cluster and subdomain are auto-assigned on first provider create and immutable thereafter.
+      description: Per-account Agent Network gateway settings. One row per account; cluster and subdomain are assigned at bootstrap and immutable thereafter. Before bootstrap the account reads as the default values with empty cluster, subdomain and endpoint.
      properties:
        cluster:
          type: string
-          description: Address of the NetBird proxy cluster fronting this account's agent-network endpoint.
+          description: Address of the NetBird proxy cluster fronting this account's agent-network endpoint. Empty until the account is bootstrapped.
          example: "eu.proxy.netbird.io"
        subdomain:
          type: string
-          description: Auto-generated DNS-safe label that prefixes the cluster to form the agent-network endpoint.
+          description: Auto-generated DNS-safe label that prefixes the cluster to form the agent-network endpoint. Empty until the account is bootstrapped.
          example: "violet"
        endpoint:
          type: string
-          description: Bare hostname agents call for this account, computed as `<subdomain>.<cluster>`.
+          description: Bare hostname agents call for this account, computed as `<subdomain>.<cluster>`. Empty until the account is bootstrapped.
          example: "violet.eu.proxy.netbird.io"
        enable_log_collection:
          type: boolean
@@ -6237,13 +6239,13 @@ components:
        created_at:
          type: string
          format: date-time
-          description: Timestamp when the settings row was created.
+          description: Timestamp when the settings row was created. Absent until the account is bootstrapped.
          readOnly: true
          example: "2026-04-26T10:30:00Z"
        updated_at:
          type: string
          format: date-time
-          description: Timestamp when the settings row was last updated.
+          description: Timestamp when the settings row was last updated. Absent until the account is bootstrapped.
          readOnly: true
          example: "2026-04-26T10:30:00Z"
      required:
@@ -6253,12 +6255,14 @@ components:
        - enable_log_collection
        - enable_prompt_collection
        - redact_pii
-        - created_at
-        - updated_at
    AgentNetworkSettingsRequest:
      type: object
-      description: Mutable account-level Agent Network settings. Cluster and subdomain are immutable and not accepted here.
+      description: Account-level Agent Network settings update. The request replaces every mutable field. `cluster` additionally bootstraps the per-account settings row when the account does not have one yet; the subdomain is always server-assigned.
      properties:
+        cluster:
+          type: string
+          description: Address of the NetBird proxy cluster fronting this account's agent-network endpoint. When the account has no settings row yet, providing it bootstraps the row (assigning the subdomain that forms the agent endpoint). The cluster is immutable once assigned — later updates must omit it or send the assigned value; any other value is rejected.
+          example: "eu.proxy.netbird.io"
        enable_log_collection:
          type: boolean
          description: Whether per-request access-log entries are collected for this account's agent-network traffic.
@@ -13703,7 +13707,7 @@ paths:
  /api/agent-network/settings:
    get:
      summary: Retrieve Agent Network settings
-      description: Returns the per-account Agent Network gateway settings (cluster, subdomain, endpoint). Returns 404 when no provider has been created yet — settings are lazily bootstrapped on first provider create.
+      description: Returns the per-account Agent Network gateway settings (cluster, subdomain, endpoint). Before the account is bootstrapped — on first provider create (`bootstrap_cluster`) or via PUT with `cluster` — the response carries the default values with empty cluster, subdomain and endpoint.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
@@ -13719,13 +13723,11 @@ paths:
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
-        '404':
-          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update Agent Network settings
-      description: Updates the mutable account-level Agent Network settings (collection toggles). Cluster and subdomain are immutable and ignored if sent. Returns 404 when settings have not been bootstrapped (no provider created yet).
+      description: Updates the account-level Agent Network settings; the request replaces every mutable field (collection toggles and retention). When the account has no settings row yet, providing `cluster` bootstraps it (assigning the subdomain that forms the agent endpoint); without `cluster` the request returns 404. Sending a `cluster` different from the assigned one is rejected (the cluster is immutable once assigned). The subdomain is always server-assigned and immutable.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
@@ -13751,6 +13753,8 @@ paths:
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
+        '422':
+          "$ref": "#/components/responses/validation_failed"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/agent-network/budget-rules:
@@ -2275,11 +2275,11 @@ type AgentNetworkProvider struct {
 	// Id Provider ID
 	Id string `json:"id"`

-	// IdentityHeaderGroups Wire header name the proxy stamps with the caller's NetBird groups as a comma-separated list (sorted) when the catalog entry's HeaderPair is `customizable`. Empty disables stamping for this dimension. Same per-catalog semantics as `identity_header_user_id`.
-	IdentityHeaderGroups *string `json:"identity_header_groups,omitempty"`
+	// IdentityHeaderGroups Wire header name the proxy stamps with the caller's NetBird groups as a comma-separated list (sorted) when the catalog entry's HeaderPair is `customizable`. Always present in responses; empty disables stamping for this dimension. Same per-catalog semantics as `identity_header_user_id`.
+	IdentityHeaderGroups string `json:"identity_header_groups"`

-	// IdentityHeaderUserId Wire header name the proxy stamps with the caller's display identity (user email or peer name) when the catalog entry's HeaderPair is `customizable`. Empty disables stamping for this dimension. Ignored when the catalog entry has a fixed HeaderPair (e.g. LiteLLM, Portkey). Used today by Bifrost: typical values are `x-bf-lh-netbird_user_id` (always-on log metadata) or `x-bf-dim-netbird_user_id` (Prometheus / OTEL — requires the label to be pre-declared in the gateway's `client.prometheus_labels` config).
-	IdentityHeaderUserId *string `json:"identity_header_user_id,omitempty"`
+	// IdentityHeaderUserId Wire header name the proxy stamps with the caller's display identity (user email or peer name) when the catalog entry's HeaderPair is `customizable`. Always present in responses; empty disables stamping for this dimension. Ignored when the catalog entry has a fixed HeaderPair (e.g. LiteLLM, Portkey). Used today by Bifrost: typical values are `x-bf-lh-netbird_user_id` (always-on log metadata) or `x-bf-dim-netbird_user_id` (Prometheus / OTEL — requires the label to be pre-declared in the gateway's `client.prometheus_labels` config).
+	IdentityHeaderUserId string `json:"identity_header_user_id"`

 	// MetadataDisabled Whether identity metadata injection is disabled for this provider. When enabled (the default), the proxy stamps the caller's user and authorizing group onto upstream requests as provider-specific metadata (e.g. AWS Bedrock's X-Amzn-Bedrock-Request-Metadata header). Set true to suppress it.
 	MetadataDisabled bool `json:"metadata_disabled"`
@@ -2335,16 +2335,16 @@ type AgentNetworkProviderRequest struct {
 	// Enabled Whether the provider is enabled. Defaults to true on create.
 	Enabled *bool `json:"enabled,omitempty"`

-	// ExtraValues Operator-typed values for catalog-declared extra headers (see AgentNetworkProvider.extra_values). When present on a request, the whole map replaces the stored values. Empty strings drop the corresponding key.
+	// ExtraValues Operator-typed values for catalog-declared extra headers (see AgentNetworkProvider.extra_values). The request's map replaces the stored values; empty strings drop the corresponding key.
 	ExtraValues *map[string]string `json:"extra_values,omitempty"`

-	// IdentityHeaderGroups Wire header name for the caller's groups CSV. See AgentNetworkProvider.identity_header_groups. Same omit / empty semantics as `identity_header_user_id`.
+	// IdentityHeaderGroups Wire header name for the caller's groups CSV. See AgentNetworkProvider.identity_header_groups. Same semantics as `identity_header_user_id`.
 	IdentityHeaderGroups *string `json:"identity_header_groups,omitempty"`

-	// IdentityHeaderUserId Wire header name for the caller's display identity. See AgentNetworkProvider.identity_header_user_id. When omitted on a request, the stored value is left unchanged; pass an empty string explicitly to clear it (which disables stamping for this dimension).
+	// IdentityHeaderUserId Wire header name for the caller's display identity. See AgentNetworkProvider.identity_header_user_id. Empty or omitted disables stamping for this dimension.
 	IdentityHeaderUserId *string `json:"identity_header_user_id,omitempty"`

-	// MetadataDisabled Disable identity metadata injection (the caller's user + authorizing group) for this provider. Defaults to false (metadata is injected). When omitted on update, the stored value is left unchanged.
+	// MetadataDisabled Disable identity metadata injection (the caller's user + authorizing group) for this provider. Defaults to false (metadata is injected).
 	MetadataDisabled *bool `json:"metadata_disabled,omitempty"`

 	// Models Models exposed through this endpoint, with the operator's per-1k input/output prices. Empty means all catalog models are allowed at catalog prices.
@@ -2356,22 +2356,22 @@ type AgentNetworkProviderRequest struct {
 	// ProviderId Catalog identifier for the upstream AI provider (e.g. openai_api, anthropic_api, azure_openai_api, bedrock_api, vertex_ai_api, mistral_api, custom).
 	ProviderId string `json:"provider_id"`

-	// SkipTlsVerification Skip upstream TLS certificate verification when the proxy dials this provider's URL. For self-hosted / internal gateways behind a private or self-signed certificate. Defaults to false. When omitted on update, the stored value is left unchanged.
+	// SkipTlsVerification Skip upstream TLS certificate verification when the proxy dials this provider's URL. For self-hosted / internal gateways behind a private or self-signed certificate. Defaults to false.
 	SkipTlsVerification *bool `json:"skip_tls_verification,omitempty"`

 	// UpstreamUrl Full upstream URL (with scheme) that NetBird forwards traffic to.
 	UpstreamUrl string `json:"upstream_url"`
 }

-// AgentNetworkSettings Per-account Agent Network gateway settings. One row per account; cluster and subdomain are auto-assigned on first provider create and immutable thereafter.
+// AgentNetworkSettings Per-account Agent Network gateway settings. One row per account; cluster and subdomain are assigned at bootstrap and immutable thereafter. Before bootstrap the account reads as the default values with empty cluster, subdomain and endpoint.
 type AgentNetworkSettings struct {
 	// AccessLogRetentionDays Days to retain full access-log rows; older rows are swept. 0 or less means keep indefinitely. Usage records are retained independently.
 	AccessLogRetentionDays *int `json:"access_log_retention_days,omitempty"`

-	// Cluster Address of the NetBird proxy cluster fronting this account's agent-network endpoint.
+	// Cluster Address of the NetBird proxy cluster fronting this account's agent-network endpoint. Empty until the account is bootstrapped.
 	Cluster string `json:"cluster"`

-	// CreatedAt Timestamp when the settings row was created.
+	// CreatedAt Timestamp when the settings row was created. Absent until the account is bootstrapped.
 	CreatedAt *time.Time `json:"created_at,omitempty"`

 	// EnableLogCollection Whether per-request access-log entries are collected for this account's agent-network traffic.
@@ -2380,24 +2380,27 @@ type AgentNetworkSettings struct {
 	// EnablePromptCollection Master switch for request/response prompt capture. Capture runs only when this is on AND a policy guardrail also enables it.
 	EnablePromptCollection bool `json:"enable_prompt_collection"`

-	// Endpoint Bare hostname agents call for this account, computed as `<subdomain>.<cluster>`.
+	// Endpoint Bare hostname agents call for this account, computed as `<subdomain>.<cluster>`. Empty until the account is bootstrapped.
 	Endpoint string `json:"endpoint"`

 	// RedactPii Whether captured prompts have PII redacted. Effective redaction is the OR of this and any policy guardrail's redact setting.
 	RedactPii bool `json:"redact_pii"`

-	// Subdomain Auto-generated DNS-safe label that prefixes the cluster to form the agent-network endpoint.
+	// Subdomain Auto-generated DNS-safe label that prefixes the cluster to form the agent-network endpoint. Empty until the account is bootstrapped.
 	Subdomain string `json:"subdomain"`

-	// UpdatedAt Timestamp when the settings row was last updated.
+	// UpdatedAt Timestamp when the settings row was last updated. Absent until the account is bootstrapped.
 	UpdatedAt *time.Time `json:"updated_at,omitempty"`
 }

-// AgentNetworkSettingsRequest Mutable account-level Agent Network settings. Cluster and subdomain are immutable and not accepted here.
+// AgentNetworkSettingsRequest Account-level Agent Network settings update. The request replaces every mutable field. `cluster` additionally bootstraps the per-account settings row when the account does not have one yet; the subdomain is always server-assigned.
 type AgentNetworkSettingsRequest struct {
 	// AccessLogRetentionDays Days to retain full access-log rows; older rows are swept. 0 or less means keep indefinitely.
 	AccessLogRetentionDays *int `json:"access_log_retention_days,omitempty"`

+	// Cluster Address of the NetBird proxy cluster fronting this account's agent-network endpoint. When the account has no settings row yet, providing it bootstraps the row (assigning the subdomain that forms the agent endpoint). The cluster is immutable once assigned — later updates must omit it or send the assigned value; any other value is rejected.
+	Cluster *string `json:"cluster,omitempty"`
+
 	// EnableLogCollection Whether per-request access-log entries are collected for this account's agent-network traffic.
 	EnableLogCollection bool `json:"enable_log_collection"`

@@ -228,15 +228,17 @@ func DecodeEnvelope(env *proto.NetworkMapEnvelope) (*types.NetworkMapComponents,
 	return c, nil
 }

+// decodeAccountNetwork never returns nil — Calculate() dereferences
+// c.Network unconditionally, and servers that predate the fix omit the field
+// entirely from the empty-components envelope.
 func decodeAccountNetwork(an *proto.AccountNetwork) *types.Network {
+	n := &types.Network{}
 	if an == nil {
-		return nil
-	}
-	n := &types.Network{
-		Identifier: an.Identifier,
-		Dns:        an.Dns,
-		Serial:     an.Serial,
+		return n
 	}
+	n.Identifier = an.Identifier
+	n.Dns = an.Dns
+	n.Serial = an.Serial
 	if an.NetCidr != "" {
 		if _, ipnet, err := net.ParseCIDR(an.NetCidr); err == nil && ipnet != nil {
 			n.Net = *ipnet
@@ -292,6 +292,66 @@ func TestEnvelopeRoundTrip_AllGroupShortCircuitParity(t *testing.T) {
 		"client-side Calculate must connect the same remote peers as the server")
 }

+// TestEnvelopeToNetworkMap_EmptyComponents covers the graceful-degrade path
+// the server takes for a peer that is missing from the account or absent from
+// the validated-peers map. The legacy server short-circuited before
+// Calculate() and shipped a NetworkMap carrying only the account Network; the
+// components path runs Calculate() on the client instead, so the envelope must
+// carry Network or the client panics dereferencing a nil *types.Network.
+func TestEnvelopeToNetworkMap_EmptyComponents(t *testing.T) {
+	localPeerKey := randomWgKey(t)
+	c := types.EmptyNetworkMapComponents(&types.NetworkMapComponents{
+		PeerID: "peer-A",
+		Network: &types.Network{
+			Identifier: "net-empty",
+			Net:        net.IPNet{IP: net.IP{100, 64, 0, 0}, Mask: net.CIDRMask(10, 32)},
+			Serial:     7,
+		},
+		Peers: map[string]*types.ComponentPeer{
+			"peer-A": {ID: "peer-A", Key: localPeerKey, IP: netip.AddrFrom4([4]byte{100, 64, 0, 1})},
+		},
+	})
+
+	envelope := mgmtgrpc.EncodeNetworkMapEnvelope(mgmtgrpc.ComponentsEnvelopeInput{
+		Components: c,
+		DNSDomain:  "netbird.cloud",
+	})
+	require.NotNil(t, envelope.GetFull().Network, "empty envelope must carry the account Network")
+
+	wire, err := goproto.Marshal(envelope)
+	require.NoError(t, err, "marshal envelope")
+	var decoded proto.NetworkMapEnvelope
+	require.NoError(t, goproto.Unmarshal(wire, &decoded), "unmarshal envelope")
+
+	result, err := nbnetworkmap.EnvelopeToNetworkMap(context.Background(), &decoded, localPeerKey, "netbird.cloud")
+	require.NoError(t, err, "EnvelopeToNetworkMap must degrade gracefully on empty components")
+	require.Equal(t, uint64(7), result.NetworkMap.Serial)
+	require.Empty(t, result.NetworkMap.RemotePeers, "unvalidated peer connects to nobody")
+}
+
+// TestEnvelopeToNetworkMap_MissingNetwork simulates a server that omits
+// AccountNetwork from the envelope. Clients must degrade rather than panic, so
+// they survive talking to a management server that predates the encoder fix.
+func TestEnvelopeToNetworkMap_MissingNetwork(t *testing.T) {
+	c, localPeerKey := buildSmokeComponents(t)
+
+	envelope := mgmtgrpc.EncodeNetworkMapEnvelope(mgmtgrpc.ComponentsEnvelopeInput{
+		Components: c,
+		DNSDomain:  "netbird.cloud",
+	})
+	envelope.GetFull().Network = nil
+
+	wire, err := goproto.Marshal(envelope)
+	require.NoError(t, err, "marshal envelope")
+	var decoded proto.NetworkMapEnvelope
+	require.NoError(t, goproto.Unmarshal(wire, &decoded), "unmarshal envelope")
+
+	result, err := nbnetworkmap.EnvelopeToNetworkMap(context.Background(), &decoded, localPeerKey, "netbird.cloud")
+	require.NoError(t, err, "a missing AccountNetwork must not panic the client")
+	require.NotNil(t, result.Components.Network)
+	require.NotEmpty(t, result.NetworkMap.RemotePeers, "the rest of the snapshot stays usable")
+}
+
 // buildSmokeComponents returns a minimal NetworkMapComponents (2 peers, 1
 // group, 1 allow policy) plus the receiving peer's WG public key. Sufficient
 // to validate the encode → marshal → decode → Calculate pipeline produces
@@ -156,9 +156,11 @@ func (g *Guard) notifyReconnected() {
 func (g *Guard) exponentTicker(ctx context.Context) *backoff.Ticker {
 	bo := backoff.WithContext(&backoff.ExponentialBackOff{
 		InitialInterval: 2 * time.Second,
-		Multiplier:      2,
-		MaxInterval:     g.maxBackoffInterval,
-		Clock:           backoff.SystemClock,
+		// Spreads the reconnects of every client that lost the same relay server.
+		RandomizationFactor: backoff.DefaultRandomizationFactor,
+		Multiplier:          2,
+		MaxInterval:         g.maxBackoffInterval,
+		Clock:               backoff.SystemClock,
 	}, ctx)

 	return backoff.NewTicker(bo)