Configuration Reference

Wippy is configured via .wippy.yaml files. All options have sensible defaults.

Any value below can be overridden at launch with wippy run --set section.path=value (repeatable, takes precedence over the file). To override individual registry entries rather than these config sections, use the override: section or -o — see Overriding Entries.

Config Composition

--config is repeatable; files compose left to right using the same schema:

wippy run --config .wippy.yaml --config .wippy.local.yaml

• Later files override matching values and keep everything else.
• Every explicitly named file must exist. Without --config, the default .wippy.yaml is optional.
• The first file anchors the directory used to resolve relative paths.
• Filenames carry no reserved meaning; nothing besides the default is auto-discovered.

Configuration applies in order: file composition, then --profile selections, then --set overrides. For applications run from packs, packed runtime defaults sit below all of these (see Publishing Runtime Defaults).

Profiles

A config file may declare named overlays under profiles:. Each profile body mirrors the normal config sections; selecting it with --profile <name> overlays those values on the merged base config:

version: "1.0"

vars:
  port: 8085

override:
  app:db:kind: db.sql.sqlite

disable:
  namespaces: ["legacy.**"]

profiles:
  pg:
    vars:
      port: 18085
    override:
      app:db:kind: db.sql.postgres
    disable:
      namespaces.add: ["experimental.**"]

wippy run --profile pg

• --profile is repeatable; profiles compose left to right, after file composition and before --set. An unknown name is an error.
• Values merge per leaf (last writer wins). The profiles: section itself is stripped from the resolved config.
• The disable section supports list operations inside profiles — namespaces.add, namespaces.remove, entries.add, entries.remove — so a profile can adjust the base list instead of replacing it.
• ${name} references interpolate from the merged vars: section. OS environment references are not allowed inside profile vars; use ${env:NAME} in the base config, resolved at file load.

wippy run, test, and pack accept --profile; install, update, lint, and registry accept it as well for workspace profiles (together with --set). Applications can ship profiles inside packs — see Publishing Profiles.

Logger

Controls the zap logger encoder. CLI flags (-v, -c, -s) override level/output; the only yaml-driven option is the encoding.

logger:
  encoding: json

Log Manager

Controls runtime log routing. Console output is configured via CLI flags (-v, -c, -s).

logmanager:
  propagate_downstream: true
  stream_to_events: false
  min_level: 0

See: Logger Module

Profiler

Go pprof HTTP server for CPU/memory profiling. Enable with -p flag or config.

profiler:
  enabled: true
  address: "localhost:6060"

Access at http://localhost:6060/debug/pprof/

Security

Global security behavior. Individual policies are defined as security.policy entries.

security:
  strict_mode: true

See: Security System, Security Module

Registry

Entry storage and version history. The registry holds all configuration entries.

registry:
  history_type: sqlite
  history_path: /var/lib/wippy/registry.db

registry:
  history_type: postgres
  history_dsn: ${env:WIPPY_REGISTRY_HISTORY_DSN}
  history_schema: wippy_registry

See: Registry Concept, Registry Module

Relay

Message routing between processes across nodes.

relay:
  node_name: worker-1

See: Process Model

Supervisor

Service lifecycle management. Controls the supervisor's internal control mailbox used to dispatch lifecycle events.

supervisor:
  host:
    buffer_size: 2048
    worker_count: 32

See: Supervision Guide

Lua Runtime

Lua VM caching and expression evaluation.

lua:
  proto_cache_size: 60000
  cache:
    enabled: true
    dir: .cache/lua
  type_system:
    enabled: true

See: Lua Overview

Finder

Registry search caching. Used internally for entry lookups.

finder:
  query_cache_size: 2000

OpenTelemetry

Distributed tracing and metrics export via OTLP.

otel:
  enabled: true
  endpoint: "http://jaeger:4318"
  traces_enabled: true
  process:
    trace_lifecycle: true

Standard OTEL environment variables (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, OTEL_TRACES_SAMPLER_ARG, OTEL_PROPAGATORS, OTEL_SDK_DISABLED) override the matching fields.

See: Observability Guide

Shutdown

Graceful shutdown behavior.

shutdown:
  timeout: 60s

Metrics

Internal metrics collection buffer.

metrics:
  buffer:
    size: 20000
  interceptor:
    enabled: true

See: Metrics Module, Observability Guide

Prometheus

Prometheus metrics endpoint.

prometheus:
  enabled: true
  address: "0.0.0.0:9090"

Exposes /metrics endpoint for Prometheus scraping.

See: Observability Guide

Cluster

Multi-node clustering: gossip membership plus a bounded Raft consensus core. See the Cluster Guide for the architecture and operational model; this section is the config-key reference.

Top-level

Membership (gossip)

SWIM gossip via memberlist. Used for node discovery, failure detection, and metadata dissemination.

The four probe keys inherit memberlist's local-network defaults when unset; raise them for high-latency links (e.g. probe_interval: 2s, probe_timeout: 500ms, suspicion_mult: 5).

Internode (transport)

TCP mesh carrying the relay and Raft traffic between nodes. Raft rides this mesh over internode request/reply; there is no separate Raft port.

advertise_addr/advertise_port publish an additive endpoint in node metadata while the bind endpoint stays advertised unchanged, so mixed-version clusters keep connecting during a rolling upgrade.

Raft (consensus)

Bounded Raft. Raft state is fs-durable by default, stored under raft.data_dir (default ~/.wippy/store); a restarted node still rejoins quorum from peers. store.kv.raft entries replicate through it. Bootstrap is gossip-driven (Consul/Nomad bootstrap_expect style).

Single-node (development) — clustering on, bootstraps itself immediately:

cluster:
  enabled: true
  name: dev
  raft:
    bootstrap_expect: 1

Three-node voting cluster — each node lists the others as seeds and waits for all three before forming quorum:

cluster:
  enabled: true
  name: node-1
  failure_domain: us-east-1a
  membership:
    bind_port: 7946
    join_addrs: "node-2:7946,node-3:7946"
    secret_file: /etc/wippy/cluster.key
  raft:
    bootstrap_expect: 3
    max_voters: 5

Gossip-only client — joins the cluster for naming/messaging but never runs Raft:

cluster:
  enabled: true
  name: edge-7
  membership:
    join_addrs: "node-1:7946,node-2:7946"
  raft:
    role: client

LSP

Language Server Protocol server for editor integrations.

lsp:
  enabled: true
  address: ":7777"
  http_enabled: true

See: LSP Guide

Network Service

Overlay network manager (SOCKS5, I2P, Tailscale drivers).

network_service:
  state_dir: /var/lib/wippy/net
  default_network: app:tailscale

See: Network Overlays

HTTP Dispatcher

Tuning for the shared HTTP client pool used by HTTP-dispatched functions and outbound requests.

dispatcher:
  http:
    timeout: 30s
    max_idle_per_host: 32

Modules

Module registry client used by wippy install/update.

modules:
  registry_url: https://internal-registry.example.com

Extensions

Native Go plugin extensions loaded at boot (Unix only).

extensions:
  enabled: true
  paths:
    - ./extensions/myplugin.so

Environment Variables

See Also

• CLI Reference - Command line options
• Cluster Guide - Clustering architecture and operations
• Entry Kinds - All entry types
• Observability Guide - Logging, metrics, tracing