Configuration Reference

edged requires --config <path>. Load() accepts YAML or TOML.

Load pipeline:

  1. Parse file (.toml uses TOML decoder; other extensions use YAML decoder).

  2. Apply EDGE_* environment overrides (ApplyEnv).

  3. Run structural validation (Validate).

  4. Runtime startup checks are separate (StartupValidate).

Top-Level Keys

Key

Required

Purpose

schema

yes

must be v1

identity

yes

domain id and fleet salt

storage

yes

local store root and disk envelope

assurance

yes

high/baseline assurance mode

transport

yes

mTLS listener and cert/CA/CRL files

quota

yes

per-peer ingest quota

retry

yes

retry bounds and window

scheduler

yes

deterministic scheduling knobs

eviction

yes

eviction policy and retention window

metrics

yes

log format/level and metrics endpoint

state_root

optional

persistent state root for OS-survival/relay ledger

relay

optional

outbound relay worker settings

known_peers

optional

static relay peer endpoints

Canonical State Root Layout

When state_root.root is configured, layout is defined by edge/stateroot:

{root}/edge/segments/
{root}/edge/relay/
{root}/identity/
{root}/runtime/
{root}/runtime/binaries/
{root}/epoch/
{root}/bootstrap/

Relay-Specific Keys

relay section:

  • success_condition: one_peer or all_peers

  • evict_on_relay: boolean flag passed to executor

  • worker_count: integer > 0

  • dial_timeout_seconds: integer > 0

  • ack_timeout_seconds: integer > 0

known_peers.peers[]:

  • peer_id non-empty, no whitespace

  • addr in host:port form

Example (YAML)

schema: v1
identity:
  edge_domain_id: edge-prod-a
  fleet_salt: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
storage:
  local_root: /var/lib/edge/segments
  disk_ceiling_bytes: 10737418240
  eviction_threshold_fraction: 0.85
assurance:
  mode: high
  memory_ceiling_bytes: 536870912
transport:
  listen_addr: ":7300"
  cert_file: /etc/edge/tls/node.crt
  key_file: /etc/edge/tls/node.key
  ca_file: /etc/edge/tls/ca.crt
  handshake_timeout_seconds: 10
  max_connections_per_peer: 4
  connection_rate_limit_per_minute: 120
quota:
  max_active_peers: 256
  ingest_bytes_per_peer_per_window: 104857600
  ingest_segments_per_peer_per_window: 1000
  window_seconds: 60
retry:
  max_retry_count: 5
  backoff_base_seconds: 10
  window_seconds: 120
scheduler:
  max_concurrent_relays: 8
  schedule_interval_seconds: 5
  max_segments_per_scheduling_round: 32
  tie_break_comparator: lex_segment_id
eviction:
  policy: lru_priority
  max_eviction_batch_size: 64
  retention_window_seconds: 3600
metrics:
  prometheus_addr: ":9300"
  log_level: info
  log_format: json
state_root:
  root: /var/lib/edge-state
relay:
  success_condition: one_peer
  evict_on_relay: false
  worker_count: 2
  dial_timeout_seconds: 5
  ack_timeout_seconds: 5
known_peers:
  peers:
    - peer_id: peer-a
      addr: 10.0.1.10:7300

Example (TOML)

schema = "v1"

[identity]
edge_domain_id = "edge-prod-a"
fleet_salt = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"

[storage]
local_root = "/var/lib/edge/segments"
disk_ceiling_bytes = 10737418240
eviction_threshold_fraction = 0.85

[assurance]
mode = "high"
memory_ceiling_bytes = 536870912

[transport]
listen_addr = ":7300"
cert_file = "/etc/edge/tls/node.crt"
key_file = "/etc/edge/tls/node.key"
ca_file = "/etc/edge/tls/ca.crt"
handshake_timeout_seconds = 10
max_connections_per_peer = 4
connection_rate_limit_per_minute = 120

[quota]
max_active_peers = 256
ingest_bytes_per_peer_per_window = 104857600
ingest_segments_per_peer_per_window = 1000
window_seconds = 60

[retry]
max_retry_count = 5
backoff_base_seconds = 10
window_seconds = 120

[scheduler]
max_concurrent_relays = 8
schedule_interval_seconds = 5
max_segments_per_scheduling_round = 32
tie_break_comparator = "lex_segment_id"

[eviction]
policy = "lru_priority"
max_eviction_batch_size = 64
retention_window_seconds = 3600

[metrics]
prometheus_addr = ":9300"
log_level = "info"
log_format = "json"

[state_root]
root = "/var/lib/edge-state"

[relay]
success_condition = "one_peer"
evict_on_relay = false
worker_count = 2
dial_timeout_seconds = 5
ack_timeout_seconds = 5

[[known_peers.peers]]
peer_id = "peer-a"
addr = "10.0.1.10:7300"

Notes on Defaults

If a value has no explicit default assignment in code, it is operator-defined. Validation enforces ranges/enums but does not auto-populate missing required fields.

Evidence

Code:

  • edge/config/config.go

  • edge/config/validate.go

  • edge/config/startup.go

  • edge/stateroot/stateroot.go

Examples/tests:

  • edge/edge.example.yaml

  • edge/edge.example.toml

  • edge/config/testdata/valid_full.yaml

  • edge/config/testdata/valid_full.toml

  • edge/config/config_test.go

Verification commands:

GOWORK=off go run ./edge/cmd/edged validate --config ./edge/config/testdata/valid_full.yaml
GOWORK=off go run ./edge/cmd/edged validate --config ./edge/config/testdata/valid_full.toml

See Also