Config reference

Every Zever config service, adapter, option key, default, and environment variable, plus the layering and strictness rules.

34 min readEdit on GitHub

Zever config is one block per service, shaped { adapter, options }. This page lists all 37 services and every option each one accepts.

Layering and rules

Rule	Behavior
Layers	`defaults < env`. Later layers win.
Defaults	`config.Default()` selects zero-infrastructure adapters (memory, local, sqlite, log, noop). The only dev secret is the crypto key, which is deterministic and must never ship to production.
Env	`config.FromEnv()` / `config.LoadEnv()` reads instance-aware environment variables: `<SERVICE>__<NAME>__<FIELD>=value`, uppercase. Example: `DB__PRIMARY__DSN=postgres://...`, `DB__PRIMARY__MAX_CONNS=20`. The legacy flat format `<SERVICE>_<FIELD>` (e.g. `DB_MAXCONNS`) is still accepted but triggers `warnLegacyConfigFile` logging. Matching ignores case and `_`. `<SERVICE>__<NAME>__ADAPTER` sets the adapter.
Env strictness	Best-effort. Unknown variables are ignored, so a noisy process environment cannot break startup. Only a value that fails to parse for a resolved field returns `InvalidOptionsError` (the value is never echoed).
Durations	In env, a Go duration string such as `5s` or `5m`.
Options replace defaults	Env variables overlay one field at a time and do not replace the block.
Unset values	A zero value (`0`, `""`, `false`) means unset: the adapter applies its own default, shown in the Default column when known.
Redaction	Raw option maps can hold secrets. Log only through `RedactedServices` or `Redact`. Error text names services and fields, never values.
Plugins	A top-level `plugins` map holds third-party services as `{adapter, options}` envelopes. The envelope is strict, but the options pass through raw and the plugin validates them. Env can override only `<PLUGIN>__<NAME>__ADAPTER`.
Exceptions	The `secrets` env adapter reads secrets with a non-empty `prefix` (default `ZEVER`, so `ZEVER_FOO` is secret `FOO`). CLI switches use `ZEVER_INTERACTIVE` and `ZEVER_NO_HINT`.

DB__PRIMARY__ADAPTER=postgres
DB__PRIMARY__DSN=postgres://app:secret@db:5432/app
DB__PRIMARY__MAX_CONNS=20
LOG__DEFAULT__ADAPTER=slog

DB__PRIMARY__MAXCONNS=20 DB__PRIMARY__MAXCONNLIFETIME=5m AUTH__DEFAULT__JWT_SECRET=prod-secret-at-least-32-bytes-long zever serve

Services at a glance

Service	Adapters	Accessor	Guide
`ai`	anthropic, openai, gemini, ollama	`c.AI()`	AI
`analytics`	log, posthog	`c.Analytics()`	Analytics
`auth`	jwt, session, oidc	`c.Auth()`	Auth
`billing`	stub, stripe, paddle	`c.Billing()`	Billing
`cache`	memory, redis, db	`c.Cache()`	Cache
`cdn`	noop, cloudflare	`c.CDN()`	CDN
`crypto`	local	`c.Crypto()`	Crypto and secrets
`db`	sqlite, postgres	`c.DB()`	Query builder
`document`	local, remote, latex	`c.Document()`	Document
`eventbus`	memory, redis	`c.EventBus()`	Events
`flag`	static, firebase	`c.Flag()`	Feature flags
`geo`	google, static, osm	`c.Geo()`	Geo
`i18n`	embed, remote	`c.I18n()`	i18n
`idempotency`	memory, redis, db	`c.Idempotency()`	Locks and idempotency
`lock`	memory, redis	`c.Lock()`	Locks and idempotency
`log`	noop, zerolog, slog, pretty	`c.Log()`	Logging
`mailer`	log, smtp	`c.Mailer()`	Mailer
`media`	local, s3	`c.Media()`	Media
`notification`	log, twilio, fcm	`c.Notification()`	Notifications
`observability`	noop, stdout, otlp	`c.Observability()`	Observability
`outbox`	memory, db, cdc	`c.Outbox()`	Outbox
`password`	argon2id	`c.Password()`	Password hashing
`payment`	stub, stripe, paddle	`c.Payment()`	Payment
`permission`	noop, rbac, casbin	`c.Permission()`	Permissions
`queue`	memory, redis, db	`c.Queue()`	Queue
`ratelimit`	memory, redis	`c.RateLimit()`	Ratelimit
`resilience`	memory, redis	`c.Resilience()`	Resilience
`router`	fiber, stdhttp	`c.Router()`	Routing
`scheduler`	embedded, postgres	`c.Scheduler()`	Scheduler and jobs
`search`	db, postgres, meilisearch, sqlite	`c.Search()`	Search
`secrets`	env, vault	`c.Secrets()`	Secrets
`session`	memory, redis, db	`c.Session()`	Sessions
`storage`	local, s3, r2	`c.Storage()`	Storage
`tenant`	single, header	`c.Tenant()`	Tenants
`vectorstore`	db, sqlite, pgvector, qdrant	`c.VectorStore()`	Vectorstore
`webhook`	http, queue	`c.Webhook()`	Webhooks
`workflow`	memory, db, postgres	`c.Workflow()`	Workflows

The bold adapter is the default. The search, vectorstore, and workflow services accept db as the canonical DB-backed name (empty DSN selects embedded sqlite, a postgres URL selects postgres). The older postgres, sqlite, and pgvector names stay registered as aliases.

Shared option groups

Redis connection options

Services with a Redis adapter embed the same connection keys. Flat services (cache, lock, queue) take them directly. Services with a redis block (eventbus, idempotency, ratelimit, resilience, session) take them under redis..

Key	Type	Default	Description
`addr`	string	`localhost:6379`	Redis address as `host:port`, or a `redis://` or `rediss://` URL.
`password`	string	`""`	Redis password. Never logged.
`db`	integer	`0`	Redis database index.
`tls`	boolean	`false`	Enable TLS with a TLS 1.2 floor for plain addresses. Off means plaintext, including the password.
`require_tls`	boolean	`false`	Fail connection setup instead of connecting in plaintext when the address would not use TLS.
`pool_size`	integer	go-redis default	Base number of socket connections (10 per GOMAXPROCS when `<= 0`).
`min_idle_conns`	integer	`2`	Pre-warmed idle connections.
`pool_timeout`	duration	go-redis default	Wait for a pooled connection when exhausted.
`max_conn_idle_time`	duration	go-redis default	Idle time before a connection may close.
`max_conn_lifetime`	duration	unbounded	Maximum reuse time for a connection.

lock and queue accept only addr, password, db, tls, and require_tls from this group. cache and queue also accept a top-level url that takes precedence over addr. Under redis., url is reserved and ignored.

Retry policy

outbox and resilience take a retry block. Its keys are exported Go field names, matched case-insensitively.

Key	Type	Default	Description
`retry.BaseDelay`	duration	`0`	Delay before the first retry. `resilience` default is `50ms`.
`retry.MaxDelay`	duration	unbounded	Cap on the computed delay, before jitter. `resilience` default is `2s`.
`retry.Multiplier`	number	`0`	Per-attempt growth factor. Values `<= 1` keep the delay flat. `resilience` default is `2`.
`retry.Linear`	boolean	`false`	Grow linearly (`BaseDelay * attempt`) instead of exponentially. Ignores `Multiplier`.
`retry.Jitter`	number	`0`	Fraction of the delay to randomize, clamped to `[0, 1]`. `resilience` default is `0.1`.
`retry.JitterMode`	integer	`0`	`0` symmetric (plus or minus), `1` additive (never shortens), `2` flat (adds up to `JitterMax`).
`retry.JitterMax`	duration	`0`	Upper bound of the flat jitter draw. Used only when `JitterMode` is `2`.
`retry.MaxAttempts`	integer	`1`	Total attempts including the first. `<= 0` means 1. `resilience` default is `3`.

DB-backed services (db, cache, queue, search, session, idempotency, workflow, scheduler, vectorstore, outbox) share one container pool per exact DSN by default. Matching is on the trimmed DSN string, so a URL with and without a query string are different pools. SQLite shares by cleaned file path, and :memory: never shares.

The second service to open a DSN borrows the first pool and never closes it. The shared pool takes the first opener’s pool settings, and a differing nonzero max_conns logs a warning without DSN content.
Set dedicated_pool: true to open a private pool. Use it with a separate database for queue, workflow, and scheduler under sustained load.
dedicated_pool is ignored on db itself, which owns the pool.
Env: SEARCH__DEFAULT__DEDICATEDPOOL=true, QUEUE__DEFAULT__DSN=..., SESSION__DEFAULT__DSN=....
Old binaries reject dedicated_pool and dsn under strict decoding, so remove those lines before a downgrade.

SEARCH__DEFAULT__ADAPTER=db
SEARCH__DEFAULT__DSN=postgres://app:secret@db:5432/app?sslmode=require
SEARCH__DEFAULT__DEDICATED_POOL=false

Service reference

Each service lists its adapters, accessor, and every option key. Options form a union across adapters: an adapter reads only the keys it needs and ignores the rest. Keys such as jwt.secret are nested under options.

`ai`

LLM completions, chat, and embeddings. Every backend needs a key, so there is no zero-infra adapter.


Adapters	`anthropic`, `openai`, `gemini`, `ollama`
Default adapter	`anthropic`
Accessor	`c.AI()`
Guide	AI guide

Key	Type	Default	Description
`api_key`	string	`""`	Provider API key. Never logged
`model`	string	`""`	Model identifier
`base_url`	string	`""`	Provider base URL. Must be https unless `allow_insecure` is set
`allow_insecure`	boolean	`false`	Permits http BaseURL for testing
`allow_private`	boolean	`false`	Permits dialing private, loopback, and link-local addresses (local sidecars). Logs a line at startup
`insecure_skip_verify`	boolean	`false`	Disables TLS certificate verification for self-signed test servers. Logs a warning at startup
`timeout`	duration	`0`	Request timeout

AI__DEFAULT__ADAPTER=anthropic
AI__DEFAULT__API_KEY=sk-ant-...
AI__DEFAULT__MODEL=claude-sonnet-4-5
AI__DEFAULT__TIMEOUT=30s

`analytics`

Event tracking, identify, and group calls.


Adapters	`log`, `posthog`
Default adapter	`log`
Accessor	`c.Analytics()`
Guide	Analytics guide

Key	Type	Default	Description
`api_key`	string	`""`	Backend write key. Never logged
`endpoint`	string	`""`	Optional custom backend endpoint URL
`anonymous_id`	string	`anonymous`	Fallback identity for anonymous tracking
`group_type`	string	`organization`	Group type for group calls
`max_properties_bytes`	integer	`65536`	Bounds the JSON-encoded properties payload size
`max_properties`	integer	`0`	Bounds the number of properties per call

ANALYTICS__DEFAULT__ADAPTER=posthog
ANALYTICS__DEFAULT__API_KEY=phc_...
ANALYTICS__DEFAULT__GROUP_TYPE=organization

`auth`

Token and identity verification. Options nest under the adapter name (jwt, session, oidc).


Adapters	`jwt`, `session`, `oidc`
Default adapter	`jwt`
Accessor	`c.Auth()`
Guide	Auth guide

Key	Type	Default	Description
`jwt.secret`	string	`""`	HMAC signing secret; also verifies kid-less (legacy) tokens
`jwt.keys`	array	`[]`	Rotatable `{kid, secret}` keys; signed tokens carry the `kid` header
`jwt.active_kid`	string	`""`	Signing key ID within `keys`; empty defaults to the first entry
`jwt.issuer`	string	`""`	Token issuer
`jwt.audience`	string	`""`	Intended token audience
`jwt.max_ttl`	duration	`0`	Caps token lifetimes
`jwt.leeway`	duration	`0`	Tolerates clock skew when validating exp/nbf
`oidc.issuer`	string	`""`	OIDC issuer URL
`oidc.client_id`	string	`""`	Relying-party client ID
`oidc.timeout`	duration	`30s`	Operation timeout
`oidc.allow_insecure`	boolean	`false`	Permits an http:// issuer (and a private-address issuer) for testing

The session adapter has no file-settable options: its session.Store is injected from Go.

AUTH__DEFAULT__ADAPTER=jwt
AUTH__DEFAULT__JWT_SECRET=change-me-to-at-least-32-bytes
AUTH__DEFAULT__JWT_ISSUER=my-app
AUTH__DEFAULT__JWT_MAX_TTL=1h

`billing`

Customers, subscriptions, and invoices through a billing provider.


Adapters	`stub`, `stripe`, `paddle`
Default adapter	`stub`
Accessor	`c.Billing()`
Guide	Billing guide

Key	Type	Default	Description
`secret_key`	string	`""`	Provider secret key (Stripe). Never logged
`api_key`	string	`""`	Provider API key (Paddle). Never logged
`endpoint`	string	`""`	Optional custom provider endpoint URL
`sandbox`	boolean	`false`	Selects the provider sandbox environment

BILLING__DEFAULT__ADAPTER=stripe
BILLING__DEFAULT__SECRET_KEY=sk_live_...

`cache`

Key/value cache with TTL. db selects postgres or sqlite by DSN.


Adapters	`memory`, `redis`, `db`
Default adapter	`memory`
Accessor	`c.Cache()`
Guide	Cache guide

Key	Type	Default	Description
`capacity`	integer	`0`	Hints at the expected number of cache entries
`verbose`	boolean	`false`	Enables additional diagnostic output
`dsn`	string	`""`	Postgres connection string or sqlite path for the db adapter
`dedicated_pool`	boolean	`false`	Opts out of container-level pool sharing
`sweep_interval`	duration	`1m`	Controls how often expired entries are purged (memory adapter)
`max_entries`	integer	`1000`	Bounds the number of stored entries before eviction (memory adapter)
`url`	string	`""`	Redis connection URL

Redis connection keys, documented in Redis connection options: addr, password, db, tls, require_tls, pool_size, min_idle_conns, pool_timeout, max_conn_idle_time, max_conn_lifetime.

The db adapter’s table, key prefix, and TTL are set from Go, not from config. The adapter field inside options is a legacy duplicate and is omitted here; use the outer adapter string.

CACHE__DEFAULT__ADAPTER=redis
CACHE__DEFAULT__ADDR=localhost:6379
CACHE__DEFAULT__REQUIRE_TLS=true

`cdn`

Invalidates cached content at the edge. noop discards purges (default); cloudflare calls the Cloudflare cache-purge API.


Adapters	`noop`, `cloudflare`
Default adapter	`noop`
Accessor	`c.CDN()`
Guide	CDN guide

Key	Type	Default	Description
`api_token`	string	`""`	Cloudflare API token (cloudflare adapter)
`zone_id`	string	`""`	Cloudflare zone ID to purge (cloudflare adapter)
`base_url`	string	`""`	Overrides the Cloudflare API endpoint (cloudflare adapter)

CDN__DEFAULT__ADAPTER=cloudflare
CDN__DEFAULT__API_TOKEN=CLOUDFLARE_API_TOKEN
CDN__DEFAULT__ZONE_ID=CLOUDFLARE_ZONE_ID

`crypto`

Symmetric encryption and signing. The default config ships a deterministic dev key that must never reach production.


Adapters	`local`, `kms`
Default adapter	`local`
Accessor	`c.Crypto()`
Guide	Crypto and secrets guide

Key	Type	Default	Description
`key`	string	`dev key (config default)`	Base64-encoded 32-byte encryption key
`sign_key`	string	`""`	Base64-encoded 64-byte signing key
`key_id`	string	`""`	Primary KMS key identifier used for envelope encryption
`key_ids`	list of strings	none	Lists accepted KMS key identifiers for rotation
`region`	string	`""`	KMS region (for example an AWS region)
`endpoint`	string	`""`	Overrides the KMS endpoint (custom KMS, tests, VPC endpoints)
`use_envelope`	boolean	`false`	Selects KMS envelope encryption
`allow_dev_key`	boolean	`false`	Permits the deterministic public dev key for local development; when false, the local adapter rejects that key unless `ZEVER_ENV` is `dev`, `test`, or `development`

The kms adapter fails closed from config: it needs a real KMS client injected from Go, because its dev stub is not a file option. Use local for file-only setups.

CRYPTO__DEFAULT__ADAPTER=local
CRYPTO__DEFAULT__KEY=<base64-32-bytes>
CRYPTO__DEFAULT__SIGN_KEY=<base64-64-bytes>

`db`

SQL connection pool. Other db-backed services borrow this pool when their DSN matches.


Adapters	`sqlite`, `postgres`
Default adapter	`sqlite`
Accessor	`c.DB()`
Guide	Query builder guide

Key	Type	Default	Description
`dsn`	string	`""`	Postgres connection string
`max_conns`	integer	`0`	Caps the connection pool size
`min_conns`	integer	`0`	Minimum pool size for Postgres and the idle connection target for SQLite
`max_conn_lifetime`	duration	`0`	Bounds how long a pooled connection may be reused
`max_conn_idle_time`	duration	`0`	Bounds how long a pooled connection may stay idle
`path`	string	`""`	SQLite database file path
`dedicated_pool`	boolean	`false`	Opts out of container-level pool sharing

DB__PRIMARY__ADAPTER=postgres
DB__PRIMARY__DSN=postgres://app:secret@db:5432/app
DB__PRIMARY__MAX_CONNS=20
DB__PRIMARY__MAX_CONN_LIFETIME=5m

`document`

Render documents to PDF or images locally, through a remote service, or with LaTeX.


Adapters	`local`, `remote`, `latex`
Default adapter	`local`
Accessor	`c.Document()`
Guide	Document guide

Key	Type	Default	Description
`tmp_dir`	string	`""`	Directory for intermediate render artifacts
`timeout`	duration	`30s`	Bounds document render operations
`quality`	integer	`80`	Controls raster output quality in the range 0-100
`dpi`	integer	`150`	Controls raster output resolution
`endpoint`	string	`""`	Optional remote render endpoint URL
`allow_insecure`	boolean	`false`	Permits http Endpoint for testing
`allow_private`	boolean	`false`	Permits dialing private, loopback, and link-local addresses (local sidecars). Logs a line at startup
`api_key`	string	`""`	Remote API key. Never logged
`latex_command`	string	`pdflatex`	LaTeX compiler command
`latex_pdf_to_ppm`	string	`pdftoppm`	PDF-to-image converter command
`max_output_bytes`	integer	`64 MiB`	Bounds the rendered output size
`latex_runs`	integer	`0`	Bounds the number of LaTeX compiler passes
`latex_sandbox`	string	`auto`	OS sandbox (bubblewrap) for LaTeX: `auto`, `required`, or `off`
`latex_allow_unsafe_source`	boolean	`false`	Disables the LaTeX source pre-scan (absolute or `..` file paths, shell-escape packages). Trusted sources only

DOCUMENT__DEFAULT__ADAPTER=latex
DOCUMENT__DEFAULT__LATEX_COMMAND=pdflatex
DOCUMENT__DEFAULT__TIMEOUT=1m

`eventbus`

In-process or Redis publish/subscribe.


Adapters	`memory`, `redis`
Default adapter	`memory`
Accessor	`c.EventBus()`
Guide	Events guide

Key	Type	Default	Description
`buffer_size`	integer	`1024`	Per-topic buffer size
`max_handlers`	integer	`128`	Maximum handler count
`handler_timeout`	duration	`30s`	Per-handler delivery timeout
`close_timeout`	duration	`5s`	Shutdown timeout
`redis.url`	string	`""`	Reserved and currently ignored
`redis.prefix`	string	`""`	Key prefix for Redis eventbus data

Redis connection keys, documented in Redis connection options: redis.addr, redis.password, redis.db, redis.tls, redis.require_tls, redis.pool_size, redis.min_idle_conns, redis.pool_timeout, redis.max_conn_idle_time, redis.max_conn_lifetime.

EVENTBUS__DEFAULT__ADAPTER=redis
EVENTBUS__DEFAULT__REDIS_ADDR=localhost:6379
EVENTBUS__DEFAULT__REDIS_PREFIX=events

`flag`

Feature flags from a static file or Firebase. Options nest under the adapter name.


Adapters	`static`, `firebase`
Default adapter	`static`
Accessor	`c.Flag()`
Guide	Feature flags guide

Key	Type	Default	Description
`static.path`	string	`""`	Flag file path
`static.reload`	boolean	`false`	Enables file reloading
`firebase.project_id`	string	`""`	Firebase project ID
`firebase.service_account`	string	`""`	Path to the service account JSON key file
`firebase.timeout`	duration	`30s`	Operation timeout

FLAG__DEFAULT__ADAPTER=static
FLAG__DEFAULT__STATIC_PATH=flags.json
FLAG__DEFAULT__STATIC_RELOAD=true

`geo`

Geocoding and reverse geocoding.


Adapters	`google`, `static`, `osm`
Default adapter	`static`
Accessor	`c.Geo()`
Guide	Geo guide

Key	Type	Default	Description
`api_key`	string	`""`	Provider API key. Never logged
`base_url`	string	`""`	Overrides the Google Maps API base URL
`endpoint`	string	`""`	Overrides the Mapbox/OSM API endpoint
`timeout`	duration	`0`	Bounds HTTP requests
`path`	string	`""`	JSON file for the static adapter
`max_response_body`	integer	`0`	Bounds response bodies
`allow_insecure`	boolean	`false`	Permits http BaseURL/Endpoint for testing
`allow_private`	boolean	`false`	Permits dialing private, loopback, and link-local addresses (local sidecars). Logs a line at startup
`user_agent`	string	`""`	User-Agent for OSM Nominatim

GEO__DEFAULT__ADAPTER=osm
GEO__DEFAULT__USER_AGENT=my-app/1.0 (ops@example.com)

`i18n`

Message catalogs. Options nest under the adapter name.


Adapters	`embed`, `remote`
Default adapter	`embed`
Accessor	`c.I18n()`
Guide	i18n guide

Key	Type	Default	Description
`embed.dir`	string	`""`	Catalog directory
`embed.fallback`	string	`""`	Fallback locale
`remote.endpoint`	string	`""`	Remote service base URL
`remote.api_key`	string	`""`	Remote service credential
`remote.timeout`	duration	`30s`	Operation timeout
`remote.max_in_flight`	integer	`1000`	Caps concurrent requests
`remote.allow_insecure`	boolean	`false`	Permits http:// endpoints
`remote.allow_private`	boolean	`false`	Permits dialing private, loopback, and link-local addresses (local sidecars). Logs a line at startup

I18N__DEFAULT__ADAPTER=embed
I18N__DEFAULT__EMBED_DIR=locales
I18N__DEFAULT__EMBED_FALLBACK=en

`idempotency`

Reserve-then-commit store that makes retried requests safe.


Adapters	`memory`, `redis`, `db`
Default adapter	`memory`
Accessor	`c.Idempotency()`
Guide	Locks and idempotency guide

Key	Type	Default	Description
`ttl`	duration	`24h`	Default reservation lifetime
`dsn`	string	`""`	Postgres connection string or sqlite path for the db adapter
`dedicated_pool`	boolean	`false`	Opts out of container-level pool sharing
`redis.url`	string	`""`	Reserved and currently ignored
`redis.prefix`	string	`""`	Key prefix for Redis idempotency data
`max_entries`	integer	`1000`	Bounds the number of stored records in the memory adapter before least-recently-used eviction

IDEMPOTENCY__DEFAULT__ADAPTER=redis
IDEMPOTENCY__DEFAULT__TTL=24h
IDEMPOTENCY__DEFAULT__REDIS_ADDR=localhost:6379

`lock`

Distributed leases with a TTL.


Adapters	`memory`, `redis`
Default adapter	`memory`
Accessor	`c.Lock()`
Guide	Locks and idempotency guide

Key	Type	Default	Description
`url`	string	`""`	Redis connection URL
`prefix`	string	`""`	Scopes lock keys to one namespace
`ttl`	duration	`30s`	Default lease lifetime
`retry_interval`	duration	`50ms`	How long Acquire waits between attempts
`max_entries`	integer	`1000`	Bounds the number of stored leases before LRU eviction (memory adapter)

Redis connection keys, documented in Redis connection options: addr, password, db, tls, require_tls.

LOCK__DEFAULT__ADAPTER=redis
LOCK__DEFAULT__ADDR=localhost:6379
LOCK__DEFAULT__TTL=30s

`log`

Structured logging. Only the minimum level is configurable here.


Adapters	`noop`, `zerolog`, `slog`, `pretty`
Default adapter	`slog`
Accessor	`c.Log()`
Guide	Logging guide

Key	Type	Default	Description
`min_level`	integer	`0`	Minimum severity emitted by the logger: `0` debug, `1` info, `2` warn, `3` error, `4` fatal. In a file it is an integer, not a name.

LOG__DEFAULT__ADAPTER=slog
LOG__DEFAULT__MIN_LEVEL=1

`mailer`

Outbound email. host and port are required by validation, so the default log adapter keeps a dummy localhost:25.


Adapters	`log`, `smtp`
Default adapter	`log`
Accessor	`c.Mailer()`
Guide	Mailer guide

Key	Type	Default	Description
`host`	string	`localhost (config default)`	SMTP server hostname
`port`	integer	`25 (config default)`	SMTP server port (1-65535)
`username`	string	`""`	SMTP auth username
`password`	string	`""`	SMTP auth password
`encryption`	string	`starttls`	Transport encryption mode
`timeout`	duration	`30s`	Operation timeout
`max_message_size`	integer	`10 MiB`	Maximum message size in bytes

MAILER__DEFAULT__ADAPTER=smtp
MAILER__DEFAULT__HOST=smtp.example.com
MAILER__DEFAULT__PORT=587
MAILER__DEFAULT__USERNAME=apikey
MAILER__DEFAULT__PASSWORD=secret
MAILER__DEFAULT__ENCRYPTION=starttls

`media`

Image and video storage and derivation, locally or on S3.


Adapters	`local`, `s3`
Default adapter	`local`
Accessor	`c.Media()`
Guide	Media guide

Key	Type	Default	Description
`root`	string	`/tmp/media`	Local storage root directory
`base_url`	string	`/media`	Base URL for served assets
`max_download_bytes`	integer	`64 MiB`	Bounds a single download in bytes
`max_pixels`	integer	`52428800`	Bounds the decoded image pixel count
`derived_ttl`	duration	`10m`	Time-to-live for derived assets
`presign_ttl`	duration	`1h`	Time-to-live for presigned URLs
`max_duration`	duration	`0 (unlimited)`	Bounds media duration
`endpoint`	string	`""`	Optional custom storage endpoint URL
`region`	string	`us-east-1`	Storage region
`bucket`	string	`""`	Storage bucket name
`access_key_id`	string	`""`	Storage access key. Never logged
`secret_access_key`	string	`""`	Storage secret key. Never logged
`ffmpeg`	string	`ffmpeg`	Ffmpeg binary path
`ffprobe`	string	`ffprobe`	Ffprobe binary path

MEDIA__DEFAULT__ADAPTER=s3
MEDIA__DEFAULT__BUCKET=my-media
MEDIA__DEFAULT__REGION=us-east-1
MEDIA__DEFAULT__ACCESS_KEY_ID=AKIA...
MEDIA__DEFAULT__SECRET_ACCESS_KEY=...

`notification`

SMS and push notifications. Twilio and FCM options nest under their names.


Adapters	`log`, `twilio`, `fcm`
Default adapter	`log`
Accessor	`c.Notification()`
Guide	Notifications guide

Key	Type	Default	Description
`timeout`	duration	`30s`	Operation timeout
`twilio.account_sid`	string	`""`	Twilio account SID for basic-auth and URL path
`twilio.auth_token`	string	`""`	Twilio auth token for basic-auth
`twilio.from_number`	string	`""`	Twilio sender phone number in E.164 format
`fcm.project_id`	string	`""`	Firebase project ID
`fcm.service_account`	string	`""`	Path to the service account JSON key file

NOTIFICATION__DEFAULT__ADAPTER=twilio
NOTIFICATION__DEFAULT__TWILIO_ACCOUNT_SID=AC...
NOTIFICATION__DEFAULT__TWILIO_AUTH_TOKEN=...
NOTIFICATION__DEFAULT__TWILIO_FROM_NUMBER=+15551234567

`observability`

Traces and metrics, to stdout or an OTLP collector.


Adapters	`noop`, `stdout`, `otlp`
Default adapter	`stdout`
Accessor	`c.Observability()`
Guide	Observability guide

Key	Type	Default	Description
`endpoint`	string	`""`	Collector address as host:port
`service_name`	string	`zever (config default)`	Identifies the service emitting telemetry
`insecure`	boolean	`false`	Disables TLS; only allowed for loopback endpoints
`set_globals`	boolean	`false`	Registers the provider as the global default
`verbose`	boolean	`false`	Enables debug logging
`ca_file`	string	`""`	Path to a PEM-encoded CA bundle
`cert_file`	string	`""`	Path to a PEM-encoded client certificate
`key_file`	string	`""`	Path to a PEM-encoded client key
`headers`	map	none	Outbound request headers
`sample_ratio`	number	`0`	Trace sampling probability in [0,1]
`attr_value_limit`	integer	`0`	Caps string attribute values; 0 selects the default

OBSERVABILITY__DEFAULT__ADAPTER=otlp
OBSERVABILITY__DEFAULT__ENDPOINT=collector:4317
OBSERVABILITY__DEFAULT__SERVICE_NAME=my-app
OBSERVABILITY__DEFAULT__SAMPLE_RATIO=0.1

`outbox`

Transactional outbox and inbox with a polling relay, or postgres logical-replication capture (cdc).


Adapters	`memory`, `db`, `cdc`
Default adapter	`db`
Accessor	`c.Outbox()`
Guide	Outbox guide

Key	Type	Default	Description
`dsn`	string	`""`	Postgres connection string or sqlite path for the db adapter
`table`	string	`outbox`	Outbox table name
`inbox_table`	string	`inbox`	Inbox table name
`publisher`	string	`""`	Records which transport the relay publishes through: “eventbus”, “queue”, or “” (unset)
`poll_interval`	duration	`1s`	Relay poll cadence
`batch_size`	integer	`100`	Caps how many messages one poll claims
`max_attempts`	integer	`5`	Publish attempt cap
`retention`	duration	`168h`	How long processed messages are kept
`lock_seconds`	integer	`30`	Claim lease in seconds
`notify_channel`	string	`""`	Postgres LISTEN/NOTIFY channel (cdc adapter)
`prefix`	string	`zever_outbox`	Logical-replication message prefix (cdc adapter)
`slot`	string	`zever_outbox_slot`	Logical-replication slot name (cdc adapter)
`publication`	string	`zever_outbox_pub`	Logical-replication publication name (cdc adapter)
`dedicated_pool`	boolean	`false`	Opts out of container-level pool sharing
`retry`	object		Backoff policy. Keys are listed in Retry policy.

OUTBOX__DEFAULT__ADAPTER=db
OUTBOX__DEFAULT__DSN=postgres://app:secret@db:5432/app
OUTBOX__DEFAULT__POLL_INTERVAL=1s
OUTBOX__DEFAULT__PUBLISHER=eventbus

`password`

Argon2id password hashing. All five parameters are range-validated.


Adapters	`argon2id`
Default adapter	`argon2id`
Accessor	`c.Password()`
Guide	Password hashing guide

Key	Type	Default	Description
`time`	integer	`3`	Argon2id iteration count in the range 1-10
`memory`	integer	`65536`	Argon2id memory cost in KiB in the range 8192-1048576
`threads`	integer	`4`	Argon2id parallelism degree in the range 1-16
`salt_length`	integer	`16`	Salt length in bytes in the range 8-64
`key_length`	integer	`32`	Derived key length in bytes in the range 16-128

PASSWORD__DEFAULT__ADAPTER=argon2id
PASSWORD__DEFAULT__TIME=3
PASSWORD__DEFAULT__MEMORY=65536
PASSWORD__DEFAULT__THREADS=4
PASSWORD__DEFAULT__SALT_LENGTH=16
PASSWORD__DEFAULT__KEY_LENGTH=32

`payment`

Payment intents and webhooks. The stub adapter performs no webhook verification and holds no funds.


Adapters	`stub`, `stripe`, `paddle`
Default adapter	`stub`
Accessor	`c.Payment()`
Guide	Payment guide

Key	Type	Default	Description
`secret_key`	string	`""`	Provider secret key (Stripe). Never logged
`api_key`	string	`""`	Provider API key (Paddle). Never logged
`endpoint`	string	`""`	Optional custom provider endpoint URL
`sandbox`	boolean	`false`	Selects the provider sandbox environment
`webhook_secret`	string	`""`	Webhook verification secret. Never logged
`auto_approve`	boolean	`false`	Marks new payments as succeeded instead of pending
`max_webhook_bytes`	integer	`1 MiB`	Bounds the webhook payload size

The refund idempotency store (Idempotency) is injected from Go and is not a file option.

PAYMENT__DEFAULT__ADAPTER=stripe
PAYMENT__DEFAULT__SECRET_KEY=sk_live_...
PAYMENT__DEFAULT__WEBHOOK_SECRET=whsec_...

`permission`

Authorization checks from inline rules, RBAC roles, or Casbin files.


Adapters	`noop`, `rbac`, `casbin`
Default adapter	`noop`
Accessor	`c.Permission()`
Guide	Permissions guide

Key	Type	Default	Description
`model_path`	string	`""`	Path to the Casbin model file
`policy_path`	string	`""`	Path to the Casbin policy file
`roles`	map of lists	none	Subject-ID to allowed-roles allowlist gating privilege escalation: a subject may only be granted a role (asserted via Subject.Roles at check time) that appears in its list here
`rules`	list of objects	`[]`	Authorization rules. See below.

rules entries use the exported Go field names verbatim (capitalized), unlike every other key.

Key	Type	Default	Description
`Role`	string	`""`	Role the rule applies to.
`Action`	string	`""`	Action the rule applies to.
`Effect`	string	`allow`	`allow` or `deny`. Empty means `allow`.
`OwnedOnly`	boolean	`false`	Restrict the rule to resources owned by the subject.
`OwnedAttr`	string	`""`	Resource attribute carrying the owner ID. Required when `OwnedOnly` is true.

PERMISSION__DEFAULT__ADAPTER=rbac
PERMISSION__DEFAULT__ROLES_-_ROLE=admin
PERMISSION__DEFAULT__ROLES_ACTION=*
PERMISSION__DEFAULT__ROLES_EFFECT=allow

`queue`

Message queue with visibility timeouts.


Adapters	`memory`, `redis`, `db`
Default adapter	`memory`
Accessor	`c.Queue()`
Guide	Queue guide

Key	Type	Default	Description
`visibility_timeout`	duration	`30s`	Duration a popped message remains invisible before reclaim
`poll_timeout`	duration	`5s`	Duration Pop waits for a message before returning empty
`buffer`	integer	`10000` (memory)	Maximum number of buffered ready messages per topic
`url`	string	`""`	Redis connection URL
`prefix`	string	`""`	Key prefix for Redis queue data
`dsn`	string	`""`	Postgres connection string or sqlite path
`table`	string	`""`	Queue-messages table name
`dedicated_pool`	boolean	`false`	Opts out of container-level pool sharing

Redis connection keys, documented in Redis connection options: addr, password, db, tls, require_tls.

QUEUE__DEFAULT__ADAPTER=redis
QUEUE__DEFAULT__ADDR=localhost:6379
QUEUE__DEFAULT__VISIBILITY_TIMEOUT=30s

`ratelimit`

Token-bucket rate limiting. rate and burst are required.


Adapters	`memory`, `redis`
Default adapter	`memory`
Accessor	`c.RateLimit()`
Guide	Ratelimit guide

Key	Type	Default	Description
`rate`	number	`10 (config default)`	Token refill rate per second
`burst`	integer	`20 (config default)`	Maximum bucket size
`idle_ttl`	duration	`10m`	Idle entry TTL
`sweep_interval`	duration	`1m`	Idle-entry sweep interval
`max_entries`	integer	`1000`	Bounds the number of stored buckets in the memory adapter before least-recently-used eviction
`redis.url`	string	`""`	Reserved and currently ignored
`redis.prefix`	string	`""`	Key prefix for Redis ratelimit data

RATELIMIT__DEFAULT__ADAPTER=memory
RATELIMIT__DEFAULT__RATE=100
RATELIMIT__DEFAULT__BURST=200

`resilience`

Retry, timeout, circuit breaker, and bulkhead policies.


Adapters	`memory`, `redis`
Default adapter	`memory`
Accessor	`c.Resilience()`
Guide	Resilience guide

Key	Type	Default	Description
`name`	string	`""`	Base name applied to the breaker
`timeout`	duration	`5s`	Bounds the whole operation, including retries
`breaker.enabled`	boolean	`false`	Turns the circuit breaker on
`breaker.max_requests`	integer	`1`	Number of probes allowed while half-open
`breaker.interval`	duration	`30s`	Closed-state window before counts reset
`breaker.bucket_period`	duration	`10s`	Rolling-window bucket width; Interval becomes a multiple of it
`breaker.timeout`	duration	`30s`	Open-state duration before the breaker half-opens
`breaker.min_requests`	integer	`10`	Minimum request count before the failure ratio applies
`breaker.failure_ratio`	number	`0.5`	Failure ratio in [0,1] that trips the breaker
`breaker.consecutive_failures`	integer	`5`	Trips the breaker after this many consecutive failures
`bulkhead.max_concurrent`	integer	`100`	Number of concurrent executions admitted
`bulkhead.max_queue`	integer	`100`	Bounds the number of waiters; 0 or less is unbounded
`bulkhead.max_wait`	duration	`1s`	Bounds how long a caller waits for a slot; 0 or less waits indefinitely
`redis.url`	string	`""`	Reserved and currently ignored
`redis.prefix`	string	`resilience`	Key namespace for Redis resilience data
`retry`	object		Backoff policy. Keys are listed in Retry policy.

RESILIENCE__DEFAULT__ADAPTER=memory
RESILIENCE__DEFAULT__TIMEOUT=5s
RESILIENCE__DEFAULT__BREAKER_ENABLED=true
RESILIENCE__DEFAULT__BREAKER_CONSECUTIVE_FAILURES=5

`router`

HTTP router adapter.


Adapters	`fiber`, `stdhttp`
Default adapter	`stdhttp`
Accessor	`c.Router()`
Guide	Routing guide

Key	Type	Default	Description
`app_name`	string	`app`	Application name used by adapters, defaulting to “app” when empty

ROUTER__DEFAULT__ADAPTER=fiber
ROUTER__DEFAULT__APP_NAME=my-app

`scheduler`

Cron-style scheduler. It resolves the job dispatcher, so it shares the process-wide queue.


Adapters	`embedded`, `postgres`
Default adapter	`embedded`
Accessor	`c.Scheduler()`
Guide	Scheduler and jobs guide

Key	Type	Default	Description
`close_timeout`	duration	`5s`	Bounds Stop’s wait for running ticks
`dsn`	string	`""`	Postgres connection string or sqlite path for the postgres adapter
`dedicated_pool`	boolean	`false`	Opts out of container-level pool sharing

scheduler.Options.Dispatcher is required and is injected in code, so a file options block replaces it with nil and Load fails with dispatcher_is_required. Leave options out of the file and set close_timeout, dsn, and dedicated_pool with env instead: SCHEDULER__DEFAULT__CLOSETIMEOUT=3s, SCHEDULER__DEFAULT__DSN=....

SCHEDULER__DEFAULT__ADAPTER=postgres

`search`

Full-text search. db is the canonical name; postgres and sqlite stay as aliases.


Adapters	`db`, `postgres`, `meilisearch`, `sqlite`
Default adapter	`db`
Accessor	`c.Search()`
Guide	Search guide

Key	Type	Default	Description
`host`	string	`""`	Meilisearch URL required by meilisearch
`api_key`	string	`""`	Backend API key. Never logged
`dsn`	string	`""`	Postgres URL or sqlite path, required by postgres/sqlite
`dedicated_pool`	boolean	`false`	Opts out of container-level pool sharing
`allow_insecure`	boolean	`false`	Permits an http:// Host for testing

SEARCH__DEFAULT__ADAPTER=meilisearch
SEARCH__DEFAULT__HOST=https://search.example.com
SEARCH__DEFAULT__API_KEY=...

`secrets`

Secret lookup from the environment or Vault. prefix is required.


Adapters	`env`, `vault`
Default adapter	`env`
Accessor	`c.Secrets()`
Guide	Secrets guide

Key	Type	Default	Description
`addr`	string	`""`	Vault server address
`allow_insecure`	boolean	`false`	Permit a plain-http Addr for testing (https only by default)
`allow_insecure_token_file_perms`	boolean	`false`	Permit a TokenFile readable beyond its owner (0600 or stricter by default)
`token`	string	`""`	Vault authentication token
`token_file`	string	`""`	Reads the Vault token from a file when Token is empty
`mount`	string	`""`	Vault KV mount path
`namespace`	string	`""`	Vault namespace
`project_id`	string	`""`	GCP project ID
`prefix`	string	`ZEVER (config default)`	Scopes secret names to one namespace
`region`	string	`""`	AWS region

SECRETS__DEFAULT__ADAPTER=vault
SECRETS__DEFAULT__ADDR=https://vault.example.com
SECRETS__DEFAULT__TOKEN_FILE=/run/secrets/vault-token
SECRETS__DEFAULT__MOUNT=secret

`session`

Server-side session store.


Adapters	`memory`, `redis`, `db`
Default adapter	`memory`
Accessor	`c.Session()`
Guide	Sessions guide

Key	Type	Default	Description
`ttl`	duration	`15m`	Default session lifetime
`dsn`	string	`""`	Postgres connection string or sqlite path for the db adapter
`dedicated_pool`	boolean	`false`	Opts out of container-level pool sharing
`redis.url`	string	`""`	Reserved and currently ignored
`redis.prefix`	string	`""`	Key prefix for Redis session data

SESSION__DEFAULT__ADAPTER=redis
SESSION__DEFAULT__TTL=15m
SESSION__DEFAULT__REDIS_ADDR=localhost:6379

`storage`

Object storage with presigned URLs and an optional access policy.


Adapters	`local`, `s3`, `r2`
Default adapter	`local`
Accessor	`c.Storage()`
Guide	Storage guide

Key	Type	Default	Description
`url_base`	string	`""`	Base URL minted presigned URLs build on
`root`	string	`""`	Directory objects are stored under
`secret`	string	`""`	HMAC key for presigned URLs
`public_url`	string	`""`	Public base URL for unsigned links
`access_key_id`	string	`""`	AWS access key
`secret_access_key`	string	`""`	AWS secret key
`region`	string	`us-east-1`	AWS region, defaulting to us-east-1 when empty
`endpoint`	string	`""`	Overrides the S3 endpoint (S3-compatible stores)
`policy_sync`	string	`""`	Manual or auto for bucket-policy sync
`sync_fail`	string	`""`	Warn or require on sync failure
`account_id`	string	`""`	Cloudflare account ID
`policy`	object		Typed access policy. See below.

policy is a flat map: the Default key is the fallback policy for unlisted buckets, and every other key is a bucket name. A nil policy means legacy private mode.

Key	Type	Default	Description
`policy.<bucket>.version`	string	`"0"`	Policy schema version.
`policy.<bucket>.<op>.public`	boolean	`false`	Allow unsigned access.
`policy.<bucket>.<op>.allow`	list of strings	`[]`	Subjects granted access (`*` matches any authenticated subject, `anonymous` matches unauthenticated callers).
`policy.<bucket>.<op>.deny`	list of strings	`[]`	Subjects refused access. Deny wins over allow.

<op> is one of read (downloads), write (new objects), update (overwrites), or delete.

STORAGE__DEFAULT__ADAPTER=s3
STORAGE__DEFAULT__REGION=us-east-1
STORAGE__DEFAULT__ACCESS_KEY_ID=AKIA...
STORAGE__DEFAULT__SECRET_ACCESS_KEY=...

`tenant`

Tenant resolution from a fixed ID, a header, or a subdomain.


Adapters	`single`, `header`
Default adapter	`single`
Accessor	`c.Tenant()`
Guide	Tenants guide

Key	Type	Default	Description
`header`	string	`X-Tenant-ID`	Header name carrying the tenant ID
`subdomain_regex`	string	`""`	Optional subdomain matching pattern
`id`	string	`default`	Fixed tenant ID for the single-tenant backend

TENANT__DEFAULT__ADAPTER=header
TENANT__DEFAULT__HEADER=X-Tenant-ID

`vectorstore`

Embedding storage and similarity search. db is canonical; sqlite and pgvector stay as aliases.


Adapters	`db`, `sqlite`, `pgvector`, `qdrant`
Default adapter	`db`
Accessor	`c.VectorStore()`
Guide	Vectorstore guide

Key	Type	Default	Description
`dsn`	string	`""`	Sqlite path or postgres URL
`dedicated_pool`	boolean	`false`	Opts out of container-level pool sharing
`url`	string	`""`	Qdrant address
`api_key`	string	`""`	Backend credential. Never logged
`dimension`	integer	`1536`	Expected embedding dimension
`allow_insecure`	boolean	`false`	Permits an http:// URL for testing

VECTORSTORE__DEFAULT__ADAPTER=qdrant
VECTORSTORE__DEFAULT__URL=https://qdrant.example.com
VECTORSTORE__DEFAULT__API_KEY=...
VECTORSTORE__DEFAULT__DIMENSION=1536

`webhook`

Signed webhook delivery with retries, directly over HTTP or through the queue.


Adapters	`http`, `queue`
Default adapter	`http`
Accessor	`c.Webhook()`
Guide	Webhooks guide

Key	Type	Default	Description
`timeout`	duration	`10s`	Per-delivery operation timeout
`max_retries`	integer	`0`	Number of delivery retries after the initial attempt
`allow_private_targets`	boolean	`false`	Permits http(s) targets resolving to private addresses
`queue_adapter`	string	`""`	Names the queue adapter backing the queue adapter
`dead_letter_topic`	string	`""`	Queue topic for deliveries that exhaust retries
`replay_tolerance`	duration	`5m`	Bounds how far a signature’s embedded timestamp may drift from the verifier’s clock before verification rejects it as expired or replayed, on top of the HMAC check itself
`queue_opts`	object		Queue settings for the `queue` adapter. See below.

queue_opts carries the queue settings for the queue adapter. It accepts every queue option (visibility_timeout, poll_timeout, buffer, addr, url, prefix, dsn, table, dedicated_pool, and the Redis connection keys) under the queue_opts. prefix.

Logger is injected from Go and is not a file option.

WEBHOOK__DEFAULT__ADAPTER=http
WEBHOOK__DEFAULT__TIMEOUT=10s
WEBHOOK__DEFAULT__MAX_RETRIES=5

`workflow`

Durable workflow runs. An empty DSN selects sqlite, a postgres URL selects postgres.


Adapters	`memory`, `db`, `postgres`
Default adapter	`memory`
Accessor	`c.Workflow()`
Guide	Workflows guide

Key	Type	Default	Description
`host_port`	string	`""`	Workflow server address
`namespace`	string	`""`	Workflow namespace
`dsn`	string	`""`	Postgres connection string
`table`	string	`""`	Workflow-runs table name
`dedicated_pool`	boolean	`false`	Opts out of container-level pool sharing

WORKFLOW__DEFAULT__ADAPTER=db
WORKFLOW__DEFAULT__DSN=postgres://app:secret@db:5432/app
WORKFLOW__DEFAULT__TABLE=workflow_runs

Layering and rules

Services at a glance

Shared option groups

Redis connection options

Retry policy

Pool sharing

Service reference

ai

analytics

auth

billing

cache

cdn

crypto

db

document

eventbus

flag

geo

i18n

idempotency

lock

log

mailer

media

notification

observability

outbox

password

payment

permission

queue

ratelimit

resilience

router

scheduler

search

secrets

session

storage

tenant

vectorstore

webhook

workflow