Configuration Reference

Wippy reads runtime configuration from .wippy.yaml files.

Use the repeatable wippy run --set section.path=value option to override the configuration fields below at launch. To override individual registry entries rather than configuration 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 this order: composed files, selected --profile overlays, and then --set overrides. For applications run from packs, packed runtime defaults have lower precedence than all three; see Publishing Runtime Defaults.

Profiles

A configuration file may declare named overlays under profiles:. Each profile body mirrors the standard configuration sections. Selecting it with --profile <name> applies those values over the merged base configuration:

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; run list, 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 the level and output; encoding is the only YAML-configured option.

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

See: Logger Module

Profiler

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

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

When enabled with the default address, the profiler is available at http://localhost:6060/debug/pprof/.

Security

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

security:
  strict_mode: false

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

Artifact

Output root for materialized build-time artifacts.

artifact:
  materialization_root: build/wippy

See: Build-time artifacts

Workspace

Local module replacements, keyed by org/module. Values are directories; relative paths resolve against the first --config file's directory, and null disables a replacement inherited from an earlier config layer or profile.

workspace:
  replacements:
    acme/http: ../local-http
    acme/sql: null

Replacements are never written to wippy.lock. See Local Development with Replacements.

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:
  cache:
    enabled: true
    dir: .cache/lua
  type_system:
    enabled: true

See: Lua Overview

Scheduler

Core partitioning for the WASM runtime. When enabled, reserved_cores CPUs are set aside for WASM execution and the rest serve the actor scheduler; an invalid split (for example more reserved cores than available) is logged and ignored.

scheduler:
  wasm_isolation:
    enabled: true
    reserved_cores: 2

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_SDK_DISABLED, OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_INSECURE, OTEL_SERVICE_NAME, OTEL_SERVICE_VERSION, OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG, OTEL_PROPAGATORS) 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, plus /livez.

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.

A gossip secret is required. Set membership.secret_key or membership.secret_file (the file wins if both are given); with neither, the cluster component fails to start. The value is base64-encoded.

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.

Internode identity is mandatory whenever clustering is enabled. identity_key and identity_key_file are mutually exclusive and one of them must be present; the value decodes (standard or raw base64) to either a 32-byte ed25519 seed or a 64-byte ed25519 private key. trusted_peer_keys maps each node name to that node's 32-byte ed25519 public key, and must contain an entry for the local cluster.name whose value matches the local identity — otherwise startup fails. See the Cluster Guide.

TLS requires all three credential paths and TLS 1.2 or later. Unknown settings, invalid values, unreadable or invalid credentials, and credential paths supplied while TLS is disabled fail startup. The ed25519 identity configuration remains required. See Internode TLS for an example.

Raft (consensus)

The bounded Raft core stores durable state under raft.data_dir by default (~/.wippy/store). A restarted node rejoins quorum from its peers. store.kv.raft entries replicate through this core, and gossip coordinates bootstrap using a bootstrap_expect model.

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

cluster:
  enabled: true
  name: dev
  membership:
    secret_key: "d2lwcHktZG9jcy1nb3NzaXAtc2VjcmV0LTMyYnl0ZXM="
  internode:
    identity_key: "d2lwcHktZG9jcy1kZXYtbm9kZS1leGFtcGxlc2VlZCE="
    trusted_peer_keys:
      dev: "rNqImcjOzef28dzvma80mSrCW1px5LBAc5TbaYqAgm0="
  raft:
    bootstrap_expect: 1

Three-node voting cluster — each node lists the others as seeds and waits for all three before forming quorum. Every node carries the same trusted_peer_keys map and its own private key:

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
  internode:
    identity_key_file: /etc/wippy/node-1.key
    trusted_peer_keys:
      node-1: "okmamN3PKkMpPwPBurknHy2Wi3dwp/rz+uTM2fF9aD0="
      node-2: "PWX+oOYrFdtjUxbgmTkXCFI0KEvG++ZM52HOWfDkqP8="
      node-3: "QfP0fgllbj4s95VAztTORhy3bv9mst1l0lwuUNvO/hE="
  raft:
    bootstrap_expect: 3
    max_voters: 5

Gossip-only client — joins the cluster for naming/messaging but never runs Raft. It still needs its own identity and must appear in every node's trusted map:

cluster:
  enabled: true
  name: edge-7
  membership:
    join_addrs: "node-1:7946,node-2:7946"
    secret_file: /etc/wippy/cluster.key
  internode:
    identity_key_file: /etc/wippy/edge-7.key
    trusted_peer_keys:
      node-1: "okmamN3PKkMpPwPBurknHy2Wi3dwp/rz+uTM2fF9aD0="
      node-2: "PWX+oOYrFdtjUxbgmTkXCFI0KEvG++ZM52HOWfDkqP8="
      node-3: "QfP0fgllbj4s95VAztTORhy3bv9mst1l0lwuUNvO/hE="
      edge-7: "7lzP4jBAkC3P+0jq4vtMsC45571BlVXk3mSlOD/Z0SA="
  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 — Entry types and fields
• Observability Guide — Logging, metrics, and tracing