Skip to content

configuration.md

Latest commit

 

History

History
214 lines (211 loc) · 8.3 KB

configuration.md

File metadata and controls

214 lines (211 loc) · 8.3 KB

Configuration

All configuration is via environment variables.

Variables

  • CONSENSUS_HOST
    • Default: 127.0.0.1
    • Bind address for the server.
  • CONSENSUS_ALLOW_REMOTE
    • Default: disabled
    • Set to 1 to allow binding to non-loopback hosts. Requires CONSENSUS_API_TOKEN.
  • CONSENSUS_API_TOKEN
    • Default: unset
    • If set, all API and WebSocket clients must send Authorization: Bearer <token> or ?token=<token>.
  • CONSENSUS_PORT
    • Default: 8787
    • Port for the HTTP server.
  • CONSENSUS_UI_PORT
    • Default: 5173
    • Port for the Vite dev server when running npm run dev.
  • CONSENSUS_POLL_MS
    • Default: 250
    • Poll interval for process presence scans.
  • CONSENSUS_SCAN_TIMEOUT_MS
    • Default: 5000
    • Max time (ms) for a scan tick before timing out (guardrail for stuck scans).
  • CONSENSUS_SCAN_STALL_MS
    • Default: 60% of CONSENSUS_SCAN_TIMEOUT_MS (min 250)
    • Emit a stall warning/metric when a scan exceeds this duration.
  • CONSENSUS_SCAN_STALL_CHECK_MS
    • Default: min(1000, CONSENSUS_SCAN_STALL_MS) (min 250)
    • Interval for checking whether a scan is stalling.
  • CONSENSUS_OTEL_ENABLED
    • Default: disabled
    • Set to 1 to enable Effect OpenTelemetry tracing/metrics (dev-only rollout).
  • CONSENSUS_OTEL_ENDPOINT
    • Default: unset
    • OTLP/HTTP base endpoint (e.g., http://localhost:4318). When unset, exporters fall back to console.
  • CONSENSUS_OTEL_SERVICE_NAME
    • Default: consensus-cli
    • Service name for telemetry resource.
  • CONSENSUS_OTEL_ENV
    • Default: development
    • Deployment environment.
  • CONSENSUS_OTEL_VERSION
    • Default: package version (or unknown).
    • Service version for telemetry resource.
  • CONSENSUS_OTEL_SAMPLE_RATIO
    • Default: 1
    • Trace sampling ratio (0–1). Prod can lower to 0.1 later.
  • CONSENSUS_OTEL_METRIC_INTERVAL_MS
    • Default: 10000
    • Metric export interval in milliseconds.
  • CONSENSUS_OTEL_CONSOLE_FALLBACK
    • Default: enabled
    • Set to 0 to disable console exporters when OTLP endpoint is unset.
  • CONSENSUS_CODEX_HOME
    • Default: ~/.codex
    • Override Codex home directory.
  • CONSENSUS_CODEX_NOTIFY_INSTALL
    • Optional. If set, consensus will run codex config set -g notify=["<path>"] on startup.
    • Intended for wiring Codex TUI notify hook to consensus without manual setup.
    • Use CONSENSUS_CODEX_NOTIFY_INSTALL_TIMEOUT_MS to cap install time (default 5000).
    • Set to 0, false, or off to disable the auto-install.
  • CONSENSUS_CODEX_WATCH_POLL
    • Default: enabled
    • Set to 0 to disable polling for Codex JSONL watch events. Polling is the default because native FS events are unreliable for these files.
  • CONSENSUS_CODEX_WATCH_INTERVAL_MS
    • Default: 1000
    • Polling interval (ms) for Codex JSONL watcher when polling is enabled.
  • CONSENSUS_CODEX_WATCH_BINARY_INTERVAL_MS
    • Default: CONSENSUS_CODEX_WATCH_INTERVAL_MS
    • Polling interval (ms) for binary file changes when polling is enabled.
  • CONSENSUS_OPENCODE_HOST
    • Default: 127.0.0.1
    • OpenCode server host.
  • CONSENSUS_OPENCODE_PORT
    • Default: 4096
    • OpenCode server port.
  • CONSENSUS_OPENCODE_TIMEOUT_MS
    • Default: 5000
    • Timeout for OpenCode HTTP requests.
  • CONSENSUS_OPENCODE_AUTOSTART
    • Default: enabled
    • Set to 0 to disable OpenCode server autostart.
  • CONSENSUS_OPENCODE_EVENTS
    • Default: enabled
    • Set to 0 to disable OpenCode event stream.
  • CONSENSUS_OPENCODE_HOME
    • Default: ~/.local/share/opencode
    • Override OpenCode storage directory.
  • CONSENSUS_OPENCODE_EVENT_ACTIVE_MS
    • Default: 0
    • OpenCode event window before dropping to idle.
  • CONSENSUS_OPENCODE_ACTIVE_HOLD_MS
    • Default: 3000
    • OpenCode hold window after activity.
  • CONSENSUS_OPENCODE_INFLIGHT_IDLE_MS
    • Default: CONSENSUS_OPENCODE_INFLIGHT_TIMEOUT_MS
    • OpenCode in-flight idle timeout in ms before dropping to idle if no activity is observed.
  • CONSENSUS_OPENCODE_INFLIGHT_TIMEOUT_MS
    • Default: 15000
    • Hard timeout (ms) used to clear OpenCode in-flight when no fresh events are observed.
  • CONSENSUS_PROCESS_MATCH
    • Default: unset
    • Regex to match process name or command line.
  • CONSENSUS_DEBUG_OPENCODE
    • Default: unset
    • Set to 1 to log OpenCode server discovery (debug only).
  • CONSENSUS_REDACT_PII
    • Default: enabled
    • Set to 0 to disable redaction.
  • CONSENSUS_REDACT_STRICT
    • Default: disabled
    • Set to 1 to enable strict secret/token redaction patterns.
  • CONSENSUS_RATE_LIMIT_WINDOW_MS
    • Default: 10000
    • Sliding window size for API rate limiting (ms).
  • CONSENSUS_RATE_LIMIT_MAX
    • Default: 120
    • Max requests per window per IP+route before 429.
  • ACTIVITY_TEST_MODE
    • Default: disabled
    • Set to 1 to enable test-only activity injection endpoints under /__test.
  • CONSENSUS_CODEX_EVENT_ACTIVE_MS
    • Default: 30000
    • Codex event window before dropping to idle.
  • CONSENSUS_CODEX_MTIME_ACTIVE_MS
    • Default: 750
    • Treat recent Codex JSONL file mtime as activity within this window (bridges log write lag).
  • CONSENSUS_CODEX_ACTIVE_HOLD_MS
    • Default: 3000
    • Codex hold window after activity.
  • CONSENSUS_CODEX_INFLIGHT_GRACE_MS
    • Default: 750
    • Codex in-flight grace window after the last in-flight signal (prevents brief idle flicker).
  • CONSENSUS_CODEX_STRICT_INFLIGHT
    • Default: disabled
    • Set to 1 to require explicit in-flight signals from logs (disables CPU/mtime bridging).
  • CONSENSUS_CODEX_INFLIGHT_IDLE_MS
    • Default: 30000
    • Idle timeout to clear Codex in-flight when activity is stale. Set to 0 to disable.
  • CONSENSUS_CODEX_INFLIGHT_TIMEOUT_MS
    • Default: 3000
    • Hard timeout to clear Codex in-flight if no recent signals and file is not fresh.
  • CONSENSUS_CODEX_FILE_FRESH_MS
    • Default: 10000
    • Treat recent Codex JSONL file mtime within this window as fresh and keep in-flight on.
  • CONSENSUS_CODEX_CPU_SUSTAIN_MS
    • Default: 500
    • Require sustained Codex CPU activity (ms) before marking active when logs are missing.
  • CONSENSUS_CODEX_CPU_SPIKE
    • Default: derived (max(cpuThreshold * 10, 25))
    • Codex CPU spike threshold for immediate active state when logs are missing.
  • CONSENSUS_CODEX_STALE_FILE_MS
    • Default: 120000
    • Treat Codex JSONL files older than this as stale to prevent stale sessions from staying active.
  • CONSENSUS_CODEX_SIGNAL_MAX_AGE_MS
    • Default: CONSENSUS_CODEX_INFLIGHT_TIMEOUT_MS
    • Ignore Codex events older than this when setting in-flight signals (prevents stale sessions after restart).
  • CONSENSUS_PROCESS_CACHE_MS
    • Default: 1000
    • Process cache TTL (ms) for full scans.
  • CONSENSUS_PROCESS_CACHE_FAST_MS
    • Default: 500
    • Process cache TTL (ms) for fast scans.
  • CONSENSUS_SESSION_CACHE_MS
    • Default: 1000
    • Codex session list cache TTL (ms) for full scans.
  • CONSENSUS_SESSION_CACHE_FAST_MS
    • Default: 500
    • Codex session list cache TTL (ms) for fast scans.
  • CONSENSUS_EVENT_ACTIVE_MS
    • Default: 300000
    • Window after the last event to mark an agent active.
  • Claude activity is hook-driven; CPU thresholds are legacy and ignored for TUI activity.
  • CONSENSUS_CPU_ACTIVE
    • Default: 1
    • CPU threshold for marking an agent active.
  • CONSENSUS_CLAUDE_CPU_ACTIVE
    • Default: 1
    • Claude CPU threshold override.
  • CONSENSUS_CLAUDE_CPU_SUSTAIN_MS
    • Default: 1000
    • Claude sustained CPU window in ms.
  • CONSENSUS_CLAUDE_CPU_SPIKE
    • Default: derived
    • Claude spike threshold override.
  • CONSENSUS_CLAUDE_EVENT_TTL_MS
    • Default: 1800000
    • Claude hook event TTL before a session is pruned.
  • CONSENSUS_CLAUDE_INFLIGHT_TIMEOUT_MS
    • Default: 15000
    • Clear Claude in-flight if no hook activity arrives within this window.
  • CONSENSUS_CLAUDE_ACTIVE_HOLD_MS
    • Default: 3000
    • Claude-specific active hold window to smooth brief hook gaps (reduce flicker).
  • CONSENSUS_CLAUDE_START_ACTIVE_MS
    • Default: 1200
    • Legacy (not used for hook-driven Claude activity).
  • CONSENSUS_ACTIVE_HOLD_MS
    • Default: 3000
    • Keep agents active for this long after activity.
  • CONSENSUS_IDLE_HOLD_MS
    • Default: 200
    • Hold an agent in idle briefly after spans end (prevents idle flicker).
  • CONSENSUS_SPAN_STALE_MS
    • Default: 15000
    • Consider agent spans stale after this duration with no progress updates.

Example

CONSENSUS_PORT=8790 CONSENSUS_POLL_MS=250 npm run dev