config

package
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package config provides configuration management for the CLI Proxy API server. It handles loading and parsing YAML configuration files, and provides structured access to application settings including server port, authentication directory, debug settings, proxy configuration, and API keys.

Package config provides configuration management for the CLI Proxy API server. It handles loading and parsing YAML configuration files, and provides structured access to application settings including server port, authentication directory, debug settings, proxy configuration, and API keys.

Index

Constants

View Source
const (
	DefaultPanelGitHubRepository = "https://github.com/router-for-me/Home-Management-Center"
	DefaultCPAPort               = 8317
)
View Source
const (
	DefaultCPAHeartbeatTimeout = 3 * time.Second
	DefaultCPACancelBound      = 5 * time.Second
	DefaultReclaimGrace        = 5 * time.Second
	DefaultCleanupInterval     = 5 * time.Second
)
View Source
const (
	DefaultInFlightMaxPartBytes       = 256 * 1024
	DefaultInFlightMaxPartCount       = 64
	DefaultInFlightMaxRevisionBytes   = 16 * 1024 * 1024
	DefaultInFlightMaxAggregateGroups = 100000
	DefaultInFlightMaxDetails         = 10000
	DefaultInFlightMaxStringBytes     = 256
)
View Source
const (
	DefaultUserEmailVerificationTokenTTL = "24h"
	DefaultUserEmailResetTokenTTL        = "30m"
	DefaultUserEmailSMTPPort             = 587
)
View Source
const HomeCredentialConfigMetadataKey = "home_config"

HomeCredentialConfigMetadataKey is private persistence data, never a CPA payload.

View Source
const MaxCredentialWeight = 1_000_000

MaxCredentialWeight is the largest positive credential routing weight.

Variables

View Source
var ErrInvalidProviderCredentialID = errors.New("provider credential id must be a canonical UUID")
View Source
var HomeCredentialFields = [...]string{"id", "uuid", "api-key", "base-url", "proxy-url", "prefix", "priority", "headers", "excluded-models", "disable-cooling", "request-retry", "name", "disabled"}

These fields are stored authoritatively on auth records, not in CPA options.

Functions

func ApplyDownstreamHomeModeScalars added in v1.0.34

func ApplyDownstreamHomeModeScalars(root map[string]any)

ApplyDownstreamHomeModeScalars only applies scalar Home-mode overrides. It does not remove sensitive or Home-local roots such as api-keys, remote-management, auth-dir, tls, or credential roots. Callers that build downstream CPA YAML must filter those roots separately first.

func ApplyHomeRuntimeScalars added in v1.0.67

func ApplyHomeRuntimeScalars(root map[string]any)

ApplyHomeRuntimeScalars applies scalar invariants owned by Home.

func CredentialConfigFromOptions added in v1.1.10

func CredentialConfigFromOptions(entry, options any) (map[string]any, error)

CredentialConfigFromOptions upgrades older records that only retained the CPA JSON projection. New records always export their original credential tree. Seed the SDK view with recoverable auth fields before applying retained options.

func CredentialExecutionOptions added in v1.1.10

func CredentialExecutionOptions(entry any) (map[string]any, error)

CredentialExecutionOptions translates YAML to CPA JSON using SDK types. This projection is not used to reconstruct newly stored configuration.

func ForceHomeRuntimeConfig added in v1.0.67

func ForceHomeRuntimeConfig(cfg *Config)

ForceHomeRuntimeConfig applies invariants owned by the Home runtime.

func FormatSortedHeaders added in v1.0.70

func FormatSortedHeaders(headers map[string]string) string

FormatSortedHeaders serializes headers deterministically with null byte separators.

func IsOAuthProviderRoot added in v1.0.75

func IsOAuthProviderRoot(key string) bool

IsOAuthProviderRoot identifies legacy roots that contain OAuth-scoped fields.

func LegacyConfigRoot added in v1.0.75

func LegacyConfigRoot(cfg *Config) (map[string]any, error)

LegacyConfigRoot materializes effective runtime fields for v0 field updates. Scope is retained in the persisted document by UpdateOAuthScope.

func NormalizeCommentIndentation

func NormalizeCommentIndentation(data []byte) []byte

NormalizeCommentIndentation removes indentation from standalone YAML comment lines to keep them left aligned.

func NormalizeConfigLayout added in v1.0.75

func NormalizeConfigLayout(data []byte, migrate bool) ([]byte, bool, error)

NormalizeConfigLayout removes conflicting legacy fields. migrate also moves legacy-only fields; callers use it only for an explicit v8 configuration write.

func NormalizeConfigRoot added in v1.0.75

func NormalizeConfigRoot(root map[string]any) (map[string]any, error)

NormalizeConfigRoot keeps the database's legacy roots while retaining OAuth provider paths as scope information. Both layouts describe the same values. Keeping the legacy projection also lets older CPA nodes consume the snapshot.

func NormalizeExcludedModels

func NormalizeExcludedModels(models []string) []string

NormalizeExcludedModels trims, lowercases, and deduplicates model exclusion patterns. It preserves the order of first occurrences and drops empty entries.

func NormalizeHeaders

func NormalizeHeaders(headers map[string]string) map[string]string

NormalizeHeaders trims header keys and values and removes empty pairs.

func NormalizeOAuthExcludedModels

func NormalizeOAuthExcludedModels(entries map[string][]string) map[string][]string

NormalizeOAuthExcludedModels cleans provider -> excluded models mappings by normalizing provider keys and applying model exclusion normalization to each entry.

func NormalizeRemoteManagementSecret added in v1.0.2

func NormalizeRemoteManagementSecret(secret string) (string, bool, error)

NormalizeRemoteManagementSecret normalizes a remote management secret.

func NormalizeV8ConfigAliases added in v1.1.0

func NormalizeV8ConfigAliases(root *yaml.Node) error

NormalizeV8ConfigAliases accepts historical v8 paths without discarding unknown fields. Callers still validate the canonical document before saving. Normalize request bodies before merging so an alias update can replace a canonical value already present in the stored configuration.

func ProjectV8ConfigAliases added in v1.1.0

func ProjectV8ConfigAliases(root *yaml.Node, path string)

ProjectV8ConfigAliases moves canonical fields into a requested historical subtree. Moving, rather than copying, preserves PUT and DELETE semantics when the subtree contains both shared settings and OAuth-only fields.

func SaveConfigPreserveCommentsUpdateNestedScalar

func SaveConfigPreserveCommentsUpdateNestedScalar(configFile string, path []string, value string) error

SaveConfigPreserveCommentsUpdateNestedScalar updates a nested scalar key path like ["a","b"] while preserving comments and positions.

func UpdateOAuthScope added in v1.0.75

func UpdateOAuthScope(oauth any, key string, value any) (any, bool, error)

UpdateOAuthScope applies a legacy root edit to any existing v8 OAuth paths. A nil value removes the corresponding scoped settings as well as their root.

func ValidateCredentialConcurrencyConfig added in v1.0.61

func ValidateCredentialConcurrencyConfig(cfg CredentialConcurrencyConfig) error

ValidateCredentialConcurrencyConfig validates limiter timing and configured bounds.

func ValidateCredentialWeight added in v1.0.75

func ValidateCredentialWeight(weight *int) error

ValidateCredentialWeight validates one optional config credential weight.

func ValidateTrustedProxies added in v1.0.60

func ValidateTrustedProxies(values []string) error

ValidateTrustedProxies accepts only explicit IP addresses and CIDRs, and rejects trust-all networks that would let direct clients spoof their source.

func ValidateV8Config added in v1.0.75

func ValidateV8Config(data []byte) error

ValidateV8Config accepts only the v8 layout in management writes. Plugin-owned configuration remains extensible through its existing decoder.

Types

type AntigravityConfig added in v1.0.72

type AntigravityConfig struct {
	TOSPauseWindow string `yaml:"tos-pause-window,omitempty" json:"tos-pause-window,omitempty"`
}

AntigravityConfig configures provider-wide Antigravity request behavior.

type ClaudeKey

type ClaudeKey struct {
	CredentialConfig `yaml:",inline" json:"-"`
	// ID is the immutable credential identity.
	ID string `yaml:"id,omitempty" json:"id,omitempty"`
	// UUID is accepted for backward-compatible input and normalized to ID.
	UUID string `yaml:"uuid,omitempty" json:"uuid,omitempty"`
	// APIKey is the authentication key for accessing Claude API services.
	APIKey string `yaml:"api-key" json:"api-key"`

	// Priority controls selection preference when multiple credentials match.
	// Higher values are preferred; defaults to 0.
	Priority int `yaml:"priority,omitempty" json:"priority,omitempty"`

	// Prefix optionally namespaces models for this credential (e.g., "teamA/claude-sonnet-4").
	Prefix string `yaml:"prefix,omitempty" json:"prefix,omitempty"`

	// BaseURL is the base URL for the Claude API endpoint.
	// If empty, the default Claude API URL will be used.
	BaseURL string `yaml:"base-url" json:"base-url"`

	// ProxyURL overrides the global proxy setting for this API key if provided.
	ProxyURL string `yaml:"proxy-url" json:"proxy-url"`

	// Models defines upstream model names and aliases for request routing.
	Models []ClaudeModel `yaml:"models" json:"models"`

	// Headers optionally adds extra HTTP headers for requests sent with this key.
	Headers map[string]string `yaml:"headers,omitempty" json:"headers,omitempty"`

	// ExcludedModels lists model IDs that should be excluded for this provider.
	ExcludedModels []string `yaml:"excluded-models,omitempty" json:"excluded-models,omitempty"`

	// DisableCooling overrides the global cooling policy for this credential when set.
	// True disables request-error and quota cooldowns; false explicitly enables them.
	DisableCooling *bool `yaml:"disable-cooling,omitempty" json:"disable-cooling,omitempty"`

	// RequestRetry optionally overrides the global number of additional retry rounds.
	// Nil or a negative value inherits the global setting; zero disables additional rounds.
	RequestRetry *int `yaml:"request-retry,omitempty" json:"request-retry,omitempty"`

	// Settings shared with CPA V8.
	Weight              *int                     `yaml:"weight,omitempty" json:"weight,omitempty"`
	RequestScopedErrors []RequestScopedErrorRule `yaml:"request-scoped-errors,omitempty" json:"request-scoped-errors,omitempty"`
	// NativeToolSearch trusts a custom base URL with Anthropic native tool search
	// (defer_loading tools and tool_reference results) for Codex tool_search.
	NativeToolSearch bool `yaml:"native-tool-search,omitempty" json:"native-tool-search,omitempty"`
}

ClaudeKey represents the configuration for a Claude API key, including the API key itself and an optional base URL for the API endpoint.

func (ClaudeKey) GetAPIKey

func (k ClaudeKey) GetAPIKey() string

GetAPIKey returns an api key.

func (ClaudeKey) GetBaseURL

func (k ClaudeKey) GetBaseURL() string

GetBaseURL returns a base url.

func (ClaudeKey) GetPrefix added in v1.0.70

func (k ClaudeKey) GetPrefix() string

GetPrefix returns a model prefix.

func (ClaudeKey) GetProxyURL added in v1.0.70

func (k ClaudeKey) GetProxyURL() string

GetProxyURL returns a proxy url.

func (ClaudeKey) MarshalYAML added in v1.1.10

func (c ClaudeKey) MarshalYAML() (any, error)

type ClaudeModel

type ClaudeModel struct {
	// Name is the upstream model identifier used when issuing requests.
	Name string `yaml:"name" json:"name"`

	// Alias is the client-facing model name that maps to Name.
	Alias string `yaml:"alias" json:"alias"`

	// Settings shared with CPA V8.
	DisplayName      string                    `yaml:"display-name,omitempty" json:"display-name,omitempty"`
	MaxContextLength int                       `yaml:"max-context-length,omitempty" json:"max-context-length,omitempty"`
	ForceMapping     bool                      `yaml:"force-mapping,omitempty" json:"force-mapping,omitempty"`
	IsCompat         bool                      `yaml:"is-compat,omitempty" json:"is-compat,omitempty"`
	Thinking         *registry.ThinkingSupport `yaml:"thinking,omitempty" json:"thinking,omitempty"`
}

ClaudeModel defines the complete Claude model configuration shared with CPA.

func (ClaudeModel) GetAlias

func (m ClaudeModel) GetAlias() string

GetAlias returns an alias.

func (ClaudeModel) GetDisplayName added in v1.0.75

func (m ClaudeModel) GetDisplayName() string

GetDisplayName returns a display name.

func (ClaudeModel) GetForceMapping added in v1.0.75

func (m ClaudeModel) GetForceMapping() bool

GetForceMapping returns whether response model fields should be rewritten.

func (ClaudeModel) GetMaxContextLength added in v1.0.75

func (m ClaudeModel) GetMaxContextLength() int

GetMaxContextLength returns the configured context limit.

func (ClaudeModel) GetName

func (m ClaudeModel) GetName() string

GetName returns a name.

func (ClaudeModel) GetThinking added in v1.0.75

func (m ClaudeModel) GetThinking() *registry.ThinkingSupport

GetThinking returns configured reasoning capabilities.

type CodexKey

type CodexKey struct {
	CredentialConfig `yaml:",inline" json:"-"`
	// ID is the immutable credential identity.
	ID string `yaml:"id,omitempty" json:"id,omitempty"`
	// UUID is accepted for backward-compatible input and normalized to ID.
	UUID string `yaml:"uuid,omitempty" json:"uuid,omitempty"`
	// APIKey is the authentication key for accessing Codex API services.
	APIKey string `yaml:"api-key" json:"api-key"`

	// Priority controls selection preference when multiple credentials match.
	// Higher values are preferred; defaults to 0.
	Priority int `yaml:"priority,omitempty" json:"priority,omitempty"`

	// Prefix optionally namespaces models for this credential (e.g., "teamA/gpt-5-codex").
	Prefix string `yaml:"prefix,omitempty" json:"prefix,omitempty"`

	// BaseURL is the base URL for the Codex API endpoint.
	// If empty, the default Codex API URL will be used.
	BaseURL string `yaml:"base-url" json:"base-url"`

	// Websockets enables the Responses API websocket transport for this credential.
	Websockets bool `yaml:"websockets,omitempty" json:"websockets,omitempty"`

	// AlphaSearch allows this Codex API key to serve the Alpha Search endpoint.
	AlphaSearch bool `yaml:"alpha-search,omitempty" json:"alpha-search,omitempty"`

	// ProxyURL overrides the global proxy setting for this API key if provided.
	ProxyURL string `yaml:"proxy-url" json:"proxy-url"`

	// Models defines upstream model names and aliases for request routing.
	Models []CodexModel `yaml:"models" json:"models"`

	// Headers optionally adds extra HTTP headers for requests sent with this key.
	Headers map[string]string `yaml:"headers,omitempty" json:"headers,omitempty"`

	// ExcludedModels lists model IDs that should be excluded for this provider.
	ExcludedModels []string `yaml:"excluded-models,omitempty" json:"excluded-models,omitempty"`

	// DisableCooling overrides the global cooling policy for this credential when set.
	// True disables request-error and quota cooldowns; false explicitly enables them.
	DisableCooling *bool `yaml:"disable-cooling,omitempty" json:"disable-cooling,omitempty"`

	// RequestRetry optionally overrides the global number of additional retry rounds.
	// Nil or a negative value inherits the global setting; zero disables additional rounds.
	RequestRetry *int `yaml:"request-retry,omitempty" json:"request-retry,omitempty"`

	// Settings shared with CPA V8.
	Weight              *int                     `yaml:"weight,omitempty" json:"weight,omitempty"`
	RequestScopedErrors []RequestScopedErrorRule `yaml:"request-scoped-errors,omitempty" json:"request-scoped-errors,omitempty"`
}

CodexKey represents the configuration for a Codex API key, including the API key itself and an optional base URL for the API endpoint.

func (CodexKey) GetAPIKey

func (k CodexKey) GetAPIKey() string

GetAPIKey returns an api key.

func (CodexKey) GetBaseURL

func (k CodexKey) GetBaseURL() string

GetBaseURL returns a base url.

func (CodexKey) GetPrefix added in v1.0.70

func (k CodexKey) GetPrefix() string

GetPrefix returns a model prefix.

func (CodexKey) GetProxyURL added in v1.0.70

func (k CodexKey) GetProxyURL() string

GetProxyURL returns a proxy url.

func (CodexKey) MarshalYAML added in v1.1.10

func (c CodexKey) MarshalYAML() (any, error)

type CodexModel

type CodexModel struct {
	// Name is the upstream model identifier used when issuing requests.
	Name string `yaml:"name" json:"name"`

	// Alias is the client-facing model name that maps to Name.
	Alias string `yaml:"alias" json:"alias"`

	// SupportConfigurationUpdate enables Responses configuration updates for this model.
	SupportConfigurationUpdate bool `yaml:"support-configuration-update,omitempty" json:"support-configuration-update,omitempty"`

	// DisplayName is the optional human-readable name shown in model catalogs.
	DisplayName string `yaml:"display-name,omitempty" json:"display-name,omitempty"`

	// ForceMapping rewrites upstream response model fields back to Alias.
	ForceMapping bool `yaml:"force-mapping,omitempty" json:"force-mapping,omitempty"`

	// Settings shared with CPA V8.
	MaxContextLength int                       `yaml:"max-context-length,omitempty" json:"max-context-length,omitempty"`
	IsCompat         bool                      `yaml:"is-compat,omitempty" json:"is-compat,omitempty"`
	Thinking         *registry.ThinkingSupport `yaml:"thinking,omitempty" json:"thinking,omitempty"`
}

CodexModel defines the complete Codex model configuration shared with CPA.

func (CodexModel) GetAlias

func (m CodexModel) GetAlias() string

GetAlias returns an alias.

func (CodexModel) GetDisplayName added in v1.0.55

func (m CodexModel) GetDisplayName() string

GetDisplayName returns a display name.

func (CodexModel) GetForceMapping added in v1.0.55

func (m CodexModel) GetForceMapping() bool

GetForceMapping returns whether response model fields should be rewritten.

func (CodexModel) GetMaxContextLength added in v1.0.75

func (m CodexModel) GetMaxContextLength() int

GetMaxContextLength returns the configured context limit.

func (CodexModel) GetName

func (m CodexModel) GetName() string

GetName returns a name.

func (CodexModel) GetThinking added in v1.0.75

func (m CodexModel) GetThinking() *registry.ThinkingSupport

GetThinking returns configured reasoning capabilities.

type Config

type Config struct {
	// RawConfig is the complete submitted configuration, not an execution-field remainder.
	// Runtime fields below are a read projection; configuration writes update the tree.
	RawConfig map[string]any `yaml:"-" json:"-"`
	// Models selects optional catalog sources independently for each catalog.
	Models ModelCatalogs `yaml:"models" json:"models"`

	SDKConfig `yaml:",inline"`
	// Host is the network host/interface on which the API server will bind.
	// Default is empty ("") to bind all interfaces (IPv4 + IPv6). Use "127.0.0.1" or "localhost" for local-only access.
	Host string `yaml:"host" json:"-"`
	// Port is the CPA server port distributed by Home.
	Port int `yaml:"port" json:"-"`

	// OAuth model capabilities are owned and published by Home.
	OAuthSettings map[string][]OAuthModelSetting `yaml:"oauth-settings,omitempty" json:"oauth-settings,omitempty"`

	// AllowHost limits RESP client connections to the listed IP addresses.
	// Empty means all client hosts are allowed.
	AllowHost []string `yaml:"allow-host" json:"-"`

	// TLS config controls HTTPS server settings.
	TLS TLSConfig `yaml:"tls" json:"tls"`

	// TrustedProxies lists reverse-proxy IPs or CIDRs whose forwarded client
	// address headers the HTTP server may trust. Empty disables forwarded headers.
	TrustedProxies []string `yaml:"trusted-proxies" json:"trusted-proxies"`

	// RemoteManagement nests management-related options under 'remote-management'.
	RemoteManagement RemoteManagement `yaml:"remote-management" json:"-"`

	// Plugins configures dynamic plugin distribution for downstream CPA nodes.
	Plugins PluginsConfig `yaml:"plugins" json:"plugins"`

	// UserEmail configures verified user emails and password-recovery delivery.
	UserEmail UserEmailConfig `yaml:"user-email" json:"-"`

	// CredentialConcurrency controls Home credential concurrency lifecycle behavior.
	CredentialConcurrency CredentialConcurrencyConfig `yaml:"credential-concurrency" json:"credential-concurrency"`

	// CredentialInFlight configures credential observation snapshots.
	CredentialInFlight CredentialInFlightConfig `yaml:"credential-in-flight" json:"credential-in-flight"`

	// AuthDir is the directory where authentication token files are stored.
	AuthDir string `yaml:"auth-dir" json:"-"`

	// Debug enables or disables debug-level logging and other debug features.
	Debug bool `yaml:"debug" json:"debug"`

	// LoggingToFile controls whether application logs are written to rotating files or stdout.
	LoggingToFile bool `yaml:"logging-to-file" json:"logging-to-file"`

	// LogsMaxTotalSizeMB limits local log files independently on each Home and downstream CPA node.
	// When exceeded, the oldest log files are deleted until within the limit (in MB). Set to 0 to disable.
	LogsMaxTotalSizeMB int `yaml:"logs-max-total-size-mb" json:"logs-max-total-size-mb"`

	// ErrorLogsMaxFiles limits the number of error log files retained when request logging is disabled.
	// When exceeded, the oldest error log files are deleted. Default is 10. Set to 0 to disable cleanup.
	ErrorLogsMaxFiles int `yaml:"error-logs-max-files" json:"error-logs-max-files"`

	// UsageStatisticsEnabled toggles in-memory usage aggregation; when false, usage data is discarded.
	UsageStatisticsEnabled bool `yaml:"usage-statistics-enabled" json:"usage-statistics-enabled"`

	// DisableCooling disables Home request-error and quota cooldown scheduling when true.
	DisableCooling bool `yaml:"disable-cooling" json:"disable-cooling"`

	// AuthAutoRefreshWorkers overrides the size of the core auth auto-refresh worker pool.
	// When <= 0, the default worker count is used.
	AuthAutoRefreshWorkers int `yaml:"auth-auto-refresh-workers" json:"auth-auto-refresh-workers"`

	// RequestRetry defines the number of additional credential retry rounds for
	// downstream CPA execution after the first round exhausts its credentials.
	RequestRetry int `yaml:"request-retry" json:"request-retry"`
	// MaxRetryCredentials defines the maximum number of different credentials to
	// try in each credential retry round.
	// Set to 0 or a negative value to keep trying all available credentials (legacy behavior).
	MaxRetryCredentials int `yaml:"max-retry-credentials" json:"max-retry-credentials"`
	// MaxRetryInterval defines the maximum positive cooldown wait, in seconds,
	// allowed before starting another credential retry round. A non-positive value
	// forbids positive cooldown waits; it does not disable same-round credential
	// failover or immediate additional rounds allowed by RequestRetry.
	MaxRetryInterval int `yaml:"max-retry-interval" json:"max-retry-interval"`

	// QuotaExceeded defines the behavior when a quota is exceeded.
	QuotaExceeded QuotaExceeded `yaml:"quota-exceeded" json:"quota-exceeded"`

	// Routing controls credential selection behavior.
	Routing RoutingConfig `yaml:"routing" json:"routing"`

	// Antigravity configures provider-wide Antigravity request behavior.
	Antigravity AntigravityConfig `yaml:"antigravity" json:"antigravity"`

	// GeminiKey defines Gemini API key configurations with optional routing overrides.
	GeminiKey []GeminiKey `yaml:"gemini-api-key" json:"gemini-api-key"`

	// InteractionsKey defines native Google Interactions API key configurations.
	InteractionsKey []GeminiKey `yaml:"interactions-api-key" json:"interactions-api-key"`

	// Codex defines a list of Codex API key configurations as specified in the YAML configuration file.
	CodexKey []CodexKey `yaml:"codex-api-key" json:"codex-api-key"`

	// XAIKey defines xAI API key configurations using the same structure as Codex API keys.
	XAIKey []XAIKey `yaml:"xai-api-key" json:"xai-api-key"`

	// MetaKey defines Meta API key configurations using the same structure as Codex API keys.
	MetaKey []MetaKey `yaml:"meta-api-key" json:"meta-api-key"`

	// ClaudeKey defines a list of Claude API key configurations as specified in the YAML configuration file.
	ClaudeKey []ClaudeKey `yaml:"claude-api-key" json:"claude-api-key"`

	// OpenAICompatibility defines OpenAI API compatibility configurations for external providers.
	OpenAICompatibility []OpenAICompatibility `yaml:"openai-compatibility" json:"openai-compatibility"`

	// VertexCompatAPIKey defines Vertex AI-compatible API key configurations for third-party providers.
	// Used for services that use Vertex AI-style paths but with simple API key authentication.
	VertexCompatAPIKey []VertexCompatKey `yaml:"vertex-api-key" json:"vertex-api-key"`

	// OAuthExcludedModels defines per-provider global model exclusions applied to OAuth/file-backed auth entries.
	OAuthExcludedModels map[string][]string `yaml:"oauth-excluded-models,omitempty" json:"oauth-excluded-models,omitempty"`

	// OAuthModelAlias defines global model name aliases for OAuth/file-backed auth channels.
	// These aliases affect both model listing and model routing for supported channels:
	// vertex, antigravity, claude, codex, kimi, xai, meta, devin.
	//
	// NOTE: This does not apply to existing per-credential model alias features under:
	// gemini-api-key, interactions-api-key, codex-api-key, xai-api-key, meta-api-key, claude-api-key, openai-compatibility, and vertex-api-key.
	OAuthModelAlias map[string][]OAuthModelAlias `yaml:"oauth-model-alias,omitempty" json:"oauth-model-alias,omitempty"`

	OAuthRequestScopedErrors map[string][]RequestScopedErrorRule `yaml:"oauth-request-scoped-errors,omitempty" json:"oauth-request-scoped-errors,omitempty"`
}

Config represents the application's configuration, loaded from a YAML file.

func LoadConfigOptional

func LoadConfigOptional(configFile string, optional bool) (*Config, error)

LoadConfigOptional reads YAML from configFile. If optional is true and the file is missing, it returns a Config with credential defaults. If optional is true and the file is empty or invalid, it returns a Config with credential defaults.

func (Config) MarshalYAML added in v1.0.75

func (cfg Config) MarshalYAML() (any, error)

MarshalYAML returns the complete source tree without rebuilding it from runtime fields. Programmatically constructed configs retain the legacy fallback below. Legacy field updates explicitly use LegacyConfigRoot instead.

func (*Config) NormalizePluginsConfig added in v1.0.39

func (cfg *Config) NormalizePluginsConfig()

NormalizePluginsConfig applies default plugin configuration values.

func (*Config) NormalizeProviderCredentialIDs added in v1.0.61

func (cfg *Config) NormalizeProviderCredentialIDs() error

NormalizeProviderCredentialIDs normalizes legacy UUID input to immutable IDs.

func (*Config) NormalizeTrustedProxies added in v1.0.60

func (cfg *Config) NormalizeTrustedProxies()

NormalizeTrustedProxies trims, removes empty values, and de-duplicates the explicit reverse-proxy allowlist while preserving its configured order.

func (*Config) NormalizeUserEmailConfig added in v1.0.60

func (cfg *Config) NormalizeUserEmailConfig()

NormalizeUserEmailConfig applies stable defaults without deciding whether the feature is usable.

func (*Config) SanitizeClaudeKeys

func (cfg *Config) SanitizeClaudeKeys()

SanitizeClaudeKeys normalizes headers and excluded models for Claude credentials.

func (*Config) SanitizeCodexKeys

func (cfg *Config) SanitizeCodexKeys()

SanitizeCodexKeys removes Codex API key entries missing a BaseURL. It trims whitespace and preserves order for remaining entries.

func (*Config) SanitizeGeminiKeys

func (cfg *Config) SanitizeGeminiKeys()

SanitizeGeminiKeys deduplicates and normalizes Gemini credentials. Distinct scheduling, model, and CPA execution options remain separate credentials.

func (*Config) SanitizeInteractionsKeys added in v1.0.70

func (cfg *Config) SanitizeInteractionsKeys()

SanitizeInteractionsKeys deduplicates and normalizes native Interactions credentials.

func (*Config) SanitizeMetaKeys added in v1.0.73

func (cfg *Config) SanitizeMetaKeys()

SanitizeMetaKeys normalizes Meta API key entries, defaulting BaseURL to https://api.meta.ai/v1 if empty.

func (*Config) SanitizeOAuthModelAlias

func (cfg *Config) SanitizeOAuthModelAlias()

SanitizeOAuthModelAlias normalizes and deduplicates global OAuth model name aliases. It trims whitespace, normalizes channel keys to lower-case, drops empty entries, allows multiple aliases per upstream name, and ensures aliases are unique within each channel.

func (*Config) SanitizeOpenAICompatibility

func (cfg *Config) SanitizeOpenAICompatibility()

SanitizeOpenAICompatibility removes OpenAI-compatibility provider entries that are not actionable, specifically those missing a BaseURL. It trims whitespace before evaluation and preserves the relative order of remaining entries.

func (*Config) SanitizeVertexCompatKeys

func (cfg *Config) SanitizeVertexCompatKeys()

SanitizeVertexCompatKeys deduplicates and normalizes Vertex-compatible API key credentials.

func (*Config) SanitizeXAIKeys added in v1.0.55

func (cfg *Config) SanitizeXAIKeys()

SanitizeXAIKeys removes xAI API key entries missing a BaseURL. It applies the same normalization rules as codex-api-key.

func (*Config) UnmarshalYAML added in v1.0.75

func (cfg *Config) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML accepts both layouts, including partially migrated documents. Presence, rather than Go zero values, determines which setting wins.

func (*Config) ValidateCredentialWeights added in v1.0.75

func (cfg *Config) ValidateCredentialWeights() error

ValidateCredentialWeights validates weights for every API-key family.

func (*Config) ValidateHomePolicies added in v1.1.10

func (cfg *Config) ValidateHomePolicies() error

ValidateHomePolicies validates only policies that Home actually executes.

type CredentialConcurrencyConfig added in v1.0.61

type CredentialConcurrencyConfig struct {
	LifecycleConfigRevision    int64         `yaml:"lifecycle-config-revision" json:"lifecycle-config-revision"`
	ObservationBarrierRevision int64         `yaml:"observation-barrier-revision" json:"observation-barrier-revision"`
	CPAHeartbeatTimeout        time.Duration `yaml:"cpa-heartbeat-timeout" json:"cpa-heartbeat-timeout"`
	CPACancelBound             time.Duration `yaml:"cpa-cancel-bound" json:"cpa-cancel-bound"`
	ReclaimGrace               time.Duration `yaml:"reclaim-grace" json:"reclaim-grace"`
	CleanupInterval            time.Duration `yaml:"cleanup-interval" json:"cleanup-interval"`
	ReleaseFlushInterval       string        `yaml:"release-flush-interval" json:"release-flush-interval"`
	ReleaseMaxBackoff          string        `yaml:"release-max-backoff" json:"release-max-backoff"`
	BusyRetryMin               string        `yaml:"busy-retry-min" json:"busy-retry-min"`
	BusyRetryMax               string        `yaml:"busy-retry-max" json:"busy-retry-max"`
	MaxLimit                   int64         `yaml:"max-limit" json:"max-limit"`
}

CredentialConcurrencyConfig controls Home credential concurrency lifecycle behavior.

func DefaultCredentialConcurrencyConfig added in v1.0.61

func DefaultCredentialConcurrencyConfig() CredentialConcurrencyConfig

DefaultCredentialConcurrencyConfig returns the lifecycle and limiter defaults.

type CredentialConfig added in v1.1.10

type CredentialConfig struct {
	RawConfig map[string]any `yaml:"-" json:"-"`
}

CredentialConfig retains the complete credential subtree, including models and cloak settings. Credential fields project Home scheduling policy, while model definitions retain the complete model configuration shared with CPA.

func (*CredentialConfig) SetConfigTree added in v1.1.10

func (c *CredentialConfig) SetConfigTree(tree map[string]any)

type CredentialInFlightConfig added in v1.0.61

type CredentialInFlightConfig struct {
	SnapshotInterval   string `yaml:"snapshot-interval" json:"snapshot-interval"`
	StaleAfter         string `yaml:"stale-after" json:"stale-after"`
	MaxPartBytes       int    `yaml:"max-part-bytes" json:"max-part-bytes"`
	MaxPartCount       int    `yaml:"max-part-count" json:"max-part-count"`
	MaxRevisionBytes   int    `yaml:"max-revision-bytes" json:"max-revision-bytes"`
	MaxAggregateGroups int    `yaml:"max-aggregate-groups" json:"max-aggregate-groups"`
	MaxDetails         int    `yaml:"max-details" json:"max-details"`
	MaxStringBytes     int    `yaml:"max-string-bytes" json:"max-string-bytes"`
	StagingRetention   string `yaml:"staging-retention" json:"staging-retention"`
}

CredentialInFlightConfig controls in-flight credential observation snapshots.

func DefaultCredentialInFlightConfig added in v1.0.61

func DefaultCredentialInFlightConfig() CredentialInFlightConfig

DefaultCredentialInFlightConfig returns the in-flight observation defaults.

func (CredentialInFlightConfig) Durations added in v1.0.61

Durations parses and validates the in-flight observation durations.

func (CredentialInFlightConfig) Validate added in v1.0.61

func (c CredentialInFlightConfig) Validate() error

Validate verifies the in-flight observation bounds.

type GeminiKey

type GeminiKey struct {
	CredentialConfig `yaml:",inline" json:"-"`
	// ID is the immutable credential identity.
	ID string `yaml:"id,omitempty" json:"id,omitempty"`
	// UUID is accepted for backward-compatible input and normalized to ID.
	UUID string `yaml:"uuid,omitempty" json:"uuid,omitempty"`
	// APIKey is the authentication key for accessing Gemini API services.
	APIKey string `yaml:"api-key" json:"api-key"`

	// Priority controls selection preference when multiple credentials match.
	// Higher values are preferred; defaults to 0.
	Priority int `yaml:"priority,omitempty" json:"priority,omitempty"`

	// Prefix optionally namespaces models for this credential (e.g., "teamA/gemini-3-pro-preview").
	Prefix string `yaml:"prefix,omitempty" json:"prefix,omitempty"`

	// BaseURL optionally overrides the Gemini API endpoint.
	BaseURL string `yaml:"base-url,omitempty" json:"base-url,omitempty"`

	// ProxyURL optionally overrides the global proxy for this API key.
	ProxyURL string `yaml:"proxy-url,omitempty" json:"proxy-url,omitempty"`

	// Models defines upstream model names and aliases for request routing.
	Models []GeminiModel `yaml:"models,omitempty" json:"models,omitempty"`

	// Headers optionally adds extra HTTP headers for requests sent with this key.
	Headers map[string]string `yaml:"headers,omitempty" json:"headers,omitempty"`

	// ExcludedModels lists model IDs that should be excluded for this provider.
	ExcludedModels []string `yaml:"excluded-models,omitempty" json:"excluded-models,omitempty"`

	// DisableCooling overrides the global cooling policy for this credential when set.
	// True disables request-error and quota cooldowns; false explicitly enables them.
	DisableCooling *bool `yaml:"disable-cooling,omitempty" json:"disable-cooling,omitempty"`

	// RequestRetry optionally overrides the global number of additional retry rounds.
	// Nil or a negative value inherits the global setting; zero disables additional rounds.
	RequestRetry *int `yaml:"request-retry,omitempty" json:"request-retry,omitempty"`

	// Settings shared with CPA V8.
	Weight              *int                     `yaml:"weight,omitempty" json:"weight,omitempty"`
	RequestScopedErrors []RequestScopedErrorRule `yaml:"request-scoped-errors,omitempty" json:"request-scoped-errors,omitempty"`
}

GeminiKey represents the configuration for a Gemini API key, including optional overrides for upstream base URL, proxy routing, and headers.

func (GeminiKey) GetAPIKey

func (k GeminiKey) GetAPIKey() string

GetAPIKey returns an api key.

func (GeminiKey) GetBaseURL

func (k GeminiKey) GetBaseURL() string

GetBaseURL returns a base url.

func (GeminiKey) GetPrefix added in v1.0.70

func (k GeminiKey) GetPrefix() string

GetPrefix returns a model prefix.

func (GeminiKey) GetProxyURL added in v1.0.70

func (k GeminiKey) GetProxyURL() string

GetProxyURL returns a proxy url.

func (GeminiKey) MarshalYAML added in v1.1.10

func (c GeminiKey) MarshalYAML() (any, error)

type GeminiModel

type GeminiModel struct {
	// Name is the upstream model identifier used when issuing requests.
	Name string `yaml:"name" json:"name"`

	// Alias is the client-facing model name that maps to Name.
	Alias string `yaml:"alias" json:"alias"`

	// DisplayName is the optional human-readable name shown in model catalogs.
	DisplayName string `yaml:"display-name,omitempty" json:"display-name,omitempty"`

	// ForceMapping rewrites upstream response model fields back to Alias.
	ForceMapping bool `yaml:"force-mapping,omitempty" json:"force-mapping,omitempty"`

	// Settings shared with CPA V8.
	MaxContextLength int                       `yaml:"max-context-length,omitempty" json:"max-context-length,omitempty"`
	IsCompat         bool                      `yaml:"is-compat,omitempty" json:"is-compat,omitempty"`
	Thinking         *registry.ThinkingSupport `yaml:"thinking,omitempty" json:"thinking,omitempty"`
}

GeminiModel defines the complete Gemini model configuration shared with CPA.

func (GeminiModel) GetAlias

func (m GeminiModel) GetAlias() string

GetAlias returns an alias.

func (GeminiModel) GetDisplayName added in v1.0.70

func (m GeminiModel) GetDisplayName() string

GetDisplayName returns a display name.

func (GeminiModel) GetForceMapping added in v1.0.70

func (m GeminiModel) GetForceMapping() bool

GetForceMapping returns whether response model fields should be rewritten.

func (GeminiModel) GetMaxContextLength added in v1.0.75

func (m GeminiModel) GetMaxContextLength() int

GetMaxContextLength returns the configured context limit.

func (GeminiModel) GetName

func (m GeminiModel) GetName() string

GetName returns a name.

func (GeminiModel) GetThinking added in v1.0.75

func (m GeminiModel) GetThinking() *registry.ThinkingSupport

GetThinking returns configured reasoning capabilities.

type MetaKey added in v1.0.73

type MetaKey = CodexKey

MetaKey uses the Codex API key structure for native Meta Muse execution.

type MetaModel added in v1.0.73

type MetaModel = CodexModel

MetaModel uses the Codex model mapping structure for Meta Muse models.

type ModelCatalogs added in v1.1.3

type ModelCatalogs = registry.CatalogSources

ModelCatalogs selects optional sources for the process-wide model catalogs.

type OAuthModelAlias

type OAuthModelAlias struct {
	Name         string `yaml:"name" json:"name"`
	Alias        string `yaml:"alias" json:"alias"`
	Fork         bool   `yaml:"fork,omitempty" json:"fork,omitempty"`
	ForceMapping bool   `yaml:"force-mapping,omitempty" json:"force-mapping,omitempty"`

	// Settings shared with CPA V8.
	DisplayName string `yaml:"display-name,omitempty" json:"display-name,omitempty"`
	// OpenAPI selects the Vertex execution endpoint without changing Home alias resolution.
	OpenAPI *bool `yaml:"openapi,omitempty" json:"openapi,omitempty"`
}

OAuthModelAlias defines a model ID alias for a specific channel. It maps the upstream model name (Name) to the client-visible alias (Alias). When Fork is true, the alias is added as an additional model in listings while keeping the original model ID available.

type OAuthModelSetting added in v1.1.10

type OAuthModelSetting = cpaconfig.OAuthModelSetting

OAuthModelSetting remains typed because Home publishes the authoritative model catalog.

type OpenAICompatibility

type OpenAICompatibility struct {
	CredentialConfig `yaml:",inline" json:"-"`
	// ID is the immutable identity of the fallback credential when no API key entries exist.
	ID string `yaml:"id,omitempty" json:"id,omitempty"`
	// UUID is accepted for backward-compatible input and normalized to ID.
	UUID string `yaml:"uuid,omitempty" json:"uuid,omitempty"`
	// Name is the identifier for this OpenAI compatibility configuration.
	Name string `yaml:"name" json:"name"`

	// Priority controls selection preference when multiple providers or credentials match.
	// Higher values are preferred; defaults to 0.
	Priority int `yaml:"priority,omitempty" json:"priority,omitempty"`

	// Disabled prevents this provider from being used for routing.
	Disabled bool `yaml:"disabled,omitempty" json:"disabled,omitempty"`

	// Prefix optionally namespaces model aliases for this provider (e.g., "teamA/kimi-k2").
	Prefix string `yaml:"prefix,omitempty" json:"prefix,omitempty"`

	// BaseURL is the base URL for the external OpenAI-compatible API endpoint.
	BaseURL string `yaml:"base-url" json:"base-url"`

	// APIKeyEntries defines API keys with optional per-key proxy configuration.
	APIKeyEntries []OpenAICompatibilityAPIKey `yaml:"api-key-entries,omitempty" json:"api-key-entries,omitempty"`

	// Models defines the model configurations including aliases for routing.
	Models []OpenAICompatibilityModel `yaml:"models" json:"models"`

	// Headers optionally adds extra HTTP headers for requests sent to this provider.
	Headers map[string]string `yaml:"headers,omitempty" json:"headers,omitempty"`

	// DisableCooling overrides the global cooling policy for this provider when set.
	// True disables request-error and quota cooldowns; false explicitly enables them.
	DisableCooling *bool `yaml:"disable-cooling,omitempty" json:"disable-cooling,omitempty"`

	// RequestRetry optionally overrides the global number of additional retry rounds.
	// Nil or a negative value inherits the global setting; zero disables additional rounds.
	RequestRetry *int `yaml:"request-retry,omitempty" json:"request-retry,omitempty"`

	// Settings shared with CPA V8.
	RequestScopedErrors []RequestScopedErrorRule `yaml:"request-scoped-errors,omitempty" json:"request-scoped-errors,omitempty"`
}

OpenAICompatibility represents the configuration for OpenAI API compatibility with external providers, allowing model aliases to be routed through OpenAI API format.

func (OpenAICompatibility) MarshalYAML added in v1.1.10

func (c OpenAICompatibility) MarshalYAML() (any, error)

type OpenAICompatibilityAPIKey

type OpenAICompatibilityAPIKey struct {
	CredentialConfig `yaml:",inline" json:"-"`
	// ID is the immutable credential identity.
	ID string `yaml:"id,omitempty" json:"id,omitempty"`
	// UUID is accepted for backward-compatible input and normalized to ID.
	UUID string `yaml:"uuid,omitempty" json:"uuid,omitempty"`
	// APIKey is the authentication key for accessing the external API services.
	APIKey string `yaml:"api-key" json:"api-key"`

	// ProxyURL overrides the global proxy setting for this API key if provided.
	ProxyURL string `yaml:"proxy-url,omitempty" json:"proxy-url,omitempty"`

	// Settings shared with CPA V8.
	Weight *int `yaml:"weight,omitempty" json:"weight,omitempty"`
}

OpenAICompatibilityAPIKey represents an API key configuration with optional proxy setting.

func (OpenAICompatibilityAPIKey) MarshalYAML added in v1.1.10

func (c OpenAICompatibilityAPIKey) MarshalYAML() (any, error)

type OpenAICompatibilityModel

type OpenAICompatibilityModel struct {
	// Name is the actual model name used by the external provider.
	Name string `yaml:"name" json:"name"`

	// Alias is the model name alias that clients will use to reference this model.
	Alias string `yaml:"alias" json:"alias"`

	// Thinking configures the thinking/reasoning capability for this model.
	// If nil, the model defaults to level-based reasoning with levels ["low", "medium", "high"].
	Thinking *registry.ThinkingSupport `yaml:"thinking,omitempty" json:"thinking,omitempty"`

	// Settings shared with CPA V8.
	DisplayName            string   `yaml:"display-name,omitempty" json:"display-name,omitempty"`
	MaxContextLength       int      `yaml:"max-context-length,omitempty" json:"max-context-length,omitempty"`
	ForceMapping           bool     `yaml:"force-mapping,omitempty" json:"force-mapping,omitempty"`
	Image                  bool     `yaml:"image,omitempty" json:"image,omitempty"`
	InputModalities        []string `yaml:"input-modalities,omitempty" json:"input-modalities,omitempty"`
	OutputModalities       []string `yaml:"output-modalities,omitempty" json:"output-modalities,omitempty"`
	IsCompat               bool     `yaml:"is-compat,omitempty" json:"is-compat,omitempty"`
	UseMaxCompletionTokens bool     `yaml:"use-max-completion-tokens,omitempty" json:"use-max-completion-tokens,omitempty"`
}

OpenAICompatibilityModel defines the complete OpenAI-compatible model configuration shared with CPA, including model capabilities and protocol compatibility options.

func (OpenAICompatibilityModel) GetAlias

func (m OpenAICompatibilityModel) GetAlias() string

GetAlias returns an alias.

func (OpenAICompatibilityModel) GetMaxContextLength added in v1.0.75

func (m OpenAICompatibilityModel) GetMaxContextLength() int

GetMaxContextLength returns the configured context limit.

func (OpenAICompatibilityModel) GetName

func (m OpenAICompatibilityModel) GetName() string

GetName returns a name.

func (OpenAICompatibilityModel) GetThinking added in v1.0.75

GetThinking returns configured reasoning capabilities.

type PluginInstanceConfig added in v1.0.39

type PluginInstanceConfig struct {
	// Enabled toggles this plugin instance. Nil is normalized to false during YAML parsing.
	Enabled *bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	// Priority controls plugin startup and routing order.
	Priority int `yaml:"priority,omitempty" json:"priority,omitempty"`
	// Raw preserves the full original plugin configuration YAML subtree.
	Raw yaml.Node `yaml:"-" json:"-"`
}

PluginInstanceConfig stores host-owned plugin settings and the original plugin YAML subtree.

func (PluginInstanceConfig) MarshalJSON added in v1.0.39

func (c PluginInstanceConfig) MarshalJSON() ([]byte, error)

MarshalJSON returns the preserved raw plugin subtree for lossless Management API output.

func (PluginInstanceConfig) MarshalYAML added in v1.0.39

func (c PluginInstanceConfig) MarshalYAML() (any, error)

MarshalYAML returns the preserved raw plugin YAML subtree for lossless config output.

func (*PluginInstanceConfig) UnmarshalYAML added in v1.0.39

func (c *PluginInstanceConfig) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML extracts host-owned fields while preserving the full original YAML node.

type PluginsConfig added in v1.0.39

type PluginsConfig struct {
	// Enabled toggles dynamic plugin loading on downstream CPA nodes.
	Enabled bool `yaml:"enabled" json:"enabled"`
	// Dir is the downstream plugin discovery directory.
	Dir string `yaml:"dir" json:"dir"`
	// StoreSources appends third-party plugin store registries to the built-in official source.
	StoreSources []string `yaml:"store-sources,omitempty" json:"store-sources,omitempty"`
	// Configs stores per-plugin instance configuration by plugin ID.
	Configs map[string]PluginInstanceConfig `yaml:"configs" json:"configs"`
}

PluginsConfig holds dynamic plugin distribution settings for downstream CPA nodes.

type QuotaExceeded

type QuotaExceeded struct {
	// SwitchProject indicates whether to automatically switch to another project when a quota is exceeded.
	SwitchProject bool `yaml:"switch-project" json:"switch-project"`

	// SwitchPreviewModel indicates whether to automatically switch to a preview model when a quota is exceeded.
	SwitchPreviewModel bool `yaml:"switch-preview-model" json:"switch-preview-model"`

	// AntigravityCredits enables credits-based last-resort fallback for Claude models.
	// When all free-tier auths are exhausted (429/503), the conductor retries with
	// an auth that has available Google One AI credits.
	AntigravityCredits bool `yaml:"antigravity-credits" json:"antigravity-credits"`
}

QuotaExceeded defines the behavior when API quota limits are exceeded. It provides configuration options for automatic failover mechanisms.

type RemoteManagement

type RemoteManagement struct {
	// AllowRemote toggles remote (non-localhost) access to management API.
	AllowRemote bool `yaml:"allow-remote"`
	// SecretKey is the management key (plaintext or bcrypt hashed). YAML key intentionally 'secret-key'.
	SecretKey string `yaml:"secret-key"`
	// DisableControlPanel skips serving and syncing the bundled management UI when true.
	DisableControlPanel bool `yaml:"disable-control-panel"`
	// DisableAutoUpdatePanel is retained for configuration compatibility with older deployments.
	// Embedded bundle mode serves local assets at build time and does not perform runtime remote updates.
	DisableAutoUpdatePanel bool `yaml:"disable-auto-update-panel"`
	// PanelGitHubRepository is retained for legacy compatibility and version tracking.
	// Embedded bundle mode does not fetch control panel assets from GitHub at runtime.
	PanelGitHubRepository string `yaml:"panel-github-repository"`

	// Settings shared with CPA V8.
	BaseURL string `yaml:"base-url,omitempty" json:"base-url,omitempty"`
}

RemoteManagement holds management API configuration under 'remote-management'.

type RequestScopedErrorRule added in v1.0.75

type RequestScopedErrorRule struct {
	// Status matches the HTTP status code of the upstream response (e.g. 400).
	Status int `yaml:"status,omitempty" json:"status,omitempty"`
	// Match matches substrings in the upstream error body.
	Match []string `yaml:"match,omitempty" json:"match,omitempty"`
	// MatchRegexr matches regular expressions in the upstream error body.
	MatchRegexr []string `yaml:"match-regexr,omitempty" json:"match-regexr,omitempty"`
	// Action specifies the handling behavior: "stop", "stop-and-cooldown", "continue", "continue-and-cooldown".
	Action string `yaml:"action,omitempty" json:"action,omitempty"`
}

type RoutingConfig

type RoutingConfig struct {
	// SessionAffinityRebindOn controls failover binding changes: any, quota, or never.
	SessionAffinityRebindOn string `yaml:"session-affinity-rebind-on,omitempty" json:"session-affinity-rebind-on,omitempty"`
	// Strategy selects the credential selection strategy.
	// Supported values: "round-robin" (default), "fill-first".
	Strategy string `yaml:"strategy,omitempty" json:"strategy,omitempty"`

	// SessionAffinity enables universal session-sticky routing for all clients.
	// Session IDs are extracted from multiple sources:
	// metadata.user_id (Claude Code session format), X-Session-ID, Session_id (Codex),
	// X-Client-Request-Id (PI), metadata.user_id, conversation_id, or message hash.
	// Automatic failover is always enabled when bound auth becomes unavailable.
	SessionAffinity bool `yaml:"session-affinity,omitempty" json:"session-affinity,omitempty"`

	// SessionAffinityTTL specifies how long session-to-auth bindings are retained.
	// Default: 1h. Accepts duration strings like "30m", "1h", "2h30m".
	SessionAffinityTTL string `yaml:"session-affinity-ttl,omitempty" json:"session-affinity-ttl,omitempty"`

	// SessionAffinitySubagents controls initial parent-credential inheritance for child sessions.
	// Guardian children may inherit the parent's latest eligible selection across models.
	// Defaults to true; ignored when SessionAffinity is false. Existing child bindings,
	// conversational forks, compaction, and content-hash fallbacks are unaffected.
	SessionAffinitySubagents *bool `yaml:"session-affinity-subagents,omitempty" json:"session-affinity-subagents,omitempty"`
}

RoutingConfig configures how credentials are selected for requests.

type SDKConfig

type SDKConfig struct {
	// OAuthOnlyFields preserves the scope of v8 provider settings.
	OAuthOnlyFields map[string]bool `yaml:"-" json:"-"`

	// ProxyURL is the URL of an optional proxy server to use for outbound requests.
	ProxyURL string `yaml:"proxy-url" json:"proxy-url"`

	// ForceModelPrefix requires explicit model prefixes (e.g., "teamA/gemini-3-pro-preview")
	// to target prefixed credentials. When false, unprefixed model requests may use prefixed
	// credentials as well.
	ForceModelPrefix bool `yaml:"force-model-prefix" json:"force-model-prefix"`

	// RequestLog enables or disables detailed request logging functionality.
	RequestLog bool `yaml:"request-log" json:"request-log"`
}

SDKConfig represents the application's configuration, loaded from a YAML file.

type TLSConfig

type TLSConfig struct {
	// Enable toggles HTTPS server mode.
	Enable bool `yaml:"enable" json:"enable"`
	// Cert is the path to the TLS certificate file.
	Cert string `yaml:"cert" json:"cert"`
	// Key is the path to the TLS private key file.
	Key string `yaml:"key" json:"key"`
}

TLSConfig holds HTTPS server settings.

type UserEmailConfig added in v1.0.60

type UserEmailConfig struct {
	Enabled              bool                  `yaml:"enabled" json:"enabled"`
	PublicUserURL        string                `yaml:"public-user-url" json:"public-user-url"`
	FromAddress          string                `yaml:"from-address" json:"from-address"`
	FromName             string                `yaml:"from-name" json:"from-name"`
	Sender               UserEmailSenderConfig `yaml:"sender" json:"sender"`
	VerificationTokenTTL string                `yaml:"verification-token-ttl" json:"verification-token-ttl"`
	ResetTokenTTL        string                `yaml:"reset-token-ttl" json:"reset-token-ttl"`
}

UserEmailConfig controls optional verified-email and password-recovery behavior.

type UserEmailSMTPConfig added in v1.0.60

type UserEmailSMTPConfig struct {
	Host        string `yaml:"host" json:"host"`
	Port        int    `yaml:"port" json:"port"`
	Username    string `yaml:"username" json:"username"`
	PasswordEnv string `yaml:"password-env" json:"password-env"`
	StartTLS    bool   `yaml:"starttls" json:"starttls"`
}

UserEmailSMTPConfig configures SMTP delivery without persisting the password itself.

type UserEmailSenderConfig added in v1.0.60

type UserEmailSenderConfig struct {
	Type string              `yaml:"type" json:"type"`
	SMTP UserEmailSMTPConfig `yaml:"smtp" json:"smtp"`
}

UserEmailSenderConfig selects the configured mail transport.

type VertexCompatKey

type VertexCompatKey struct {
	CredentialConfig `yaml:",inline" json:"-"`
	// ID is the immutable credential identity.
	ID string `yaml:"id,omitempty" json:"id,omitempty"`
	// UUID is accepted for backward-compatible input and normalized to ID.
	UUID string `yaml:"uuid,omitempty" json:"uuid,omitempty"`
	// APIKey is the authentication key for accessing the Vertex-compatible API.
	// Maps to the x-goog-api-key header.
	APIKey string `yaml:"api-key" json:"api-key"`

	// Priority controls selection preference when multiple credentials match.
	// Higher values are preferred; defaults to 0.
	Priority int `yaml:"priority,omitempty" json:"priority,omitempty"`

	// Prefix optionally namespaces model aliases for this credential (e.g., "teamA/vertex-pro").
	Prefix string `yaml:"prefix,omitempty" json:"prefix,omitempty"`

	// BaseURL optionally overrides the Vertex-compatible API endpoint.
	// The executor will append "/v1/publishers/google/models/{model}:action" to this.
	// When empty, requests fall back to the default Vertex API base URL.
	BaseURL string `yaml:"base-url,omitempty" json:"base-url,omitempty"`

	// ProxyURL optionally overrides the global proxy for this API key.
	ProxyURL string `yaml:"proxy-url,omitempty" json:"proxy-url,omitempty"`

	// Headers optionally adds extra HTTP headers for requests sent with this key.
	// Commonly used for cookies, user-agent, and other authentication headers.
	Headers map[string]string `yaml:"headers,omitempty" json:"headers,omitempty"`

	// Models defines the model configurations including aliases for routing.
	Models []VertexCompatModel `yaml:"models,omitempty" json:"models,omitempty"`

	// ExcludedModels lists model IDs that should be excluded for this provider.
	ExcludedModels []string `yaml:"excluded-models,omitempty" json:"excluded-models,omitempty"`

	// DisableCooling overrides the global cooling policy for this credential when set.
	// True disables request-error and quota cooldowns; false explicitly enables them.
	DisableCooling *bool `yaml:"disable-cooling,omitempty" json:"disable-cooling,omitempty"`

	// RequestRetry optionally overrides the global number of additional retry rounds.
	// Nil or a negative value inherits the global setting; zero disables additional rounds.
	RequestRetry *int `yaml:"request-retry,omitempty" json:"request-retry,omitempty"`

	// Settings shared with CPA V8.
	Weight *int `yaml:"weight,omitempty" json:"weight,omitempty"`
}

VertexCompatKey represents the configuration for Vertex AI-compatible API keys. This supports third-party services that use Vertex AI-style endpoint paths (/publishers/google/models/{model}:streamGenerateContent) but authenticate with simple API keys instead of Google Cloud service account credentials.

Example services: zenmux.ai and similar Vertex-compatible providers.

func (VertexCompatKey) GetAPIKey

func (k VertexCompatKey) GetAPIKey() string

GetAPIKey returns an api key.

func (VertexCompatKey) GetBaseURL

func (k VertexCompatKey) GetBaseURL() string

GetBaseURL returns a base url.

func (VertexCompatKey) GetPrefix added in v1.0.70

func (k VertexCompatKey) GetPrefix() string

GetPrefix returns a model prefix.

func (VertexCompatKey) GetProxyURL added in v1.0.70

func (k VertexCompatKey) GetProxyURL() string

GetProxyURL returns a proxy url.

func (VertexCompatKey) MarshalYAML added in v1.1.10

func (c VertexCompatKey) MarshalYAML() (any, error)

type VertexCompatModel

type VertexCompatModel struct {
	// Name is the actual model name used by the external provider.
	Name string `yaml:"name" json:"name"`

	// Alias is the model name alias that clients will use to reference this model.
	Alias string `yaml:"alias" json:"alias"`

	// Settings shared with CPA V8.
	DisplayName  string                    `yaml:"display-name,omitempty" json:"display-name,omitempty"`
	ForceMapping bool                      `yaml:"force-mapping,omitempty" json:"force-mapping,omitempty"`
	OpenAPI      *bool                     `yaml:"openapi,omitempty" json:"openapi,omitempty"`
	Thinking     *registry.ThinkingSupport `yaml:"thinking,omitempty" json:"thinking,omitempty"`
}

VertexCompatModel defines the complete Vertex-compatible model configuration shared with CPA.

func (VertexCompatModel) GetAlias

func (m VertexCompatModel) GetAlias() string

GetAlias returns an alias.

func (VertexCompatModel) GetDisplayName added in v1.0.75

func (m VertexCompatModel) GetDisplayName() string

GetDisplayName returns a display name.

func (VertexCompatModel) GetForceMapping added in v1.0.75

func (m VertexCompatModel) GetForceMapping() bool

GetForceMapping returns whether response model fields should be rewritten.

func (VertexCompatModel) GetName

func (m VertexCompatModel) GetName() string

GetName returns a name.

func (VertexCompatModel) GetThinking added in v1.0.75

func (m VertexCompatModel) GetThinking() *registry.ThinkingSupport

GetThinking returns configured reasoning capabilities.

type XAIKey added in v1.0.55

type XAIKey = CodexKey

XAIKey uses the Codex API key structure for native xAI execution.

type XAIModel added in v1.0.55

type XAIModel = CodexModel

XAIModel uses the Codex model mapping structure for xAI models.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL