Configuration

Functional Options

The primary way to configure Nexus is via functional options:

gw := nexus.New(
    nexus.WithBasePath("/ai"),
    nexus.WithRateLimit(1000),
    nexus.WithTimeout(30 * time.Second),
    nexus.WithMaxRetries(3),
)

Config Struct

The Config struct holds all gateway settings:

type Config struct {
    BasePath          string
    GlobalRateLimit   int
    DefaultTimeout    time.Duration
    DefaultMaxRetries int
    EnableCache       bool
    LogLevel          string
}

DefaultConfig() returns sensible defaults.

Available Options

Option	Description
`WithConfig(cfg)`	Set the full config struct
`WithDatabase(store)`	Set the persistence store
`WithAuth(provider)`	Set the auth provider
`WithProvider(p)`	Register an LLM provider
`WithRouter(strategy)`	Set the routing strategy
`WithCache(cache)`	Enable response caching
`WithGuard(guard)`	Add a guardrail
`WithMiddleware(m)`	Add custom pipeline middleware
`WithExtension(ext)`	Register a lifecycle plugin
`WithAlias(name, targets...)`	Register a model alias
`WithLogger(logger)`	Set a custom logger
`WithBasePath(path)`	Set the HTTP base path
`WithRateLimit(rpm)`	Set global rate limit
`WithTracer(tracer)`	Set the request tracer
`WithTransforms(registry)`	Set input/output transforms
`WithTimeout(duration)`	Set default request timeout
`WithMaxRetries(n)`	Set default max retries
`WithTenantAlias(tid, name, targets...)`	Per-tenant alias override

File-based configuration (Forge extension)

When Nexus runs as a Forge extension, it can load configuration from the application's YAML config file. The extension checks two keys in order:

extensions.nexus -- namespaced under the Forge extensions convention (recommended)
nexus -- legacy top-level key

forge.yaml

extensions:
  nexus:
    base_path: "/ai"
    default_timeout: "30s"
    default_max_retries: 2
    global_rate_limit: 1000
    log_level: "info"
    enable_usage: true
    enable_cache: false
    grove_database: ""
    disable_routes: false
    disable_migrate: false

Extension-specific fields

In addition to the gateway config fields, the extension config adds:

Field	Type	Description	Default
`disable_routes`	`bool`	Disable automatic route registration	`false`
`disable_migrate`	`bool`	Disable automatic store migration	`false`
`grove_database`	`string`	Name of grove.DB to resolve from DI (empty = default DB)	`""`

Configuration precedence

When both file-based and programmatic options are provided, they are merged:

YAML values take precedence for string, duration, and integer fields.
Programmatic boolean flags (DisableRoutes, DisableMigrate, EnableCache) override when set to true.
Any remaining zero-valued fields are filled from DefaultConfig().

If no file-based config is found and RequireConfig is not set, the extension falls back to programmatic options merged with defaults.