Configure | Ory

On this page

Configure Ory Talos through files passed with --config or -c. Repeat the flag to load multiple files; later files override earlier ones. Override any setting with environment variables (for example, DB_DSN overrides db.dsn). Per-key CLI flags don't exist. See the configuration reference for every key, type, default, environment variable mapping, and the precedence rules.

Hot-reload

Ory Talos watches the config file for changes. Some settings reload automatically; others require a restart.

Hot-reloadable (read per request through the config provider):

• credentials.api_keys.default_ttl / max_ttl
• credentials.api_keys.prefix.current / retired
• credentials.api_keys.prefix.public_current / public_retired
• credentials.derived_tokens.default_ttl
• credentials.derived_tokens.macaroon.prefix.current / retired
• credentials.issuer, credentials.issuer_retired
• credentials.clock_skew
• secrets.hmac.current / retired
• cache.ttl
• serve.http.cors.*
• serve.http.client_ip_source
• serve.http.request_log.exclude_health_endpoints
• rate_limit.enabled (commercial; OSS exposes the metadata field but doesn't enforce it)

Requires restart (the configx immutable list, plus keys marked immutable in the schema):

• db.dsn, tls.key, redis.password (configx-enforced immutables)
• serve.http.host / port
• serve.http.trust_forwarded_host
• serve.metrics.host / port (Commercial only)
• cache.type and connection settings (entire cache.memory.* block; cache.redis.* except pool_size and timeout, which reload without restart)
• multitenancy.enabled / multitenancy.networks (Commercial only — adding tenants requires a restart; Talos hot-reloads per-tenant config files referenced by config_path)
• rate_limit.backend
• last_used.queue_size / flush_size / flush_interval / num_workers
• log.level / format
• tracing.* (Commercial only)

Duration syntax

All duration values (TTLs, timeouts, and intervals) are Go duration strings. Combine one or more unsigned numbers with a unit, with no spaces. Supported units:

Examples: 500ms, 30s, 5m, 1h30m, and 8760h (one year). Talos has no unit for days, weeks, months, or years. Express those in hours: 24h (one day), 168h (one week), 8760h (one year).

Minimal configuration

credentials:

issuer: "https://api.example.com"

secrets:

hmac:

current: "change-me-to-a-32-or-more-character-hmac-secret"

db:

dsn: "sqlite://./data/talos.db"

Schema validation rejects any secrets.hmac.current or secrets.hmac.retired[] value shorter than 32 characters (minLength: 32). Generate one with:

openssl rand -base64 48 | tr -d '\n+/=' | cut -c1-64

Production configuration

The serve.metrics.*, cache.*, rate_limit.*, and tracing.* blocks take effect only in commercial builds (-tags commercial). The OSS edition serves health endpoints on the metrics listener but not Prometheus metrics.

serve:

http:

host: "0.0.0.0"

port: 4420

cors:

enabled: true

allowed_origins: ["https://app.example.com"]

request_log:

exclude_health_endpoints: true

metrics: # Commercial only

host: "0.0.0.0"

port: 4422

credentials:

issuer: "https://api.example.com"

api_keys:

default_ttl: "2160h" # 90 days

max_ttl: "8760h" # 1 year

prefix:

current: "talos"

derived_tokens:

default_ttl: "1h" # Applies to both JWT and macaroon tokens

jwt:

signing_key_id: "" # Optional JWK kid hint; defaults to the first key with use="sig"

signing_keys:

# Talos accepts only base64:// JWKS literals; file://, https://, and http:// schemes are

# rejected by schema validation. To produce the value below, run:

#   base64 < /etc/talos/jwks.json | tr -d '\n'

urls:

- "base64://eyJrZXlzIjpbXX0="

db:

# postgres/cockroach use pgxpool query parameters: pool_max_conns, pool_min_conns,
  # pool_max_conn_lifetime, pool_max_conn_idle_time.

dsn: "postgres://talos:secret@db:5432/talos?pool_max_conns=25&pool_max_conn_lifetime=5m"

cache: # Commercial only

type: "redis"

ttl: "5m"

redis:

addrs: ["redis:6379"]

password: "secret"

pool_size: 100

timeout: "3s"

rate_limit: # Commercial only — OSS exposes the field but does not enforce it

enabled: true

backend: redis # "memory" for single-pod, "redis" for multi-pod

secrets:

# secrets.hmac.current and every secrets.hmac.retired[] entry must be at least
  # 32 characters (schema minLength: 32). Use 64 random characters for new
  # deployments.

hmac:

current: "change-me-64-chars-of-base64ish-randomness-do-not-reuse-elsewhere"

log:

level: "info"

format: "json"

tracing: # Commercial only

enabled: true

service_name: "talos"

exporter: "otlp"

endpoint: "otel-collector:4317"

sample_rate: 0.01