feat(agentnetwork): store the endpoint as domain + proxy address

Replace the settings row's (cluster, subdomain) identity columns with
(domain, proxy_address): domain is the endpoint hostname agents call,
proxy_address the declared cluster address of the proxy serving it. The
serving shape is the shape of the pin -- self-addressed (domain ==
proxy_address, a proxy dedicated to the account) or labeled (domain one
label beneath a shared cluster's address) -- so no mode flag or config
exists anywhere, and any mix of shapes coexists per account on one
deployment.

Bootstrap becomes an explicit POST /api/agent-network/settings taking
exactly one of proxy_address (the server allocates an adjective-noun
label beneath it) or endpoint (claimed verbatim, address-first). The
identity fields leave the PUT schema entirely -- immutability by shape
rather than by runtime rejection -- and provider create loses
bootstrap_cluster and all settings side effects, which also retires two
latent bugs: the dashboard's unsorted [0] free-domain pick making a
permanent decision, and bootstrap failures swallowed at debug level
inside a 200 provider create.

The global unique index moves from the label to the full hostname --
the actual invariant. Labels may repeat across clusters again, and
self-addressed rows (no label) cannot collide on an empty string. The
reverse lookup becomes a point query on that index, deleting the
clusterFromDomain suffix heuristic, and the synthesizer stamps
ProxyCluster from the settings row as a field read. A pre-AutoMigrate
migration backfills existing rows (domain = subdomain.cluster,
proxy_address = cluster) and drops the legacy columns, failing loudly
on rows with no identity to derive.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

management/internals/modules/agentnetwork/handlers/budget_handler_test.go

@@ -102,8 +102,8 @@ func TestSettingsHandler_GetExposesCollectionToggles(t *testing.T) {
 
 	require.NoError(t, f.store.SaveAgentNetworkSettings(context.Background(), &agentNetworkTypes.Settings{
 		AccountID:              testAccountID,
-		Cluster:                "eu.proxy.netbird.io",
-		Subdomain:              "violet",
+		Domain:                 "violet.eu.proxy.netbird.io",
+		ProxyAddress:           "eu.proxy.netbird.io",
 		EnableLogCollection:    true,
 		EnablePromptCollection: true,
 		RedactPii:              false,

management/internals/modules/agentnetwork/handlers/providers_handler.go

@@ -155,12 +155,7 @@ func (h *handler) createProvider(w http.ResponseWriter, r *http.Request) {
 	provider := types.NewProvider(userAuth.AccountId)
 	provider.FromAPIRequest(&req)
 
-	bootstrapCluster := ""
-	if req.BootstrapCluster != nil {
-		bootstrapCluster = *req.BootstrapCluster
-	}
-
-	created, err := h.manager.CreateProvider(r.Context(), userAuth.UserId, provider, bootstrapCluster)
+	created, err := h.manager.CreateProvider(r.Context(), userAuth.UserId, provider)
 	if err != nil {
 		util.WriteError(r.Context(), err, w)
 		return

management/internals/modules/agentnetwork/handlers/settings_handler.go

@@ -12,15 +12,54 @@ import (
 	"github.com/netbirdio/netbird/shared/management/http/util"
 )
 
-// addSettingsEndpoints registers the Agent Network settings routes. The
-// settings row is bootstrapped server-side on first provider create or on the
-// first PUT carrying a cluster; GET reads it and PUT applies a partial update
-// of the mutable collection toggles (cluster/subdomain stay immutable).
+// addSettingsEndpoints registers the Agent Network settings routes. POST
+// bootstraps the settings row, assigning the account's immutable endpoint;
+// GET reads it (defaults with an empty endpoint before bootstrap) and PUT
+// replaces the mutable collection toggles. The identity fields are not part
+// of the PUT schema — immutability by shape, not by rejection.
 func (h *handler) addSettingsEndpoints(router *mux.Router) {
 	router.HandleFunc("/agent-network/settings", h.getSettings).Methods("GET", "OPTIONS")
+	router.HandleFunc("/agent-network/settings", h.createSettings).Methods("POST", "OPTIONS")
 	router.HandleFunc("/agent-network/settings", h.updateSettings).Methods("PUT", "OPTIONS")
 }
 
+// createSettings bootstraps the account's settings row. Exactly one of
+// proxy_address (labeled endpoint; the server allocates the label) and
+// endpoint (self-addressed, claimed verbatim) must be provided; optional
+// collection toggles ride along with defaults for omitted fields.
+func (h *handler) createSettings(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	var req api.AgentNetworkSettingsCreateRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		util.WriteErrorResponse("couldn't parse JSON request", http.StatusBadRequest, w)
+		return
+	}
+
+	settings := types.DefaultSettings(userAuth.AccountId)
+	settings.FromAPICreateRequest(&req)
+
+	proxyAddress := ""
+	if req.ProxyAddress != nil {
+		proxyAddress = *req.ProxyAddress
+	}
+	endpoint := ""
+	if req.Endpoint != nil {
+		endpoint = *req.Endpoint
+	}
+
+	created, err := h.manager.CreateSettings(r.Context(), userAuth.UserId, settings, proxyAddress, endpoint)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+	util.WriteJSONObject(r.Context(), w, created.ToAPIResponse())
+}
+
 // updateSettings replaces the mutable settings fields on the account's row.
 // A request carrying a cluster bootstraps the row when the account doesn't
 // have one yet.

management/internals/modules/agentnetwork/handlers/settings_handler_test.go

@@ -3,6 +3,7 @@ package handlers
 import (
 	"encoding/json"
 	"net/http"
+	"strings"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -14,7 +15,7 @@ import (
 // TestSettingsHandler_GetUnbootstrappedReturnsDefaults pins the settings-read
 // convention shared with the account and DNS settings endpoints: settings
 // always read as a JSON object. Before bootstrap that object carries the
-// defaults with an empty cluster/subdomain/endpoint (the "not bootstrapped"
+// defaults with an empty endpoint/proxy_address (the "not bootstrapped"
 // signal) and no timestamps — never a 404 and never the legacy null body.
 func TestSettingsHandler_GetUnbootstrappedReturnsDefaults(t *testing.T) {
 	f := newAgentNetworkHandlerFixture(t)
@@ -27,9 +28,9 @@ func TestSettingsHandler_GetUnbootstrappedReturnsDefaults(t *testing.T) {
 
 	var got api.AgentNetworkSettings
 	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &got))
-	assert.Empty(t, got.Cluster, "cluster must be empty until bootstrapped")
-	assert.Empty(t, got.Subdomain, "subdomain must be empty until bootstrapped")
-	assert.Empty(t, got.Endpoint, "endpoint must be empty until bootstrapped, not a bare dot")
+	assert.Empty(t, got.Endpoint, "endpoint must be empty until bootstrapped")
+	assert.Empty(t, got.ProxyAddress, "proxy address must be empty until bootstrapped")
+	assert.False(t, got.Dedicated, "an unbootstrapped account has no serving shape")
 	assert.True(t, got.EnableLogCollection, "defaults must show log collection on, matching bootstrap")
 	assert.False(t, got.EnablePromptCollection, "defaults must show prompt collection off")
 	assert.False(t, got.RedactPii, "defaults must show redaction off")
@@ -39,56 +40,142 @@ func TestSettingsHandler_GetUnbootstrappedReturnsDefaults(t *testing.T) {
 	assert.Nil(t, got.UpdatedAt, "no timestamps before a row exists")
 }
 
-// TestSettingsHandler_PutBootstrapsWithCluster covers the settings-first
-// bootstrap path: a PUT carrying a cluster on an unbootstrapped account
-// creates the row (cluster pinned, subdomain assigned) and applies the
-// mutable fields from the same request.
-func TestSettingsHandler_PutBootstrapsWithCluster(t *testing.T) {
+// TestSettingsHandler_PostBootstrapsLabeled covers the labeled bootstrap
+// shape: a POST carrying a proxy_address allocates a label beneath it, so the
+// endpoint hangs one label under the shared cluster's address and the pin is
+// not dedicated. Toggles riding along apply; omitted ones keep defaults.
+func TestSettingsHandler_PostBootstrapsLabeled(t *testing.T) {
 	f := newAgentNetworkHandlerFixture(t)
 
-	rec := f.do(t, http.MethodPut, "/agent-network/settings",
-		`{"cluster": "eu.proxy.netbird.io", "enable_log_collection": true, "enable_prompt_collection": true, "redact_pii": false, "access_log_retention_days": 30}`)
-	require.Equal(t, http.StatusOK, rec.Code, "bootstrap PUT must succeed: %s", rec.Body.String())
+	rec := f.do(t, http.MethodPost, "/agent-network/settings",
+		`{"proxy_address": "eu.proxy.netbird.io", "enable_prompt_collection": true, "access_log_retention_days": 14}`)
+	require.Equal(t, http.StatusOK, rec.Code, "bootstrap POST must succeed: %s", rec.Body.String())
 
 	var got api.AgentNetworkSettings
 	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &got))
-	assert.Equal(t, "eu.proxy.netbird.io", got.Cluster, "cluster must be pinned from the request")
-	assert.NotEmpty(t, got.Subdomain, "subdomain must be assigned at bootstrap")
-	assert.Equal(t, got.Subdomain+".eu.proxy.netbird.io", got.Endpoint, "endpoint must combine subdomain and cluster")
-	assert.True(t, got.EnableLogCollection, "toggle from the bootstrap request must apply")
+	assert.Equal(t, "eu.proxy.netbird.io", got.ProxyAddress, "proxy address must be pinned from the request")
+	require.NotEmpty(t, got.Endpoint, "endpoint must be allocated at bootstrap")
+	assert.True(t, strings.HasSuffix(got.Endpoint, ".eu.proxy.netbird.io"),
+		"labeled endpoint must hang off the proxy address: %s", got.Endpoint)
+	label := strings.TrimSuffix(got.Endpoint, ".eu.proxy.netbird.io")
+	assert.NotContains(t, label, ".", "the allocated label must be a single DNS label: %s", label)
+	assert.False(t, got.Dedicated, "a labeled pin is not dedicated")
+	assert.True(t, got.EnableLogCollection, "omitted toggle must keep its default")
 	assert.True(t, got.EnablePromptCollection, "toggle from the bootstrap request must apply")
 	require.NotNil(t, got.AccessLogRetentionDays)
-	assert.Equal(t, 30, *got.AccessLogRetentionDays, "retention from the bootstrap request must apply")
+	assert.Equal(t, 14, *got.AccessLogRetentionDays, "retention from the bootstrap request must apply")
+	assert.NotNil(t, got.CreatedAt, "a persisted row carries timestamps")
 
 	// The row is now readable via GET.
 	rec = f.do(t, http.MethodGet, "/agent-network/settings", "")
 	require.Equal(t, http.StatusOK, rec.Code, "GET after bootstrap must succeed")
+	var read api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &read))
+	assert.Equal(t, got.Endpoint, read.Endpoint, "GET must return the bootstrapped endpoint")
 }
 
-// TestSettingsHandler_PutWithoutClusterOnUnbootstrapped pins that a PUT
-// without a cluster cannot conjure a settings row out of nothing — there is
-// no cluster to pin — and surfaces as 404 like the GET.
-func TestSettingsHandler_PutWithoutClusterOnUnbootstrapped(t *testing.T) {
+// TestSettingsHandler_PostBootstrapsSelfAddressed covers the dedicated shape:
+// a POST carrying an endpoint claims the hostname verbatim, the proxy address
+// equals it, and the pin reads as dedicated. The claim is legitimate before
+// any proxy declares the address (address-first).
+func TestSettingsHandler_PostBootstrapsSelfAddressed(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodPost, "/agent-network/settings",
+		`{"endpoint": "Brave-Otter.Gateway.Example.com"}`)
+	require.Equal(t, http.StatusOK, rec.Code, "bootstrap POST must succeed: %s", rec.Body.String())
+
+	var got api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &got))
+	assert.Equal(t, "brave-otter.gateway.example.com", got.Endpoint,
+		"endpoint must be claimed verbatim, lowercased")
+	assert.Equal(t, got.Endpoint, got.ProxyAddress, "self-addressed: the proxy address is the endpoint")
+	assert.True(t, got.Dedicated, "a self-addressed pin is dedicated")
+	assert.True(t, got.EnableLogCollection, "omitted toggles must keep their defaults")
+}
+
+// TestSettingsHandler_PostRequiresExactlyOneIdentityField pins the request
+// contract: proxy_address and endpoint are mutually exclusive and one is
+// required — both or neither is a validation error, not a guess.
+func TestSettingsHandler_PostRequiresExactlyOneIdentityField(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodPost, "/agent-network/settings", `{}`)
+	assert.Equal(t, http.StatusUnprocessableEntity, rec.Code,
+		"empty POST must be rejected: got %d body=%s", rec.Code, rec.Body.String())
+
+	rec = f.do(t, http.MethodPost, "/agent-network/settings",
+		`{"proxy_address": "eu.proxy.netbird.io", "endpoint": "brave-otter.gateway.example.com"}`)
+	assert.Equal(t, http.StatusUnprocessableEntity, rec.Code,
+		"POST with both identity fields must be rejected: got %d body=%s", rec.Code, rec.Body.String())
+}
+
+// TestSettingsHandler_PostRejectsMalformedHostnames pins per-write input
+// validation: shapes canonicalization cannot repair — trailing dots, embedded
+// whitespace, empty labels — are rejected with a validation error instead of
+// landing in an immutable column.
+func TestSettingsHandler_PostRejectsMalformedHostnames(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	for name, body := range map[string]string{
+		"trailing dot":     `{"endpoint": "gateway.example.com."}`,
+		"leading dot":      `{"endpoint": ".gateway.example.com"}`,
+		"inner whitespace": `{"endpoint": "gate way.example.com"}`,
+		"empty label":      `{"proxy_address": "eu..proxy.netbird.io"}`,
+	} {
+		rec := f.do(t, http.MethodPost, "/agent-network/settings", body)
+		assert.Equal(t, http.StatusUnprocessableEntity, rec.Code,
+			"%s must be rejected: got %d body=%s", name, rec.Code, rec.Body.String())
+	}
+}
+
+// TestSettingsHandler_PostConflictsOnSecondBootstrap pins that bootstrap is a
+// one-time create: a second POST returns 409 and leaves the row untouched.
+func TestSettingsHandler_PostConflictsOnSecondBootstrap(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodPost, "/agent-network/settings", `{"proxy_address": "eu.proxy.netbird.io"}`)
+	require.Equal(t, http.StatusOK, rec.Code, "first bootstrap must succeed: %s", rec.Body.String())
+	var first api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &first))
+
+	rec = f.do(t, http.MethodPost, "/agent-network/settings", `{"proxy_address": "us.proxy.netbird.io"}`)
+	assert.Equal(t, http.StatusConflict, rec.Code,
+		"second bootstrap must 409: got %d body=%s", rec.Code, rec.Body.String())
+
+	rec = f.do(t, http.MethodGet, "/agent-network/settings", "")
+	require.Equal(t, http.StatusOK, rec.Code)
+	var got api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &got))
+	assert.Equal(t, first.Endpoint, got.Endpoint, "the original endpoint must survive the rejected bootstrap")
+	assert.Equal(t, first.ProxyAddress, got.ProxyAddress, "the original proxy address must survive")
+}
+
+// TestSettingsHandler_PutBeforeBootstrapIs404 pins that a PUT cannot conjure a
+// settings row out of nothing — bootstrap is the explicit POST — and the
+// error points the caller there.
+func TestSettingsHandler_PutBeforeBootstrapIs404(t *testing.T) {
 	f := newAgentNetworkHandlerFixture(t)
 
 	rec := f.do(t, http.MethodPut, "/agent-network/settings",
 		`{"enable_log_collection": false, "enable_prompt_collection": false, "redact_pii": false}`)
 	assert.Equal(t, http.StatusNotFound, rec.Code,
-		"cluster-less PUT on an unbootstrapped account must 404: got %d body=%s", rec.Code, rec.Body.String())
-	assert.Contains(t, rec.Body.String(), "cluster",
-		"the error must point the caller at the bootstrap paths: %s", rec.Body.String())
+		"PUT on an unbootstrapped account must 404: got %d body=%s", rec.Code, rec.Body.String())
+	assert.Contains(t, rec.Body.String(), "/api/agent-network/settings",
+		"the error must point the caller at the bootstrap POST: %s", rec.Body.String())
 }
 
 // TestSettingsHandler_PutReplacesMutableFields pins the update contract shared
 // with the other PUT endpoints: the request replaces every mutable field, so a
 // toggle absent from the JSON lands as its zero value rather than being
-// preserved. Cluster and subdomain survive untouched.
+// preserved. The identity fields are not part of the PUT schema at all, so
+// the endpoint and proxy address survive updates by construction.
 func TestSettingsHandler_PutReplacesMutableFields(t *testing.T) {
 	f := newAgentNetworkHandlerFixture(t)
 
-	rec := f.do(t, http.MethodPut, "/agent-network/settings",
-		`{"cluster": "eu.proxy.netbird.io", "enable_log_collection": true, "enable_prompt_collection": true, "redact_pii": true, "access_log_retention_days": 14}`)
-	require.Equal(t, http.StatusOK, rec.Code, "bootstrap PUT must succeed: %s", rec.Body.String())
+	rec := f.do(t, http.MethodPost, "/agent-network/settings",
+		`{"proxy_address": "eu.proxy.netbird.io", "enable_prompt_collection": true, "redact_pii": true, "access_log_retention_days": 14}`)
+	require.Equal(t, http.StatusOK, rec.Code, "bootstrap POST must succeed: %s", rec.Body.String())
 
 	var before api.AgentNetworkSettings
 	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &before))
@@ -105,33 +192,6 @@ func TestSettingsHandler_PutReplacesMutableFields(t *testing.T) {
 	require.NotNil(t, got.AccessLogRetentionDays)
 	assert.Equal(t, 0, *got.AccessLogRetentionDays,
 		"retention absent from the request must land as the zero value — PUT replaces all mutable fields")
-	assert.Equal(t, before.Cluster, got.Cluster, "cluster must survive updates untouched")
-	assert.Equal(t, before.Subdomain, got.Subdomain, "subdomain must survive updates untouched")
-}
-
-// TestSettingsHandler_PutRejectsClusterChange pins cluster immutability: once
-// assigned, a differing cluster is rejected as a validation error instead of
-// being silently ignored, so callers never observe a value other than the one
-// they sent. Echoing the assigned cluster back stays valid, which lets
-// declarative clients send their full desired state idempotently.
-func TestSettingsHandler_PutRejectsClusterChange(t *testing.T) {
-	f := newAgentNetworkHandlerFixture(t)
-
-	rec := f.do(t, http.MethodPut, "/agent-network/settings",
-		`{"cluster": "eu.proxy.netbird.io", "enable_log_collection": true, "enable_prompt_collection": false, "redact_pii": false}`)
-	require.Equal(t, http.StatusOK, rec.Code, "bootstrap PUT must succeed: %s", rec.Body.String())
-
-	rec = f.do(t, http.MethodPut, "/agent-network/settings",
-		`{"cluster": "us.proxy.netbird.io", "enable_log_collection": true, "enable_prompt_collection": false, "redact_pii": false}`)
-	assert.Equal(t, http.StatusUnprocessableEntity, rec.Code,
-		"cluster change must be rejected as a validation error: got %d body=%s", rec.Code, rec.Body.String())
-
-	rec = f.do(t, http.MethodPut, "/agent-network/settings",
-		`{"cluster": "eu.proxy.netbird.io", "enable_log_collection": true, "enable_prompt_collection": false, "redact_pii": true}`)
-	require.Equal(t, http.StatusOK, rec.Code, "echoing the assigned cluster must stay valid: %s", rec.Body.String())
-
-	var got api.AgentNetworkSettings
-	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &got))
-	assert.Equal(t, "eu.proxy.netbird.io", got.Cluster, "cluster must be unchanged")
-	assert.True(t, got.RedactPii, "toggle sent alongside the echoed cluster must apply")
+	assert.Equal(t, before.Endpoint, got.Endpoint, "endpoint must survive updates untouched")
+	assert.Equal(t, before.ProxyAddress, got.ProxyAddress, "proxy address must survive updates untouched")
 }

management/internals/modules/agentnetwork/manager.go

@@ -47,7 +47,7 @@ func ensureSessionKeys(p *types.Provider) error {
 type Manager interface {
 	GetAllProviders(ctx context.Context, accountID, userID string) ([]*types.Provider, error)
 	GetProvider(ctx context.Context, accountID, userID, providerID string) (*types.Provider, error)
-	CreateProvider(ctx context.Context, userID string, provider *types.Provider, bootstrapCluster string) (*types.Provider, error)
+	CreateProvider(ctx context.Context, userID string, provider *types.Provider) (*types.Provider, error)
 	UpdateProvider(ctx context.Context, userID string, provider *types.Provider) (*types.Provider, error)
 	DeleteProvider(ctx context.Context, accountID, userID, providerID string) error
 
@@ -70,6 +70,7 @@ type Manager interface {
 	DeleteBudgetRule(ctx context.Context, accountID, userID, ruleID string) error
 
 	GetSettings(ctx context.Context, accountID, userID string) (*types.Settings, error)
+	CreateSettings(ctx context.Context, userID string, settings *types.Settings, proxyAddress, endpoint string) (*types.Settings, error)
 	UpdateSettings(ctx context.Context, userID string, settings *types.Settings) (*types.Settings, error)
 
 	ListConsumption(ctx context.Context, accountID, userID string) ([]*types.Consumption, error)
@@ -168,19 +169,14 @@ func (m *managerImpl) GetProvider(ctx context.Context, accountID, userID, provid
 	return m.store.GetAgentNetworkProviderByID(ctx, store.LockingStrengthNone, accountID, providerID)
 }
 
-// CreateProvider persists a new provider for the account. bootstrapCluster
-// is used only when the per-account agent-network Settings row hasn't
-// been created yet; otherwise it is ignored (the cluster is pinned on
-// Settings and every provider in the account routes through it).
-func (m *managerImpl) CreateProvider(ctx context.Context, userID string, provider *types.Provider, bootstrapCluster string) (*types.Provider, error) {
+// CreateProvider persists a new provider for the account. Providers have no
+// settings side effects: the account's endpoint is bootstrapped separately and
+// explicitly via CreateSettings, and every provider in the account routes
+// through it.
+func (m *managerImpl) CreateProvider(ctx context.Context, userID string, provider *types.Provider) (*types.Provider, error) {
 	if err := m.requirePermission(ctx, provider.AccountID, userID, modules.AgentNetworkProviders, operations.Create); err != nil {
 		return nil, err
 	}
-	if strings.TrimSpace(bootstrapCluster) != "" {
-		if err := m.requireSettingsBootstrapPermission(ctx, provider.AccountID, userID); err != nil {
-			return nil, err
-		}
-	}
 
 	// An empty api_key would silently produce a synthesised service
 	// that 401s on every upstream request. Surface the misconfiguration
@@ -204,16 +200,6 @@ func (m *managerImpl) CreateProvider(ctx context.Context, userID string, provide
 		return nil, fmt.Errorf("save agent network provider: %w", err)
 	}
 
-	if strings.TrimSpace(bootstrapCluster) != "" {
-		if _, err := m.bootstrapSettingsIfNeeded(ctx, m.store, provider.AccountID, bootstrapCluster); err != nil {
-			// The provider create has already succeeded; logging the
-			// bootstrap miss matches the plan's PoC behaviour. The synth
-			// path treats a missing settings row as a no-op, and the next
-			// provider create retries the bootstrap.
-			log.WithContext(ctx).Debugf("agent-network bootstrap settings for account %s on cluster %s: %v", provider.AccountID, bootstrapCluster, err)
-		}
-	}
-
 	m.accountManager.StoreEvent(ctx, userID, provider.ID, provider.AccountID, activity.AgentNetworkProviderCreated, provider.EventMeta())
 	m.reconcile(ctx, provider.AccountID)
 
@@ -558,48 +544,28 @@ func (m *managerImpl) DeleteBudgetRule(ctx context.Context, accountID, userID, r
 }
 
 // UpdateSettings replaces the mutable account-level settings — the collection
-// toggles and retention — on the account's row. When the account has no
-// settings row yet, a non-empty settings.Cluster bootstraps one (same path as
-// first provider create); without it the update fails with NotFound. On an
-// existing row the cluster and subdomain are immutable: a differing
-// settings.Cluster is rejected rather than silently ignored so callers never
-// observe a value other than what they sent. Because the collection toggles
-// change the synthesised service config (prompt-capture gating, access-log
-// emission), a reconcile is triggered so the proxy and peer network maps
-// converge on the new state.
+// toggles and retention — on the account's row. The identity fields (Domain,
+// ProxyAddress) are assigned at bootstrap (CreateSettings) and are not part of
+// the update surface at all; when the account has no settings row yet the
+// update fails with NotFound. Because the collection toggles change the
+// synthesised service config (prompt-capture gating, access-log emission), a
+// reconcile is triggered so the proxy and peer network maps converge on the
+// new state.
 func (m *managerImpl) UpdateSettings(ctx context.Context, userID string, settings *types.Settings) (*types.Settings, error) {
 	if err := m.requirePermission(ctx, settings.AccountID, userID, modules.AgentNetworkSettings, operations.Update); err != nil {
 		return nil, err
 	}
 
-	requestedCluster := strings.TrimSpace(settings.Cluster)
-
 	// The row lock from LockingStrengthUpdate only holds for the duration of
-	// the surrounding transaction, so the read, the cluster-immutability
-	// check, and the save must share one — otherwise concurrent PUTs could
-	// interleave between them.
+	// the surrounding transaction, so the read and the save must share one —
+	// otherwise concurrent PUTs could interleave between them.
 	var updated *types.Settings
 	err := m.store.ExecuteInTransaction(ctx, func(tx store.Store) error {
 		existing, err := tx.GetAgentNetworkSettings(ctx, store.LockingStrengthUpdate, settings.AccountID)
 		switch {
 		case err == nil:
-			if requestedCluster != "" && requestedCluster != existing.Cluster {
-				return status.Errorf(status.InvalidArgument, "cluster is immutable once assigned (current: %s)", existing.Cluster)
-			}
 		case isNotFound(err):
-			if requestedCluster == "" {
-				return status.Errorf(status.NotFound, "agent network settings have not been bootstrapped yet; pass cluster to bootstrap them, or create a provider with bootstrap_cluster set")
-			}
-			// Bootstrapping pins the cluster and subdomain — a settings
-			// create on top of the update the caller already passed, matching
-			// the gate on the provider-create bootstrap path.
-			if err := m.requirePermission(ctx, settings.AccountID, userID, modules.AgentNetworkSettings, operations.Create); err != nil {
-				return err
-			}
-			existing, err = m.bootstrapSettingsIfNeeded(ctx, tx, settings.AccountID, requestedCluster)
-			if err != nil {
-				return err
-			}
+			return status.Errorf(status.NotFound, "agent network settings have not been bootstrapped yet; POST /api/agent-network/settings to bootstrap them")
 		default:
 			return fmt.Errorf("get agent network settings: %w", err)
 		}
@@ -676,74 +642,162 @@ func (m *managerImpl) GetSettings(ctx context.Context, accountID, userID string)
 	}
 }
 
-// requireSettingsBootstrapPermission gates the one-time settings bootstrap a
-// first provider create performs. Pinning the account's cluster and subdomain
-// is a settings write, so it needs the settings permission on top of the
-// provider one. No-op once the settings row exists.
-func (m *managerImpl) requireSettingsBootstrapPermission(ctx context.Context, accountID, userID string) error {
-	_, err := m.store.GetAgentNetworkSettings(ctx, store.LockingStrengthNone, accountID)
-	if err == nil {
-		return nil
-	}
-	if !isNotFound(err) {
-		return fmt.Errorf("get agent network settings: %w", err)
-	}
-	return m.requirePermission(ctx, accountID, userID, modules.AgentNetworkSettings, operations.Create)
-}
+// maxDomainAllocationAttempts bounds the label search when bootstrapping a
+// labeled endpoint. Package-level (rather than function-local) so tests can
+// assert on the exhaustion path without duplicating the literal.
+const maxDomainAllocationAttempts = 10
 
-// bootstrapSettingsIfNeeded creates the per-account agent-network
-// settings row when missing. The cluster comes from the create-time
-// hint the dashboard sends (auto-picked from the active cluster list);
-// the subdomain is picked from the curated wordlist avoiding
-// collisions on the same cluster. Idempotent: if a row already exists
-// it is returned untouched and the hint is ignored. st is the store to
-// operate on — pass the transaction store when calling from within one.
-func (m *managerImpl) bootstrapSettingsIfNeeded(ctx context.Context, st store.Store, accountID, providerCluster string) (*types.Settings, error) {
-	if accountID == "" {
-		return nil, fmt.Errorf("bootstrap settings: account id is required")
+// CreateSettings bootstraps the per-account settings row, assigning the
+// account's immutable endpoint. Exactly one of proxyAddress and endpoint must
+// be non-empty: proxyAddress allocates a labeled endpoint one label beneath
+// the given cluster address; endpoint claims the given hostname verbatim as a
+// self-addressed (dedicated) endpoint — a legitimate claim before any proxy
+// declares the address (address-first). settings carries the account ID and
+// the initial collection toggles; its identity fields are assigned here.
+func (m *managerImpl) CreateSettings(ctx context.Context, userID string, settings *types.Settings, proxyAddress, endpoint string) (*types.Settings, error) {
+	if settings == nil || settings.AccountID == "" {
+		return nil, status.Errorf(status.InvalidArgument, "account id is required")
 	}
-	if strings.TrimSpace(providerCluster) == "" {
-		return nil, fmt.Errorf("bootstrap settings: provider cluster is required")
+	if err := m.requirePermission(ctx, settings.AccountID, userID, modules.AgentNetworkSettings, operations.Create); err != nil {
+		return nil, err
 	}
 
-	existing, err := st.GetAgentNetworkSettings(ctx, store.LockingStrengthNone, accountID)
-	if err == nil {
-		return existing, nil
+	hasProxyAddress := strings.TrimSpace(proxyAddress) != ""
+	hasEndpoint := strings.TrimSpace(endpoint) != ""
+	if hasProxyAddress == hasEndpoint {
+		return nil, status.Errorf(status.InvalidArgument, "exactly one of proxy_address and endpoint is required")
 	}
-	if !isNotFound(err) {
+
+	// Fail fast on an existing row for a clean 409; the insert below stays
+	// the authority against concurrent bootstraps (the primary key wins).
+	if _, err := m.store.GetAgentNetworkSettings(ctx, store.LockingStrengthNone, settings.AccountID); err == nil {
+		return nil, status.Errorf(status.AlreadyExists, "agent network settings already bootstrapped for account %s", settings.AccountID)
+	} else if !isNotFound(err) {
 		return nil, fmt.Errorf("get agent network settings: %w", err)
 	}
 
-	siblings, err := st.GetAgentNetworkSettingsByCluster(ctx, store.LockingStrengthNone, providerCluster)
-	if err != nil {
-		return nil, fmt.Errorf("list agent network settings on cluster: %w", err)
-	}
-	taken := make(map[string]struct{}, len(siblings))
-	for _, s := range siblings {
-		taken[s.Subdomain] = struct{}{}
-	}
-
-	suffix := accountID
-	if len(suffix) > 4 {
-		suffix = suffix[:4]
-	}
-
-	m.labelRngMu.Lock()
-	subdomain := labelgen.PickUnique(m.labelRng, taken, suffix)
-	m.labelRngMu.Unlock()
-
 	now := time.Now().UTC()
-	settings := types.DefaultSettings(accountID)
-	settings.Cluster = providerCluster
-	settings.Subdomain = subdomain
 	settings.CreatedAt = now
 	settings.UpdatedAt = now
-	if err := st.SaveAgentNetworkSettings(ctx, settings); err != nil {
-		return nil, fmt.Errorf("save agent network settings: %w", err)
+
+	var err error
+	if hasEndpoint {
+		err = m.bootstrapSelfAddressed(ctx, settings, endpoint)
+	} else {
+		err = m.bootstrapLabeled(ctx, settings, proxyAddress)
 	}
+	if err != nil {
+		return nil, err
+	}
+
+	m.accountManager.StoreEvent(ctx, userID, settings.AccountID, settings.AccountID, activity.AgentNetworkSettingsUpdated, map[string]any{
+		"bootstrapped": true,
+		"endpoint":     settings.Domain,
+		"dedicated":    settings.Dedicated(),
+	})
+	m.reconcile(ctx, settings.AccountID)
+
 	return settings, nil
 }
 
+// bootstrapSelfAddressed claims the given hostname as the account's endpoint,
+// served only by a proxy declaring exactly that address (Domain ==
+// ProxyAddress). The domain unique index is the arbiter of availability.
+func (m *managerImpl) bootstrapSelfAddressed(ctx context.Context, settings *types.Settings, endpoint string) error {
+	hostname, err := types.NormalizeHostname(endpoint)
+	if err != nil {
+		return status.Errorf(status.InvalidArgument, "invalid endpoint: %s", err)
+	}
+
+	settings.Domain = hostname
+	settings.ProxyAddress = hostname
+	if err := m.store.CreateAgentNetworkSettings(ctx, settings); err != nil {
+		if isUniqueConstraintError(err) {
+			// The violation is either the account primary key (a concurrent
+			// bootstrap for the same account won) or the domain index
+			// (another account holds the hostname). Distinguish by re-read.
+			if _, getErr := m.store.GetAgentNetworkSettings(ctx, store.LockingStrengthNone, settings.AccountID); getErr == nil {
+				return status.Errorf(status.AlreadyExists, "agent network settings already bootstrapped for account %s", settings.AccountID)
+			}
+			return status.Errorf(status.AlreadyExists, "endpoint %s is already taken", hostname)
+		}
+		return fmt.Errorf("create agent network settings: %w", err)
+	}
+	return nil
+}
+
+// bootstrapLabeled allocates a labeled endpoint one label beneath the given
+// cluster address: Domain = <label>.<proxyAddress>, served by whichever proxy
+// declares the parent. Labels are adjective-noun tuples; a candidate is
+// checked by read and the domain unique index stays the authority, so a
+// concurrent allocation of the same tuple surfaces as a unique violation and
+// another tuple is drawn.
+func (m *managerImpl) bootstrapLabeled(ctx context.Context, settings *types.Settings, proxyAddress string) error {
+	parent, err := types.NormalizeHostname(proxyAddress)
+	if err != nil {
+		return status.Errorf(status.InvalidArgument, "invalid proxy_address: %s", err)
+	}
+
+	for attempt := 1; attempt <= maxDomainAllocationAttempts; attempt++ {
+		m.labelRngMu.Lock()
+		label := labelgen.PickTuple(m.labelRng)
+		m.labelRngMu.Unlock()
+		if label == "" {
+			// Only reachable if either word pool were emptied. An empty label
+			// would produce a broken endpoint like ".example.com", so fail
+			// loudly rather than looping or inserting.
+			return fmt.Errorf("allocate agent network endpoint for account %s: label generator returned an empty label", settings.AccountID)
+		}
+
+		candidate, err := types.NormalizeHostname(label + "." + parent)
+		if err != nil {
+			return status.Errorf(status.InvalidArgument, "proxy_address leaves no room for a label: %s", err)
+		}
+
+		_, err = m.store.GetAgentNetworkSettingsByDomain(ctx, store.LockingStrengthNone, candidate)
+		if err == nil {
+			log.WithContext(ctx).Tracef("agent-network endpoint %q taken, retrying (attempt %d/%d)", candidate, attempt, maxDomainAllocationAttempts)
+			continue
+		}
+		if !isNotFound(err) {
+			return fmt.Errorf("check agent network endpoint availability: %w", err)
+		}
+
+		settings.Domain = candidate
+		settings.ProxyAddress = parent
+		if err := m.store.CreateAgentNetworkSettings(ctx, settings); err != nil {
+			if isUniqueConstraintError(err) {
+				// A concurrent bootstrap for the same account may have won on
+				// the primary key — return the conflict. A lost race on the
+				// domain index just means the tuple was taken between the
+				// read and the insert: draw another.
+				if _, getErr := m.store.GetAgentNetworkSettings(ctx, store.LockingStrengthNone, settings.AccountID); getErr == nil {
+					return status.Errorf(status.AlreadyExists, "agent network settings already bootstrapped for account %s", settings.AccountID)
+				}
+				log.WithContext(ctx).Tracef("agent-network endpoint %q lost an allocation race, retrying (attempt %d/%d)", candidate, attempt, maxDomainAllocationAttempts)
+				continue
+			}
+			return fmt.Errorf("create agent network settings: %w", err)
+		}
+		return nil
+	}
+
+	return fmt.Errorf("allocate agent network endpoint for account %s: %d attempts exhausted", settings.AccountID, maxDomainAllocationAttempts)
+}
+
+// isUniqueConstraintError reports whether err is a database unique-constraint
+// violation, matched on the driver message because CreateAgentNetworkSettings
+// deliberately returns the driver error unwrapped.
+func isUniqueConstraintError(err error) bool {
+	if err == nil {
+		return false
+	}
+	msg := err.Error()
+	return strings.Contains(msg, "(SQLSTATE 23505)") || // postgres
+		strings.Contains(msg, "Error 1062 (23000)") || // mysql
+		strings.Contains(msg, "UNIQUE constraint failed") // sqlite
+}
+
 // ListConsumption returns every consumption row recorded for the
 // account, ordered window-newest-first. Backs the dashboard's basic
 // counter view; permission gate is the same Read role that gates
@@ -877,7 +931,7 @@ func (*mockManager) GetProvider(_ context.Context, _, _, _ string) (*types.Provi
 	return &types.Provider{}, nil
 }
 
-func (*mockManager) CreateProvider(_ context.Context, _ string, p *types.Provider, _ string) (*types.Provider, error) {
+func (*mockManager) CreateProvider(_ context.Context, _ string, p *types.Provider) (*types.Provider, error) {
 	return p, nil
 }
 
@@ -945,6 +999,17 @@ func (*mockManager) GetSettings(_ context.Context, accountID, _ string) (*types.
 	return types.DefaultSettings(accountID), nil
 }
 
+func (*mockManager) CreateSettings(_ context.Context, _ string, s *types.Settings, proxyAddress, endpoint string) (*types.Settings, error) {
+	if endpoint != "" {
+		s.Domain = endpoint
+		s.ProxyAddress = endpoint
+	} else {
+		s.Domain = "mock." + proxyAddress
+		s.ProxyAddress = proxyAddress
+	}
+	return s, nil
+}
+
 func (*mockManager) UpdateSettings(_ context.Context, _ string, s *types.Settings) (*types.Settings, error) {
 	return s, nil
 }

management/internals/modules/agentnetwork/provider_bootstrap_test.go

@@ -1,134 +0,0 @@
-package agentnetwork
-
-import (
-	"context"
-	"runtime"
-	"testing"
-
-	"github.com/golang/mock/gomock"
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-
-	"github.com/netbirdio/netbird/management/internals/modules/agentnetwork/types"
-	"github.com/netbirdio/netbird/management/server/account"
-	"github.com/netbirdio/netbird/management/server/permissions"
-	"github.com/netbirdio/netbird/management/server/permissions/modules"
-	"github.com/netbirdio/netbird/management/server/permissions/operations"
-	"github.com/netbirdio/netbird/management/server/store"
-	nbtypes "github.com/netbirdio/netbird/management/server/types"
-	"github.com/netbirdio/netbird/shared/management/status"
-)
-
-// bootstrapFixture wires a real sqlite store to a gomock permissions manager
-// so tests can grant the provider permission while denying (or never
-// expecting) the settings one.
-type bootstrapFixture struct {
-	manager Manager
-	store   store.Store
-	perms   *permissions.MockManager
-}
-
-func newBootstrapFixture(t *testing.T) *bootstrapFixture {
-	t.Helper()
-	if runtime.GOOS == "windows" {
-		t.Skip("sqlite store not properly supported on Windows yet")
-	}
-	t.Setenv("NETBIRD_STORE_ENGINE", string(nbtypes.SqliteStoreEngine))
-
-	st, cleanUp, err := store.NewTestStoreFromSQL(context.Background(), "", t.TempDir())
-	require.NoError(t, err, "test store setup must succeed")
-	t.Cleanup(cleanUp)
-
-	ctrl := gomock.NewController(t)
-	perms := permissions.NewMockManager(ctrl)
-
-	accounts := account.NewMockManager(ctrl)
-	accounts.EXPECT().StoreEvent(gomock.Any(), gomock.Any(), gomock.Any(), gomock.Any(), gomock.Any(), gomock.Any()).AnyTimes()
-	accounts.EXPECT().UpdateAccountPeers(gomock.Any(), gomock.Any(), gomock.Any()).AnyTimes()
-	accounts.EXPECT().BufferUpdateAccountPeers(gomock.Any(), gomock.Any(), gomock.Any()).AnyTimes()
-
-	return &bootstrapFixture{
-		manager: NewManager(st, perms, accounts, nil),
-		store:   st,
-		perms:   perms,
-	}
-}
-
-func (f *bootstrapFixture) expectPermission(accountID, userID string, module modules.Module, op operations.Operation, allowed bool) {
-	f.perms.EXPECT().
-		ValidateUserPermissions(gomock.Any(), accountID, userID, module, op).
-		Return(allowed, context.Background(), nil)
-}
-
-func newBootstrapProvider(accountID string) *types.Provider {
-	p := types.NewProvider(accountID)
-	p.Name = "openai"
-	p.UpstreamURL = "https://api.openai.com"
-	p.APIKey = "sk-test"
-	p.Enabled = true
-	return p
-}
-
-// TestCreateProviderBootstrapRequiresSettingsPermission pins the gate on the
-// one-time settings bootstrap: creating the first provider with a
-// bootstrap_cluster pins the account's cluster and subdomain, which is a
-// settings write and must not ride on the providers permission alone.
-func TestCreateProviderBootstrapRequiresSettingsPermission(t *testing.T) {
-	ctx := context.Background()
-
-	t.Run("denied without settings permission", func(t *testing.T) {
-		f := newBootstrapFixture(t)
-		f.expectPermission("account1", "user1", modules.AgentNetworkProviders, operations.Create, true)
-		f.expectPermission("account1", "user1", modules.AgentNetworkSettings, operations.Create, false)
-
-		_, err := f.manager.CreateProvider(ctx, "user1", newBootstrapProvider("account1"), "cluster1.example.com")
-		require.Error(t, err, "bootstrap without settings permission must fail")
-		var sErr *status.Error
-		require.ErrorAs(t, err, &sErr)
-		assert.Equal(t, status.PermissionDenied, sErr.Type(), "denial should surface as permission denied")
-
-		providers, err := f.store.GetAccountAgentNetworkProviders(ctx, store.LockingStrengthNone, "account1")
-		require.NoError(t, err)
-		assert.Empty(t, providers, "provider must not be persisted when bootstrap is denied")
-		_, err = f.store.GetAgentNetworkSettings(ctx, store.LockingStrengthNone, "account1")
-		assert.Error(t, err, "settings row must not be created when bootstrap is denied")
-	})
-
-	t.Run("allowed with settings permission", func(t *testing.T) {
-		f := newBootstrapFixture(t)
-		f.expectPermission("account1", "user1", modules.AgentNetworkProviders, operations.Create, true)
-		f.expectPermission("account1", "user1", modules.AgentNetworkSettings, operations.Create, true)
-
-		created, err := f.manager.CreateProvider(ctx, "user1", newBootstrapProvider("account1"), "cluster1.example.com")
-		require.NoError(t, err, "bootstrap with both permissions must succeed")
-		require.NotNil(t, created)
-
-		settings, err := f.store.GetAgentNetworkSettings(ctx, store.LockingStrengthNone, "account1")
-		require.NoError(t, err, "bootstrap must create the settings row")
-		assert.Equal(t, "cluster1.example.com", settings.Cluster, "settings should pin the bootstrap cluster")
-	})
-
-	t.Run("existing settings need no settings permission", func(t *testing.T) {
-		f := newBootstrapFixture(t)
-		require.NoError(t, f.store.SaveAgentNetworkSettings(ctx, &types.Settings{
-			AccountID: "account1",
-			Cluster:   "cluster1.example.com",
-			Subdomain: "existing",
-		}), "pre-existing settings row setup must succeed")
-
-		// Only the providers permission may be consulted: gomock fails the
-		// test on any unexpected settings-permission call.
-		f.expectPermission("account1", "user1", modules.AgentNetworkProviders, operations.Create, true)
-
-		_, err := f.manager.CreateProvider(ctx, "user1", newBootstrapProvider("account1"), "cluster1.example.com")
-		require.NoError(t, err, "create with existing settings must not require the settings permission")
-	})
-
-	t.Run("no bootstrap cluster needs no settings permission", func(t *testing.T) {
-		f := newBootstrapFixture(t)
-		f.expectPermission("account1", "user1", modules.AgentNetworkProviders, operations.Create, true)
-
-		_, err := f.manager.CreateProvider(ctx, "user1", newBootstrapProvider("account1"), "")
-		require.NoError(t, err, "create without bootstrap must not require the settings permission")
-	})
-}

management/internals/modules/agentnetwork/reconcile_test.go

@@ -52,9 +52,9 @@ func newReconcileTestPolicy(providerID, sourceGroupID string) *types.Policy {
 
 func newReconcileTestSettings() *types.Settings {
 	return &types.Settings{
-		AccountID: "acct-1",
-		Cluster:   "eu.proxy.netbird.io",
-		Subdomain: "violet",
+		AccountID:    "acct-1",
+		Domain:       "violet.eu.proxy.netbird.io",
+		ProxyAddress: "eu.proxy.netbird.io",
 	}
 }
 

management/internals/modules/agentnetwork/settings_bootstrap_test.go

@@ -0,0 +1,225 @@
+package agentnetwork
+
+import (
+	"context"
+	"runtime"
+	"strings"
+	"testing"
+
+	"github.com/golang/mock/gomock"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/netbirdio/netbird/management/internals/modules/agentnetwork/types"
+	"github.com/netbirdio/netbird/management/server/account"
+	"github.com/netbirdio/netbird/management/server/permissions"
+	"github.com/netbirdio/netbird/management/server/permissions/modules"
+	"github.com/netbirdio/netbird/management/server/permissions/operations"
+	"github.com/netbirdio/netbird/management/server/store"
+	nbtypes "github.com/netbirdio/netbird/management/server/types"
+	"github.com/netbirdio/netbird/shared/management/status"
+)
+
+// bootstrapFixture wires a real sqlite store to a gomock permissions manager
+// so tests can grant or deny the settings permission per case.
+type bootstrapFixture struct {
+	manager Manager
+	store   store.Store
+	perms   *permissions.MockManager
+}
+
+func newBootstrapFixture(t *testing.T) *bootstrapFixture {
+	t.Helper()
+	if runtime.GOOS == "windows" {
+		t.Skip("sqlite store not properly supported on Windows yet")
+	}
+	t.Setenv("NETBIRD_STORE_ENGINE", string(nbtypes.SqliteStoreEngine))
+
+	st, cleanUp, err := store.NewTestStoreFromSQL(context.Background(), "", t.TempDir())
+	require.NoError(t, err, "test store setup must succeed")
+	t.Cleanup(cleanUp)
+
+	ctrl := gomock.NewController(t)
+	perms := permissions.NewMockManager(ctrl)
+
+	accounts := account.NewMockManager(ctrl)
+	accounts.EXPECT().StoreEvent(gomock.Any(), gomock.Any(), gomock.Any(), gomock.Any(), gomock.Any(), gomock.Any()).AnyTimes()
+	accounts.EXPECT().UpdateAccountPeers(gomock.Any(), gomock.Any(), gomock.Any()).AnyTimes()
+	accounts.EXPECT().BufferUpdateAccountPeers(gomock.Any(), gomock.Any(), gomock.Any()).AnyTimes()
+
+	return &bootstrapFixture{
+		manager: NewManager(st, perms, accounts, nil),
+		store:   st,
+		perms:   perms,
+	}
+}
+
+func (f *bootstrapFixture) expectPermission(accountID, userID string, module modules.Module, op operations.Operation, allowed bool) {
+	f.perms.EXPECT().
+		ValidateUserPermissions(gomock.Any(), accountID, userID, module, op).
+		Return(allowed, context.Background(), nil)
+}
+
+func (f *bootstrapFixture) createSettings(ctx context.Context, accountID, userID, proxyAddress, endpoint string) (*types.Settings, error) {
+	return f.manager.CreateSettings(ctx, userID, types.DefaultSettings(accountID), proxyAddress, endpoint)
+}
+
+// TestCreateSettingsRequiresPermission pins the gate: bootstrap assigns the
+// account's immutable endpoint, a settings write requiring the settings
+// Create permission — and a denial leaves no row behind.
+func TestCreateSettingsRequiresPermission(t *testing.T) {
+	ctx := context.Background()
+	f := newBootstrapFixture(t)
+	f.expectPermission("account1", "user1", modules.AgentNetworkSettings, operations.Create, false)
+
+	_, err := f.createSettings(ctx, "account1", "user1", "cluster1.example.com", "")
+	require.Error(t, err, "bootstrap without the settings permission must fail")
+	var sErr *status.Error
+	require.ErrorAs(t, err, &sErr)
+	assert.Equal(t, status.PermissionDenied, sErr.Type(), "denial should surface as permission denied")
+
+	_, err = f.store.GetAgentNetworkSettings(ctx, store.LockingStrengthNone, "account1")
+	assert.Error(t, err, "settings row must not be created when bootstrap is denied")
+}
+
+// TestCreateSettingsLabeled pins the labeled shape: the server allocates an
+// adjective-noun label beneath the proxy address, the pin is not dedicated,
+// and the domain records the full endpoint hostname.
+func TestCreateSettingsLabeled(t *testing.T) {
+	ctx := context.Background()
+	f := newBootstrapFixture(t)
+	f.expectPermission("account1", "user1", modules.AgentNetworkSettings, operations.Create, true)
+
+	created, err := f.createSettings(ctx, "account1", "user1", "Cluster1.Example.com", "")
+	require.NoError(t, err, "labeled bootstrap must succeed")
+	assert.Equal(t, "cluster1.example.com", created.ProxyAddress, "proxy address must be pinned lowercased")
+	require.True(t, strings.HasSuffix(created.Domain, ".cluster1.example.com"),
+		"domain must hang one label beneath the proxy address: %s", created.Domain)
+	label := strings.TrimSuffix(created.Domain, ".cluster1.example.com")
+	assert.NotContains(t, label, ".", "the allocated label must be a single DNS label: %s", label)
+	assert.False(t, created.Dedicated(), "a labeled pin is not dedicated")
+	assert.Equal(t, created.Domain, created.Endpoint(), "the endpoint is the domain column")
+
+	stored, err := f.store.GetAgentNetworkSettings(ctx, store.LockingStrengthNone, "account1")
+	require.NoError(t, err, "bootstrap must persist the row")
+	assert.Equal(t, created.Domain, stored.Domain)
+	assert.Equal(t, created.ProxyAddress, stored.ProxyAddress)
+}
+
+// TestCreateSettingsSelfAddressed pins the dedicated shape: the endpoint is
+// claimed verbatim (normalized), Domain == ProxyAddress, and the claim
+// succeeds with no proxy declaring the address yet (address-first).
+func TestCreateSettingsSelfAddressed(t *testing.T) {
+	ctx := context.Background()
+	f := newBootstrapFixture(t)
+	f.expectPermission("account1", "user1", modules.AgentNetworkSettings, operations.Create, true)
+
+	created, err := f.createSettings(ctx, "account1", "user1", "", "Brave-Otter.GW.Example.com")
+	require.NoError(t, err, "self-addressed bootstrap must succeed")
+	assert.Equal(t, "brave-otter.gw.example.com", created.Domain, "endpoint must be claimed lowercased")
+	assert.Equal(t, created.Domain, created.ProxyAddress, "self-addressed: proxy address is the endpoint")
+	assert.True(t, created.Dedicated(), "a self-addressed pin is dedicated")
+}
+
+// TestCreateSettingsIdentityFieldValidation pins the request contract: exactly
+// one of proxyAddress and endpoint, and both must be well-formed hostnames.
+func TestCreateSettingsIdentityFieldValidation(t *testing.T) {
+	ctx := context.Background()
+
+	cases := map[string]struct {
+		proxyAddress string
+		endpoint     string
+	}{
+		"neither":               {"", ""},
+		"both":                  {"cluster1.example.com", "gw.example.com"},
+		"trailing dot endpoint": {"", "gw.example.com."},
+		"leading dot endpoint":  {"", ".gw.example.com"},
+		"whitespace inside":     {"", "g w.example.com"},
+		"empty label in parent": {"eu..example.com", ""},
+		"hyphen-edged label":    {"", "-gw.example.com"},
+	}
+	for name, tc := range cases {
+		t.Run(name, func(t *testing.T) {
+			f := newBootstrapFixture(t)
+			f.expectPermission("account1", "user1", modules.AgentNetworkSettings, operations.Create, true)
+
+			_, err := f.createSettings(ctx, "account1", "user1", tc.proxyAddress, tc.endpoint)
+			require.Error(t, err, "invalid identity input must be rejected")
+			var sErr *status.Error
+			require.ErrorAs(t, err, &sErr)
+			assert.Equal(t, status.InvalidArgument, sErr.Type(), "rejection must be a validation error")
+
+			_, err = f.store.GetAgentNetworkSettings(ctx, store.LockingStrengthNone, "account1")
+			assert.Error(t, err, "no row may be left behind by a rejected bootstrap")
+		})
+	}
+}
+
+// TestCreateSettingsConflictsOnSecondBootstrap pins that bootstrap is a
+// one-time create per account: a second call is a conflict, whatever shape it
+// asks for, and the original row survives untouched.
+func TestCreateSettingsConflictsOnSecondBootstrap(t *testing.T) {
+	ctx := context.Background()
+	f := newBootstrapFixture(t)
+	f.expectPermission("account1", "user1", modules.AgentNetworkSettings, operations.Create, true)
+
+	first, err := f.createSettings(ctx, "account1", "user1", "cluster1.example.com", "")
+	require.NoError(t, err)
+
+	f.expectPermission("account1", "user1", modules.AgentNetworkSettings, operations.Create, true)
+	_, err = f.createSettings(ctx, "account1", "user1", "", "other.example.com")
+	require.Error(t, err, "second bootstrap must fail")
+	var sErr *status.Error
+	require.ErrorAs(t, err, &sErr)
+	assert.Equal(t, status.AlreadyExists, sErr.Type(), "second bootstrap must surface as a conflict")
+
+	stored, err := f.store.GetAgentNetworkSettings(ctx, store.LockingStrengthNone, "account1")
+	require.NoError(t, err)
+	assert.Equal(t, first.Domain, stored.Domain, "the original endpoint must survive the rejected bootstrap")
+}
+
+// TestCreateSettingsEndpointTaken pins global hostname uniqueness: a hostname
+// held by one account cannot be claimed by another, in either direction —
+// self-addressed onto self-addressed, or self-addressed onto an allocated
+// labeled endpoint.
+func TestCreateSettingsEndpointTaken(t *testing.T) {
+	ctx := context.Background()
+	f := newBootstrapFixture(t)
+
+	f.expectPermission("account1", "user1", modules.AgentNetworkSettings, operations.Create, true)
+	first, err := f.createSettings(ctx, "account1", "user1", "", "gw.example.com")
+	require.NoError(t, err)
+
+	f.expectPermission("account2", "user2", modules.AgentNetworkSettings, operations.Create, true)
+	_, err = f.createSettings(ctx, "account2", "user2", "", "gw.example.com")
+	require.Error(t, err, "a taken hostname must be refused")
+	var sErr *status.Error
+	require.ErrorAs(t, err, &sErr)
+	assert.Equal(t, status.AlreadyExists, sErr.Type(), "the refusal must surface as a conflict")
+
+	f.expectPermission("account3", "user3", modules.AgentNetworkSettings, operations.Create, true)
+	_, err = f.createSettings(ctx, "account3", "user3", "", first.Domain)
+	require.Error(t, err, "claiming another account's endpoint must be refused")
+}
+
+// TestCreateProviderHasNoSettingsSideEffects pins the decoupling: provider
+// create needs only the providers permission (gomock fails the test on any
+// settings-permission call) and never creates a settings row.
+func TestCreateProviderHasNoSettingsSideEffects(t *testing.T) {
+	ctx := context.Background()
+	f := newBootstrapFixture(t)
+	f.expectPermission("account1", "user1", modules.AgentNetworkProviders, operations.Create, true)
+
+	provider := types.NewProvider("account1")
+	provider.Name = "openai"
+	provider.UpstreamURL = "https://api.openai.com"
+	provider.APIKey = "sk-test"
+	provider.Enabled = true
+
+	created, err := f.manager.CreateProvider(ctx, "user1", provider)
+	require.NoError(t, err, "provider create must succeed on the providers permission alone")
+	require.NotNil(t, created)
+
+	_, err = f.store.GetAgentNetworkSettings(ctx, store.LockingStrengthNone, "account1")
+	assert.Error(t, err, "provider create must not conjure a settings row")
+}

management/internals/modules/agentnetwork/synthesizer.go

@@ -89,7 +89,7 @@ func SynthesizeServicesForCluster(ctx context.Context, s store.Store, clusterAdd
 		return nil, nil
 	}
 
-	settingsRows, err := s.GetAgentNetworkSettingsByCluster(ctx, store.LockingStrengthNone, clusterAddr)
+	settingsRows, err := s.GetAgentNetworkSettingsByProxyAddress(ctx, store.LockingStrengthNone, clusterAddr)
 	if err != nil {
 		return nil, fmt.Errorf("list agent network settings on cluster: %w", err)
 	}
@@ -116,53 +116,41 @@ func SynthesizeServicesForCluster(ctx context.Context, s store.Store, clusterAdd
 }
 
 // SynthesizeServiceForDomain resolves a single agent-network service by its
-// public endpoint domain. It lists the (few) settings rows on the domain's
-// cluster, matches the one whose endpoint equals the domain, and synthesises
-// only that account — avoiding full per-account synthesis for every tenant on
-// the cluster, which is what auth/session paths previously paid. Returns nil
-// (no error) when no account owns the domain.
+// public endpoint domain — a point query on the settings domain unique index,
+// then synthesis of just that account. Returns nil (no error) when no account
+// owns the domain.
 func SynthesizeServiceForDomain(ctx context.Context, s store.Store, domain string) (*rpservice.Service, error) {
-	domain = strings.TrimSpace(domain)
-	cluster := clusterFromDomain(domain)
-	if domain != "" && cluster != "" {
-		settingsRows, err := s.GetAgentNetworkSettingsByCluster(ctx, store.LockingStrengthNone, cluster)
-		if err != nil {
-			return nil, fmt.Errorf("list agent network settings on cluster: %w", err)
+	domain = strings.ToLower(strings.TrimSpace(domain))
+	if domain == "" {
+		return nil, nil //nolint:nilnil // optional lookup: no account owns the domain
+	}
+
+	settings, err := s.GetAgentNetworkSettingsByDomain(ctx, store.LockingStrengthNone, domain)
+	if err != nil {
+		if isNotFound(err) {
+			return nil, nil //nolint:nilnil // optional lookup: no account owns the domain
 		}
-		for _, settings := range settingsRows {
-			if settings == nil || settings.Endpoint() != domain {
-				continue
-			}
-			services, serr := SynthesizeServices(ctx, s, settings.AccountID)
-			if serr != nil {
-				return nil, serr
-			}
-			for _, svc := range services {
-				if svc != nil && svc.Domain == domain {
-					return svc, nil
-				}
-			}
-			break
+		return nil, fmt.Errorf("get agent network settings by domain: %w", err)
+	}
+
+	services, err := SynthesizeServices(ctx, s, settings.AccountID)
+	if err != nil {
+		return nil, err
+	}
+	for _, svc := range services {
+		if svc != nil && svc.Domain == domain {
+			return svc, nil
 		}
 	}
 	return nil, nil //nolint:nilnil // optional lookup: no account owns the domain
 }
 
-// clusterFromDomain returns the cluster portion of an endpoint domain (every
-// label after the first).
-func clusterFromDomain(domain string) string {
-	if i := strings.IndexByte(domain, '.'); i >= 0 {
-		return domain[i+1:]
-	}
-	return ""
-}
-
 // SynthesizeServices builds the in-memory reverse-proxy service that
 // fronts the account's agent-network gateway. Returns nil when the
 // account has no settings row, no enabled providers, or no enabled
 // policies — in any of those cases there's nothing useful to expose.
 //
-// One service per (account, settings.Cluster) is emitted. The router
+// One service per (account, settings.ProxyAddress) is emitted. The router
 // middleware encodes a denormalised model→provider routing table
 // (auth headers + decrypted API keys baked in); the policy_check
 // middleware encodes per-provider authorised group IDs derived from
@@ -175,7 +163,7 @@ func SynthesizeServices(ctx context.Context, s store.Store, accountID string) ([
 	if err != nil {
 		return nil, err
 	}
-	if !ok || strings.TrimSpace(settings.Cluster) == "" {
+	if !ok || strings.TrimSpace(settings.ProxyAddress) == "" {
 		return nil, nil
 	}
 
@@ -934,7 +922,7 @@ func buildAccountService(
 	middlewares []rpservice.MiddlewareConfig,
 	sessionPriv, sessionPub string,
 ) *rpservice.Service {
-	cluster := settings.Cluster
+	cluster := settings.ProxyAddress
 	domain := settings.Endpoint()
 	serviceID := SynthesizedServiceIDPrefix + accountID
 

management/internals/modules/agentnetwork/synthesizer_test.go

@@ -19,15 +19,14 @@ import (
 const (
 	testAccountID = "acct-1"
 	testCluster   = "eu.proxy.netbird.io"
-	testSubdomain = "violet"
 	testEndpoint  = "violet.eu.proxy.netbird.io"
 )
 
 func newSynthTestSettings() *types.Settings {
 	return &types.Settings{
-		AccountID: testAccountID,
-		Cluster:   testCluster,
-		Subdomain: testSubdomain,
+		AccountID:    testAccountID,
+		Domain:       testEndpoint,
+		ProxyAddress: testCluster,
 	}
 }
 

management/internals/modules/agentnetwork/types/settings.go

@@ -1,6 +1,7 @@
 package types
 
 import (
+	"fmt"
 	"strings"
 	"time"
 
@@ -12,13 +13,23 @@ import (
 // the long-term aggregate and are retained independently.
 const DefaultAccessLogRetentionDays = 30
 
-// Settings is the per-account agent-network configuration row. One
-// row per account. Cluster + Subdomain are immutable once written and
-// produce the public endpoint agents call (`<subdomain>.<cluster>`).
+// Settings is the per-account agent-network configuration row. One row per
+// account. Domain and ProxyAddress are assigned at bootstrap and immutable
+// thereafter; a persisted row is always fully allocated — there is no "row
+// exists, endpoint pending" state.
 type Settings struct {
 	AccountID string `gorm:"primaryKey"`
-	Cluster   string
-	Subdomain string `gorm:"index:idx_agent_network_settings_cluster_subdomain"`
+
+	// Domain is the gateway endpoint hostname agents call. Globally unique
+	// across accounts. Sized explicitly because MySQL cannot index an
+	// unbounded TEXT column; 255 covers the RFC 1035 253-octet bound.
+	Domain string `gorm:"type:varchar(255);uniqueIndex:idx_agent_network_settings_domain"`
+
+	// ProxyAddress is the declared cluster address of the proxy serving this
+	// account's gateway. Either equal to Domain — a proxy dedicated to this
+	// account, declaring the tenant's own hostname — or Domain's immediate
+	// parent, with the endpoint one label beneath it on a shared cluster.
+	ProxyAddress string `gorm:"type:varchar(255);index:idx_agent_network_settings_proxy_address"`
 
 	// Account-level collection controls sourced by the synthesizer.
 	// EnableLogCollection gates the per-request access-log trail and defaults
@@ -45,9 +56,9 @@ func (Settings) TableName() string { return "agent_network_settings" }
 
 // DefaultSettings returns the settings an account observes before its row is
 // bootstrapped: log collection on with the default retention, everything else
-// off, and no cluster/subdomain assigned yet. Bootstrap persists exactly these
-// values plus the assigned cluster and subdomain, so the pre-bootstrap read
-// and the freshly bootstrapped row agree.
+// off, and no domain or proxy address assigned yet. Bootstrap persists exactly
+// these values plus the assigned domain and proxy address, so the
+// pre-bootstrap read and the freshly bootstrapped row agree.
 func DefaultSettings(accountID string) *Settings {
 	return &Settings{
 		AccountID:              accountID,
@@ -56,14 +67,15 @@ func DefaultSettings(accountID string) *Settings {
 	}
 }
 
-// Endpoint returns the bare hostname agents reach this account at:
-// `<subdomain>.<cluster>`. Empty until both halves are assigned at bootstrap.
-func (s *Settings) Endpoint() string {
-	if s.Cluster == "" || s.Subdomain == "" {
-		return ""
-	}
-	return s.Subdomain + "." + s.Cluster
-}
+// Endpoint returns the bare hostname agents reach this account at — the
+// Domain column. Empty until the row is bootstrapped.
+func (s *Settings) Endpoint() string { return s.Domain }
+
+// Dedicated reports whether the account's gateway is served by a proxy
+// dedicated to it — the self-addressed shape, where the serving proxy declares
+// the endpoint hostname itself. The alternative (labeled) shape has the
+// endpoint one label beneath a shared cluster's address.
+func (s *Settings) Dedicated() bool { return s.Domain != "" && s.Domain == s.ProxyAddress }
 
 // ToAPIResponse renders the settings as the API representation. The
 // timestamps are omitted while zero — a default (not yet bootstrapped) view
@@ -71,9 +83,9 @@ func (s *Settings) Endpoint() string {
 func (s *Settings) ToAPIResponse() *api.AgentNetworkSettings {
 	retention := s.AccessLogRetentionDays
 	resp := &api.AgentNetworkSettings{
-		Cluster:                s.Cluster,
-		Subdomain:              s.Subdomain,
 		Endpoint:               s.Endpoint(),
+		ProxyAddress:           s.ProxyAddress,
+		Dedicated:              s.Dedicated(),
 		EnableLogCollection:    s.EnableLogCollection,
 		EnablePromptCollection: s.EnablePromptCollection,
 		RedactPii:              s.RedactPii,
@@ -90,15 +102,11 @@ func (s *Settings) ToAPIResponse() *api.AgentNetworkSettings {
 	return resp
 }
 
-// FromAPIRequest applies the request onto the receiver. The mutable
-// collection fields are always replaced with the request values. Cluster
-// participates only in bootstrap and the immutability check (see
-// Manager.UpdateSettings); Subdomain is server-assigned and never taken
-// from a request.
+// FromAPIRequest applies the update request onto the receiver: the mutable
+// collection fields are always replaced with the request values. The identity
+// fields (Domain, ProxyAddress) are assigned at bootstrap and are not part of
+// the update schema at all — immutability by shape, not by rejection.
 func (s *Settings) FromAPIRequest(req *api.AgentNetworkSettingsRequest) {
-	if req.Cluster != nil {
-		s.Cluster = strings.TrimSpace(*req.Cluster)
-	}
 	s.EnableLogCollection = req.EnableLogCollection
 	s.EnablePromptCollection = req.EnablePromptCollection
 	s.RedactPii = req.RedactPii
@@ -106,3 +114,69 @@ func (s *Settings) FromAPIRequest(req *api.AgentNetworkSettingsRequest) {
 		s.AccessLogRetentionDays = *req.AccessLogRetentionDays
 	}
 }
+
+// FromAPICreateRequest applies the optional collection toggles of a bootstrap
+// request onto the receiver (typically DefaultSettings), leaving defaults in
+// place for omitted fields. The identity fields are resolved by the manager
+// from the request's proxy_address / endpoint, not copied here.
+func (s *Settings) FromAPICreateRequest(req *api.AgentNetworkSettingsCreateRequest) {
+	if req.EnableLogCollection != nil {
+		s.EnableLogCollection = *req.EnableLogCollection
+	}
+	if req.EnablePromptCollection != nil {
+		s.EnablePromptCollection = *req.EnablePromptCollection
+	}
+	if req.RedactPii != nil {
+		s.RedactPii = *req.RedactPii
+	}
+	if req.AccessLogRetentionDays != nil {
+		s.AccessLogRetentionDays = *req.AccessLogRetentionDays
+	}
+}
+
+// maxHostnameLength is the RFC 1035 bound on a full domain name.
+const maxHostnameLength = 253
+
+// NormalizeHostname lowercases and trims a caller-supplied hostname and
+// validates its shape: non-empty DNS labels of letters, digits and inner
+// hyphens, joined by single dots, within length bounds. Shapes that
+// canonicalization cannot repair — leading/trailing dots, empty labels,
+// whitespace inside the name — are rejected rather than guessed at, because
+// the value lands in an immutable column.
+func NormalizeHostname(raw string) (string, error) {
+	hostname := strings.ToLower(strings.TrimSpace(raw))
+	if hostname == "" {
+		return "", fmt.Errorf("hostname is empty")
+	}
+	if len(hostname) > maxHostnameLength {
+		return "", fmt.Errorf("hostname exceeds %d characters", maxHostnameLength)
+	}
+	for _, label := range strings.Split(hostname, ".") {
+		if err := validateHostnameLabel(label); err != nil {
+			return "", fmt.Errorf("invalid hostname %q: %w", hostname, err)
+		}
+	}
+	return hostname, nil
+}
+
+func validateHostnameLabel(label string) error {
+	if label == "" {
+		return fmt.Errorf("empty label (leading, trailing or doubled dot)")
+	}
+	if len(label) > 63 {
+		return fmt.Errorf("label %q exceeds 63 characters", label)
+	}
+	if label[0] == '-' || label[len(label)-1] == '-' {
+		return fmt.Errorf("label %q must not start or end with a hyphen", label)
+	}
+	for _, r := range label {
+		switch {
+		case r >= 'a' && r <= 'z':
+		case r >= '0' && r <= '9':
+		case r == '-':
+		default:
+			return fmt.Errorf("label %q contains invalid character %q", label, r)
+		}
+	}
+	return nil
+}

management/server/agentnetwork_budgetrule_realstack_test.go

@@ -68,7 +68,8 @@ func TestAgentNetwork_BudgetRuleCRUD_RealManager(t *testing.T) {
 
 // TestAgentNetwork_UpdateSettings_PreservesImmutableAndTogglesCollection is the
 // GC-1 guard for UpdateSettings: it must apply the collection toggles while
-// preserving the immutable Cluster/Subdomain pinned at bootstrap.
+// preserving the immutable Domain/ProxyAddress assigned at bootstrap — the
+// identity fields are not part of the update surface at all.
 func TestAgentNetwork_UpdateSettings_PreservesImmutableAndTogglesCollection(t *testing.T) {
 	am, _, err := createManager(t)
 	require.NoError(t, err, "createManager must succeed")
@@ -84,7 +85,14 @@ func TestAgentNetwork_UpdateSettings_PreservesImmutableAndTogglesCollection(t *t
 
 	mgr := agentnetwork.NewManager(am.Store, permissions.NewManager(am.Store), am, nil)
 
-	// Creating a provider bootstraps the settings row (cluster + subdomain).
+	// Bootstrap is an explicit settings create; providers have no settings
+	// side effects anymore.
+	before, err := mgr.CreateSettings(ctx, adminUserID, agenttypes.DefaultSettings(accountID), clusterAddr, "")
+	require.NoError(t, err, "CreateSettings must bootstrap the row")
+	require.Equal(t, clusterAddr, before.ProxyAddress, "proxy address pinned at bootstrap")
+	require.NotEmpty(t, before.Domain, "endpoint allocated at bootstrap")
+	assert.False(t, before.EnablePromptCollection, "prompt collection defaults off")
+
 	_, err = mgr.CreateProvider(ctx, adminUserID, &agenttypes.Provider{
 		AccountID:   accountID,
 		ProviderID:  "openai_api",
@@ -93,43 +101,30 @@ func TestAgentNetwork_UpdateSettings_PreservesImmutableAndTogglesCollection(t *t
 		APIKey:      "sk-test",
 		Enabled:     true,
 		Models:      []agenttypes.ProviderModel{{ID: "gpt-5.4"}},
-	}, clusterAddr)
-	require.NoError(t, err, "CreateProvider must bootstrap settings")
-
-	before, err := mgr.GetSettings(ctx, accountID, adminUserID)
-	require.NoError(t, err, "GetSettings must succeed after bootstrap")
-	require.Equal(t, clusterAddr, before.Cluster, "cluster pinned at bootstrap")
-	require.NotEmpty(t, before.Subdomain, "subdomain pinned at bootstrap")
-	assert.False(t, before.EnablePromptCollection, "prompt collection defaults off")
-
-	// A cluster different from the one pinned at bootstrap must be rejected
-	// outright — never silently swapped or ignored.
-	_, err = mgr.UpdateSettings(ctx, adminUserID, &agenttypes.Settings{
-		AccountID:           accountID,
-		Cluster:             "attacker.cluster",
-		EnableLogCollection: true,
 	})
-	require.Error(t, err, "UpdateSettings with a mismatched cluster must fail")
+	require.NoError(t, err, "CreateProvider must succeed")
 
-	// Flipping the toggles works with the pinned cluster echoed back (and
-	// with it omitted); the subdomain is never taken from the request.
+	// Flipping the toggles works; identity fields set on the request value
+	// are ignored by FromAPIRequest/UpdateSettings by construction, but even
+	// a hand-rolled Settings value cannot smuggle them into the row.
 	updated, err := mgr.UpdateSettings(ctx, adminUserID, &agenttypes.Settings{
 		AccountID:              accountID,
-		Cluster:                clusterAddr,
-		Subdomain:              "evil",
+		Domain:                 "evil.example.com",
+		ProxyAddress:           "attacker.cluster",
 		EnableLogCollection:    true,
 		EnablePromptCollection: true,
 		RedactPii:              true,
 	})
 	require.NoError(t, err, "UpdateSettings must succeed")
-	assert.Equal(t, before.Cluster, updated.Cluster, "cluster is immutable and must be preserved")
-	assert.Equal(t, before.Subdomain, updated.Subdomain, "subdomain is immutable and must be preserved")
+	assert.Equal(t, before.Domain, updated.Domain, "domain is immutable and must be preserved")
+	assert.Equal(t, before.ProxyAddress, updated.ProxyAddress, "proxy address is immutable and must be preserved")
 	assert.True(t, updated.EnableLogCollection, "log collection toggle must apply")
 	assert.True(t, updated.EnablePromptCollection, "prompt collection toggle must apply")
 	assert.True(t, updated.RedactPii, "redact toggle must apply")
 
 	reloaded, err := am.Store.GetAgentNetworkSettings(ctx, store.LockingStrengthNone, accountID)
 	require.NoError(t, err)
-	assert.Equal(t, before.Cluster, reloaded.Cluster, "persisted cluster unchanged")
+	assert.Equal(t, before.Domain, reloaded.Domain, "persisted domain unchanged")
+	assert.Equal(t, before.ProxyAddress, reloaded.ProxyAddress, "persisted proxy address unchanged")
 	assert.True(t, reloaded.EnablePromptCollection, "persisted prompt collection toggled on")
 }

management/server/agentnetwork_realstack_test.go

@@ -92,6 +92,9 @@ func TestAgentNetwork_ProviderCRUD_FansOutToProxyAndClientPeers(t *testing.T) {
 	// UpdateAccountPeers, which is the path under test.
 	agentMgr := agentnetwork.NewManager(am.Store, permissions.NewManager(am.Store), am, nil)
 
+	_, err = agentMgr.CreateSettings(ctx, adminUserID, agenttypes.DefaultSettings(accountID), clusterAddr, "")
+	require.NoError(t, err, "CreateSettings must bootstrap the endpoint")
+
 	provider, err := agentMgr.CreateProvider(ctx, adminUserID, &agenttypes.Provider{
 		AccountID:   accountID,
 		ProviderID:  "openai_api",
@@ -100,7 +103,7 @@ func TestAgentNetwork_ProviderCRUD_FansOutToProxyAndClientPeers(t *testing.T) {
 		APIKey:      "sk-test-key",
 		Enabled:     true,
 		Models:      []agenttypes.ProviderModel{{ID: "gpt-5.4"}},
-	}, clusterAddr)
+	})
 	require.NoError(t, err, "CreateProvider must succeed")
 
 	policy, err := agentMgr.CreatePolicy(ctx, adminUserID, &agenttypes.Policy{

management/server/migration/migration_agentnetwork.go

@@ -0,0 +1,97 @@
+package migration
+
+import (
+	"context"
+	"fmt"
+
+	log "github.com/sirupsen/logrus"
+	"gorm.io/gorm"
+)
+
+// agentNetworkSettingsMigration is a local view of the agent_network_settings
+// table spanning both the legacy identity columns (cluster, subdomain) and
+// their replacement (domain, proxy_address), so the migrator can address all
+// four during the reshape without importing the current model.
+type agentNetworkSettingsMigration struct {
+	AccountID    string `gorm:"primaryKey"`
+	Cluster      string
+	Subdomain    string
+	Domain       string `gorm:"type:varchar(255)"`
+	ProxyAddress string `gorm:"type:varchar(255)"`
+}
+
+func (agentNetworkSettingsMigration) TableName() string { return "agent_network_settings" }
+
+// MigrateAgentNetworkSettingsToDomain reshapes agent_network_settings from the
+// legacy (cluster, subdomain) identity columns to (domain, proxy_address):
+// domain becomes `<subdomain>.<cluster>` — the endpoint hostname the old
+// columns derived — and proxy_address becomes the cluster address, preserving
+// which proxy serves the account. Runs before AutoMigrate, which then creates
+// the unique index on the freshly backfilled domain column.
+//
+// A legacy row missing either half cannot be given an endpoint; the old
+// bootstrap always wrote both, so such a row indicates corruption and the
+// migration fails loudly rather than leaving an empty domain to collide with
+// the unique index confusingly.
+func MigrateAgentNetworkSettingsToDomain(ctx context.Context, db *gorm.DB) error {
+	model := &agentNetworkSettingsMigration{}
+	migrator := db.Migrator()
+
+	if !migrator.HasTable(model) {
+		return nil
+	}
+	if !migrator.HasColumn(model, "cluster") {
+		// Fresh schema or already migrated — nothing to reshape.
+		return nil
+	}
+
+	return db.Transaction(func(tx *gorm.DB) error {
+		txMigrator := tx.Migrator()
+		for _, field := range []string{"Domain", "ProxyAddress"} {
+			if !txMigrator.HasColumn(model, field) {
+				if err := txMigrator.AddColumn(model, field); err != nil {
+					return fmt.Errorf("add %s column to agent_network_settings: %w", field, err)
+				}
+			}
+		}
+
+		concat := "subdomain || '.' || cluster"
+		if tx.Name() == "mysql" {
+			concat = "CONCAT(subdomain, '.', cluster)"
+		}
+		res := tx.Exec(fmt.Sprintf(
+			"UPDATE agent_network_settings SET domain = %s, proxy_address = cluster WHERE (domain IS NULL OR domain = '') AND cluster <> '' AND subdomain <> ''",
+			concat,
+		))
+		if res.Error != nil {
+			return fmt.Errorf("backfill agent_network_settings domain: %w", res.Error)
+		}
+
+		var unmigratable int64
+		if err := tx.Model(model).Where("domain IS NULL OR domain = ''").Count(&unmigratable).Error; err != nil {
+			return fmt.Errorf("count unmigratable agent_network_settings rows: %w", err)
+		}
+		if unmigratable > 0 {
+			return fmt.Errorf(
+				"%d agent_network_settings row(s) have no cluster/subdomain to derive an endpoint from; resolve them manually before upgrading",
+				unmigratable,
+			)
+		}
+
+		if txMigrator.HasIndex(model, "idx_agent_network_settings_cluster_subdomain") {
+			if err := txMigrator.DropIndex(model, "idx_agent_network_settings_cluster_subdomain"); err != nil {
+				return fmt.Errorf("drop legacy agent_network_settings index: %w", err)
+			}
+		}
+		for _, field := range []string{"Cluster", "Subdomain"} {
+			if err := txMigrator.DropColumn(model, field); err != nil {
+				return fmt.Errorf("drop legacy agent_network_settings column %s: %w", field, err)
+			}
+		}
+
+		if res.RowsAffected > 0 {
+			log.WithContext(ctx).Infof("migrated %d agent_network_settings row(s) to domain/proxy_address", res.RowsAffected)
+		}
+		return nil
+	})
+}

management/server/migration/migration_test.go

@@ -736,3 +736,85 @@ func TestFoldCostAggregatesIntoBuckets_SkipsAlreadyMigrated(t *testing.T) {
 	assert.InDelta(t, 0.004, row.OutputCostUSD, 1e-9)
 	assert.InDelta(t, 0.01, row.TotalCostUSD(), 1e-9, "derived total sums the four buckets")
 }
+
+// legacyAgentNetworkSettings is the pre-reshape schema: identity carried as
+// (cluster, subdomain) instead of (domain, proxy_address).
+type legacyAgentNetworkSettings struct {
+	AccountID           string `gorm:"primaryKey"`
+	Cluster             string
+	Subdomain           string
+	EnableLogCollection bool
+}
+
+func (legacyAgentNetworkSettings) TableName() string { return "agent_network_settings" }
+
+// TestMigrateAgentNetworkSettingsToDomain_BackfillsAndDropsLegacyColumns pins
+// the reshape: domain becomes `<subdomain>.<cluster>`, proxy_address becomes
+// the cluster, the legacy columns are dropped, and non-identity fields ride
+// through untouched.
+func TestMigrateAgentNetworkSettingsToDomain_BackfillsAndDropsLegacyColumns(t *testing.T) {
+	ctx := context.Background()
+	db := setupDatabase(t)
+	require.NoError(t, db.Migrator().DropTable(&legacyAgentNetworkSettings{}))
+	require.NoError(t, db.AutoMigrate(&legacyAgentNetworkSettings{}))
+	require.NoError(t, db.Create(&legacyAgentNetworkSettings{
+		AccountID: "acct-1", Cluster: "eu.proxy.netbird.io", Subdomain: "violet", EnableLogCollection: true,
+	}).Error)
+	require.NoError(t, db.Create(&legacyAgentNetworkSettings{
+		AccountID: "acct-2", Cluster: "us.proxy.netbird.io", Subdomain: "violet",
+	}).Error)
+
+	require.NoError(t, migration.MigrateAgentNetworkSettingsToDomain(ctx, db))
+	require.NoError(t, db.AutoMigrate(&agentNetworkTypes.Settings{}),
+		"AutoMigrate must create the domain unique index over the backfilled values")
+
+	var one, two agentNetworkTypes.Settings
+	require.NoError(t, db.First(&one, "account_id = ?", "acct-1").Error)
+	assert.Equal(t, "violet.eu.proxy.netbird.io", one.Domain, "domain must combine subdomain and cluster")
+	assert.Equal(t, "eu.proxy.netbird.io", one.ProxyAddress, "proxy address must carry the cluster")
+	assert.True(t, one.EnableLogCollection, "non-identity fields must ride through")
+	require.NoError(t, db.First(&two, "account_id = ?", "acct-2").Error)
+	assert.Equal(t, "violet.us.proxy.netbird.io", two.Domain,
+		"duplicate labels on different clusters are distinct hostnames and must both survive")
+
+	migrator := db.Migrator()
+	assert.False(t, migrator.HasColumn(&legacyAgentNetworkSettings{}, "cluster"), "legacy cluster column must be dropped")
+	assert.False(t, migrator.HasColumn(&legacyAgentNetworkSettings{}, "subdomain"), "legacy subdomain column must be dropped")
+}
+
+// TestMigrateAgentNetworkSettingsToDomain_SkipsAlreadyMigrated proves the
+// migration is safe to re-run: with no legacy column present it is a no-op.
+func TestMigrateAgentNetworkSettingsToDomain_SkipsAlreadyMigrated(t *testing.T) {
+	ctx := context.Background()
+	db := setupDatabase(t)
+	require.NoError(t, db.Migrator().DropTable(&agentNetworkTypes.Settings{}))
+	require.NoError(t, db.AutoMigrate(&agentNetworkTypes.Settings{}))
+	require.NoError(t, db.Create(&agentNetworkTypes.Settings{
+		AccountID: "acct-1", Domain: "gw.example.com", ProxyAddress: "gw.example.com",
+	}).Error)
+
+	require.NoError(t, migration.MigrateAgentNetworkSettingsToDomain(ctx, db),
+		"running against an already-migrated table must be a no-op, not an error")
+
+	var row agentNetworkTypes.Settings
+	require.NoError(t, db.First(&row, "account_id = ?", "acct-1").Error)
+	assert.Equal(t, "gw.example.com", row.Domain, "migrated rows must be untouched")
+}
+
+// TestMigrateAgentNetworkSettingsToDomain_FailsOnUnmigratableRow pins the
+// loud-failure contract: a legacy row missing its identity halves cannot be
+// given an endpoint, and silently leaving an empty domain would collide with
+// the unique index confusingly later.
+func TestMigrateAgentNetworkSettingsToDomain_FailsOnUnmigratableRow(t *testing.T) {
+	ctx := context.Background()
+	db := setupDatabase(t)
+	require.NoError(t, db.Migrator().DropTable(&legacyAgentNetworkSettings{}))
+	require.NoError(t, db.AutoMigrate(&legacyAgentNetworkSettings{}))
+	require.NoError(t, db.Create(&legacyAgentNetworkSettings{
+		AccountID: "acct-broken", Cluster: "", Subdomain: "",
+	}).Error)
+
+	err := migration.MigrateAgentNetworkSettingsToDomain(ctx, db)
+	require.Error(t, err, "a row with no identity to derive an endpoint from must fail the migration")
+	assert.Contains(t, err.Error(), "resolve them manually", "the error must tell the operator what to do")
+}

management/server/store/sql_store_agentnetwork.go

@@ -315,25 +315,65 @@ func (s *SqlStore) GetAllAgentNetworkSettings(ctx context.Context, lockStrength
 	return settings, nil
 }
 
-// GetAgentNetworkSettingsByCluster returns every Settings row pinned to
-// the given proxy cluster. Used by the bootstrap label generator to
-// build the set of subdomains already taken on a cluster.
-func (s *SqlStore) GetAgentNetworkSettingsByCluster(ctx context.Context, lockStrength LockingStrength, cluster string) ([]*agentNetworkTypes.Settings, error) {
+// GetAgentNetworkSettingsByProxyAddress returns every Settings row whose
+// gateway is served by the proxy declaring the given cluster address. Used by
+// cluster-scoped synthesis to find the accounts a shared proxy serves.
+func (s *SqlStore) GetAgentNetworkSettingsByProxyAddress(ctx context.Context, lockStrength LockingStrength, proxyAddress string) ([]*agentNetworkTypes.Settings, error) {
 	tx := s.db
 	if lockStrength != LockingStrengthNone {
 		tx = tx.Clauses(clause.Locking{Strength: string(lockStrength)})
 	}
 
 	var settings []*agentNetworkTypes.Settings
-	result := tx.Find(&settings, "cluster = ?", cluster)
+	result := tx.Find(&settings, "proxy_address = ?", proxyAddress)
 	if result.Error != nil {
-		log.WithContext(ctx).Errorf("failed to get agent network settings by cluster from store: %v", result.Error)
-		return nil, status.Errorf(status.Internal, "failed to get agent network settings by cluster from store")
+		log.WithContext(ctx).Errorf("failed to get agent network settings by proxy address from store: %v", result.Error)
+		return nil, status.Errorf(status.Internal, "failed to get agent network settings by proxy address from store")
 	}
 
 	return settings, nil
 }
 
+// GetAgentNetworkSettingsByDomain resolves the single Settings row holding the
+// given endpoint hostname — a point query on the domain unique index. Returns
+// status.NotFound when no account owns the domain.
+func (s *SqlStore) GetAgentNetworkSettingsByDomain(ctx context.Context, lockStrength LockingStrength, domain string) (*agentNetworkTypes.Settings, error) {
+	tx := s.db
+	if lockStrength != LockingStrengthNone {
+		tx = tx.Clauses(clause.Locking{Strength: string(lockStrength)})
+	}
+
+	var settings agentNetworkTypes.Settings
+	result := tx.Take(&settings, "domain = ?", domain)
+	if result.Error != nil {
+		if errors.Is(result.Error, gorm.ErrRecordNotFound) {
+			return nil, status.Errorf(status.NotFound, "agent network settings for domain %s not found", domain)
+		}
+
+		log.WithContext(ctx).Errorf("failed to get agent network settings by domain from store: %v", result.Error)
+		return nil, status.Errorf(status.Internal, "failed to get agent network settings by domain from store")
+	}
+
+	return &settings, nil
+}
+
+// CreateAgentNetworkSettings inserts a new settings row.
+//
+// Unlike SaveAgentNetworkSettings (an upsert) this is a plain INSERT, and it
+// returns the driver error unwrapped. Both properties are required by the
+// bootstrap allocator: an upsert would overwrite whichever row it collided
+// with, and the allocator classifies the rejection by matching the driver's
+// message — a unique violation on the account primary key means a concurrent
+// bootstrap for the same account won, and one on the domain index means the
+// hostname is taken.
+func (s *SqlStore) CreateAgentNetworkSettings(ctx context.Context, settings *agentNetworkTypes.Settings) error {
+	if err := s.db.Create(settings).Error; err != nil {
+		log.WithContext(ctx).Debugf("failed to create agent network settings: %v", err)
+		return err
+	}
+	return nil
+}
+
 // SaveAgentNetworkSettings upserts the per-account Agent Network
 // settings row.
 func (s *SqlStore) SaveAgentNetworkSettings(ctx context.Context, settings *agentNetworkTypes.Settings) error {

management/server/store/sql_store_agentnetwork_budgetrule_test.go

@@ -88,9 +88,9 @@ func TestAgentNetworkSettings_RealStore_CollectionTogglesRoundTrip(t *testing.T)
 
 	const accountID = "acc-settings-toggles"
 	require.NoError(t, s.SaveAgentNetworkSettings(ctx, &agentNetworkTypes.Settings{
-		AccountID: accountID,
-		Cluster:   "eu.proxy.netbird.io",
-		Subdomain: "violet",
+		AccountID:    accountID,
+		Domain:       "violet.eu.proxy.netbird.io",
+		ProxyAddress: "eu.proxy.netbird.io",
 	}))
 
 	got, err := s.GetAgentNetworkSettings(ctx, LockingStrengthNone, accountID)

management/server/store/store.go

@@ -360,7 +360,9 @@ type Store interface {
 	DeleteAgentNetworkGuardrail(ctx context.Context, accountID, guardrailID string) error
 	GetAgentNetworkSettings(ctx context.Context, lockStrength LockingStrength, accountID string) (*agentNetworkTypes.Settings, error)
 	GetAllAgentNetworkSettings(ctx context.Context, lockStrength LockingStrength) ([]*agentNetworkTypes.Settings, error)
-	GetAgentNetworkSettingsByCluster(ctx context.Context, lockStrength LockingStrength, cluster string) ([]*agentNetworkTypes.Settings, error)
+	GetAgentNetworkSettingsByProxyAddress(ctx context.Context, lockStrength LockingStrength, proxyAddress string) ([]*agentNetworkTypes.Settings, error)
+	GetAgentNetworkSettingsByDomain(ctx context.Context, lockStrength LockingStrength, domain string) (*agentNetworkTypes.Settings, error)
+	CreateAgentNetworkSettings(ctx context.Context, settings *agentNetworkTypes.Settings) error
 	SaveAgentNetworkSettings(ctx context.Context, settings *agentNetworkTypes.Settings) error
 	IncrementAgentNetworkConsumption(ctx context.Context, accountID string, kind agentNetworkTypes.ConsumptionDimension, dimID string, windowSeconds int64, windowStart time.Time, tokensIn, tokensOut int64, costUSD float64) error
 	IncrementAgentNetworkConsumptionBatch(ctx context.Context, accountID string, keys []agentNetworkTypes.ConsumptionKey, tokensIn, tokensOut int64, costUSD float64) error
@@ -608,6 +610,9 @@ func getMigrationsPreAuto(ctx context.Context) []migrationFunc {
 		func(db *gorm.DB) error {
 			return migration.BackfillPublicIDs[posture.Checks](ctx, db)
 		},
+		func(db *gorm.DB) error {
+			return migration.MigrateAgentNetworkSettingsToDomain(ctx, db)
+		},
 	}
 }
 

management/server/store/store_mock.go

@@ -268,6 +268,20 @@ func (mr *MockStoreMockRecorder) CreateAgentNetworkAccessLog(ctx, entry, groups
 	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "CreateAgentNetworkAccessLog", reflect.TypeOf((*MockStore)(nil).CreateAgentNetworkAccessLog), ctx, entry, groups)
 }
 
+// CreateAgentNetworkSettings mocks base method.
+func (m *MockStore) CreateAgentNetworkSettings(ctx context.Context, settings *types.Settings) error {
+	m.ctrl.T.Helper()
+	ret := m.ctrl.Call(m, "CreateAgentNetworkSettings", ctx, settings)
+	ret0, _ := ret[0].(error)
+	return ret0
+}
+
+// CreateAgentNetworkSettings indicates an expected call of CreateAgentNetworkSettings.
+func (mr *MockStoreMockRecorder) CreateAgentNetworkSettings(ctx, settings interface{}) *gomock.Call {
+	mr.mock.ctrl.T.Helper()
+	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "CreateAgentNetworkSettings", reflect.TypeOf((*MockStore)(nil).CreateAgentNetworkSettings), ctx, settings)
+}
+
 // CreateAgentNetworkUsage mocks base method.
 func (m *MockStore) CreateAgentNetworkUsage(ctx context.Context, usage *types.AgentNetworkUsage, groups []types.AgentNetworkUsageGroup) error {
 	m.ctrl.T.Helper()
@@ -1687,19 +1701,34 @@ func (mr *MockStoreMockRecorder) GetAgentNetworkSettings(ctx, lockStrength, acco
 	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "GetAgentNetworkSettings", reflect.TypeOf((*MockStore)(nil).GetAgentNetworkSettings), ctx, lockStrength, accountID)
 }
 
-// GetAgentNetworkSettingsByCluster mocks base method.
-func (m *MockStore) GetAgentNetworkSettingsByCluster(ctx context.Context, lockStrength LockingStrength, cluster string) ([]*types.Settings, error) {
+// GetAgentNetworkSettingsByDomain mocks base method.
+func (m *MockStore) GetAgentNetworkSettingsByDomain(ctx context.Context, lockStrength LockingStrength, domain string) (*types.Settings, error) {
 	m.ctrl.T.Helper()
-	ret := m.ctrl.Call(m, "GetAgentNetworkSettingsByCluster", ctx, lockStrength, cluster)
+	ret := m.ctrl.Call(m, "GetAgentNetworkSettingsByDomain", ctx, lockStrength, domain)
+	ret0, _ := ret[0].(*types.Settings)
+	ret1, _ := ret[1].(error)
+	return ret0, ret1
+}
+
+// GetAgentNetworkSettingsByDomain indicates an expected call of GetAgentNetworkSettingsByDomain.
+func (mr *MockStoreMockRecorder) GetAgentNetworkSettingsByDomain(ctx, lockStrength, domain interface{}) *gomock.Call {
+	mr.mock.ctrl.T.Helper()
+	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "GetAgentNetworkSettingsByDomain", reflect.TypeOf((*MockStore)(nil).GetAgentNetworkSettingsByDomain), ctx, lockStrength, domain)
+}
+
+// GetAgentNetworkSettingsByProxyAddress mocks base method.
+func (m *MockStore) GetAgentNetworkSettingsByProxyAddress(ctx context.Context, lockStrength LockingStrength, proxyAddress string) ([]*types.Settings, error) {
+	m.ctrl.T.Helper()
+	ret := m.ctrl.Call(m, "GetAgentNetworkSettingsByProxyAddress", ctx, lockStrength, proxyAddress)
 	ret0, _ := ret[0].([]*types.Settings)
 	ret1, _ := ret[1].(error)
 	return ret0, ret1
 }
 
-// GetAgentNetworkSettingsByCluster indicates an expected call of GetAgentNetworkSettingsByCluster.
-func (mr *MockStoreMockRecorder) GetAgentNetworkSettingsByCluster(ctx, lockStrength, cluster interface{}) *gomock.Call {
+// GetAgentNetworkSettingsByProxyAddress indicates an expected call of GetAgentNetworkSettingsByProxyAddress.
+func (mr *MockStoreMockRecorder) GetAgentNetworkSettingsByProxyAddress(ctx, lockStrength, proxyAddress interface{}) *gomock.Call {
 	mr.mock.ctrl.T.Helper()
-	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "GetAgentNetworkSettingsByCluster", reflect.TypeOf((*MockStore)(nil).GetAgentNetworkSettingsByCluster), ctx, lockStrength, cluster)
+	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "GetAgentNetworkSettingsByProxyAddress", reflect.TypeOf((*MockStore)(nil).GetAgentNetworkSettingsByProxyAddress), ctx, lockStrength, proxyAddress)
 }
 
 // GetAgentNetworkUsageRows mocks base method.

shared/management/http/api/openapi.yml

@@ -5208,10 +5208,6 @@ components:
           type: string
           description: Full upstream URL (with scheme) that NetBird forwards traffic to.
           example: "https://api.openai.com"
-        bootstrap_cluster:
-          type: string
-          description: Proxy cluster used to bootstrap the per-account agent-network endpoint when the first provider is created. Ignored on subsequent creates and on updates because the cluster is pinned on the account-level Settings row.
-          example: "eu.proxy.netbird.io"
         api_key:
           type: string
           description: Upstream provider API key. Sealed at rest on the management server and never returned in responses. Required on create; optional on update (omit to keep the existing key).
@@ -6193,20 +6189,20 @@ components:
         - cache_cost_usd
     AgentNetworkSettings:
       type: object
-      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.
+      description: Per-account Agent Network gateway settings. One row per account; endpoint and proxy_address are assigned at bootstrap (POST) and immutable thereafter. Before bootstrap the account reads as the default values with empty endpoint and proxy_address.
       properties:
-        cluster:
-          type: string
-          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. Empty until the account is bootstrapped.
-          example: "violet"
         endpoint:
           type: string
-          description: Bare hostname agents call for this account, computed as `<subdomain>.<cluster>`. Empty until the account is bootstrapped.
-          example: "violet.eu.proxy.netbird.io"
+          description: Bare hostname agents call for this account. Empty until the account is bootstrapped.
+          example: "brave-otter.eu.proxy.netbird.io"
+        proxy_address:
+          type: string
+          description: Declared cluster address of the proxy serving this account's gateway. Equal to `endpoint` when a dedicated proxy serves the account; otherwise the endpoint's immediate parent (a shared cluster the endpoint hangs one label beneath). Empty until the account is bootstrapped.
+          example: "eu.proxy.netbird.io"
+        dedicated:
+          type: boolean
+          description: Whether the account's gateway is served by a proxy dedicated to it (endpoint equals proxy_address).
+          example: false
         enable_log_collection:
           type: boolean
           description: Whether per-request access-log entries are collected for this account's agent-network traffic.
@@ -6236,20 +6232,44 @@ components:
           readOnly: true
           example: "2026-04-26T10:30:00Z"
       required:
-        - cluster
-        - subdomain
         - endpoint
+        - proxy_address
+        - dedicated
         - enable_log_collection
         - enable_prompt_collection
         - redact_pii
+    AgentNetworkSettingsCreateRequest:
+      type: object
+      description: Bootstraps the per-account Agent Network settings row, assigning the account's immutable endpoint. Exactly one of `proxy_address` and `endpoint` must be provided. `proxy_address` requests a labeled endpoint — the server allocates a label and the endpoint becomes `<label>.<proxy_address>`, served by whichever proxy declares that parent address. `endpoint` claims the given hostname itself as a self-addressed (dedicated) endpoint, served only by a proxy declaring exactly that address — the claim is legitimate before the proxy exists (address-first). Collection toggles may ride along; omitted toggles take their defaults.
+      properties:
+        proxy_address:
+          type: string
+          description: Cluster address to allocate a labeled endpoint beneath. Mutually exclusive with `endpoint`.
+          example: "eu.proxy.netbird.io"
+        endpoint:
+          type: string
+          description: Hostname to claim as the account's self-addressed (dedicated) endpoint. Mutually exclusive with `proxy_address`. Rejected when another account already holds it.
+          example: "brave-otter.gateway.example.com"
+        enable_log_collection:
+          type: boolean
+          description: Whether per-request access-log entries are collected for this account's agent-network traffic. Defaults to true.
+          example: true
+        enable_prompt_collection:
+          type: boolean
+          description: Master switch for request/response prompt capture. Defaults to false.
+          example: false
+        redact_pii:
+          type: boolean
+          description: Whether captured prompts have PII redacted. Defaults to false.
+          example: false
+        access_log_retention_days:
+          type: integer
+          description: Days to retain full access-log rows; older rows are swept. 0 or less means keep indefinitely. Defaults to 30.
+          example: 30
     AgentNetworkSettingsRequest:
       type: object
-      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.
+      description: Account-level Agent Network settings update. The request replaces every mutable field (the collection toggles and retention). The endpoint and proxy address are assigned at bootstrap (POST) and are not part of this schema.
       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.
@@ -13694,7 +13714,7 @@ paths:
   /api/agent-network/settings:
     get:
       summary: Retrieve Agent Network settings
-      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.
+      description: Returns the per-account Agent Network gateway settings (endpoint, proxy address, collection toggles). Before the account is bootstrapped via POST, the response carries the default values with an empty endpoint and proxy address.
       tags: [ Agent Network ]
       security:
         - BearerAuth: [ ]
@@ -13712,9 +13732,41 @@ paths:
           "$ref": "#/components/responses/forbidden"
         '500':
           "$ref": "#/components/responses/internal_error"
+    post:
+      summary: Bootstrap Agent Network settings
+      description: Creates the per-account Agent Network settings row and allocates the account's endpoint. Exactly one of `proxy_address` (labeled endpoint under that cluster; the server allocates the label) and `endpoint` (self-addressed dedicated endpoint, claimed verbatim) must be provided. The endpoint and proxy address are immutable once assigned. Returns 409 when the account already has a settings row.
+      tags: [ Agent Network ]
+      security:
+        - BearerAuth: [ ]
+        - TokenAuth: [ ]
+      requestBody:
+        description: Settings bootstrap request
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AgentNetworkSettingsCreateRequest'
+      responses:
+        '200':
+          description: The freshly bootstrapped Agent Network settings
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AgentNetworkSettings'
+        '400':
+          "$ref": "#/components/responses/bad_request"
+        '401':
+          "$ref": "#/components/responses/requires_authentication"
+        '403':
+          "$ref": "#/components/responses/forbidden"
+        '409':
+          "$ref": "#/components/responses/conflict"
+        '422':
+          "$ref": "#/components/responses/validation_failed"
+        '500':
+          "$ref": "#/components/responses/internal_error"
     put:
       summary: Update Agent Network settings
-      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.
+      description: Updates the account-level Agent Network settings; the request replaces every mutable field (collection toggles and retention). Returns 404 when the account has no settings row yet — bootstrap it with POST first. The endpoint and proxy address are assigned at bootstrap and are not part of the update schema.
       tags: [ Agent Network ]
       security:
         - BearerAuth: [ ]

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

@@ -2329,9 +2329,6 @@ type AgentNetworkProviderRequest struct {
 	// ApiKey Upstream provider API key. Sealed at rest on the management server and never returned in responses. Required on create; optional on update (omit to keep the existing key).
 	ApiKey *string `json:"api_key,omitempty"`
 
-	// BootstrapCluster Proxy cluster used to bootstrap the per-account agent-network endpoint when the first provider is created. Ignored on subsequent creates and on updates because the cluster is pinned on the account-level Settings row.
-	BootstrapCluster *string `json:"bootstrap_cluster,omitempty"`
-
 	// Enabled Whether the provider is enabled. Defaults to true on create.
 	Enabled *bool `json:"enabled,omitempty"`
 
@@ -2363,44 +2360,62 @@ type AgentNetworkProviderRequest struct {
 	UpstreamUrl string `json:"upstream_url"`
 }
 
-// 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.
+// AgentNetworkSettings Per-account Agent Network gateway settings. One row per account; endpoint and proxy_address are assigned at bootstrap (POST) and immutable thereafter. Before bootstrap the account reads as the default values with empty endpoint and proxy_address.
 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. Empty until the account is bootstrapped.
-	Cluster string `json:"cluster"`
-
 	// CreatedAt Timestamp when the settings row was created. Absent until the account is bootstrapped.
 	CreatedAt *time.Time `json:"created_at,omitempty"`
 
+	// Dedicated Whether the account's gateway is served by a proxy dedicated to it (endpoint equals proxy_address).
+	Dedicated bool `json:"dedicated"`
+
 	// EnableLogCollection Whether per-request access-log entries are collected for this account's agent-network traffic.
 	EnableLogCollection bool `json:"enable_log_collection"`
 
 	// 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>`. Empty until the account is bootstrapped.
+	// Endpoint Bare hostname agents call for this account. Empty until the account is bootstrapped.
 	Endpoint string `json:"endpoint"`
 
+	// ProxyAddress Declared cluster address of the proxy serving this account's gateway. Equal to `endpoint` when a dedicated proxy serves the account; otherwise the endpoint's immediate parent (a shared cluster the endpoint hangs one label beneath). Empty until the account is bootstrapped.
+	ProxyAddress string `json:"proxy_address"`
+
 	// 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. Empty until the account is bootstrapped.
-	Subdomain string `json:"subdomain"`
-
 	// UpdatedAt Timestamp when the settings row was last updated. Absent until the account is bootstrapped.
 	UpdatedAt *time.Time `json:"updated_at,omitempty"`
 }
 
-// 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.
+// AgentNetworkSettingsCreateRequest Bootstraps the per-account Agent Network settings row, assigning the account's immutable endpoint. Exactly one of `proxy_address` and `endpoint` must be provided. `proxy_address` requests a labeled endpoint — the server allocates a label and the endpoint becomes `<label>.<proxy_address>`, served by whichever proxy declares that parent address. `endpoint` claims the given hostname itself as a self-addressed (dedicated) endpoint, served only by a proxy declaring exactly that address — the claim is legitimate before the proxy exists (address-first). Collection toggles may ride along; omitted toggles take their defaults.
+type AgentNetworkSettingsCreateRequest struct {
+	// AccessLogRetentionDays Days to retain full access-log rows; older rows are swept. 0 or less means keep indefinitely. Defaults to 30.
+	AccessLogRetentionDays *int `json:"access_log_retention_days,omitempty"`
+
+	// EnableLogCollection Whether per-request access-log entries are collected for this account's agent-network traffic. Defaults to true.
+	EnableLogCollection *bool `json:"enable_log_collection,omitempty"`
+
+	// EnablePromptCollection Master switch for request/response prompt capture. Defaults to false.
+	EnablePromptCollection *bool `json:"enable_prompt_collection,omitempty"`
+
+	// Endpoint Hostname to claim as the account's self-addressed (dedicated) endpoint. Mutually exclusive with `proxy_address`. Rejected when another account already holds it.
+	Endpoint *string `json:"endpoint,omitempty"`
+
+	// ProxyAddress Cluster address to allocate a labeled endpoint beneath. Mutually exclusive with `endpoint`.
+	ProxyAddress *string `json:"proxy_address,omitempty"`
+
+	// RedactPii Whether captured prompts have PII redacted. Defaults to false.
+	RedactPii *bool `json:"redact_pii,omitempty"`
+}
+
+// AgentNetworkSettingsRequest Account-level Agent Network settings update. The request replaces every mutable field (the collection toggles and retention). The endpoint and proxy address are assigned at bootstrap (POST) and are not part of this schema.
 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"`
 
@@ -6176,6 +6191,9 @@ type PostApiAgentNetworkProvidersJSONRequestBody = AgentNetworkProviderRequest
 // PutApiAgentNetworkProvidersProviderIdJSONRequestBody defines body for PutApiAgentNetworkProvidersProviderId for application/json ContentType.
 type PutApiAgentNetworkProvidersProviderIdJSONRequestBody = AgentNetworkProviderRequest
 
+// PostApiAgentNetworkSettingsJSONRequestBody defines body for PostApiAgentNetworkSettings for application/json ContentType.
+type PostApiAgentNetworkSettingsJSONRequestBody = AgentNetworkSettingsCreateRequest
+
 // PutApiAgentNetworkSettingsJSONRequestBody defines body for PutApiAgentNetworkSettings for application/json ContentType.
 type PutApiAgentNetworkSettingsJSONRequestBody = AgentNetworkSettingsRequest