feat(agentnetwork): require identity echo on settings PUT, add guarded DELETE

Lands the review decision from #7085: PUT keeps the API-wide convention
of requiring every field. endpoint and proxy_address join the update
schema as required fields, compared against the stored row (trimmed,
case-folded) and rejected with 422 on mismatch. They are never written,
so the identity stays immutable while the request shape stays
conventional.

Because the identity is immutable, clients that model change-as-replace
(the Terraform provider's RequiresReplace) need a real delete. DELETE
/api/agent-network/settings now exists with two guards, both checked
under the row lock: no providers may exist for the account, and no
active proxy may declare the endpoint hostname as its cluster address.
Either refusal is a 412. The proxy guard checks the endpoint hostname
rather than the proxy address: for a dedicated pin they are equal, and
for a labeled pin the shared parent cluster being up says nothing about
this account once its providers are gone. Re-creating after a delete
allocates a fresh endpoint; the released hostname is not reserved.

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

e2e/agentnetwork/chat_test.go

@@ -438,14 +438,10 @@ func TestProvidersMatrix(t *testing.T) {
 	// Create every provider, all enabled, each with a unique model string so the
 	// proxy's connect-time snapshot carries them all and model→provider routing
 	// is unambiguous (provider toggles after connect don't reconcile to the
-	// proxy, so we enable everything up front). The first create bootstraps the
-	// cluster.
+	// proxy, so we enable everything up front).
 	ids := make([]string, 0, len(matrix))
-	for i, pc := range matrix {
+	for _, pc := range matrix {
 		req := providerRequest(pc)
-		if i == 0 {
-			req.BootstrapCluster = ptr(harness.AgentNetworkCluster)
-		}
 		prov, perr := srv.CreateProvider(ctx, req)
 		require.NoError(t, perr, "create provider %s", pc.name)
 		ids = append(ids, prov.Id)

e2e/agentnetwork/custom_pricing_test.go

@@ -82,13 +82,12 @@ func provisionPricedProvider(t *testing.T, ctx context.Context, name string, mod
 	// need NOT be in the catalog — the operator names it and prices it here.
 	dummyKey := "sk-price-e2e"
 	prov, err := srv.CreateProvider(ctx, api.AgentNetworkProviderRequest{
-		Name:             name,
-		ProviderId:       "openai_api",
-		UpstreamUrl:      vllm.URL,
-		ApiKey:           &dummyKey,
-		Enabled:          ptr(true),
-		BootstrapCluster: ptr(harness.AgentNetworkCluster),
-		Models:           &models,
+		Name:        name,
+		ProviderId:  "openai_api",
+		UpstreamUrl: vllm.URL,
+		ApiKey:      &dummyKey,
+		Enabled:     ptr(true),
+		Models:      &models,
 	})
 	require.NoError(t, err, "create provider")
 	t.Cleanup(func() { _ = srv.DeleteProvider(context.Background(), prov.Id) })

e2e/agentnetwork/guardrail_block_test.go

@@ -113,15 +113,14 @@ func runPathRoutedGuardrailCase(t *testing.T, tc pathRoutedGuardrailCase) {
 
 	// Catch-all provider (no models) so the router forwards any model; a static
 	// bearer key means the router injects a static auth header instead of minting
-	// a GCP token. Bootstraps the cluster if it isn't already.
+	// a GCP token.
 	staticKey := "static-e2e-token"
 	prov, err := srv.CreateProvider(ctx, api.AgentNetworkProviderRequest{
-		Name:             tc.name,
-		ProviderId:       tc.catalogID,
-		UpstreamUrl:      vllm.URL,
-		ApiKey:           &staticKey,
-		Enabled:          ptr(true),
-		BootstrapCluster: ptr(harness.AgentNetworkCluster),
+		Name:        tc.name,
+		ProviderId:  tc.catalogID,
+		UpstreamUrl: vllm.URL,
+		ApiKey:      &staticKey,
+		Enabled:     ptr(true),
 	})
 	require.NoError(t, err, "create %s provider", tc.name)
 	t.Cleanup(func() { _ = srv.DeleteProvider(context.Background(), prov.Id) })

e2e/agentnetwork/guardrail_groupswitch_test.go

@@ -73,7 +73,6 @@ func TestGuardrailGroupSwitchTakesEffectAfterTTL(t *testing.T) {
 			{Id: modelA, InputPer1k: 0.001, OutputPer1k: 0.001},
 			{Id: modelB, InputPer1k: 0.001, OutputPer1k: 0.001},
 		},
-		BootstrapCluster: ptr(harness.AgentNetworkCluster),
 	})
 	require.NoError(t, err, "create provider")
 	t.Cleanup(func() { _ = srv.DeleteProvider(context.Background(), prov.Id) })

e2e/agentnetwork/guardrail_multipolicy_test.go

@@ -61,15 +61,14 @@ func TestGuardrailMultiPolicyModelAllowlist(t *testing.T) {
 	}
 
 	// pRestricted declares the two guardrailed models so routing is deterministic
-	// (model -> provider). Created first, so it carries the bootstrap cluster.
+	// (model -> provider).
 	pRestricted, err := srv.CreateProvider(ctx, api.AgentNetworkProviderRequest{
-		Name:             "restricted",
-		ProviderId:       "openai_api",
-		UpstreamUrl:      vllm.URL,
-		ApiKey:           &staticKey,
-		Enabled:          ptr(true),
-		Models:           models(modelSelected, modelOther),
-		BootstrapCluster: ptr(harness.AgentNetworkCluster),
+		Name:        "restricted",
+		ProviderId:  "openai_api",
+		UpstreamUrl: vllm.URL,
+		ApiKey:      &staticKey,
+		Enabled:     ptr(true),
+		Models:      models(modelSelected, modelOther),
 	})
 	require.NoError(t, err, "create restricted provider")
 	t.Cleanup(func() { _ = srv.DeleteProvider(context.Background(), pRestricted.Id) })

e2e/agentnetwork/guardrail_pergroup_providers_test.go

@@ -115,7 +115,7 @@ func TestGuardrailPerGroupAllowlist_AllProviders(t *testing.T) {
 	staticKey := "static-e2e-token"
 	enabled := true
 
-	for i, c := range cases {
+	for _, c := range cases {
 		req := api.AgentNetworkProviderRequest{
 			Name:        "e2e-pergroup-" + c.name,
 			ProviderId:  c.catalogID,
@@ -124,9 +124,6 @@ func TestGuardrailPerGroupAllowlist_AllProviders(t *testing.T) {
 			Enabled:     ptr(true),
 			Models:      c.models,
 		}
-		if i == 0 {
-			req.BootstrapCluster = ptr(harness.AgentNetworkCluster)
-		}
 		prov, perr := srv.CreateProvider(ctx, req)
 		require.NoError(t, perr, "create provider %s", c.name)
 		c.providerID = prov.Id
@@ -283,13 +280,12 @@ func TestGuardrailMultiGroupUser(t *testing.T) {
 
 	// P1 — union scenario: two restricting policies, one per group.
 	p1, err := srv.CreateProvider(ctx, api.AgentNetworkProviderRequest{
-		Name:             "e2e-mg-union",
-		ProviderId:       "openai_api",
-		UpstreamUrl:      vllm.URL,
-		ApiKey:           &staticKey,
-		Enabled:          ptr(true),
-		Models:           priced(unionA, unionB, unionC),
-		BootstrapCluster: ptr(harness.AgentNetworkCluster),
+		Name:        "e2e-mg-union",
+		ProviderId:  "openai_api",
+		UpstreamUrl: vllm.URL,
+		ApiKey:      &staticKey,
+		Enabled:     ptr(true),
+		Models:      priced(unionA, unionB, unionC),
 	})
 	require.NoError(t, err, "create union provider")
 	t.Cleanup(func() { _ = srv.DeleteProvider(context.Background(), p1.Id) })

e2e/agentnetwork/guardrail_test.go

@@ -115,14 +115,11 @@ func TestModelAllowlistEnforced(t *testing.T) {
 	})
 	require.NoError(t, err, "mint setup key")
 
-	// Providers with their configured (allowed) models; the first bootstraps the cluster.
+	// Providers with their configured (allowed) models
 	ids := make([]string, 0, len(providers))
 	allowed := make([]string, 0, len(providers))
-	for i, pc := range providers {
+	for _, pc := range providers {
 		req := providerRequest(pc)
-		if i == 0 {
-			req.BootstrapCluster = ptr(harness.AgentNetworkCluster)
-		}
 		prov, perr := srv.CreateProvider(ctx, req)
 		require.NoError(t, perr, "create provider %s", pc.name)
 		id := prov.Id

e2e/agentnetwork/main_test.go

@@ -14,6 +14,7 @@ import (
 	"time"
 
 	"github.com/netbirdio/netbird/e2e/harness"
+	"github.com/netbirdio/netbird/shared/management/http/api"
 )
 
 // srv is the shared combined server for the package, ready (PAT-authenticated)
@@ -42,5 +43,14 @@ func run(m *testing.M) int {
 		return 1
 	}
 
+	// Bootstrap the account's agent-network endpoint once for the package:
+	// providers no longer have settings side effects, and every data-plane
+	// test expects the shared account pinned to the combined proxy cluster.
+	cluster := harness.AgentNetworkCluster
+	if _, err := srv.CreateSettings(ctx, api.AgentNetworkSettingsCreateRequest{ProxyAddress: &cluster}); err != nil {
+		fmt.Fprintf(os.Stderr, "e2e: bootstrap agent-network endpoint: %v\n", err)
+		return 1
+	}
+
 	return m.Run()
 }

e2e/agentnetwork/management_test.go

@@ -21,11 +21,10 @@ func ptr[T any](v T) *T { return &v }
 func newProvider(t *testing.T, ctx context.Context, name string) api.AgentNetworkProvider {
 	t.Helper()
 	prov, err := srv.CreateProvider(ctx, api.AgentNetworkProviderRequest{
-		Name:             name,
-		ProviderId:       "openai_api",
-		UpstreamUrl:      "https://api.openai.com",
-		ApiKey:           ptr("sk-dummy-e2e-key"),
-		BootstrapCluster: ptr("eu.proxy.netbird.test"),
+		Name:        name,
+		ProviderId:  "openai_api",
+		UpstreamUrl: "https://api.openai.com",
+		ApiKey:      ptr("sk-dummy-e2e-key"),
 	})
 	require.NoError(t, err, "create provider %q", name)
 	t.Cleanup(func() { _ = srv.DeleteProvider(context.Background(), prov.Id) })
@@ -57,17 +56,11 @@ func TestProviderLifecycle(t *testing.T) {
 		}}
 	}
 
-	for i, pc := range cases {
-		i, pc := i, pc
+	for _, pc := range cases {
+		pc := pc
 		t.Run(pc.name, func(t *testing.T) {
 			req := providerRequest(pc)
 			req.Name = "lc-" + pc.name
-			// Bootstrap the cluster on the first create in case the matrix has
-			// not run (e.g. no provider keys → settings not yet bootstrapped).
-			if i == 0 {
-				req.BootstrapCluster = ptr(harness.AgentNetworkCluster)
-			}
-
 			prov, err := srv.CreateProvider(ctx, req)
 			require.NoError(t, err, "create %s provider", pc.name)
 			t.Cleanup(func() { _ = srv.DeleteProvider(context.Background(), prov.Id) })
@@ -137,45 +130,65 @@ func TestProviderValidation(t *testing.T) {
 	requireClientError(t, err)
 }
 
-// TestSettingsRoundTrip flips the collection toggles and confirms cluster /
-// subdomain stay immutable, then restores the original state.
+// TestSettingsRoundTrip flips the collection toggles and confirms the
+// endpoint and proxy address stay immutable, then restores the original
+// state. A second bootstrap attempt must be rejected as a conflict.
 func TestSettingsRoundTrip(t *testing.T) {
 	ctx := context.Background()
 
-	// Settings are bootstrapped on first provider create.
-	newProvider(t, ctx, "Settings Bootstrap")
-
+	// The package's TestMain bootstrapped the shared account's endpoint.
 	before, err := srv.GetSettings(ctx)
 	require.NoError(t, err, "get settings")
-	require.NotEmpty(t, before.Cluster, "settings must carry an assigned cluster")
+	require.NotEmpty(t, before.Endpoint, "settings must carry the bootstrapped endpoint")
+	require.NotEmpty(t, before.ProxyAddress, "settings must carry the bootstrapped proxy address")
+
+	require.NotNil(t, before.AccessLogRetentionDays, "bootstrapped settings must carry a retention")
+	beforeRetention := *before.AccessLogRetentionDays
 
 	flipped, err := srv.UpdateSettings(ctx, api.AgentNetworkSettingsRequest{
+		Endpoint:               before.Endpoint,
+		ProxyAddress:           before.ProxyAddress,
 		EnableLogCollection:    !before.EnableLogCollection,
 		EnablePromptCollection: !before.EnablePromptCollection,
 		RedactPii:              !before.RedactPii,
+		AccessLogRetentionDays: beforeRetention,
 	})
 	require.NoError(t, err, "update settings")
 	assert.Equal(t, !before.EnableLogCollection, flipped.EnableLogCollection, "log collection toggle must flip")
 	assert.Equal(t, !before.EnablePromptCollection, flipped.EnablePromptCollection, "prompt collection toggle must flip")
-	assert.Equal(t, before.Cluster, flipped.Cluster, "cluster must be immutable across updates")
-	assert.Equal(t, before.Subdomain, flipped.Subdomain, "subdomain must be immutable across updates")
+	require.NotNil(t, flipped.AccessLogRetentionDays)
+	assert.Equal(t, beforeRetention, *flipped.AccessLogRetentionDays,
+		"retention sent unchanged must round-trip, not reset to the zero value")
+	assert.Equal(t, before.Endpoint, flipped.Endpoint, "endpoint must be immutable across updates")
+	assert.Equal(t, before.ProxyAddress, flipped.ProxyAddress, "proxy address must be immutable across updates")
 
-	// A cluster different from the pinned one must be rejected; echoing the
-	// pinned one back is valid.
+	// The account is already bootstrapped: a second bootstrap is a conflict,
+	// whatever shape it asks for.
+	_, err = srv.CreateSettings(ctx, api.AgentNetworkSettingsCreateRequest{
+		Endpoint: ptr("attacker.cluster.invalid"),
+	})
+	requireClientError(t, err)
+
+	// The identity fields ride along on the PUT as a required echo: a request
+	// carrying a different endpoint is rejected without applying anything.
 	_, err = srv.UpdateSettings(ctx, api.AgentNetworkSettingsRequest{
-		Cluster:                ptr("attacker.cluster.invalid"),
+		Endpoint:               "other.cluster.invalid",
+		ProxyAddress:           before.ProxyAddress,
 		EnableLogCollection:    before.EnableLogCollection,
 		EnablePromptCollection: before.EnablePromptCollection,
 		RedactPii:              before.RedactPii,
+		AccessLogRetentionDays: beforeRetention,
 	})
 	requireClientError(t, err)
 
 	// Restore the original toggles.
 	_, err = srv.UpdateSettings(ctx, api.AgentNetworkSettingsRequest{
-		Cluster:                ptr(before.Cluster),
+		Endpoint:               before.Endpoint,
+		ProxyAddress:           before.ProxyAddress,
 		EnableLogCollection:    before.EnableLogCollection,
 		EnablePromptCollection: before.EnablePromptCollection,
 		RedactPii:              before.RedactPii,
+		AccessLogRetentionDays: beforeRetention,
 	})
 	require.NoError(t, err, "restore settings")
 }

e2e/agentnetwork/settings_bootstrap_test.go

@@ -4,6 +4,7 @@ package agentnetwork
 
 import (
 	"context"
+	"strings"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -14,7 +15,8 @@ import (
 )
 
 // harnessStartFresh boots a dedicated combined server with its own fresh
-// account and registers its teardown on t.
+// account and registers its teardown on t. Unlike the shared srv, the fresh
+// account has NOT had its agent-network endpoint bootstrapped.
 func harnessStartFresh(ctx context.Context, t *testing.T) (*harness.Combined, error) {
 	t.Helper()
 	fresh, err := harness.StartCombined(ctx)
@@ -28,16 +30,16 @@ func harnessStartFresh(ctx context.Context, t *testing.T) (*harness.Combined, er
 	return fresh, nil
 }
 
-// TestSettingsBootstrapViaPut covers the settings-first bootstrap path on an
+// TestSettingsBootstrapViaPost covers the explicit bootstrap contract on an
 // account that has never been bootstrapped: the GET reads as the defaults
-// with an empty cluster/subdomain/endpoint, a PUT without a cluster has
-// nothing to pin and fails, and a PUT carrying a cluster creates the row and
-// pins it immutably. The shared srv cannot provide that starting state (any
-// provider-creating test bootstraps it, and test order is deliberately not
-// relied on), so this boots a dedicated combined server — the image is
-// already built and cached by TestMain's StartCombined, so the extra cost is
-// one container start.
-func TestSettingsBootstrapViaPut(t *testing.T) {
+// with an empty endpoint/proxy_address, a PUT has no row to update and fails,
+// and a POST creates the row and assigns the immutable endpoint — labeled
+// beneath a proxy address here, with the toggle overrides from the same
+// request applied. The shared srv cannot provide that starting state
+// (TestMain bootstraps it), so this boots a dedicated combined server — the
+// image is already built and cached by TestMain's StartCombined, so the extra
+// cost is one container start.
+func TestSettingsBootstrapViaPost(t *testing.T) {
 	ctx := context.Background()
 
 	fresh, err := harnessStartFresh(ctx, t)
@@ -47,32 +49,35 @@ func TestSettingsBootstrapViaPut(t *testing.T) {
 	// as an error and not as a null body.
 	before, err := fresh.GetSettings(ctx)
 	require.NoError(t, err, "get settings on a fresh account must succeed")
-	assert.Empty(t, before.Cluster, "cluster must be empty before bootstrap")
-	assert.Empty(t, before.Subdomain, "subdomain must be empty before bootstrap")
-	assert.Empty(t, before.Endpoint, "endpoint must be empty before bootstrap, not a bare dot")
+	assert.Empty(t, before.Endpoint, "endpoint must be empty before bootstrap")
+	assert.Empty(t, before.ProxyAddress, "proxy address must be empty before bootstrap")
+	assert.False(t, before.Dedicated, "an unbootstrapped account has no serving shape")
 	assert.True(t, before.EnableLogCollection, "defaults must show log collection on, matching bootstrap")
 	assert.False(t, before.EnablePromptCollection, "defaults must show prompt collection off")
 
-	// A PUT without a cluster has nothing to pin the account to.
+	// A PUT has no row to update yet — bootstrap is the explicit POST.
 	_, err = fresh.UpdateSettings(ctx, api.AgentNetworkSettingsRequest{
-		EnableLogCollection: true,
+		EnableLogCollection:    true,
+		AccessLogRetentionDays: 30,
 	})
 	requireClientError(t, err)
 
-	// A PUT carrying a cluster bootstraps the account and applies the
-	// mutable fields from the same request. Every toggle is set away from
-	// its bootstrap default so each assertion can actually fail.
+	// A POST with a proxy address bootstraps a labeled endpoint and applies
+	// the toggles from the same request. Every toggle is set away from its
+	// bootstrap default so each assertion can actually fail.
 	const cluster = "e2e.bootstrap.netbird.selfhosted"
-	bootstrapped, err := fresh.UpdateSettings(ctx, api.AgentNetworkSettingsRequest{
-		Cluster:                ptr(cluster),
-		EnableLogCollection:    false,
-		EnablePromptCollection: true,
-		RedactPii:              true,
+	bootstrapped, err := fresh.CreateSettings(ctx, api.AgentNetworkSettingsCreateRequest{
+		ProxyAddress:           ptr(cluster),
+		EnableLogCollection:    ptr(false),
+		EnablePromptCollection: ptr(true),
+		RedactPii:              ptr(true),
 	})
-	require.NoError(t, err, "bootstrap settings via PUT must succeed")
-	assert.Equal(t, cluster, bootstrapped.Cluster, "cluster must be pinned from the request")
-	require.NotEmpty(t, bootstrapped.Subdomain, "subdomain must be assigned at bootstrap")
-	assert.Equal(t, bootstrapped.Subdomain+"."+cluster, bootstrapped.Endpoint, "endpoint must combine subdomain and cluster")
+	require.NoError(t, err, "bootstrap settings via POST must succeed")
+	assert.Equal(t, cluster, bootstrapped.ProxyAddress, "proxy address must be pinned from the request")
+	require.NotEmpty(t, bootstrapped.Endpoint, "endpoint must be assigned at bootstrap")
+	assert.True(t, strings.HasSuffix(bootstrapped.Endpoint, "."+cluster),
+		"labeled endpoint must hang one label beneath the proxy address: %s", bootstrapped.Endpoint)
+	assert.False(t, bootstrapped.Dedicated, "a labeled pin is not dedicated")
 	assert.False(t, bootstrapped.EnableLogCollection, "log collection from the bootstrap request must override the default")
 	assert.True(t, bootstrapped.EnablePromptCollection, "prompt collection from the bootstrap request must apply")
 	assert.True(t, bootstrapped.RedactPii, "redact toggle from the bootstrap request must apply")
@@ -85,30 +90,90 @@ func TestSettingsBootstrapViaPut(t *testing.T) {
 	assert.Equal(t, bootstrapped.EnablePromptCollection, after.EnablePromptCollection, "prompt collection must persist")
 	assert.Equal(t, bootstrapped.RedactPii, after.RedactPii, "redact toggle must persist")
 
-	// Once bootstrapped, later updates may omit the cluster entirely.
+	// Once bootstrapped, PUT updates the toggles. The identity fields ride
+	// along as a required echo of the assigned values; a matching echo is
+	// accepted and never written.
 	persisted, err := fresh.UpdateSettings(ctx, api.AgentNetworkSettingsRequest{
+		Endpoint:               bootstrapped.Endpoint,
+		ProxyAddress:           bootstrapped.ProxyAddress,
 		EnableLogCollection:    true,
 		EnablePromptCollection: false,
 		RedactPii:              true,
+		AccessLogRetentionDays: 21,
 	})
-	require.NoError(t, err, "post-bootstrap update without cluster must succeed")
-	assert.Equal(t, cluster, persisted.Cluster, "omitted cluster must keep the pinned value")
+	require.NoError(t, err, "post-bootstrap update must succeed")
+	require.NotNil(t, persisted.AccessLogRetentionDays)
+	assert.Equal(t, 21, *persisted.AccessLogRetentionDays, "retention from the update must apply")
+	assert.Equal(t, bootstrapped.Endpoint, persisted.Endpoint, "endpoint must survive updates untouched")
+	assert.Equal(t, cluster, persisted.ProxyAddress, "proxy address must survive updates untouched")
 	assert.True(t, persisted.EnableLogCollection, "post-bootstrap toggle must apply")
 	assert.False(t, persisted.EnablePromptCollection, "post-bootstrap toggle must apply")
 
-	// The cluster is immutable: a different value is rejected rather than
-	// silently ignored, and the rejected update must not disturb anything.
+	// The endpoint is immutable: a PUT carrying a different endpoint is
+	// rejected, and a second bootstrap is rejected as a conflict. Neither
+	// rejected write may disturb anything.
 	_, err = fresh.UpdateSettings(ctx, api.AgentNetworkSettingsRequest{
-		Cluster:             ptr("other.cluster.invalid"),
-		EnableLogCollection: false,
+		Endpoint:               "other.cluster.invalid",
+		ProxyAddress:           persisted.ProxyAddress,
+		EnableLogCollection:    persisted.EnableLogCollection,
+		EnablePromptCollection: persisted.EnablePromptCollection,
+		RedactPii:              persisted.RedactPii,
+		AccessLogRetentionDays: 21,
+	})
+	requireClientError(t, err)
+
+	_, err = fresh.CreateSettings(ctx, api.AgentNetworkSettingsCreateRequest{
+		Endpoint: ptr("other.cluster.invalid"),
 	})
 	requireClientError(t, err)
 
 	final, err := fresh.GetSettings(ctx)
-	require.NoError(t, err, "get settings after the rejected cluster change must succeed")
-	assert.Equal(t, persisted.Cluster, final.Cluster, "rejected update must not change the cluster")
-	assert.Equal(t, persisted.Endpoint, final.Endpoint, "rejected update must not change the endpoint")
-	assert.Equal(t, persisted.EnableLogCollection, final.EnableLogCollection, "rejected update must not apply its toggles")
-	assert.Equal(t, persisted.EnablePromptCollection, final.EnablePromptCollection, "rejected update must not apply its toggles")
-	assert.Equal(t, persisted.RedactPii, final.RedactPii, "rejected update must not apply its toggles")
+	require.NoError(t, err, "get settings after the rejected bootstrap must succeed")
+	assert.Equal(t, persisted.Endpoint, final.Endpoint, "rejected bootstrap must not change the endpoint")
+	assert.Equal(t, persisted.ProxyAddress, final.ProxyAddress, "rejected bootstrap must not change the proxy address")
+	assert.Equal(t, persisted.EnableLogCollection, final.EnableLogCollection, "rejected bootstrap must not apply its toggles")
+	assert.Equal(t, persisted.EnablePromptCollection, final.EnablePromptCollection, "rejected bootstrap must not apply its toggles")
+	assert.Equal(t, persisted.RedactPii, final.RedactPii, "rejected bootstrap must not apply its toggles")
+}
+
+// TestSettingsBootstrapSelfAddressed covers the dedicated shape end to end:
+// a POST carrying an endpoint claims the hostname verbatim, the proxy address
+// equals it, and the pin reads as dedicated — the address-first flow a
+// self-hosted operator uses before deploying the proxy that will declare it.
+// The tail covers the recovery path the guarded DELETE exists for: with no
+// providers and no proxy at the address, the claim can be released and a
+// fresh bootstrap succeeds — the fix for a typo'd immutable endpoint.
+func TestSettingsBootstrapSelfAddressed(t *testing.T) {
+	ctx := context.Background()
+
+	fresh, err := harnessStartFresh(ctx, t)
+	require.NoError(t, err, "start dedicated combined server")
+
+	created, err := fresh.CreateSettings(ctx, api.AgentNetworkSettingsCreateRequest{
+		Endpoint: ptr("gw.e2e.netbird.selfhosted"),
+	})
+	require.NoError(t, err, "self-addressed bootstrap must succeed")
+	assert.Equal(t, "gw.e2e.netbird.selfhosted", created.Endpoint, "endpoint must be claimed verbatim")
+	assert.Equal(t, created.Endpoint, created.ProxyAddress, "self-addressed: proxy address is the endpoint")
+	assert.True(t, created.Dedicated, "a self-addressed pin is dedicated")
+
+	// No providers exist and no proxy declares the address, so both delete
+	// guards are clear: the delete releases the claim and the account reads
+	// as unbootstrapped defaults again.
+	require.NoError(t, fresh.DeleteSettings(ctx), "guarded delete with both guards clear must succeed")
+
+	after, err := fresh.GetSettings(ctx)
+	require.NoError(t, err, "get settings after delete must succeed")
+	assert.Empty(t, after.Endpoint, "a deleted account must read as unbootstrapped")
+
+	// A second delete has nothing to remove.
+	requireClientError(t, fresh.DeleteSettings(ctx))
+
+	// Re-creating is a fresh bootstrap — the released hostname is free to be
+	// claimed again, or a different one chosen.
+	recreated, err := fresh.CreateSettings(ctx, api.AgentNetworkSettingsCreateRequest{
+		Endpoint: ptr("gw2.e2e.netbird.selfhosted"),
+	})
+	require.NoError(t, err, "bootstrap after delete must succeed")
+	assert.Equal(t, "gw2.e2e.netbird.selfhosted", recreated.Endpoint, "the fresh bootstrap claims the new hostname")
 }

e2e/agentnetwork/skiptls_test.go

@@ -66,9 +66,7 @@ func TestProviderSkipTLSVerification(t *testing.T) {
 		}
 	}
 
-	// First create bootstraps the account cluster.
 	insecureReq := newReq("skip-tls", insecureModel, true)
-	insecureReq.BootstrapCluster = ptr(harness.AgentNetworkCluster)
 	insecureProv, err := srv.CreateProvider(ctx, insecureReq)
 	require.NoError(t, err, "create skip-tls provider")
 	t.Cleanup(func() { _ = srv.DeleteProvider(context.Background(), insecureProv.Id) })

e2e/agentnetwork/vllm_test.go

@@ -57,12 +57,11 @@ func TestVLLMProvider(t *testing.T) {
 	// is enumerated so the router dispatches this model string to this provider.
 	dummyKey := "sk-vllm-e2e"
 	prov, err := srv.CreateProvider(ctx, api.AgentNetworkProviderRequest{
-		Name:             "vllm",
-		ProviderId:       "vllm",
-		UpstreamUrl:      vllm.URL,
-		ApiKey:           &dummyKey,
-		Enabled:          ptr(true),
-		BootstrapCluster: ptr(harness.AgentNetworkCluster),
+		Name:        "vllm",
+		ProviderId:  "vllm",
+		UpstreamUrl: vllm.URL,
+		ApiKey:      &dummyKey,
+		Enabled:     ptr(true),
 		Models: &[]api.AgentNetworkProviderModel{
 			{Id: harness.VLLMModel, InputPer1k: 0.001, OutputPer1k: 0.002},
 		},

e2e/harness/agentnetwork.go

@@ -126,17 +126,33 @@ func (c *Combined) DeleteGuardrail(ctx context.Context, id string) error {
 	return anDelete(ctx, c, "/api/agent-network/guardrails/"+id)
 }
 
-// GetSettings returns the account's agent-network settings row. It exists only
-// after the first provider create bootstraps it.
+// CreateSettings bootstraps the account's agent-network settings row,
+// assigning the immutable endpoint. Exactly one of req.ProxyAddress (labeled
+// endpoint beneath that cluster) and req.Endpoint (self-addressed dedicated
+// endpoint) must be set; a second bootstrap returns a conflict.
+func (c *Combined) CreateSettings(ctx context.Context, req api.AgentNetworkSettingsCreateRequest) (api.AgentNetworkSettings, error) {
+	return anRequest[api.AgentNetworkSettings](ctx, c, http.MethodPost, "/api/agent-network/settings", req)
+}
+
+// GetSettings returns the account's agent-network settings row. Before the
+// CreateSettings bootstrap it reads as the defaults with an empty endpoint.
 func (c *Combined) GetSettings(ctx context.Context) (api.AgentNetworkSettings, error) {
 	return anRequest[api.AgentNetworkSettings](ctx, c, http.MethodGet, "/api/agent-network/settings", nil)
 }
 
-// UpdateSettings applies the mutable collection toggles.
+// UpdateSettings applies the mutable collection toggles. The request must
+// echo the assigned endpoint and proxy address unchanged — the server rejects
+// a PUT that tries to change them.
 func (c *Combined) UpdateSettings(ctx context.Context, req api.AgentNetworkSettingsRequest) (api.AgentNetworkSettings, error) {
 	return anRequest[api.AgentNetworkSettings](ctx, c, http.MethodPut, "/api/agent-network/settings", req)
 }
 
+// DeleteSettings removes the account's settings row, releasing the endpoint.
+// Refused while providers exist or a proxy is actively serving the endpoint.
+func (c *Combined) DeleteSettings(ctx context.Context) error {
+	return anDelete(ctx, c, "/api/agent-network/settings")
+}
+
 // ListConsumption returns the account's consumption rows (possibly empty).
 func (c *Combined) ListConsumption(ctx context.Context) ([]api.AgentNetworkConsumption, error) {
 	return anRequest[[]api.AgentNetworkConsumption](ctx, c, http.MethodGet, "/api/agent-network/consumption", nil)

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,13 +12,55 @@ 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); PUT
+// carries every field, replacing the mutable collection toggles and rejecting
+// any change to the identity fields; DELETE removes the row — guarded so it
+// stays a bootstrap-repair operation — releasing the endpoint for a fresh
+// bootstrap.
 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")
+	router.HandleFunc("/agent-network/settings", h.deleteSettings).Methods("DELETE", "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.
@@ -48,6 +90,24 @@ func (h *handler) updateSettings(w http.ResponseWriter, r *http.Request) {
 	util.WriteJSONObject(r.Context(), w, updated.ToAPIResponse())
 }
 
+// deleteSettings removes the account's settings row, releasing the endpoint.
+// The manager refuses (412) while providers exist or a proxy is actively
+// serving the endpoint; a later POST bootstraps fresh, allocating a new
+// endpoint.
+func (h *handler) deleteSettings(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	if err := h.manager.DeleteSettings(r.Context(), userAuth.AccountId, userAuth.UserId); err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+	util.WriteJSONObject(r.Context(), w, util.EmptyObject{})
+}
+
 // getSettings returns the account's agent-network settings. Accounts that
 // haven't been bootstrapped yet read as the defaults with an empty cluster,
 // subdomain and endpoint; the manager synthesises that view.

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

@@ -1,20 +1,25 @@
 package handlers
 
 import (
+	"context"
 	"encoding/json"
+	"fmt"
 	"net/http"
+	"strings"
 	"testing"
+	"time"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
+	rpproxy "github.com/netbirdio/netbird/management/internals/modules/reverseproxy/proxy"
 	"github.com/netbirdio/netbird/shared/management/http/api"
 )
 
 // 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 +32,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,62 +44,149 @@ 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.
+// with the other PUT endpoints: the request carries every field, replacing the
+// mutable ones. The identity fields ride along as a required echo of the
+// assigned values — compared, never written — so the endpoint and proxy
+// address survive every accepted update.
 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))
 
-	rec = f.do(t, http.MethodPut, "/agent-network/settings",
-		`{"enable_log_collection": true, "enable_prompt_collection": false, "redact_pii": false}`)
+	rec = f.do(t, http.MethodPut, "/agent-network/settings", fmt.Sprintf(
+		`{"endpoint": %q, "proxy_address": %q, "enable_log_collection": true, "enable_prompt_collection": false, "redact_pii": false, "access_log_retention_days": 7}`,
+		before.Endpoint, before.ProxyAddress))
 	require.Equal(t, http.StatusOK, rec.Code, "update PUT must succeed: %s", rec.Body.String())
 
 	var got api.AgentNetworkSettings
@@ -103,35 +195,193 @@ func TestSettingsHandler_PutReplacesMutableFields(t *testing.T) {
 	assert.False(t, got.EnablePromptCollection, "sent toggle must apply")
 	assert.False(t, got.RedactPii, "sent toggle must apply")
 	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")
+	assert.Equal(t, 7, *got.AccessLogRetentionDays, "sent retention 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")
 }
 
-// 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) {
+// TestSettingsHandler_PutRejectsChangedIdentity pins the immutability contract:
+// the PUT carries the identity fields like every other field, but they are an
+// echo — a request carrying a different endpoint or proxy address is rejected
+// as a validation error and the row is left untouched. The comparison is
+// lenient about casing (the stored values are normalized lowercase), so a
+// client replaying a GET response with different casing is not rejected.
+func TestSettingsHandler_PutRejectsChangedIdentity(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.MethodPost, "/agent-network/settings",
+		`{"proxy_address": "eu.proxy.netbird.io", "enable_prompt_collection": true}`)
+	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))
 
-	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())
+	for name, body := range map[string]string{
+		"changed endpoint": fmt.Sprintf(
+			`{"endpoint": "other.gateway.example.com", "proxy_address": %q, "enable_log_collection": false, "enable_prompt_collection": false, "redact_pii": false, "access_log_retention_days": 30}`,
+			before.ProxyAddress),
+		"changed proxy_address": fmt.Sprintf(
+			`{"endpoint": %q, "proxy_address": "us.proxy.netbird.io", "enable_log_collection": false, "enable_prompt_collection": false, "redact_pii": false, "access_log_retention_days": 30}`,
+			before.Endpoint),
+		"omitted identity": `{"enable_log_collection": false, "enable_prompt_collection": false, "redact_pii": false, "access_log_retention_days": 30}`,
+	} {
+		rec = f.do(t, http.MethodPut, "/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())
+	}
 
-	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())
+	// The rejected updates must not have applied anything — toggles included.
+	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, before.Endpoint, got.Endpoint, "rejected PUT must not change the endpoint")
+	assert.Equal(t, before.ProxyAddress, got.ProxyAddress, "rejected PUT must not change the proxy address")
+	assert.True(t, got.EnablePromptCollection, "rejected PUT must not apply its toggles")
+
+	// An uppercased echo of the assigned values still names the same host and
+	// must be accepted.
+	rec = f.do(t, http.MethodPut, "/agent-network/settings", fmt.Sprintf(
+		`{"endpoint": %q, "proxy_address": %q, "enable_log_collection": true, "enable_prompt_collection": true, "redact_pii": false, "access_log_retention_days": 30}`,
+		strings.ToUpper(before.Endpoint), strings.ToUpper(before.ProxyAddress)))
+	assert.Equal(t, http.StatusOK, rec.Code,
+		"an uppercased identity echo must be accepted: got %d body=%s", rec.Code, rec.Body.String())
+}
+
+// TestSettingsHandler_PutOmittedRetentionLandsAsZero documents a residual the
+// required-ness of access_log_retention_days does not remove. Marking the field
+// required changes the generated client type from *int to int, so a generated
+// client cannot omit it — but nothing validates OpenAPI required-ness at
+// runtime, so a hand-rolled body without the field still decodes as 0, which
+// the API documents as "keep indefinitely".
+//
+// That is the same latitude the three booleans already have, so it is left
+// consistent rather than special-cased. This test exists to make the gap
+// explicit: if request validation is ever added, this expectation is what
+// changes.
+func TestSettingsHandler_PutOmittedRetentionLandsAsZero(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodPost, "/agent-network/settings",
+		`{"proxy_address": "eu.proxy.netbird.io", "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))
+
+	rec = f.do(t, http.MethodPut, "/agent-network/settings", fmt.Sprintf(
+		`{"endpoint": %q, "proxy_address": %q, "enable_log_collection": true, "enable_prompt_collection": false, "redact_pii": false}`,
+		before.Endpoint, before.ProxyAddress))
+	require.Equal(t, http.StatusOK, rec.Code, "update PUT 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 unchanged")
-	assert.True(t, got.RedactPii, "toggle sent alongside the echoed cluster must apply")
+	require.NotNil(t, got.AccessLogRetentionDays)
+	assert.Equal(t, 0, *got.AccessLogRetentionDays,
+		"a non-conforming body that omits retention still replaces it with the zero value")
+}
+
+// TestSettingsHandler_DeleteBeforeBootstrapIs404 pins that DELETE on an
+// account with no settings row is a 404, mirroring the PUT.
+func TestSettingsHandler_DeleteBeforeBootstrapIs404(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodDelete, "/agent-network/settings", "")
+	assert.Equal(t, http.StatusNotFound, rec.Code,
+		"DELETE on an unbootstrapped account must 404: got %d body=%s", rec.Code, rec.Body.String())
+}
+
+// TestSettingsHandler_DeleteBlockedByProviders pins the first delete guard:
+// while any provider exists for the account, the delete is refused with 412
+// and the row survives. Providers route through the endpoint — the guard
+// keeps DELETE a bootstrap-repair operation rather than a way to abandon a
+// configured gateway.
+func TestSettingsHandler_DeleteBlockedByProviders(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, "bootstrap POST must succeed: %s", rec.Body.String())
+	var before api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &before))
+
+	f.seedProvider(t, "prov-guard")
+
+	rec = f.do(t, http.MethodDelete, "/agent-network/settings", "")
+	assert.Equal(t, http.StatusPreconditionFailed, rec.Code,
+		"delete with a provider present must be refused: 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, before.Endpoint, got.Endpoint, "the refused delete must leave the row intact")
+}
+
+// TestSettingsHandler_DeleteBlockedByActiveProxy pins the second delete
+// guard: while a proxy is actively serving the endpoint — an active proxy
+// row declaring the endpoint hostname as its cluster address, the dedicated
+// shape — the delete is refused with 412. A proxy that has disconnected no
+// longer blocks: the guard is about a live serving path, not history.
+func TestSettingsHandler_DeleteBlockedByActiveProxy(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	const endpoint = "gw.dedicated.example.com"
+	rec := f.do(t, http.MethodPost, "/agent-network/settings", fmt.Sprintf(`{"endpoint": %q}`, endpoint))
+	require.Equal(t, http.StatusOK, rec.Code, "bootstrap POST must succeed: %s", rec.Body.String())
+
+	now := time.Now()
+	accountID := testAccountID
+	proxyRow := &rpproxy.Proxy{
+		ID:             "proxy-guard",
+		SessionID:      "sess-1",
+		ClusterAddress: endpoint,
+		AccountID:      &accountID,
+		LastSeen:       now,
+		ConnectedAt:    &now,
+		Status:         rpproxy.StatusConnected,
+	}
+	require.NoError(t, f.store.SaveProxy(context.Background(), proxyRow))
+
+	rec = f.do(t, http.MethodDelete, "/agent-network/settings", "")
+	assert.Equal(t, http.StatusPreconditionFailed, rec.Code,
+		"delete with an active proxy at the endpoint must be refused: got %d body=%s", rec.Code, rec.Body.String())
+
+	// Once the proxy disconnects it no longer serves the endpoint, so the
+	// delete goes through.
+	require.NoError(t, f.store.DisconnectProxy(context.Background(), proxyRow.ID, proxyRow.SessionID))
+	rec = f.do(t, http.MethodDelete, "/agent-network/settings", "")
+	assert.Equal(t, http.StatusOK, rec.Code,
+		"delete after the proxy disconnected must succeed: got %d body=%s", rec.Code, rec.Body.String())
+}
+
+// TestSettingsHandler_DeleteReleasesEndpointForFreshBootstrap pins the
+// full-reset semantic that gives replace-on-change clients (e.g. Terraform's
+// RequiresReplace) a real path: with both guards clear the delete succeeds,
+// the account reads as the defaults again, and a fresh bootstrap allocates a
+// new endpoint rather than resurrecting the released one.
+func TestSettingsHandler_DeleteReleasesEndpointForFreshBootstrap(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodPost, "/agent-network/settings",
+		`{"proxy_address": "eu.proxy.netbird.io", "enable_prompt_collection": true}`)
+	require.Equal(t, http.StatusOK, rec.Code, "bootstrap POST must succeed: %s", rec.Body.String())
+	var first api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &first))
+
+	rec = f.do(t, http.MethodDelete, "/agent-network/settings", "")
+	require.Equal(t, http.StatusOK, rec.Code,
+		"delete with both guards clear must succeed: 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 after api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &after))
+	assert.Empty(t, after.Endpoint, "a deleted account must read as unbootstrapped defaults")
+	assert.False(t, after.EnablePromptCollection, "the deleted row's toggles must not linger")
+
+	rec = f.do(t, http.MethodPost, "/agent-network/settings", `{"proxy_address": "eu.proxy.netbird.io"}`)
+	require.Equal(t, http.StatusOK, rec.Code, "re-bootstrap after delete must succeed: %s", rec.Body.String())
+	var second api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &second))
+	require.NotEmpty(t, second.Endpoint)
+	assert.NotEqual(t, first.Endpoint, second.Endpoint,
+		"re-creating allocates a new endpoint; the released hostname is not reserved")
 }

management/internals/modules/agentnetwork/labelgen/adjectives.go

@@ -0,0 +1,37 @@
+package labelgen
+
+// adjectives is the descriptor half of a generated label. It pairs with the
+// noun pool in words.go to form `<adjective>-<noun>` labels, and is kept
+// separate because words.go is almost entirely nouns — drawing both halves
+// from it produced unreadable pairs like "millet-hammock". Entries are
+// lowercase ASCII, 4-12 chars, free of hyphens and digits, screened for
+// offensive/brand/region-specific terms, and disjoint from the noun pool
+// (enforced by TestAdjectives_AreDisjointFromNouns).
+var adjectives = []string{
+	"able", "active", "adept", "agile", "airy", "alert", "amiable", "ample",
+	"ancient", "ardent", "artful", "astute", "balmy", "blithe", "bold", "bonny",
+	"brave", "breezy", "brisk", "bubbly", "buoyant", "bushy", "candid", "canny",
+	"cheery", "chilly", "chipper", "chunky", "civil", "classic", "clever", "comely",
+	"compact", "cordial", "cosmic", "courtly", "crafty", "creamy", "crisp", "cuddly",
+	"curious", "dainty", "dapper", "daring", "dashing", "deft", "dewy", "diligent",
+	"downy", "dreamy", "dulcet", "durable", "dusky", "eager", "earnest", "earthy",
+	"easy", "elated", "elegant", "epic", "fabled", "faithful", "fancy", "fearless",
+	"feisty", "fervent", "fleet", "fluffy", "fond", "frisky", "frosty", "gallant",
+	"genial", "genteel", "gentle", "giddy", "gilded", "glad", "glassy", "gleaming",
+	"glossy", "graceful", "grand", "grainy", "hale", "hardy", "hearty", "hefty",
+	"honest", "hopeful", "humble", "hushed", "immense", "jaunty", "jolly", "jovial",
+	"joyful", "jubilant", "keen", "kindly", "kindred", "lanky", "leafy", "limber",
+	"lively", "lofty", "loyal", "lucent", "lucid", "luminous", "lush", "maroon",
+	"mellow", "merry", "mighty", "mindful", "mirthful", "misty", "modest", "muted",
+	"nifty", "nimble", "noble", "patient", "peaceful", "pearly", "peppy", "perky",
+	"petite", "placid", "playful", "pleasant", "plucky", "plush", "polite", "posh",
+	"prancing", "pristine", "prompt", "proud", "prudent", "quaint", "quick", "quirky",
+	"radiant", "ready", "regal", "restful", "robust", "rosy", "ruddy", "rugged",
+	"sandy", "satin", "saucy", "savvy", "sedate", "serene", "shady", "shiny",
+	"silken", "silky", "sincere", "sleek", "slender", "smart", "smooth", "snappy",
+	"snug", "soaring", "sparkly", "spiffy", "spirited", "sprightly", "spry", "stalwart",
+	"stately", "steady", "sterling", "stoic", "stormy", "stout", "sturdy", "sunlit",
+	"supple", "svelte", "tawny", "tender", "tidy", "timeless", "trusty", "upbeat",
+	"urbane", "valiant", "vast", "vernal", "vibrant", "vintage", "whimsy", "willing",
+	"windy", "winsome", "wintry", "witty", "worthy", "zesty", "zippy",
+}

management/internals/modules/agentnetwork/labelgen/labelgen.go

@@ -64,3 +64,20 @@ func PickUnique(rng *rand.Rand, taken map[string]struct{}, fallbackSuffix string
 	w := pool[rng.Intn(len(pool))]
 	return fmt.Sprintf("%s-%s", w, fallbackSuffix)
 }
+
+// PickTuple returns an adjective-noun label such as "brave-otter". It is still
+// a single DNS label.
+//
+// Unlike PickUnique it takes no `taken` set and has no fallback suffix. The
+// noun pool holds 857 entries, which is ample per cluster but a hard ceiling
+// once labels must be unique across one shared zone; pairing an adjective with
+// a noun spans len(adjectives) * 857 instead. Uniqueness is enforced by a
+// database constraint and retried by the caller, rather than guessed from a
+// pre-read set that a concurrent allocation can invalidate.
+func PickTuple(rng *rand.Rand) string {
+	nouns := uniqueWords()
+	if len(nouns) == 0 || len(adjectives) == 0 {
+		return ""
+	}
+	return adjectives[rng.Intn(len(adjectives))] + "-" + nouns[rng.Intn(len(nouns))]
+}

management/internals/modules/agentnetwork/labelgen/labelgen_test.go

@@ -99,3 +99,82 @@ func TestUniqueWords_DropsDuplicates(t *testing.T) {
 	}
 	assert.GreaterOrEqual(t, len(pool), 500, "Pool must contain at least 500 unique words")
 }
+
+// TestPickTuple_ShapeAndPoolMembership locks the wire-visible shape: an
+// adjective and a noun, each from its own pool, joined by a single hyphen so
+// the result stays one DNS label.
+func TestPickTuple_ShapeAndPoolMembership(t *testing.T) {
+	nouns := uniqueWords()
+	inNouns := make(map[string]struct{}, len(nouns))
+	for _, w := range nouns {
+		inNouns[w] = struct{}{}
+	}
+	inAdjectives := make(map[string]struct{}, len(adjectives))
+	for _, a := range adjectives {
+		inAdjectives[a] = struct{}{}
+	}
+
+	rng := rand.New(rand.NewSource(7))
+	for i := 0; i < 200; i++ {
+		got := PickTuple(rng)
+
+		parts := strings.Split(got, "-")
+		require.Len(t, parts, 2, "PickTuple must produce exactly two hyphen-joined words; got %q", got)
+
+		_, adjOK := inAdjectives[parts[0]]
+		assert.True(t, adjOK, "First half must be an adjective; %q not in adjectives (from %q)", parts[0], got)
+		_, nounOK := inNouns[parts[1]]
+		assert.True(t, nounOK, "Second half must be a noun; %q not in words (from %q)", parts[1], got)
+
+		assert.LessOrEqual(t, len(got), 63, "Label must fit a DNS label; got %q (%d chars)", got, len(got))
+	}
+}
+
+// TestAdjectives_AreDisjointFromNouns keeps the namespace a clean product and
+// prevents nonsense like "azure-azure": a handful of the noun pool's entries
+// are adjectival, and any overlap would let the same word land on both sides.
+func TestAdjectives_AreDisjointFromNouns(t *testing.T) {
+	nouns := make(map[string]struct{}, len(uniqueWords()))
+	for _, w := range uniqueWords() {
+		nouns[w] = struct{}{}
+	}
+	for _, a := range adjectives {
+		_, clash := nouns[a]
+		assert.False(t, clash, "Adjective %q also appears in the noun pool; remove it from one list", a)
+	}
+}
+
+// TestAdjectives_AreDNSSafeAndDeduplicated mirrors the curation contract stated
+// in words.go: lowercase ASCII, 4-12 chars, no digits or hyphens, no repeats.
+func TestAdjectives_AreDNSSafeAndDeduplicated(t *testing.T) {
+	seen := make(map[string]struct{}, len(adjectives))
+	for _, a := range adjectives {
+		_, dup := seen[a]
+		assert.False(t, dup, "Duplicate adjective %q", a)
+		seen[a] = struct{}{}
+
+		assert.Regexp(t, `^[a-z]{4,12}$`, a, "Adjective %q must be 4-12 lowercase ASCII letters", a)
+	}
+	assert.Greater(t, len(adjectives), 150, "Adjective pool too small to give a useful namespace")
+}
+
+// TestPickTuple_DeterministicWithSeededRng documents that generation is a pure
+// function of the rng, which is what makes allocation retries reproducible in tests.
+func TestPickTuple_DeterministicWithSeededRng(t *testing.T) {
+	a := PickTuple(rand.New(rand.NewSource(42)))
+	b := PickTuple(rand.New(rand.NewSource(42)))
+	assert.Equal(t, a, b, "Same seed must yield the same tuple")
+}
+
+// TestPickTuple_SpansALargeNamespace guards the reason we moved to tuples: a
+// single-word pool caps the GLOBAL namespace at 857. Drawing many tuples must
+// yield overwhelmingly distinct values.
+func TestPickTuple_SpansALargeNamespace(t *testing.T) {
+	rng := rand.New(rand.NewSource(11))
+	seen := make(map[string]struct{}, 2000)
+	for i := 0; i < 2000; i++ {
+		seen[PickTuple(rng)] = struct{}{}
+	}
+	assert.Greater(t, len(seen), 1900,
+		"2000 draws should be nearly all distinct across a ~200k namespace; got %d unique", len(seen))
+}

management/internals/modules/agentnetwork/manager.go

@@ -22,7 +22,6 @@ import (
 	"github.com/netbirdio/netbird/management/server/permissions/modules"
 	"github.com/netbirdio/netbird/management/server/permissions/operations"
 	"github.com/netbirdio/netbird/management/server/store"
-	"github.com/netbirdio/netbird/shared/management/proto"
 	"github.com/netbirdio/netbird/shared/management/status"
 )
 
@@ -48,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
 
@@ -71,7 +70,9 @@ 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)
+	DeleteSettings(ctx context.Context, accountID, userID string) error
 
 	ListConsumption(ctx context.Context, accountID, userID string) ([]*types.Consumption, error)
 	ListAccessLogs(ctx context.Context, accountID, userID string, filter types.AgentNetworkAccessLogFilter) ([]*types.AgentNetworkAccessLog, int64, error)
@@ -123,11 +124,10 @@ type managerImpl struct {
 	proxyController    proxy.Controller
 
 	// reconcileCache holds the last set of synthesised proxy mappings
-	// per account so reconcile can emit precise Create/Update/Delete
-	// updates instead of a full re-push on every mutation. Keyed by
-	// accountID, then by synthesised service ID.
+	// per account, each paired with the proxy that served it, so a change
+	// of serving proxy can be diffed without re-deriving it.
 	reconcileMu    sync.Mutex
-	reconcileCache map[string]map[string]*proto.ProxyMapping
+	reconcileCache map[string]map[string]syntheticMapping
 
 	// labelRngMu guards labelRng. PickUnique consumes math/rand.Source
 	// state; concurrent provider creates would otherwise race.
@@ -151,7 +151,7 @@ func NewManager(
 		accountManager:     accountManager,
 		permissionsManager: permissionsManager,
 		proxyController:    proxyController,
-		reconcileCache:     make(map[string]map[string]*proto.ProxyMapping),
+		reconcileCache:     make(map[string]map[string]syntheticMapping),
 		labelRng:           rand.New(rand.NewSource(time.Now().UnixNano())),
 	}
 }
@@ -170,19 +170,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
@@ -206,16 +201,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)
 
@@ -560,52 +545,44 @@ 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 immutable: the
+// request carries them, matching the PUT convention of every other endpoint,
+// but they are only compared against the stored row — a request carrying
+// different values is rejected, and the stored values are never overwritten.
+// 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)
 		}
 
+		// The identity echo is compared leniently (trimmed, case-insensitive):
+		// the stored values are normalized lowercase, and a client replaying a
+		// GET response must never be rejected over casing it didn't choose.
+		if !hostnamesEquivalent(settings.Domain, existing.Domain) {
+			return status.Errorf(status.InvalidArgument, "endpoint is immutable: it must match the assigned endpoint %q; delete the settings to release it and bootstrap again", existing.Domain)
+		}
+		if !hostnamesEquivalent(settings.ProxyAddress, existing.ProxyAddress) {
+			return status.Errorf(status.InvalidArgument, "proxy_address is immutable: it must match the assigned proxy address %q; delete the settings to release it and bootstrap again", existing.ProxyAddress)
+		}
+
 		existing.EnableLogCollection = settings.EnableLogCollection
 		existing.EnablePromptCollection = settings.EnablePromptCollection
 		existing.RedactPii = settings.RedactPii
@@ -632,6 +609,83 @@ func (m *managerImpl) UpdateSettings(ctx context.Context, userID string, setting
 	return updated, nil
 }
 
+// hostnamesEquivalent reports whether a caller-supplied hostname names the
+// same host as a stored (normalized, lowercase) one: equal after trimming and
+// case folding. No structural validation — an arbitrary mismatch and a
+// malformed value are both simply "not the assigned value".
+func hostnamesEquivalent(supplied, stored string) bool {
+	return strings.EqualFold(strings.TrimSpace(supplied), stored)
+}
+
+// DeleteSettings removes the account's settings row, releasing the endpoint.
+// Two guards make this a bootstrap-repair operation rather than a way to tear
+// down a serving gateway, both re-checked under the row lock:
+//
+//   - No Agent Network providers may exist for the account. Providers route
+//     through the endpoint; delete them first.
+//   - No proxy may be actively serving the endpoint — that is, no active proxy
+//     declares the endpoint hostname as its cluster address. This is the
+//     dedicated (self-addressed) shape's guard: the proxy at the address IS
+//     this account's gateway. A labeled endpoint hangs beneath a shared
+//     cluster's address, and with the account's providers already gone the
+//     shared proxy serves nothing of the account's, so the parent cluster
+//     being up does not block the delete.
+//
+// Bootstrapping again after a delete allocates fresh — the released hostname
+// is not reserved. That full-reset semantic is what gives clients that model
+// immutability as replace-on-change (e.g. Terraform's RequiresReplace) a real
+// path: tear down providers, delete, re-create.
+func (m *managerImpl) DeleteSettings(ctx context.Context, accountID, userID string) error {
+	if err := m.requirePermission(ctx, accountID, userID, modules.AgentNetworkSettings, operations.Delete); err != nil {
+		return err
+	}
+
+	var deleted *types.Settings
+	err := m.store.ExecuteInTransaction(ctx, func(tx store.Store) error {
+		existing, err := tx.GetAgentNetworkSettings(ctx, store.LockingStrengthUpdate, accountID)
+		switch {
+		case err == nil:
+		case isNotFound(err):
+			return status.Errorf(status.NotFound, "agent network settings have not been bootstrapped yet; there is nothing to delete")
+		default:
+			return fmt.Errorf("get agent network settings: %w", err)
+		}
+
+		providers, err := tx.GetAccountAgentNetworkProviders(ctx, store.LockingStrengthNone, accountID)
+		if err != nil {
+			return fmt.Errorf("get agent network providers: %w", err)
+		}
+		if len(providers) > 0 {
+			return status.Errorf(status.PreconditionFailed, "agent network settings cannot be deleted while %d provider(s) exist; delete the providers first", len(providers))
+		}
+
+		serving, err := tx.HasActiveProxyAtClusterAddress(ctx, existing.Domain)
+		if err != nil {
+			return fmt.Errorf("check for a proxy serving the endpoint: %w", err)
+		}
+		if serving {
+			return status.Errorf(status.PreconditionFailed, "agent network settings cannot be deleted while a proxy is actively serving the endpoint %q", existing.Domain)
+		}
+
+		if err := tx.DeleteAgentNetworkSettings(ctx, accountID); err != nil {
+			return fmt.Errorf("delete agent network settings: %w", err)
+		}
+		deleted = existing
+		return nil
+	})
+	if err != nil {
+		return err
+	}
+
+	m.accountManager.StoreEvent(ctx, userID, accountID, accountID, activity.AgentNetworkSettingsDeleted, map[string]any{
+		"endpoint":      deleted.Domain,
+		"proxy_address": deleted.ProxyAddress,
+	})
+	m.reconcile(ctx, accountID)
+
+	return nil
+}
+
 // isNotFound reports whether err is a status.NotFound error.
 func isNotFound(err error) bool {
 	var sErr *status.Error
@@ -678,74 +732,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
@@ -879,7 +1021,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
 }
 
@@ -947,10 +1089,23 @@ 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
 }
 
+func (*mockManager) DeleteSettings(_ context.Context, _, _ string) error { return nil }
+
 func (*mockManager) ListConsumption(_ context.Context, _, _ string) ([]*types.Consumption, error) {
 	return nil, 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.go

@@ -10,6 +10,17 @@ import (
 	"github.com/netbirdio/netbird/shared/management/proto"
 )
 
+// syntheticMapping pairs a synthesised proxy mapping with the address of the
+// proxy that serves it. The cluster is recorded rather than derived from the
+// mapping's domain: ProxyMapping does not carry it, and the previous derivation
+// -- everything after the first DNS label -- is wrong whenever the service's
+// domain is not one label under its proxy's address, which silently addressed
+// updates to a cluster no proxy declares.
+type syntheticMapping struct {
+	mapping *proto.ProxyMapping
+	cluster string
+}
+
 // reconcile recomputes the synthesised reverse-proxy services for an
 // account, diffs them against the previously-synthesised set in the
 // in-memory cache, and emits Create / Update / Delete proxy mappings
@@ -45,18 +56,21 @@ func (m *managerImpl) reconcile(ctx context.Context, accountID string) {
 	}
 
 	oidcCfg := m.proxyController.GetOIDCValidationConfig()
-	current := make(map[string]*proto.ProxyMapping, len(services))
+	current := make(map[string]syntheticMapping, len(services))
 	for _, svc := range services {
 		if svc == nil || svc.ID == "" {
 			continue
 		}
-		current[svc.ID] = svc.ToProtoMapping(rpservice.Update, "", oidcCfg)
+		current[svc.ID] = syntheticMapping{
+			mapping: svc.ToProtoMapping(rpservice.Update, "", oidcCfg),
+			cluster: svc.ProxyCluster,
+		}
 	}
 
 	m.reconcileMu.Lock()
 	previous := m.reconcileCache[accountID]
 	if previous == nil {
-		previous = make(map[string]*proto.ProxyMapping)
+		previous = make(map[string]syntheticMapping)
 	}
 
 	creates, updates, deletes := diffMappings(previous, current)
@@ -67,34 +81,36 @@ func (m *managerImpl) reconcile(ctx context.Context, accountID string) {
 	}
 	m.reconcileMu.Unlock()
 
-	for _, mapping := range creates {
-		mapping.Type = proto.ProxyMappingUpdateType_UPDATE_TYPE_CREATED
-		m.proxyController.SendServiceUpdateToCluster(ctx, accountID, mapping, clusterFromMapping(mapping))
+	for _, entry := range creates {
+		entry.mapping.Type = proto.ProxyMappingUpdateType_UPDATE_TYPE_CREATED
+		m.proxyController.SendServiceUpdateToCluster(ctx, accountID, entry.mapping, entry.cluster)
 	}
-	for _, mapping := range updates {
-		mapping.Type = proto.ProxyMappingUpdateType_UPDATE_TYPE_MODIFIED
-		m.proxyController.SendServiceUpdateToCluster(ctx, accountID, mapping, clusterFromMapping(mapping))
+	for _, entry := range updates {
+		entry.mapping.Type = proto.ProxyMappingUpdateType_UPDATE_TYPE_MODIFIED
+		m.proxyController.SendServiceUpdateToCluster(ctx, accountID, entry.mapping, entry.cluster)
 	}
-	for _, mapping := range deletes {
-		mapping.Type = proto.ProxyMappingUpdateType_UPDATE_TYPE_REMOVED
-		m.proxyController.SendServiceUpdateToCluster(ctx, accountID, mapping, clusterFromMapping(mapping))
+	for _, entry := range deletes {
+		entry.mapping.Type = proto.ProxyMappingUpdateType_UPDATE_TYPE_REMOVED
+		m.proxyController.SendServiceUpdateToCluster(ctx, accountID, entry.mapping, entry.cluster)
 	}
 }
 
-// diffMappings classifies the previous→current transition for a
-// single account into Create / Update / Delete sets.
+// diffMappings classifies the previous→current transition for a single
+// account into Create / Update / Delete sets.
 //
-// Cluster moves (current.cluster != previous.cluster) are surfaced as
-// a Delete on the old cluster + Create on the new — handled by
-// emitting both a delete (on previous mapping) and a create (on the
-// current mapping) for that service ID.
-func diffMappings(previous, current map[string]*proto.ProxyMapping) (creates, updates, deletes []*proto.ProxyMapping) {
+// A change of serving proxy for the same service ID is surfaced as a Delete
+// addressed to the old proxy plus a Create addressed to the new one, so the
+// mapping actually moves. Comparing the recorded cluster is what makes that
+// detectable: with a placement-free endpoint the mapping's domain is identical
+// before and after the move, so nothing about the mapping itself reveals it.
+func diffMappings(previous, current map[string]syntheticMapping) (creates, updates, deletes []syntheticMapping) {
 	for id, cur := range current {
 		prev, existed := previous[id]
 		switch {
 		case !existed:
 			creates = append(creates, cur)
-		case prev.GetDomain() == "" || cur.GetAccountId() == prev.GetAccountId() && currentClusterChanged(prev, cur):
+		case prev.mapping.GetDomain() == "" ||
+			cur.mapping.GetAccountId() == prev.mapping.GetAccountId() && prev.cluster != cur.cluster:
 			deletes = append(deletes, prev)
 			creates = append(creates, cur)
 		default:
@@ -108,24 +124,3 @@ func diffMappings(previous, current map[string]*proto.ProxyMapping) (creates, up
 	}
 	return creates, updates, deletes
 }
-
-func currentClusterChanged(prev, cur *proto.ProxyMapping) bool {
-	return clusterFromMapping(prev) != clusterFromMapping(cur)
-}
-
-// clusterFromMapping returns the cluster the mapping should be sent
-// to. ProxyMapping doesn't carry the cluster directly, so we rely on
-// the synthesised service's domain (`<slug>.<cluster>`) and split on
-// the first '.'.
-func clusterFromMapping(m *proto.ProxyMapping) string {
-	if m == nil {
-		return ""
-	}
-	domain := m.GetDomain()
-	for i := 0; i < len(domain); i++ {
-		if domain[i] == '.' {
-			return domain[i+1:]
-		}
-	}
-	return ""
-}

management/internals/modules/agentnetwork/reconcile_test.go

@@ -21,7 +21,7 @@ func newReconcileMgr(t *testing.T, ctrl *gomock.Controller) (*managerImpl, *stor
 	return &managerImpl{
 		store:           mockStore,
 		proxyController: mockProxy,
-		reconcileCache:  make(map[string]map[string]*proto.ProxyMapping),
+		reconcileCache:  make(map[string]map[string]syntheticMapping),
 	}, mockStore, mockProxy
 }
 
@@ -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",
 	}
 }
 
@@ -196,7 +196,7 @@ func TestReconcile_PolicyRemoved_EmitsDelete(t *testing.T) {
 func TestReconcile_NilProxyController_NoOp(t *testing.T) {
 	ctx := context.Background()
 	mgr := &managerImpl{
-		reconcileCache: make(map[string]map[string]*proto.ProxyMapping),
+		reconcileCache: make(map[string]map[string]syntheticMapping),
 	}
 	// Must not panic; must not query the store.
 	mgr.reconcile(ctx, "acct-1")
@@ -212,21 +212,78 @@ func TestReconcile_EmptyAccountID_NoOp(t *testing.T) {
 	mgr.reconcile(ctx, "")
 }
 
-func TestClusterFromMapping(t *testing.T) {
-	tests := []struct {
-		name   string
-		domain string
-		want   string
-	}{
-		{"simple", "openai.eu.proxy.netbird.io", "eu.proxy.netbird.io"},
-		{"deeply nested", "a.b.c.d", "b.c.d"},
-		{"no dot", "openai", ""},
-		{"empty", "", ""},
+// TestDiffMappings_ServingProxyChange — when the proxy serving an account
+// changes, the same service ID must be deleted on the old proxy and created on
+// the new one. The cluster cannot be recovered from the mapping's domain: with a
+// placement-free endpoint the domain does not change at all when the serving
+// proxy does, so a domain-derived cluster sees no change and emits a plain
+// update, addressed to a proxy that does not exist.
+func TestDiffMappings_ServingProxyChange(t *testing.T) {
+	previous := map[string]syntheticMapping{
+		"svc-1": {
+			mapping: &proto.ProxyMapping{Id: "svc-1", AccountId: "acct-1", Domain: "brave-otter.gateway.example.com"},
+			cluster: "proxy.example.com",
+		},
 	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got := clusterFromMapping(&proto.ProxyMapping{Domain: tt.domain})
-			assert.Equal(t, tt.want, got)
-		})
+	current := map[string]syntheticMapping{
+		"svc-1": {
+			mapping: &proto.ProxyMapping{Id: "svc-1", AccountId: "acct-1", Domain: "brave-otter.gateway.example.com"},
+			cluster: "brave-otter.gateway.example.com",
+		},
+	}
+
+	creates, updates, deletes := diffMappings(previous, current)
+
+	if assert.Len(t, deletes, 1, "the old proxy must be told to drop the mapping") {
+		assert.Equal(t, "proxy.example.com", deletes[0].cluster)
+	}
+	if assert.Len(t, creates, 1, "the new proxy must be told to add it") {
+		assert.Equal(t, "brave-otter.gateway.example.com", creates[0].cluster)
+	}
+	assert.Empty(t, updates, "a serving-proxy move is a delete plus a create, not an update")
+}
+
+// TestDiffMappings_UnchangedClusterIsAnUpdate keeps the ordinary path: same
+// service, same proxy, changed contents.
+func TestDiffMappings_UnchangedClusterIsAnUpdate(t *testing.T) {
+	previous := map[string]syntheticMapping{
+		"svc-1": {
+			mapping: &proto.ProxyMapping{Id: "svc-1", AccountId: "acct-1", Domain: "otter.proxy.example.com"},
+			cluster: "proxy.example.com",
+		},
+	}
+	current := map[string]syntheticMapping{
+		"svc-1": {
+			mapping: &proto.ProxyMapping{Id: "svc-1", AccountId: "acct-1", Domain: "otter.proxy.example.com"},
+			cluster: "proxy.example.com",
+		},
+	}
+
+	creates, updates, deletes := diffMappings(previous, current)
+
+	assert.Empty(t, creates)
+	assert.Empty(t, deletes)
+	if assert.Len(t, updates, 1) {
+		assert.Equal(t, "proxy.example.com", updates[0].cluster)
+	}
+}
+
+// TestDiffMappings_RemovedServiceIsDeletedOnItsOwnCluster — a service that has
+// gone away is deleted on the cluster it was last served by, which is recorded
+// rather than re-derived.
+func TestDiffMappings_RemovedServiceIsDeletedOnItsOwnCluster(t *testing.T) {
+	previous := map[string]syntheticMapping{
+		"svc-1": {
+			mapping: &proto.ProxyMapping{Id: "svc-1", AccountId: "acct-1", Domain: "brave-otter.gateway.example.com"},
+			cluster: "brave-otter.gateway.example.com",
+		},
+	}
+
+	creates, updates, deletes := diffMappings(previous, map[string]syntheticMapping{})
+
+	assert.Empty(t, creates)
+	assert.Empty(t, updates)
+	if assert.Len(t, deletes, 1) {
+		assert.Equal(t, "brave-otter.gateway.example.com", deletes[0].cluster)
 	}
 }

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_realstore_test.go

@@ -147,7 +147,7 @@ func TestReconcile_RealStore_PushesPrivateAfterStatusToggle(t *testing.T) {
 		store:           s,
 		accountManager:  noopAccountManager{},
 		proxyController: ctrl,
-		reconcileCache:  make(map[string]map[string]*proto.ProxyMapping),
+		reconcileCache:  make(map[string]map[string]syntheticMapping),
 	}
 
 	m.reconcile(ctx, testAccountID) // initial, provider enabled

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,19 +102,91 @@ 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: every mutable
+// field is replaced with the request value, and the identity fields (Domain,
+// ProxyAddress) carry the request's echo of the assigned values. The identity
+// fields are never written to the stored row — UpdateSettings compares them
+// against it and rejects the request when they differ, so PUT keeps the
+// house convention of requiring every field while the endpoint and proxy
+// address stay immutable.
+//
+// Every field is required by the schema, so none is presence-sensitive.
+// AccessLogRetentionDays in particular must stay required: the caller receives
+// a zero-valued Settings, and UpdateSettings copies each field onto the stored
+// row unconditionally, so an omitted value would be written as 0 — which the
+// API documents as "keep indefinitely". Making retention optional would
+// therefore let a client silently maximise log retention by leaving it out.
 func (s *Settings) FromAPIRequest(req *api.AgentNetworkSettingsRequest) {
-	if req.Cluster != nil {
-		s.Cluster = strings.TrimSpace(*req.Cluster)
-	}
+	s.Domain = req.Endpoint
+	s.ProxyAddress = req.ProxyAddress
 	s.EnableLogCollection = req.EnableLogCollection
 	s.EnablePromptCollection = req.EnablePromptCollection
 	s.RedactPii = req.RedactPii
+	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/internals/modules/reverseproxy/domain/manager/manager.go

@@ -2,24 +2,28 @@ package manager
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"net"
 	"strings"
 
 	log "github.com/sirupsen/logrus"
 
+	agentnetworkTypes "github.com/netbirdio/netbird/management/internals/modules/agentnetwork/types"
 	"github.com/netbirdio/netbird/management/internals/modules/reverseproxy/domain"
 	"github.com/netbirdio/netbird/management/server/account"
 	"github.com/netbirdio/netbird/management/server/activity"
 	"github.com/netbirdio/netbird/management/server/permissions"
 	"github.com/netbirdio/netbird/management/server/permissions/modules"
 	"github.com/netbirdio/netbird/management/server/permissions/operations"
+	nbstore "github.com/netbirdio/netbird/management/server/store"
 	"github.com/netbirdio/netbird/management/server/types"
 	"github.com/netbirdio/netbird/shared/management/status"
 )
 
 type store interface {
 	GetAccount(ctx context.Context, accountID string) (*types.Account, error)
+	GetAgentNetworkSettings(ctx context.Context, lockStrength nbstore.LockingStrength, accountID string) (*agentnetworkTypes.Settings, error)
 
 	GetCustomDomain(ctx context.Context, accountID string, domainID string) (*domain.Domain, error)
 	ListFreeDomains(ctx context.Context, accountID string) ([]string, error)
@@ -311,17 +315,21 @@ func (m Manager) getClusterAllowList(ctx context.Context, accountID string) ([]s
 	if err != nil {
 		return nil, fmt.Errorf("get public cluster addresses: %w", err)
 	}
+	reserved, err := m.reservedGatewayAddress(ctx, accountID)
+	if err != nil {
+		return nil, err
+	}
 	seen := make(map[string]struct{}, len(byopAddresses)+len(publicAddresses))
 	merged := make([]string, 0, len(byopAddresses)+len(publicAddresses))
 	for _, addr := range byopAddresses {
-		if _, ok := seen[addr]; ok {
+		if _, ok := seen[addr]; ok || addr == reserved {
 			continue
 		}
 		seen[addr] = struct{}{}
 		merged = append(merged, addr)
 	}
 	for _, addr := range publicAddresses {
-		if _, ok := seen[addr]; ok {
+		if _, ok := seen[addr]; ok || addr == reserved {
 			continue
 		}
 		seen[addr] = struct{}{}
@@ -330,6 +338,31 @@ func (m Manager) getClusterAllowList(ctx context.Context, accountID string) ([]s
 	return merged, nil
 }
 
+// reservedGatewayAddress returns the account's agent-network gateway address
+// when its settings pin is self-addressed — a proxy dedicated to serving
+// exactly the gateway. Dropping that address from the cluster allow list keeps
+// it from being offered as a cluster for ordinary services, and because the
+// free-domain suffix match is depth-independent, dropping the address rejects
+// every name beneath it as well as the bare one. Only the account's own
+// gateway address can ever appear in its allow list (another tenant's gateway
+// proxy is account-scoped to them), so this single-address exclusion is
+// sufficient. Returns "" when the account has no settings row or a labeled
+// (shared-cluster) pin.
+func (m Manager) reservedGatewayAddress(ctx context.Context, accountID string) (string, error) {
+	settings, err := m.store.GetAgentNetworkSettings(ctx, nbstore.LockingStrengthNone, accountID)
+	if err != nil {
+		var sErr *status.Error
+		if errors.As(err, &sErr) && sErr.Type() == status.NotFound {
+			return "", nil
+		}
+		return "", fmt.Errorf("get agent network settings: %w", err)
+	}
+	if settings == nil || !settings.Dedicated() {
+		return "", nil
+	}
+	return settings.ProxyAddress, nil
+}
+
 func extractClusterFromCustomDomains(serviceDomain string, customDomains []*domain.Domain) (string, bool) {
 	bestCluster := ""
 	bestLen := -1

management/internals/modules/reverseproxy/domain/manager/manager_test.go

@@ -7,6 +7,12 @@ import (
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+
+	agentnetworkTypes "github.com/netbirdio/netbird/management/internals/modules/agentnetwork/types"
+	"github.com/netbirdio/netbird/management/internals/modules/reverseproxy/domain"
+	nbstore "github.com/netbirdio/netbird/management/server/store"
+	"github.com/netbirdio/netbird/management/server/types"
+	"github.com/netbirdio/netbird/shared/management/status"
 )
 
 type mockProxyManager struct {
@@ -55,7 +61,7 @@ func TestGetClusterAllowList_BYOPMergedWithPublic(t *testing.T) {
 		},
 	}
 
-	mgr := Manager{proxyManager: pm}
+	mgr := Manager{store: &stubStore{}, proxyManager: pm}
 	result, err := mgr.getClusterAllowList(context.Background(), "acc-123")
 	require.NoError(t, err)
 	assert.Equal(t, []string{"byop.example.com", "eu.proxy.netbird.io"}, result)
@@ -71,7 +77,7 @@ func TestGetClusterAllowList_DeduplicatesBYOPAndPublic(t *testing.T) {
 		},
 	}
 
-	mgr := Manager{proxyManager: pm}
+	mgr := Manager{store: &stubStore{}, proxyManager: pm}
 	result, err := mgr.getClusterAllowList(context.Background(), "acc-123")
 	require.NoError(t, err)
 	assert.Equal(t, []string{"shared.example.com", "byop.example.com", "eu.proxy.netbird.io"}, result)
@@ -87,7 +93,7 @@ func TestGetClusterAllowList_NoBYOP_FallbackToShared(t *testing.T) {
 		},
 	}
 
-	mgr := Manager{proxyManager: pm}
+	mgr := Manager{store: &stubStore{}, proxyManager: pm}
 	result, err := mgr.getClusterAllowList(context.Background(), "acc-123")
 	require.NoError(t, err)
 	assert.Equal(t, []string{"eu.proxy.netbird.io", "us.proxy.netbird.io"}, result)
@@ -100,7 +106,7 @@ func TestGetClusterAllowList_BYOPError_ReturnsError(t *testing.T) {
 		},
 	}
 
-	mgr := Manager{proxyManager: pm}
+	mgr := Manager{store: &stubStore{}, proxyManager: pm}
 	result, err := mgr.getClusterAllowList(context.Background(), "acc-123")
 	require.Error(t, err)
 	assert.Nil(t, result)
@@ -117,7 +123,7 @@ func TestGetClusterAllowList_PublicError_ReturnsError(t *testing.T) {
 		},
 	}
 
-	mgr := Manager{proxyManager: pm}
+	mgr := Manager{store: &stubStore{}, proxyManager: pm}
 	result, err := mgr.getClusterAllowList(context.Background(), "acc-123")
 	require.Error(t, err)
 	assert.Nil(t, result)
@@ -134,7 +140,7 @@ func TestGetClusterAllowList_BYOPEmptySlice_FallbackToShared(t *testing.T) {
 		},
 	}
 
-	mgr := Manager{proxyManager: pm}
+	mgr := Manager{store: &stubStore{}, proxyManager: pm}
 	result, err := mgr.getClusterAllowList(context.Background(), "acc-123")
 	require.NoError(t, err)
 	assert.Equal(t, []string{"eu.proxy.netbird.io"}, result)
@@ -150,8 +156,138 @@ func TestGetClusterAllowList_PublicEmpty_BYOPOnly(t *testing.T) {
 		},
 	}
 
-	mgr := Manager{proxyManager: pm}
+	mgr := Manager{store: &stubStore{}, proxyManager: pm}
 	result, err := mgr.getClusterAllowList(context.Background(), "acc-123")
 	require.NoError(t, err)
 	assert.Equal(t, []string{"byop.example.com"}, result)
 }
+
+// stubStore satisfies the manager's narrow store interface for allow-list
+// tests. Only the agent-network settings lookup participates; the default (a
+// nil func) reads as "no settings row", the state most accounts are in.
+type stubStore struct {
+	getAgentNetworkSettingsFunc func(ctx context.Context, accountID string) (*agentnetworkTypes.Settings, error)
+}
+
+func (s *stubStore) GetAccount(context.Context, string) (*types.Account, error) {
+	panic("not used in allow-list tests")
+}
+
+func (s *stubStore) GetAgentNetworkSettings(ctx context.Context, _ nbstore.LockingStrength, accountID string) (*agentnetworkTypes.Settings, error) {
+	if s.getAgentNetworkSettingsFunc != nil {
+		return s.getAgentNetworkSettingsFunc(ctx, accountID)
+	}
+	return nil, status.Errorf(status.NotFound, "agent network settings for account %s not found", accountID)
+}
+
+func (s *stubStore) GetCustomDomain(context.Context, string, string) (*domain.Domain, error) {
+	panic("not used in allow-list tests")
+}
+
+func (s *stubStore) ListFreeDomains(context.Context, string) ([]string, error) {
+	panic("not used in allow-list tests")
+}
+
+func (s *stubStore) ListCustomDomains(context.Context, string) ([]*domain.Domain, error) {
+	panic("not used in allow-list tests")
+}
+
+func (s *stubStore) CreateCustomDomain(context.Context, string, string, string, bool) (*domain.Domain, error) {
+	panic("not used in allow-list tests")
+}
+
+func (s *stubStore) UpdateCustomDomain(context.Context, string, *domain.Domain) (*domain.Domain, error) {
+	panic("not used in allow-list tests")
+}
+
+func (s *stubStore) DeleteCustomDomain(context.Context, string, string) error {
+	panic("not used in allow-list tests")
+}
+
+// TestGetClusterAllowList_DedicatedGatewayAddressExcluded pins invariant (B)'s
+// chokepoint: a self-addressed settings pin reserves the account's gateway
+// address, so it is dropped from the allow list — which, because the
+// free-domain suffix match is depth-independent, rejects every name beneath
+// it as well as the bare one. Other addresses are unaffected.
+func TestGetClusterAllowList_DedicatedGatewayAddressExcluded(t *testing.T) {
+	pm := &mockProxyManager{
+		getActiveClusterAddressesForAccountFunc: func(_ context.Context, _ string) ([]string, error) {
+			return []string{"brave-otter.gateway.example.com", "byop.example.com"}, nil
+		},
+		getActiveClusterAddressesFunc: func(_ context.Context) ([]string, error) {
+			return []string{"eu.proxy.netbird.io"}, nil
+		},
+	}
+	st := &stubStore{
+		getAgentNetworkSettingsFunc: func(_ context.Context, accountID string) (*agentnetworkTypes.Settings, error) {
+			assert.Equal(t, "acc-123", accountID,
+				"the exclusion must look up the requesting account's own settings")
+			return &agentnetworkTypes.Settings{
+				AccountID:    accountID,
+				Domain:       "brave-otter.gateway.example.com",
+				ProxyAddress: "brave-otter.gateway.example.com",
+			}, nil
+		},
+	}
+
+	mgr := Manager{store: st, proxyManager: pm}
+	result, err := mgr.getClusterAllowList(context.Background(), "acc-123")
+	require.NoError(t, err)
+	assert.Equal(t, []string{"byop.example.com", "eu.proxy.netbird.io"}, result,
+		"the dedicated gateway address must be reserved from cluster selection")
+}
+
+// TestGetClusterAllowList_LabeledPinDoesNotExclude pins the counterpart: a
+// labeled pin means the gateway rides on a shared cluster serving ordinary
+// services too, so nothing is reserved.
+func TestGetClusterAllowList_LabeledPinDoesNotExclude(t *testing.T) {
+	pm := &mockProxyManager{
+		getActiveClusterAddressesForAccountFunc: func(_ context.Context, _ string) ([]string, error) {
+			return []string{"byop.example.com"}, nil
+		},
+		getActiveClusterAddressesFunc: func(_ context.Context) ([]string, error) {
+			return []string{"eu.proxy.netbird.io"}, nil
+		},
+	}
+	st := &stubStore{
+		getAgentNetworkSettingsFunc: func(_ context.Context, accountID string) (*agentnetworkTypes.Settings, error) {
+			return &agentnetworkTypes.Settings{
+				AccountID:    accountID,
+				Domain:       "violet.eu.proxy.netbird.io",
+				ProxyAddress: "eu.proxy.netbird.io",
+			}, nil
+		},
+	}
+
+	mgr := Manager{store: st, proxyManager: pm}
+	result, err := mgr.getClusterAllowList(context.Background(), "acc-123")
+	require.NoError(t, err)
+	assert.Equal(t, []string{"byop.example.com", "eu.proxy.netbird.io"}, result,
+		"a labeled pin reserves nothing")
+}
+
+// TestGetClusterAllowList_SettingsLookupError_ReturnsError pins that a store
+// outage is surfaced rather than silently treated as "nothing reserved" —
+// failing open here would offer a reserved gateway address for ordinary
+// services.
+func TestGetClusterAllowList_SettingsLookupError_ReturnsError(t *testing.T) {
+	pm := &mockProxyManager{
+		getActiveClusterAddressesForAccountFunc: func(_ context.Context, _ string) ([]string, error) {
+			return []string{"byop.example.com"}, nil
+		},
+		getActiveClusterAddressesFunc: func(_ context.Context) ([]string, error) {
+			return []string{"eu.proxy.netbird.io"}, nil
+		},
+	}
+	st := &stubStore{
+		getAgentNetworkSettingsFunc: func(_ context.Context, _ string) (*agentnetworkTypes.Settings, error) {
+			return nil, status.Errorf(status.Internal, "store outage")
+		},
+	}
+
+	mgr := Manager{store: st, proxyManager: pm}
+	result, err := mgr.getClusterAllowList(context.Background(), "acc-123")
+	require.Error(t, err)
+	assert.Nil(t, result)
+	assert.Contains(t, err.Error(), "agent network settings")
+}

management/server/activity/codes.go

@@ -281,6 +281,9 @@ const (
 	// AccountMetricsPushDisabled indicates that a user disabled metrics push for the account
 	AccountMetricsPushDisabled Activity = 141
 
+	// AgentNetworkSettingsDeleted indicates that a user deleted the Agent Network account settings, releasing the endpoint
+	AgentNetworkSettingsDeleted Activity = 142
+
 	AccountDeleted Activity = 99999
 )
 
@@ -453,6 +456,7 @@ var activityMap = map[Activity]Code{
 	AgentNetworkBudgetRuleDeleted: {"Agent Network budget rule deleted", "agent_network.budget_rule.delete"},
 
 	AgentNetworkSettingsUpdated: {"Agent Network settings updated", "agent_network.settings.update"},
+	AgentNetworkSettingsDeleted: {"Agent Network settings deleted", "agent_network.settings.delete"},
 
 	AccountMetricsPushEnabled:  {"Account metrics push enabled", "account.setting.metrics.push.enable"},
 	AccountMetricsPushDisabled: {"Account metrics push disabled", "account.setting.metrics.push.disable"},

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,14 @@ 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")
+	// The bootstrap itself reconciles and queues updates on both channels;
+	// drain them so the fan-out assertions below can only be satisfied by the
+	// operation under test, not by this leftover.
+	drain(clientCh)
+	drain(proxyCh)
+
 	provider, err := agentMgr.CreateProvider(ctx, adminUserID, &agenttypes.Provider{
 		AccountID:   accountID,
 		ProviderID:  "openai_api",
@@ -100,7 +108,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,112 @@
+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.
+//
+// The transaction is real only on sqlite and postgres, where DDL is
+// transactional. MySQL implicitly commits around every ALTER TABLE, so there
+// each step stands alone; what makes an interrupted run resumable on MySQL is
+// that every step is guarded by the schema state it changes — the entry check
+// fires while either legacy column remains, the adds skip existing columns,
+// the backfill and its loud-failure check run only while the legacy cluster
+// column exists (they provably completed before any drop), and each drop
+// skips what is already gone.
+func MigrateAgentNetworkSettingsToDomain(ctx context.Context, db *gorm.DB) error {
+	model := &agentNetworkSettingsMigration{}
+	migrator := db.Migrator()
+
+	if !migrator.HasTable(model) {
+		return nil
+	}
+	hasCluster := migrator.HasColumn(model, "cluster")
+	if !hasCluster && !migrator.HasColumn(model, "subdomain") {
+		// 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)
+				}
+			}
+		}
+
+		if hasCluster {
+			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 res.RowsAffected > 0 {
+				log.WithContext(ctx).Infof("migrated %d agent_network_settings row(s) to domain/proxy_address", res.RowsAffected)
+			}
+		}
+
+		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 txMigrator.HasColumn(model, field) {
+				if err := txMigrator.DropColumn(model, field); err != nil {
+					return fmt.Errorf("drop legacy agent_network_settings column %s: %w", field, err)
+				}
+			}
+		}
+
+		return nil
+	})
+}

management/server/migration/migration_test.go

@@ -736,3 +736,125 @@ 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")
+}
+
+// partialAgentNetworkSettings models the one non-atomic state a MySQL run can
+// be interrupted in: DDL auto-commits there, so a crash between the two legacy
+// column drops leaves subdomain behind while cluster (and the completed
+// backfill) are already committed.
+type partialAgentNetworkSettings struct {
+	AccountID    string `gorm:"primaryKey"`
+	Subdomain    string
+	Domain       string `gorm:"type:varchar(255)"`
+	ProxyAddress string `gorm:"type:varchar(255)"`
+}
+
+func (partialAgentNetworkSettings) TableName() string { return "agent_network_settings" }
+
+// TestMigrateAgentNetworkSettingsToDomain_ResumesAfterPartialDrop pins MySQL
+// resumability: a rerun over the interrupted state must remove the leftover
+// subdomain column without re-running the backfill (the cluster column that
+// feeds it is gone) and without touching the migrated values.
+func TestMigrateAgentNetworkSettingsToDomain_ResumesAfterPartialDrop(t *testing.T) {
+	ctx := context.Background()
+	db := setupDatabase(t)
+	require.NoError(t, db.Migrator().DropTable(&partialAgentNetworkSettings{}))
+	require.NoError(t, db.AutoMigrate(&partialAgentNetworkSettings{}))
+	require.NoError(t, db.Create(&partialAgentNetworkSettings{
+		AccountID: "acct-1", Subdomain: "violet",
+		Domain: "violet.eu.proxy.netbird.io", ProxyAddress: "eu.proxy.netbird.io",
+	}).Error)
+
+	require.NoError(t, migration.MigrateAgentNetworkSettingsToDomain(ctx, db),
+		"a rerun over a partially-dropped schema must resume, not error")
+
+	migrator := db.Migrator()
+	assert.False(t, migrator.HasColumn(&partialAgentNetworkSettings{}, "subdomain"),
+		"the leftover legacy column must be dropped on resume")
+
+	var row agentNetworkTypes.Settings
+	require.NoError(t, db.First(&row, "account_id = ?", "acct-1").Error)
+	assert.Equal(t, "violet.eu.proxy.netbird.io", row.Domain, "migrated values must be untouched")
+	assert.Equal(t, "eu.proxy.netbird.io", row.ProxyAddress, "migrated values must be untouched")
+}

management/server/store/sql_store.go

@@ -6340,6 +6340,24 @@ func (s *SqlStore) CountProxiesByAccountID(ctx context.Context, accountID string
 	return count, nil
 }
 
+// HasActiveProxyAtClusterAddress reports whether any proxy — shared or
+// account-scoped — is currently active at the given cluster address, using
+// the same connected-within-threshold window as the other active-proxy
+// queries. Backs the agent-network settings delete guard: settings cannot be
+// deleted while a proxy declares the endpoint hostname as its address.
+func (s *SqlStore) HasActiveProxyAtClusterAddress(ctx context.Context, clusterAddress string) (bool, error) {
+	var count int64
+	result := s.db.
+		Model(&proxy.Proxy{}).
+		Where("cluster_address = ? AND status = ? AND last_seen > ?", clusterAddress, proxy.StatusConnected, time.Now().Add(-proxyActiveThreshold)).
+		Count(&count)
+	if result.Error != nil {
+		log.WithContext(ctx).Errorf("failed to count active proxies at cluster address: %v", result.Error)
+		return false, status.Errorf(status.Internal, "failed to count active proxies at cluster address")
+	}
+	return count > 0, nil
+}
+
 func (s *SqlStore) IsClusterAddressConflicting(ctx context.Context, clusterAddress, accountID string) (bool, error) {
 	var count int64
 	result := s.db.

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 {
@@ -346,6 +386,25 @@ func (s *SqlStore) SaveAgentNetworkSettings(ctx context.Context, settings *agent
 	return nil
 }
 
+// DeleteAgentNetworkSettings removes the per-account Agent Network settings
+// row, releasing the account's endpoint. Returns status.NotFound when no row
+// exists. The guards on the delete (no providers, no proxy actively serving
+// the endpoint) live in the manager, which runs this inside a transaction
+// after re-checking them under a row lock.
+func (s *SqlStore) DeleteAgentNetworkSettings(ctx context.Context, accountID string) error {
+	result := s.db.Delete(&agentNetworkTypes.Settings{}, "account_id = ?", accountID)
+	if result.Error != nil {
+		log.WithContext(ctx).Errorf("failed to delete agent network settings from store: %v", result.Error)
+		return status.Errorf(status.Internal, "failed to delete agent network settings from store")
+	}
+
+	if result.RowsAffected == 0 {
+		return status.Errorf(status.NotFound, "agent network settings for account %s not found", accountID)
+	}
+
+	return nil
+}
+
 // IncrementAgentNetworkConsumption atomically upserts the consumption
 // row keyed on (account, dim_kind, dim_id, window_seconds, window_start)
 // and adds the supplied deltas. Concurrent calls from multiple proxy

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

@@ -328,6 +328,7 @@ type Store interface {
 	GetProxyByAccountID(ctx context.Context, accountID string) (*proxy.Proxy, error)
 	CountProxiesByAccountID(ctx context.Context, accountID string) (int64, error)
 	IsClusterAddressConflicting(ctx context.Context, clusterAddress, accountID string) (bool, error)
+	HasActiveProxyAtClusterAddress(ctx context.Context, clusterAddress string) (bool, error)
 	DeleteAccountCluster(ctx context.Context, clusterAddress, accountID string) error
 
 	GetCustomDomainsCounts(ctx context.Context) (total int64, validated int64, err error)
@@ -360,8 +361,11 @@ 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
+	DeleteAgentNetworkSettings(ctx context.Context, accountID string) 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
 	GetAgentNetworkConsumption(ctx context.Context, lockStrength LockingStrength, accountID string, kind agentNetworkTypes.ConsumptionDimension, dimID string, windowSeconds int64, windowStart time.Time) (*agentNetworkTypes.Consumption, error)
@@ -608,6 +612,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()
@@ -493,6 +507,20 @@ func (mr *MockStoreMockRecorder) DeleteAgentNetworkProvider(ctx, accountID, prov
 	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "DeleteAgentNetworkProvider", reflect.TypeOf((*MockStore)(nil).DeleteAgentNetworkProvider), ctx, accountID, providerID)
 }
 
+// DeleteAgentNetworkSettings mocks base method.
+func (m *MockStore) DeleteAgentNetworkSettings(ctx context.Context, accountID string) error {
+	m.ctrl.T.Helper()
+	ret := m.ctrl.Call(m, "DeleteAgentNetworkSettings", ctx, accountID)
+	ret0, _ := ret[0].(error)
+	return ret0
+}
+
+// DeleteAgentNetworkSettings indicates an expected call of DeleteAgentNetworkSettings.
+func (mr *MockStoreMockRecorder) DeleteAgentNetworkSettings(ctx, accountID interface{}) *gomock.Call {
+	mr.mock.ctrl.T.Helper()
+	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "DeleteAgentNetworkSettings", reflect.TypeOf((*MockStore)(nil).DeleteAgentNetworkSettings), ctx, accountID)
+}
+
 // DeleteCustomDomain mocks base method.
 func (m *MockStore) DeleteCustomDomain(ctx context.Context, accountID, domainID string) error {
 	m.ctrl.T.Helper()
@@ -1687,19 +1715,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.
@@ -2956,6 +2999,21 @@ func (mr *MockStoreMockRecorder) GetZoneDNSRecordsByName(ctx, lockStrength, acco
 	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "GetZoneDNSRecordsByName", reflect.TypeOf((*MockStore)(nil).GetZoneDNSRecordsByName), ctx, lockStrength, accountID, zoneID, name)
 }
 
+// HasActiveProxyAtClusterAddress mocks base method.
+func (m *MockStore) HasActiveProxyAtClusterAddress(ctx context.Context, clusterAddress string) (bool, error) {
+	m.ctrl.T.Helper()
+	ret := m.ctrl.Call(m, "HasActiveProxyAtClusterAddress", ctx, clusterAddress)
+	ret0, _ := ret[0].(bool)
+	ret1, _ := ret[1].(error)
+	return ret0, ret1
+}
+
+// HasActiveProxyAtClusterAddress indicates an expected call of HasActiveProxyAtClusterAddress.
+func (mr *MockStoreMockRecorder) HasActiveProxyAtClusterAddress(ctx, clusterAddress interface{}) *gomock.Call {
+	mr.mock.ctrl.T.Helper()
+	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "HasActiveProxyAtClusterAddress", reflect.TypeOf((*MockStore)(nil).HasActiveProxyAtClusterAddress), ctx, clusterAddress)
+}
+
 // IncrementAgentNetworkConsumption mocks base method.
 func (m *MockStore) IncrementAgentNetworkConsumption(ctx context.Context, accountID string, kind types.ConsumptionDimension, dimID string, windowSeconds int64, windowStart time.Time, tokensIn, tokensOut int64, costUSD float64) error {
 	m.ctrl.T.Helper()

proxy/internal/proxy/agent_network_chain_realstack_test.go

@@ -73,8 +73,8 @@ func TestReverseProxy_AgentNetworkRequest_FullChain(t *testing.T) {
 		testAdminUser = "user-admin-1"
 		adminGroupID  = "grp-admins"
 		providerID    = "prov-openai-test"
-		cluster       = "test.proxy.local"
-		subdomain     = "fullchain"
+		domain        = "fullchain.test.proxy.local"
+		proxyAddress  = "test.proxy.local"
 	)
 	testLogger := log.New()
 	testLogger.SetLevel(log.PanicLevel) // keep test output clean
@@ -127,8 +127,8 @@ func TestReverseProxy_AgentNetworkRequest_FullChain(t *testing.T) {
 	// increments on the response leg.
 	require.NoError(t, st.SaveAgentNetworkSettings(ctx, &agentNetworkTypes.Settings{
 		AccountID:              testAccountID,
-		Cluster:                cluster,
-		Subdomain:              subdomain,
+		Domain:                 domain,
+		ProxyAddress:           proxyAddress,
 		EnablePromptCollection: true,
 		EnableLogCollection:    true,
 		RedactPii:              true,

shared/management/client/rest/agentnetwork.go

@@ -57,10 +57,9 @@ func (a *AgentNetworkAPI) GetProvider(ctx context.Context, providerID string) (*
 	return &ret, err
 }
 
-// CreateProvider creates a new Agent Network provider. Set
-// request.BootstrapCluster on the account's first provider to bootstrap the
-// per-account gateway endpoint (alternatively bootstrap via UpdateSettings
-// with a cluster).
+// CreateProvider creates a new Agent Network provider. Providers have no
+// settings side effects — bootstrap the account's gateway endpoint separately
+// via CreateSettings.
 func (a *AgentNetworkAPI) CreateProvider(ctx context.Context, request api.PostApiAgentNetworkProvidersJSONRequestBody) (*api.AgentNetworkProvider, error) {
 	requestBytes, err := json.Marshal(request)
 	if err != nil {
@@ -329,14 +328,13 @@ func (a *AgentNetworkAPI) DeleteBudgetRule(ctx context.Context, ruleID string) e
 	return nil
 }
 
-// GetSettings gets the account's Agent Network gateway settings (cluster,
-// subdomain, endpoint, collection toggles). An account that has not been
-// bootstrapped yet — via UpdateSettings with a cluster, or by creating the
-// first provider with bootstrap_cluster set — reads as the defaults with an
-// empty Cluster, Subdomain and Endpoint. Management servers prior to that
-// contract answered 200 with a JSON null body instead; that legacy shape is
-// translated to an APIError matchable via IsNotFound rather than fabricating
-// defaults the server never stated.
+// GetSettings gets the account's Agent Network gateway settings (endpoint,
+// proxy address, collection toggles). An account that has not been
+// bootstrapped yet — via CreateSettings — reads as the defaults with an empty
+// Endpoint and ProxyAddress. Management servers prior to that contract
+// answered 200 with a JSON null body instead; that legacy shape is translated
+// to an APIError matchable via IsNotFound rather than fabricating defaults
+// the server never stated.
 func (a *AgentNetworkAPI) GetSettings(ctx context.Context) (*api.AgentNetworkSettings, error) {
 	resp, err := a.c.NewRequest(ctx, "GET", "/api/agent-network/settings", nil, nil)
 	if err != nil {
@@ -359,11 +357,33 @@ func (a *AgentNetworkAPI) GetSettings(ctx context.Context) (*api.AgentNetworkSet
 	return &ret, nil
 }
 
+// CreateSettings bootstraps the account's Agent Network settings row,
+// assigning the immutable endpoint. Exactly one of request.ProxyAddress
+// (labeled endpoint beneath that cluster; the server allocates the label) and
+// request.Endpoint (self-addressed dedicated endpoint, claimed verbatim) must
+// be set. Returns a conflict when the account already has a settings row.
+func (a *AgentNetworkAPI) CreateSettings(ctx context.Context, request api.PostApiAgentNetworkSettingsJSONRequestBody) (*api.AgentNetworkSettings, error) {
+	requestBytes, err := json.Marshal(request)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := a.c.NewRequest(ctx, "POST", "/api/agent-network/settings", bytes.NewReader(requestBytes), nil)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+	ret, err := parseResponse[api.AgentNetworkSettings](resp)
+	return &ret, err
+}
+
 // UpdateSettings updates the account's Agent Network settings; the request
-// replaces every mutable field (collection toggles and retention). Setting
-// request.Cluster bootstraps the settings row when the account does not have
-// one yet; on a bootstrapped account it must match the assigned cluster (or
-// be nil) and any other value is rejected — the cluster is immutable.
+// carries every field, replacing the mutable ones (collection toggles and
+// retention). The endpoint and proxy address are assigned at bootstrap
+// (CreateSettings) and immutable — the request must echo them unchanged, and
+// a request carrying different values is rejected. Returns not-found until
+// the account is bootstrapped.
 func (a *AgentNetworkAPI) UpdateSettings(ctx context.Context, request api.PutApiAgentNetworkSettingsJSONRequestBody) (*api.AgentNetworkSettings, error) {
 	requestBytes, err := json.Marshal(request)
 	if err != nil {
@@ -379,3 +399,19 @@ func (a *AgentNetworkAPI) UpdateSettings(ctx context.Context, request api.PutApi
 	ret, err := parseResponse[api.AgentNetworkSettings](resp)
 	return &ret, err
 }
+
+// DeleteSettings deletes the account's Agent Network settings row, releasing
+// the endpoint. The server refuses (precondition failed) while any provider
+// exists for the account or while a proxy is actively serving the endpoint.
+// Bootstrapping again afterwards allocates a new endpoint.
+func (a *AgentNetworkAPI) DeleteSettings(ctx context.Context) error {
+	resp, err := a.c.NewRequest(ctx, "DELETE", "/api/agent-network/settings", nil, nil)
+	if err != nil {
+		return err
+	}
+	if resp.Body != nil {
+		defer resp.Body.Close()
+	}
+
+	return nil
+}

shared/management/client/rest/agentnetwork_test.go

@@ -47,9 +47,9 @@ var (
 	}
 
 	testAgentNetworkSettings = api.AgentNetworkSettings{
-		Cluster:                "eu.proxy.netbird.io",
-		Subdomain:              "violet",
 		Endpoint:               "violet.eu.proxy.netbird.io",
+		ProxyAddress:           "eu.proxy.netbird.io",
+		Dedicated:              false,
 		EnableLogCollection:    true,
 		AccessLogRetentionDays: ptr(30),
 	}
@@ -120,18 +120,15 @@ func TestAgentNetwork_CreateProvider_200(t *testing.T) {
 			var req api.PostApiAgentNetworkProvidersJSONRequestBody
 			require.NoError(t, json.Unmarshal(reqBytes, &req))
 			assert.Equal(t, "OpenAI", req.Name)
-			require.NotNil(t, req.BootstrapCluster)
-			assert.Equal(t, "eu.proxy.netbird.io", *req.BootstrapCluster)
 			retBytes, _ := json.Marshal(testAgentNetworkProvider)
 			_, err = w.Write(retBytes)
 			require.NoError(t, err)
 		})
 		ret, err := c.AgentNetwork.CreateProvider(context.Background(), api.PostApiAgentNetworkProvidersJSONRequestBody{
-			ProviderId:       "openai_api",
-			Name:             "OpenAI",
-			UpstreamUrl:      "https://api.openai.com",
-			ApiKey:           ptr("sk-test"),
-			BootstrapCluster: ptr("eu.proxy.netbird.io"),
+			ProviderId:  "openai_api",
+			Name:        "OpenAI",
+			UpstreamUrl: "https://api.openai.com",
+			ApiKey:      ptr("sk-test"),
 		})
 		require.NoError(t, err)
 		assert.Equal(t, testAgentNetworkProvider, *ret)
@@ -456,6 +453,45 @@ func TestAgentNetwork_GetSettings_LegacyNullBody(t *testing.T) {
 	})
 }
 
+func TestAgentNetwork_CreateSettings_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/settings", func(w http.ResponseWriter, r *http.Request) {
+			assert.Equal(t, "POST", r.Method)
+			reqBytes, err := io.ReadAll(r.Body)
+			require.NoError(t, err)
+			var req api.PostApiAgentNetworkSettingsJSONRequestBody
+			require.NoError(t, json.Unmarshal(reqBytes, &req))
+			require.NotNil(t, req.ProxyAddress, "proxy address must be on the wire")
+			assert.Equal(t, "eu.proxy.netbird.io", *req.ProxyAddress)
+			assert.Nil(t, req.Endpoint, "endpoint must stay off the wire for a labeled bootstrap")
+			retBytes, _ := json.Marshal(testAgentNetworkSettings)
+			_, err = w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		ret, err := c.AgentNetwork.CreateSettings(context.Background(), api.PostApiAgentNetworkSettingsJSONRequestBody{
+			ProxyAddress: ptr("eu.proxy.netbird.io"),
+		})
+		require.NoError(t, err)
+		assert.Equal(t, testAgentNetworkSettings, *ret)
+	})
+}
+
+func TestAgentNetwork_CreateSettings_Conflict(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/settings", func(w http.ResponseWriter, r *http.Request) {
+			retBytes, _ := json.Marshal(util.ErrorResponse{Message: "agent network settings already bootstrapped for account acct1", Code: 409})
+			w.WriteHeader(409)
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		_, err := c.AgentNetwork.CreateSettings(context.Background(), api.PostApiAgentNetworkSettingsJSONRequestBody{
+			Endpoint: ptr("gw.example.com"),
+		})
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "already bootstrapped")
+	})
+}
+
 func TestAgentNetwork_UpdateSettings_200(t *testing.T) {
 	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
 		mux.HandleFunc("/api/agent-network/settings", func(w http.ResponseWriter, r *http.Request) {
@@ -464,15 +500,18 @@ func TestAgentNetwork_UpdateSettings_200(t *testing.T) {
 			require.NoError(t, err)
 			var req api.PutApiAgentNetworkSettingsJSONRequestBody
 			require.NoError(t, json.Unmarshal(reqBytes, &req))
-			require.NotNil(t, req.Cluster, "bootstrap cluster must be on the wire")
-			assert.Equal(t, "eu.proxy.netbird.io", *req.Cluster)
 			assert.True(t, req.EnableLogCollection)
+			assert.Equal(t, "brave-otter.eu.proxy.netbird.io", req.Endpoint,
+				"the identity echo must be on the wire")
+			assert.Equal(t, "eu.proxy.netbird.io", req.ProxyAddress,
+				"the identity echo must be on the wire")
 			retBytes, _ := json.Marshal(testAgentNetworkSettings)
 			_, err = w.Write(retBytes)
 			require.NoError(t, err)
 		})
 		ret, err := c.AgentNetwork.UpdateSettings(context.Background(), api.PutApiAgentNetworkSettingsJSONRequestBody{
-			Cluster:             ptr("eu.proxy.netbird.io"),
+			Endpoint:            "brave-otter.eu.proxy.netbird.io",
+			ProxyAddress:        "eu.proxy.netbird.io",
 			EnableLogCollection: true,
 		})
 		require.NoError(t, err)
@@ -483,15 +522,40 @@ func TestAgentNetwork_UpdateSettings_200(t *testing.T) {
 func TestAgentNetwork_UpdateSettings_Err(t *testing.T) {
 	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
 		mux.HandleFunc("/api/agent-network/settings", func(w http.ResponseWriter, r *http.Request) {
-			retBytes, _ := json.Marshal(util.ErrorResponse{Message: "cluster is immutable once assigned (current: eu.proxy.netbird.io)", Code: 422})
-			w.WriteHeader(422)
+			retBytes, _ := json.Marshal(util.ErrorResponse{Message: "agent network settings have not been bootstrapped yet; POST /api/agent-network/settings to bootstrap them", Code: 404})
+			w.WriteHeader(404)
 			_, err := w.Write(retBytes)
 			require.NoError(t, err)
 		})
 		_, err := c.AgentNetwork.UpdateSettings(context.Background(), api.PutApiAgentNetworkSettingsJSONRequestBody{
-			Cluster: ptr("us.proxy.netbird.io"),
+			EnableLogCollection: true,
 		})
 		require.Error(t, err)
-		assert.Contains(t, err.Error(), "immutable")
+		assert.True(t, rest.IsNotFound(err), "an unbootstrapped account must surface as IsNotFound")
+	})
+}
+
+func TestAgentNetwork_DeleteSettings_200(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/settings", func(w http.ResponseWriter, r *http.Request) {
+			assert.Equal(t, "DELETE", r.Method)
+			_, err := w.Write([]byte("{}"))
+			require.NoError(t, err)
+		})
+		require.NoError(t, c.AgentNetwork.DeleteSettings(context.Background()))
+	})
+}
+
+func TestAgentNetwork_DeleteSettings_Guarded(t *testing.T) {
+	withMockClient(func(c *rest.Client, mux *http.ServeMux) {
+		mux.HandleFunc("/api/agent-network/settings", func(w http.ResponseWriter, r *http.Request) {
+			retBytes, _ := json.Marshal(util.ErrorResponse{Message: "agent network settings cannot be deleted while 2 provider(s) exist; delete the providers first", Code: 412})
+			w.WriteHeader(412)
+			_, err := w.Write(retBytes)
+			require.NoError(t, err)
+		})
+		err := c.AgentNetwork.DeleteSettings(context.Background())
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "cannot be deleted")
 	})
 }

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,19 +6232,51 @@ 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. Every field is required, matching the PUT convention of the other endpoints. The endpoint and proxy address are assigned at bootstrap (POST) and are immutable — the request must carry them unchanged, and a request carrying different values is rejected. To change them, delete the settings (DELETE, guarded) and bootstrap again; re-creating allocates a new endpoint.
       properties:
-        cluster:
+        endpoint:
           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.
+          description: The account's gateway endpoint hostname. Immutable — must match the assigned value; a different value is rejected.
+          example: "brave-otter.eu.proxy.netbird.io"
+        proxy_address:
+          type: string
+          description: Declared cluster address of the proxy serving this account's gateway. Immutable — must match the assigned value; a different value is rejected.
           example: "eu.proxy.netbird.io"
         enable_log_collection:
           type: boolean
@@ -6267,9 +6295,12 @@ components:
           description: Days to retain full access-log rows; older rows are swept. 0 or less means keep indefinitely.
           example: 30
       required:
+        - endpoint
+        - proxy_address
         - enable_log_collection
         - enable_prompt_collection
         - redact_pii
+        - access_log_retention_days
     AgentNetworkBudgetRule:
       type: object
       description: Account-level budget rule. A limit-only rule bound to groups and/or users that applies across all policies as a min-wins ceiling. Empty targets means it applies to every caller.
@@ -13694,7 +13725,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 +13743,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 carries every field, replacing the mutable ones (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 immutable; the request must carry them unchanged, and a request carrying different values is rejected.
       tags: [ Agent Network ]
       security:
         - BearerAuth: [ ]
@@ -13744,6 +13807,27 @@ paths:
           "$ref": "#/components/responses/validation_failed"
         '500':
           "$ref": "#/components/responses/internal_error"
+    delete:
+      summary: Delete Agent Network settings
+      description: Deletes the account's Agent Network settings row, releasing the endpoint. Guarded — the delete is refused with 412 while any Agent Network provider exists for the account or while a proxy is actively serving the endpoint. Bootstrapping again after a delete allocates a new endpoint; the released hostname is not reserved.
+      tags: [ Agent Network ]
+      security:
+        - BearerAuth: [ ]
+        - TokenAuth: [ ]
+      responses:
+        '200':
+          description: Settings deleted
+        '401':
+          "$ref": "#/components/responses/requires_authentication"
+        '403':
+          "$ref": "#/components/responses/forbidden"
+        '404':
+          "$ref": "#/components/responses/not_found"
+        '412':
+          description: Delete refused — Agent Network providers still exist for the account, or a proxy is actively serving the endpoint
+          content: { }
+        '500':
+          "$ref": "#/components/responses/internal_error"
   /api/agent-network/budget-rules:
     get:
       summary: List all Agent Network budget rules

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,43 +2360,61 @@ 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.
-type AgentNetworkSettingsRequest struct {
-	// AccessLogRetentionDays Days to retain full access-log rows; older rows are swept. 0 or less means keep indefinitely.
+// 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"`
 
-	// 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. 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. Every field is required, matching the PUT convention of the other endpoints. The endpoint and proxy address are assigned at bootstrap (POST) and are immutable — the request must carry them unchanged, and a request carrying different values is rejected. To change them, delete the settings (DELETE, guarded) and bootstrap again; re-creating allocates a new endpoint.
+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"`
 
 	// EnableLogCollection Whether per-request access-log entries are collected for this account's agent-network traffic.
 	EnableLogCollection bool `json:"enable_log_collection"`
@@ -2407,6 +2422,12 @@ type AgentNetworkSettingsRequest struct {
 	// EnablePromptCollection Master switch for request/response prompt capture.
 	EnablePromptCollection bool `json:"enable_prompt_collection"`
 
+	// Endpoint The account's gateway endpoint hostname. Immutable — must match the assigned value; a different value is rejected.
+	Endpoint string `json:"endpoint"`
+
+	// ProxyAddress Declared cluster address of the proxy serving this account's gateway. Immutable — must match the assigned value; a different value is rejected.
+	ProxyAddress string `json:"proxy_address"`
+
 	// RedactPii Whether captured prompts have PII redacted.
 	RedactPii bool `json:"redact_pii"`
 }
@@ -6176,6 +6197,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