Agent Configuration

The Noctuary Agent is configured via a YAML file. Pass the path with the -config flag.

noctuary-agent -config /etc/noctuary/agent.yaml

Full configuration reference

# Upstream — where to send ContextEvents
upstream:
  destination: http          # "http" (production) or "stdout" (testing/debugging)
  endpoint: ${NOCTUARY_ENDPOINT}   # e.g. https://api.noctuary.io

# Authentication
auth:
  api_key: ${NOCTUARY_API_KEY}     # noc_ingest_... key from the dashboard

# OTLP/HTTP receiver — where the OTel Collector sends log data
telemetry:
  otlp:
    http_listen: ":4318"     # port to listen on

# Vendor plugins
plugins:
  argocd:
    enabled: true
  kubernetes:
    enabled: true
  postgres:
    enabled: true

# Fingerprint router
fingerprint:
  confidence_threshold: 0.5  # discard signals with confidence below this value

Sections

upstream

Key	Type	Default	Description
destination	string	http	http sends to Noctuary; stdout prints ContextEvents locally (useful for testing)
endpoint	string	—	Base URL of the Noctuary API. Required when destination: http.

auth

Key	Type	Description
api_key	string	Ingest API key (noc_ingest_...). Required when destination: http.

telemetry.otlp

Key	Type	Default	Description
http_listen	string	:4318	Address and port for the OTLP/HTTP receiver

plugins

Each supported vendor has its own section. Set enabled: true to activate.

Plugin	Detects
argocd	ArgoCD sync events, health transitions
kubernetes	Pod restarts, OOMKills, scheduling failures
postgres	Slow queries, deadlocks, connection exhaustion, WAL events

fingerprint

Key	Type	Default	Description
confidence_threshold	float	0.5	Events below this confidence score are discarded before sending. Range: 0.0–1.0

Environment variables

Any ${VAR_NAME} reference in the config is expanded at startup from environment variables. This is the recommended way to inject secrets rather than hardcoding them in the YAML file.

stdout mode (testing)

Run with destination: stdout to see what ContextEvents would be sent without connecting to Noctuary:

upstream:
  destination: stdout

noctuary-agent -config agent.yaml
# 2026/05/31 12:00:00 {"service_name":"payments-api","vendor":"argocd","event_type":"deploy",...}

This is useful for validating that your OTel pipeline is correctly routing log lines to the agent.