fix: deprecate ai provider seeding env config (#25854)

Environment variables used to configure AI Gateway providers are now deprecated, and we need to reflect this as such.

cli/server.go

@@ -2979,6 +2979,11 @@ func parseExternalAuthProvidersFromEnv(prefix string, environ []string) ([]coder
 	return providers, nil
 }
 
+const (
+	aiGatewayProviderEnvPrefix = "CODER_AI_GATEWAY_PROVIDER_"
+	aiBridgeProviderEnvPrefix  = "CODER_AIBRIDGE_PROVIDER_"
+)
+
 // ReadAIProvidersFromEnv parses CODER_AI_GATEWAY_PROVIDER_<N>_<KEY>
 // environment variables into a slice of AIProviderConfig.
 // Deprecated alias env vars with the CODER_AIBRIDGE_PROVIDER_<N>_<KEY>
@@ -2986,16 +2991,22 @@ func parseExternalAuthProvidersFromEnv(prefix string, environ []string) ([]coder
 //
 // This follows the same indexed pattern as ReadExternalAuthProvidersFromEnv.
 func ReadAIProvidersFromEnv(logger slog.Logger, environ []string) ([]codersdk.AIProviderConfig, error) {
-	providers, err := readAIProvidersForPrefix(logger, environ, "CODER_AIBRIDGE_PROVIDER_")
+	providers, err := readAIProvidersForPrefix(logger, environ, aiBridgeProviderEnvPrefix)
 	if err != nil {
 		return nil, err
 	}
-	gatewayProviders, err := readAIProvidersForPrefix(logger, environ, "CODER_AI_GATEWAY_PROVIDER_")
+	gatewayProviders, err := readAIProvidersForPrefix(logger, environ, aiGatewayProviderEnvPrefix)
 	if err != nil {
 		return nil, err
 	}
 	if len(providers) > 0 && len(gatewayProviders) > 0 {
-		return nil, xerrors.New("cannot mix CODER_AIBRIDGE_PROVIDER_* and CODER_AI_GATEWAY_PROVIDER_* environment variables, please consolidate onto CODER_AI_GATEWAY_PROVIDER_*")
+		return nil, xerrors.Errorf("cannot mix %s* and %s* environment variables, please consolidate onto %s*", aiBridgeProviderEnvPrefix, aiGatewayProviderEnvPrefix, aiGatewayProviderEnvPrefix)
+	}
+	var activePrefix string
+	if len(providers) > 0 {
+		activePrefix = aiBridgeProviderEnvPrefix
+	} else if len(gatewayProviders) > 0 {
+		activePrefix = aiGatewayProviderEnvPrefix
 	}
 	providers = append(providers, gatewayProviders...)
 
@@ -3077,9 +3088,27 @@ func ReadAIProvidersFromEnv(logger slog.Logger, environ []string) ([]codersdk.AI
 		names[p.Name] = i
 	}
 
+	warnIfAIProvidersConfiguredFromEnv(context.Background(), logger, activePrefix, providers)
+
 	return providers, nil
 }
 
+func warnIfAIProvidersConfiguredFromEnv(ctx context.Context, logger slog.Logger, prefix string, providers []codersdk.AIProviderConfig) {
+	if len(providers) == 0 {
+		return
+	}
+
+	if prefix == "" {
+		return
+	}
+
+	logger.Warn(ctx,
+		"ai provider environment variables are deprecated for provider management and only seed provider configuration at startup",
+		slog.F("env_prefix", prefix),
+		slog.F("replacement", "Manage AI Providers from the Coder UI or HTTP API."),
+	)
+}
+
 // readAIProvidersForPrefix parses provider env vars under a single
 // indexed prefix (e.g. CODER_AI_GATEWAY_PROVIDER_) into a slice of
 // AIProviderConfig. Per-field syntax errors and unknown keys are

cli/server_aibridge_internal_test.go

@@ -1,6 +1,7 @@
 package cli
 
 import (
+	"context"
 	"database/sql"
 	"encoding/json"
 	"fmt"
@@ -575,6 +576,58 @@ func TestValidateLegacyAIBridgeConfig(t *testing.T) {
 	}
 }
 
+func TestWarnIfAIProvidersConfiguredFromEnv(t *testing.T) {
+	t.Parallel()
+
+	t.Run("NoProviders", func(t *testing.T) {
+		t.Parallel()
+
+		sink := testutil.NewFakeSink(t)
+		warnIfAIProvidersConfiguredFromEnv(context.Background(), sink.Logger(), aiGatewayProviderEnvPrefix, nil)
+
+		require.Empty(t, sink.Entries())
+	})
+
+	t.Run("EmptyPrefix", func(t *testing.T) {
+		t.Parallel()
+
+		sink := testutil.NewFakeSink(t)
+		warnIfAIProvidersConfiguredFromEnv(context.Background(), sink.Logger(), "", []codersdk.AIProviderConfig{{Type: "openai", Name: "openai"}})
+
+		require.Empty(t, sink.Entries())
+	})
+
+	t.Run("AIGatewayPrefix", func(t *testing.T) {
+		t.Parallel()
+
+		sink := testutil.NewFakeSink(t)
+		warnIfAIProvidersConfiguredFromEnv(context.Background(), sink.Logger(), aiGatewayProviderEnvPrefix, []codersdk.AIProviderConfig{{Type: "openai", Name: "openai"}})
+
+		entries := sink.Entries(func(e slog.SinkEntry) bool {
+			return e.Message == "ai provider environment variables are deprecated for provider management and only seed provider configuration at startup"
+		})
+		require.Len(t, entries, 1)
+		require.Len(t, entries[0].Fields, 2)
+		assertFieldValue(t, entries[0].Fields, "env_prefix", aiGatewayProviderEnvPrefix)
+		assertFieldValue(t, entries[0].Fields, "replacement", "Manage AI Providers from the Coder UI or HTTP API.")
+	})
+
+	t.Run("AIBridgePrefix", func(t *testing.T) {
+		t.Parallel()
+
+		sink := testutil.NewFakeSink(t)
+		warnIfAIProvidersConfiguredFromEnv(context.Background(), sink.Logger(), aiBridgeProviderEnvPrefix, []codersdk.AIProviderConfig{{Type: "openai", Name: "openai"}})
+
+		entries := sink.Entries(func(e slog.SinkEntry) bool {
+			return e.Message == "ai provider environment variables are deprecated for provider management and only seed provider configuration at startup"
+		})
+		require.Len(t, entries, 1)
+		require.Len(t, entries[0].Fields, 2)
+		assertFieldValue(t, entries[0].Fields, "env_prefix", aiBridgeProviderEnvPrefix)
+		assertFieldValue(t, entries[0].Fields, "replacement", "Manage AI Providers from the Coder UI or HTTP API.")
+	})
+}
+
 func TestBuildAIProviderFromRowSetsAPIDumpDir(t *testing.T) {
 	t.Parallel()
 
@@ -721,3 +774,14 @@ func mustMarshalSettings(s codersdk.AIProviderSettings) sql.NullString {
 	}
 	return sql.NullString{String: string(data), Valid: true}
 }
+
+func assertFieldValue(t *testing.T, fields slog.Map, name string, expected interface{}) {
+	t.Helper()
+	for _, f := range fields {
+		if f.Name == name {
+			assert.Equal(t, expected, f.Value)
+			return
+		}
+	}
+	t.Errorf("field %q not found", name)
+}

cli/testdata/coder_server_--help.golden

@@ -124,35 +124,55 @@ AI GATEWAY OPTIONS:
           disabled, only centralized key authentication is permitted.
 
       --ai-gateway-anthropic-base-url string, $CODER_AI_GATEWAY_ANTHROPIC_BASE_URL (default: https://api.anthropic.com/)
-          The base URL of the Anthropic API.
+          Deprecated: manage AI Providers from the Coder UI or HTTP API. If set,
+          this option seeds provider configuration at startup only exactly once.
+          It will not be used in service runtime. The base URL of the Anthropic
+          API.
 
       --ai-gateway-anthropic-key string, $CODER_AI_GATEWAY_ANTHROPIC_KEY
-          The key to authenticate against the Anthropic API.
+          Deprecated: manage AI Providers from the Coder UI or HTTP API. If set,
+          this option seeds provider configuration at startup only exactly once.
+          It will not be used in service runtime. The key to authenticate
+          against the Anthropic API.
 
       --ai-gateway-bedrock-access-key string, $CODER_AI_GATEWAY_BEDROCK_ACCESS_KEY
-          The access key to authenticate against the AWS Bedrock API.
+          Deprecated: manage AI Providers from the Coder UI or HTTP API. If set,
-
+          this option seeds provider configuration at startup only exactly once.
-      --ai-gateway-bedrock-access-key-secret string, $CODER_AI_GATEWAY_BEDROCK_ACCESS_KEY_SECRET
+          It will not be used in service runtime. The access key to authenticate
-          The access key secret to use with the access key to authenticate
           against the AWS Bedrock API.
 
+      --ai-gateway-bedrock-access-key-secret string, $CODER_AI_GATEWAY_BEDROCK_ACCESS_KEY_SECRET
+          Deprecated: manage AI Providers from the Coder UI or HTTP API. If set,
+          this option seeds provider configuration at startup only exactly once.
+          It will not be used in service runtime. The access key secret to use
+          with the access key to authenticate against the AWS Bedrock API.
+
       --ai-gateway-bedrock-base-url string, $CODER_AI_GATEWAY_BEDROCK_BASE_URL
-          The base URL to use for the AWS Bedrock API. Use this setting to
+          Deprecated: manage AI Providers from the Coder UI or HTTP API. If set,
-          specify an exact URL to use. Takes precedence over
+          this option seeds provider configuration at startup only exactly once.
-          CODER_AI_GATEWAY_BEDROCK_REGION.
+          It will not be used in service runtime. The base URL to use for the
+          AWS Bedrock API. Use this setting to specify an exact URL to use.
+          Takes precedence over CODER_AI_GATEWAY_BEDROCK_REGION.
 
       --ai-gateway-bedrock-model string, $CODER_AI_GATEWAY_BEDROCK_MODEL (default: global.anthropic.claude-sonnet-4-5-20250929-v1:0)
-          The model to use when making requests to the AWS Bedrock API.
+          Deprecated: manage AI Providers from the Coder UI or HTTP API. If set,
+          this option seeds provider configuration at startup only exactly once.
+          It will not be used in service runtime. The model to use when making
+          requests to the AWS Bedrock API.
 
       --ai-gateway-bedrock-region string, $CODER_AI_GATEWAY_BEDROCK_REGION
-          The AWS Bedrock API region to use. Constructs a base URL to use for
+          Deprecated: manage AI Providers from the Coder UI or HTTP API. If set,
-          the AWS Bedrock API in the form of
+          this option seeds provider configuration at startup only exactly once.
-          'https://bedrock-runtime.<region>.amazonaws.com'.
+          It will not be used in service runtime. The AWS Bedrock API region to
+          use. Constructs a base URL to use for the AWS Bedrock API in the form
+          of 'https://bedrock-runtime.<region>.amazonaws.com'.
 
       --ai-gateway-bedrock-small-fastmodel string, $CODER_AI_GATEWAY_BEDROCK_SMALL_FAST_MODEL (default: global.anthropic.claude-haiku-4-5-20251001-v1:0)
-          The small fast model to use when making requests to the AWS Bedrock
+          Deprecated: manage AI Providers from the Coder UI or HTTP API. If set,
-          API. Claude Code uses Haiku-class models to perform background tasks.
+          this option seeds provider configuration at startup only exactly once.
-          See
+          It will not be used in service runtime. The small fast model to use
+          when making requests to the AWS Bedrock API. Claude Code uses
+          Haiku-class models to perform background tasks. See
           https://docs.claude.com/en/docs/claude-code/settings#environment-variables.
 
       --ai-gateway-circuit-breaker-enabled bool, $CODER_AI_GATEWAY_CIRCUIT_BREAKER_ENABLED (default: false)
@@ -171,10 +191,16 @@ AI GATEWAY OPTIONS:
           to disable (unlimited).
 
       --ai-gateway-openai-base-url string, $CODER_AI_GATEWAY_OPENAI_BASE_URL (default: https://api.openai.com/v1/)
-          The base URL of the OpenAI API.
+          Deprecated: manage AI Providers from the Coder UI or HTTP API. If set,
+          this option seeds provider configuration at startup only exactly once.
+          It will not be used in service runtime. The base URL of the OpenAI
+          API.
 
       --ai-gateway-openai-key string, $CODER_AI_GATEWAY_OPENAI_KEY
-          The key to authenticate against the OpenAI API.
+          Deprecated: manage AI Providers from the Coder UI or HTTP API. If set,
+          this option seeds provider configuration at startup only exactly once.
+          It will not be used in service runtime. The key to authenticate
+          against the OpenAI API.
 
       --ai-gateway-rate-limit int, $CODER_AI_GATEWAY_RATE_LIMIT (default: 0)
           Maximum number of AI Gateway requests per second per replica. Set to 0

cli/testdata/server-config.yaml.golden

@@ -874,25 +874,41 @@ ai_gateway:
   # Whether to start an in-memory AI Gateway instance.
   # (default: true, type: bool)
   enabled: true
-  # The base URL of the OpenAI API.
+  # Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this
+  # option seeds provider configuration at startup only exactly once. It will not be
+  # used in service runtime. The base URL of the OpenAI API.
   # (default: https://api.openai.com/v1/, type: string)
   openai_base_url: https://api.openai.com/v1/
-  # The base URL of the Anthropic API.
+  # Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this
+  # option seeds provider configuration at startup only exactly once. It will not be
+  # used in service runtime. The base URL of the Anthropic API.
   # (default: https://api.anthropic.com/, type: string)
   anthropic_base_url: https://api.anthropic.com/
-  # The base URL to use for the AWS Bedrock API. Use this setting to specify an
+  # Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this
-  # exact URL to use. Takes precedence over CODER_AI_GATEWAY_BEDROCK_REGION.
+  # option seeds provider configuration at startup only exactly once. It will not be
+  # used in service runtime. The base URL to use for the AWS Bedrock API. Use this
+  # setting to specify an exact URL to use. Takes precedence over
+  # CODER_AI_GATEWAY_BEDROCK_REGION.
   # (default: <unset>, type: string)
   bedrock_base_url: ""
-  # The AWS Bedrock API region to use. Constructs a base URL to use for the AWS
+  # Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this
-  # Bedrock API in the form of 'https://bedrock-runtime.<region>.amazonaws.com'.
+  # option seeds provider configuration at startup only exactly once. It will not be
+  # used in service runtime. The AWS Bedrock API region to use. Constructs a base
+  # URL to use for the AWS Bedrock API in the form of
+  # 'https://bedrock-runtime.<region>.amazonaws.com'.
   # (default: <unset>, type: string)
   bedrock_region: ""
-  # The model to use when making requests to the AWS Bedrock API.
+  # Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this
+  # option seeds provider configuration at startup only exactly once. It will not be
+  # used in service runtime. The model to use when making requests to the AWS
+  # Bedrock API.
   # (default: global.anthropic.claude-sonnet-4-5-20250929-v1:0, type: string)
   bedrock_model: global.anthropic.claude-sonnet-4-5-20250929-v1:0
-  # The small fast model to use when making requests to the AWS Bedrock API. Claude
+  # Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this
-  # Code uses Haiku-class models to perform background tasks. See
+  # option seeds provider configuration at startup only exactly once. It will not be
+  # used in service runtime. The small fast model to use when making requests to the
+  # AWS Bedrock API. Claude Code uses Haiku-class models to perform background
+  # tasks. See
   # https://docs.claude.com/en/docs/claude-code/settings#environment-variables.
   # (default: global.anthropic.claude-haiku-4-5-20251001-v1:0, type: string)
   bedrock_small_fast_model: global.anthropic.claude-haiku-4-5-20251001-v1:0

codersdk/deployment.go

@@ -1700,6 +1700,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 	}
 
 	// AI Gateway options
+	aiGatewayProviderSeedingDeprecated := "Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. "
 	aiGatewayEnabled := serpent.Option{
 		Name:        "AI Gateway Enabled",
 		Description: "Whether to start an in-memory AI Gateway instance.",
@@ -1712,7 +1713,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 	}
 	aiGatewayOpenAIBaseURL := serpent.Option{
 		Name:        "AI Gateway OpenAI Base URL",
-		Description: "The base URL of the OpenAI API.",
+		Description: aiGatewayProviderSeedingDeprecated + "The base URL of the OpenAI API.",
 		Flag:        "ai-gateway-openai-base-url",
 		Env:         "CODER_AI_GATEWAY_OPENAI_BASE_URL",
 		Value:       &c.AI.BridgeConfig.LegacyOpenAI.BaseURL,
@@ -1722,7 +1723,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 	}
 	aiGatewayOpenAIKey := serpent.Option{
 		Name:        "AI Gateway OpenAI Key",
-		Description: "The key to authenticate against the OpenAI API.",
+		Description: aiGatewayProviderSeedingDeprecated + "The key to authenticate against the OpenAI API.",
 		Flag:        "ai-gateway-openai-key",
 		Env:         "CODER_AI_GATEWAY_OPENAI_KEY",
 		Value:       &c.AI.BridgeConfig.LegacyOpenAI.Key,
@@ -1732,7 +1733,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 	}
 	aiGatewayAnthropicBaseURL := serpent.Option{
 		Name:        "AI Gateway Anthropic Base URL",
-		Description: "The base URL of the Anthropic API.",
+		Description: aiGatewayProviderSeedingDeprecated + "The base URL of the Anthropic API.",
 		Flag:        "ai-gateway-anthropic-base-url",
 		Env:         "CODER_AI_GATEWAY_ANTHROPIC_BASE_URL",
 		Value:       &c.AI.BridgeConfig.LegacyAnthropic.BaseURL,
@@ -1742,7 +1743,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 	}
 	aiGatewayAnthropicKey := serpent.Option{
 		Name:        "AI Gateway Anthropic Key",
-		Description: "The key to authenticate against the Anthropic API.",
+		Description: aiGatewayProviderSeedingDeprecated + "The key to authenticate against the Anthropic API.",
 		Flag:        "ai-gateway-anthropic-key",
 		Env:         "CODER_AI_GATEWAY_ANTHROPIC_KEY",
 		Value:       &c.AI.BridgeConfig.LegacyAnthropic.Key,
@@ -1751,30 +1752,28 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 		Annotations: serpent.Annotations{}.Mark(annotationSecretKey, "true"),
 	}
 	aiGatewayBedrockBaseURL := serpent.Option{
-		Name: "AI Gateway Bedrock Base URL",
+		Name:        "AI Gateway Bedrock Base URL",
-		Description: "The base URL to use for the AWS Bedrock API. Use this setting to specify an exact URL to use. Takes precedence " +
+		Description: aiGatewayProviderSeedingDeprecated + "The base URL to use for the AWS Bedrock API. Use this setting to specify an exact URL to use. Takes precedence over CODER_AI_GATEWAY_BEDROCK_REGION.",
-			"over CODER_AI_GATEWAY_BEDROCK_REGION.",
+		Flag:        "ai-gateway-bedrock-base-url",
-		Flag:    "ai-gateway-bedrock-base-url",
+		Env:         "CODER_AI_GATEWAY_BEDROCK_BASE_URL",
-		Env:     "CODER_AI_GATEWAY_BEDROCK_BASE_URL",
+		Value:       &c.AI.BridgeConfig.LegacyBedrock.BaseURL,
-		Value:   &c.AI.BridgeConfig.LegacyBedrock.BaseURL,
+		Default:     "",
-		Default: "",
+		Group:       &deploymentGroupAIGateway,
-		Group:   &deploymentGroupAIGateway,
+		YAML:        "bedrock_base_url",
-		YAML:    "bedrock_base_url",
 	}
 	aiGatewayBedrockRegion := serpent.Option{
-		Name: "AI Gateway Bedrock Region",
+		Name:        "AI Gateway Bedrock Region",
-		Description: "The AWS Bedrock API region to use. Constructs a base URL to use for the AWS Bedrock API in the form of " +
+		Description: aiGatewayProviderSeedingDeprecated + "The AWS Bedrock API region to use. Constructs a base URL to use for the AWS Bedrock API in the form of 'https://bedrock-runtime.<region>.amazonaws.com'.",
-			"'https://bedrock-runtime.<region>.amazonaws.com'.",
+		Flag:        "ai-gateway-bedrock-region",
-		Flag:    "ai-gateway-bedrock-region",
+		Env:         "CODER_AI_GATEWAY_BEDROCK_REGION",
-		Env:     "CODER_AI_GATEWAY_BEDROCK_REGION",
+		Value:       &c.AI.BridgeConfig.LegacyBedrock.Region,
-		Value:   &c.AI.BridgeConfig.LegacyBedrock.Region,
+		Default:     "",
-		Default: "",
+		Group:       &deploymentGroupAIGateway,
-		Group:   &deploymentGroupAIGateway,
+		YAML:        "bedrock_region",
-		YAML:    "bedrock_region",
 	}
 	aiGatewayBedrockAccessKey := serpent.Option{
 		Name:        "AI Gateway Bedrock Access Key",
-		Description: "The access key to authenticate against the AWS Bedrock API.",
+		Description: aiGatewayProviderSeedingDeprecated + "The access key to authenticate against the AWS Bedrock API.",
 		Flag:        "ai-gateway-bedrock-access-key",
 		Env:         "CODER_AI_GATEWAY_BEDROCK_ACCESS_KEY",
 		Value:       &c.AI.BridgeConfig.LegacyBedrock.AccessKey,
@@ -1784,7 +1783,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 	}
 	aiGatewayBedrockAccessKeySecret := serpent.Option{
 		Name:        "AI Gateway Bedrock Access Key Secret",
-		Description: "The access key secret to use with the access key to authenticate against the AWS Bedrock API.",
+		Description: aiGatewayProviderSeedingDeprecated + "The access key secret to use with the access key to authenticate against the AWS Bedrock API.",
 		Flag:        "ai-gateway-bedrock-access-key-secret",
 		Env:         "CODER_AI_GATEWAY_BEDROCK_ACCESS_KEY_SECRET",
 		Value:       &c.AI.BridgeConfig.LegacyBedrock.AccessKeySecret,
@@ -1794,7 +1793,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 	}
 	aiGatewayBedrockModel := serpent.Option{
 		Name:        "AI Gateway Bedrock Model",
-		Description: "The model to use when making requests to the AWS Bedrock API.",
+		Description: aiGatewayProviderSeedingDeprecated + "The model to use when making requests to the AWS Bedrock API.",
 		Flag:        "ai-gateway-bedrock-model",
 		Env:         "CODER_AI_GATEWAY_BEDROCK_MODEL",
 		Value:       &c.AI.BridgeConfig.LegacyBedrock.Model,
@@ -1804,7 +1803,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 	}
 	aiGatewayBedrockSmallFastModel := serpent.Option{
 		Name:        "AI Gateway Bedrock Small Fast Model",
-		Description: "The small fast model to use when making requests to the AWS Bedrock API. Claude Code uses Haiku-class models to perform background tasks. See https://docs.claude.com/en/docs/claude-code/settings#environment-variables.",
+		Description: aiGatewayProviderSeedingDeprecated + "The small fast model to use when making requests to the AWS Bedrock API. Claude Code uses Haiku-class models to perform background tasks. See https://docs.claude.com/en/docs/claude-code/settings#environment-variables.",
 		Flag:        "ai-gateway-bedrock-small-fastmodel",
 		Env:         "CODER_AI_GATEWAY_BEDROCK_SMALL_FAST_MODEL",
 		Value:       &c.AI.BridgeConfig.LegacyBedrock.SmallFastModel,

docs/reference/cli/server.md

@@ -1743,7 +1743,7 @@ Whether to start an in-memory AI Gateway instance.
 | YAML        | <code>ai_gateway.openai_base_url</code>        |
 | Default     | <code>https://api.openai.com/v1/</code>        |
 
-The base URL of the OpenAI API.
+Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The base URL of the OpenAI API.
 
 ### --ai-gateway-openai-key
 
@@ -1752,7 +1752,7 @@ The base URL of the OpenAI API.
 | Type        | <code>string</code>                       |
 | Environment | <code>$CODER_AI_GATEWAY_OPENAI_KEY</code> |
 
-The key to authenticate against the OpenAI API.
+Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The key to authenticate against the OpenAI API.
 
 ### --ai-gateway-anthropic-base-url
 
@@ -1763,7 +1763,7 @@ The key to authenticate against the OpenAI API.
 | YAML        | <code>ai_gateway.anthropic_base_url</code>        |
 | Default     | <code>https://api.anthropic.com/</code>           |
 
-The base URL of the Anthropic API.
+Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The base URL of the Anthropic API.
 
 ### --ai-gateway-anthropic-key
 
@@ -1772,7 +1772,7 @@ The base URL of the Anthropic API.
 | Type        | <code>string</code>                          |
 | Environment | <code>$CODER_AI_GATEWAY_ANTHROPIC_KEY</code> |
 
-The key to authenticate against the Anthropic API.
+Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The key to authenticate against the Anthropic API.
 
 ### --ai-gateway-bedrock-base-url
 
@@ -1782,7 +1782,7 @@ The key to authenticate against the Anthropic API.
 | Environment | <code>$CODER_AI_GATEWAY_BEDROCK_BASE_URL</code> |
 | YAML        | <code>ai_gateway.bedrock_base_url</code>        |
 
-The base URL to use for the AWS Bedrock API. Use this setting to specify an exact URL to use. Takes precedence over CODER_AI_GATEWAY_BEDROCK_REGION.
+Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The base URL to use for the AWS Bedrock API. Use this setting to specify an exact URL to use. Takes precedence over CODER_AI_GATEWAY_BEDROCK_REGION.
 
 ### --ai-gateway-bedrock-region
 
@@ -1792,7 +1792,7 @@ The base URL to use for the AWS Bedrock API. Use this setting to specify an exac
 | Environment | <code>$CODER_AI_GATEWAY_BEDROCK_REGION</code> |
 | YAML        | <code>ai_gateway.bedrock_region</code>        |
 
-The AWS Bedrock API region to use. Constructs a base URL to use for the AWS Bedrock API in the form of 'https://bedrock-runtime.<region>.amazonaws.com'.
+Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The AWS Bedrock API region to use. Constructs a base URL to use for the AWS Bedrock API in the form of 'https://bedrock-runtime.<region>.amazonaws.com'.
 
 ### --ai-gateway-bedrock-access-key
 
@@ -1801,7 +1801,7 @@ The AWS Bedrock API region to use. Constructs a base URL to use for the AWS Bedr
 | Type        | <code>string</code>                               |
 | Environment | <code>$CODER_AI_GATEWAY_BEDROCK_ACCESS_KEY</code> |
 
-The access key to authenticate against the AWS Bedrock API.
+Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The access key to authenticate against the AWS Bedrock API.
 
 ### --ai-gateway-bedrock-access-key-secret
 
@@ -1810,7 +1810,7 @@ The access key to authenticate against the AWS Bedrock API.
 | Type        | <code>string</code>                                      |
 | Environment | <code>$CODER_AI_GATEWAY_BEDROCK_ACCESS_KEY_SECRET</code> |
 
-The access key secret to use with the access key to authenticate against the AWS Bedrock API.
+Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The access key secret to use with the access key to authenticate against the AWS Bedrock API.
 
 ### --ai-gateway-bedrock-model
 
@@ -1821,7 +1821,7 @@ The access key secret to use with the access key to authenticate against the AWS
 | YAML        | <code>ai_gateway.bedrock_model</code>                         |
 | Default     | <code>global.anthropic.claude-sonnet-4-5-20250929-v1:0</code> |
 
-The model to use when making requests to the AWS Bedrock API.
+Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The model to use when making requests to the AWS Bedrock API.
 
 ### --ai-gateway-bedrock-small-fastmodel
 
@@ -1832,7 +1832,7 @@ The model to use when making requests to the AWS Bedrock API.
 | YAML        | <code>ai_gateway.bedrock_small_fast_model</code>             |
 | Default     | <code>global.anthropic.claude-haiku-4-5-20251001-v1:0</code> |
 
-The small fast model to use when making requests to the AWS Bedrock API. Claude Code uses Haiku-class models to perform background tasks. See https://docs.claude.com/en/docs/claude-code/settings#environment-variables.
+Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The small fast model to use when making requests to the AWS Bedrock API. Claude Code uses Haiku-class models to perform background tasks. See https://docs.claude.com/en/docs/claude-code/settings#environment-variables.
 
 ### --ai-gateway-retention
 

enterprise/cli/testdata/coder_server_--help.golden

@@ -125,35 +125,55 @@ AI GATEWAY OPTIONS:
           disabled, only centralized key authentication is permitted.
 
       --ai-gateway-anthropic-base-url string, $CODER_AI_GATEWAY_ANTHROPIC_BASE_URL (default: https://api.anthropic.com/)
-          The base URL of the Anthropic API.
+          Deprecated: manage AI Providers from the Coder UI or HTTP API. If set,
+          this option seeds provider configuration at startup only exactly once.
+          It will not be used in service runtime. The base URL of the Anthropic
+          API.
 
       --ai-gateway-anthropic-key string, $CODER_AI_GATEWAY_ANTHROPIC_KEY
-          The key to authenticate against the Anthropic API.
+          Deprecated: manage AI Providers from the Coder UI or HTTP API. If set,
+          this option seeds provider configuration at startup only exactly once.
+          It will not be used in service runtime. The key to authenticate
+          against the Anthropic API.
 
       --ai-gateway-bedrock-access-key string, $CODER_AI_GATEWAY_BEDROCK_ACCESS_KEY
-          The access key to authenticate against the AWS Bedrock API.
+          Deprecated: manage AI Providers from the Coder UI or HTTP API. If set,
-
+          this option seeds provider configuration at startup only exactly once.
-      --ai-gateway-bedrock-access-key-secret string, $CODER_AI_GATEWAY_BEDROCK_ACCESS_KEY_SECRET
+          It will not be used in service runtime. The access key to authenticate
-          The access key secret to use with the access key to authenticate
           against the AWS Bedrock API.
 
+      --ai-gateway-bedrock-access-key-secret string, $CODER_AI_GATEWAY_BEDROCK_ACCESS_KEY_SECRET
+          Deprecated: manage AI Providers from the Coder UI or HTTP API. If set,
+          this option seeds provider configuration at startup only exactly once.
+          It will not be used in service runtime. The access key secret to use
+          with the access key to authenticate against the AWS Bedrock API.
+
       --ai-gateway-bedrock-base-url string, $CODER_AI_GATEWAY_BEDROCK_BASE_URL
-          The base URL to use for the AWS Bedrock API. Use this setting to
+          Deprecated: manage AI Providers from the Coder UI or HTTP API. If set,
-          specify an exact URL to use. Takes precedence over
+          this option seeds provider configuration at startup only exactly once.
-          CODER_AI_GATEWAY_BEDROCK_REGION.
+          It will not be used in service runtime. The base URL to use for the
+          AWS Bedrock API. Use this setting to specify an exact URL to use.
+          Takes precedence over CODER_AI_GATEWAY_BEDROCK_REGION.
 
       --ai-gateway-bedrock-model string, $CODER_AI_GATEWAY_BEDROCK_MODEL (default: global.anthropic.claude-sonnet-4-5-20250929-v1:0)
-          The model to use when making requests to the AWS Bedrock API.
+          Deprecated: manage AI Providers from the Coder UI or HTTP API. If set,
+          this option seeds provider configuration at startup only exactly once.
+          It will not be used in service runtime. The model to use when making
+          requests to the AWS Bedrock API.
 
       --ai-gateway-bedrock-region string, $CODER_AI_GATEWAY_BEDROCK_REGION
-          The AWS Bedrock API region to use. Constructs a base URL to use for
+          Deprecated: manage AI Providers from the Coder UI or HTTP API. If set,
-          the AWS Bedrock API in the form of
+          this option seeds provider configuration at startup only exactly once.
-          'https://bedrock-runtime.<region>.amazonaws.com'.
+          It will not be used in service runtime. The AWS Bedrock API region to
+          use. Constructs a base URL to use for the AWS Bedrock API in the form
+          of 'https://bedrock-runtime.<region>.amazonaws.com'.
 
       --ai-gateway-bedrock-small-fastmodel string, $CODER_AI_GATEWAY_BEDROCK_SMALL_FAST_MODEL (default: global.anthropic.claude-haiku-4-5-20251001-v1:0)
-          The small fast model to use when making requests to the AWS Bedrock
+          Deprecated: manage AI Providers from the Coder UI or HTTP API. If set,
-          API. Claude Code uses Haiku-class models to perform background tasks.
+          this option seeds provider configuration at startup only exactly once.
-          See
+          It will not be used in service runtime. The small fast model to use
+          when making requests to the AWS Bedrock API. Claude Code uses
+          Haiku-class models to perform background tasks. See
           https://docs.claude.com/en/docs/claude-code/settings#environment-variables.
 
       --ai-gateway-circuit-breaker-enabled bool, $CODER_AI_GATEWAY_CIRCUIT_BREAKER_ENABLED (default: false)
@@ -172,10 +192,16 @@ AI GATEWAY OPTIONS:
           to disable (unlimited).
 
       --ai-gateway-openai-base-url string, $CODER_AI_GATEWAY_OPENAI_BASE_URL (default: https://api.openai.com/v1/)
-          The base URL of the OpenAI API.
+          Deprecated: manage AI Providers from the Coder UI or HTTP API. If set,
+          this option seeds provider configuration at startup only exactly once.
+          It will not be used in service runtime. The base URL of the OpenAI
+          API.
 
       --ai-gateway-openai-key string, $CODER_AI_GATEWAY_OPENAI_KEY
-          The key to authenticate against the OpenAI API.
+          Deprecated: manage AI Providers from the Coder UI or HTTP API. If set,
+          this option seeds provider configuration at startup only exactly once.
+          It will not be used in service runtime. The key to authenticate
+          against the OpenAI API.
 
       --ai-gateway-rate-limit int, $CODER_AI_GATEWAY_RATE_LIMIT (default: 0)
           Maximum number of AI Gateway requests per second per replica. Set to 0