CHORUS/docs/comprehensive/packages/config.md

CHORUS Configuration Package

Package Path: /home/tony/chorus/project-queues/active/CHORUS/pkg/config/

The configuration package provides a comprehensive, environment-based configuration system for CHORUS agents. It supports static configuration, runtime assignment overrides from WHOOSH, role-based configuration, and dynamic reloading via SIGHUP signals.

Table of Contents

1. Overview
2. Configuration Loading
3. Configuration Structures
4. Runtime Configuration
5. Dynamic Assignments
6. Role Definitions
7. Hybrid Configuration
8. Security Configuration
9. Environment Variables Reference
10. Assignment Schema
11. Configuration Validation
12. Usage Examples

Overview

The CHORUS configuration system is designed for containerized deployments where configuration is managed through environment variables. It provides:

• Static Configuration: Base configuration loaded from environment variables
• Runtime Configuration: Dynamic configuration with assignment overrides
• WHOOSH Integration: Fetch task-specific assignments from WHOOSH API
• SIGHUP Reload: Reload configuration without restarting the agent
• Role-Based Access: Predefined roles with authority levels and encryption keys
• Hybrid Mode Support: Phase 2 feature flags for DHT, UCXL, and discovery
• Docker Secrets: Support for reading sensitive values from files

Configuration Loading

Basic Configuration Loading

import "github.com/chorus/pkg/config"

// Load static configuration from environment variables
cfg, err := config.LoadFromEnvironment()
if err != nil {
    log.Fatalf("Failed to load configuration: %v", err)
}

// Validate configuration
if err := cfg.Validate(); err != nil {
    log.Fatalf("Configuration validation failed: %v", err)
}

Runtime Configuration with Assignment Support

// Load runtime configuration (includes base + assignment support)
runtimeCfg, err := config.LoadRuntimeConfig()
if err != nil {
    log.Fatalf("Failed to load runtime configuration: %v", err)
}

// Fetch assignment from WHOOSH
ctx := context.Background()
assignURL := "https://whoosh.chorus.services/api/v1/assignments"
if err := runtimeCfg.LoadAssignment(ctx, assignURL); err != nil {
    log.Printf("No assignment available: %v", err)
}

// Get merged configuration (base + overrides)
effectiveCfg := runtimeCfg.GetConfig()

// Start SIGHUP reload handler
runtimeCfg.StartReloadHandler(ctx, assignURL)

Configuration Structures

Main Configuration Structure

The Config struct represents the complete CHORUS configuration:

type Config struct {
    Agent     AgentConfig       // Agent-specific settings
    Network   NetworkConfig     // Network and API settings
    License   LicenseConfig     // Licensing configuration
    AI        AIConfig          // AI service configuration
    Logging   LoggingConfig     // Logging settings
    V2        V2Config          // DHT and P2P settings
    UCXL      UCXLConfig        // UCXL protocol settings
    Slurp     SlurpConfig       // SLURP integration
    Security  SecurityConfig    // Security settings
    WHOOSHAPI WHOOSHAPIConfig   // WHOOSH API integration
}

Agent Configuration

Defines agent identity, capabilities, and role:

type AgentConfig struct {
    ID                    string   // Unique agent identifier
    Specialization        string   // Agent specialization type
    MaxTasks              int      // Maximum concurrent tasks
    Capabilities          []string // Agent capabilities
    Models                []string // Available AI models
    Role                  string   // Agent role (see Role Definitions)
    Project               string   // Project assignment
    Expertise             []string // Domain expertise areas
    ReportsTo             string   // Reporting hierarchy
    Deliverables          []string // Expected deliverables
    ModelSelectionWebhook string   // Webhook for model selection
    DefaultReasoningModel string   // Default AI model
}

Default Values:

• Specialization: "general_developer"
• MaxTasks: 3
• Capabilities: ["general_development", "task_coordination"]
• Models: ["meta/llama-3.1-8b-instruct"]
• DefaultReasoningModel: "meta/llama-3.1-8b-instruct"

Network Configuration

Defines network ports and binding:

type NetworkConfig struct {
    P2PPort    int    // P2P network port (default: 9000)
    APIPort    int    // API server port (default: 8080)
    HealthPort int    // Health check port (default: 8081)
    BindAddr   string // Bind address (default: "0.0.0.0")
}

License Configuration

Licensing and cluster identification:

type LicenseConfig struct {
    LicenseID        string    // Required: License identifier
    ClusterID        string    // Cluster identifier (default: "default-cluster")
    OrganizationName string    // Organization name
    KachingURL       string    // License validation URL
    IsActive         bool      // License active status
    LastValidated    time.Time // Last validation timestamp
    GracePeriodHours int       // Grace period (default: 72 hours)
    LicenseType      string    // License type
    ExpiresAt        time.Time // Expiration timestamp
    MaxNodes         int       // Maximum nodes allowed
}

Required: LicenseID must be provided via CHORUS_LICENSE_ID or CHORUS_LICENSE_ID_FILE.

AI Configuration

AI service provider settings:

type AIConfig struct {
    Provider  string          // AI provider ("ollama" or "resetdata")
    Ollama    OllamaConfig    // Ollama configuration
    ResetData ResetDataConfig // ResetData configuration
}

type OllamaConfig struct {
    Endpoint string        // Ollama endpoint (default: "http://localhost:11434")
    Timeout  time.Duration // Request timeout (default: 30s)
}

type ResetDataConfig struct {
    BaseURL string        // ResetData API URL
    APIKey  string        // API key (from env or file)
    Model   string        // Model name (default: "meta/llama-3.1-8b-instruct")
    Timeout time.Duration // Request timeout (default: 30s)
}

Default Provider: "resetdata"

Logging Configuration

type LoggingConfig struct {
    Level  string // Log level: "debug", "info", "warn", "error" (default: "info")
    Format string // Log format: "structured" or "text" (default: "structured")
}

DHT Configuration (V2)

type V2Config struct {
    DHT DHTConfig
}

type DHTConfig struct {
    Enabled        bool     // Enable DHT (default: true)
    BootstrapPeers []string // Bootstrap peer multiaddrs
    MDNSEnabled    bool     // Enable mDNS discovery (default: true)
}

UCXL Configuration

UCXL (Universal Content Exchange Layer) protocol settings:

type UCXLConfig struct {
    Enabled    bool             // Enable UCXL (default: true)
    Server     ServerConfig     // Server settings
    Storage    StorageConfig    // Storage settings
    Resolution ResolutionConfig // Resolution settings
}

type ServerConfig struct {
    Enabled  bool   // Enable UCXL server (default: true)
    Port     int    // Server port (default: 8082)
    BasePath string // Base path for server
}

type StorageConfig struct {
    Directory string // Storage directory (default: "/tmp/chorus-ucxi-storage")
}

type ResolutionConfig struct {
    CacheTTL time.Duration // Cache TTL (default: 1 hour)
}

SLURP Configuration

SLURP (Decision tracking system) integration:

type SlurpConfig struct {
    Enabled          bool                        // Enable SLURP (default: false)
    BaseURL          string                      // SLURP API URL
    APIKey           string                      // API key (from env or file)
    Timeout          time.Duration               // Request timeout (default: 15s)
    RetryCount       int                         // Retry count (default: 3)
    RetryDelay       time.Duration               // Retry delay (default: 2s)
    TemporalAnalysis SlurpTemporalAnalysisConfig // Temporal analysis settings
    Performance      SlurpPerformanceConfig      // Performance settings
}

type SlurpTemporalAnalysisConfig struct {
    MaxDecisionHops        int           // Max decision hops (default: 5)
    StalenessCheckInterval time.Duration // Staleness check interval (default: 5m)
    StalenessThreshold     float64       // Staleness threshold (default: 0.2)
}

type SlurpPerformanceConfig struct {
    MaxConcurrentResolutions  int           // Max concurrent resolutions (default: 4)
    MetricsCollectionInterval time.Duration // Metrics interval (default: 1m)
}

WHOOSH API Configuration

type WHOOSHAPIConfig struct {
    URL     string // WHOOSH API URL (default: "http://localhost:3000")
    BaseURL string // Base URL (default: "http://localhost:3000")
    Token   string // API token (required if enabled)
    Enabled bool   // Enable WHOOSH integration (default: false)
}

Runtime Configuration

The RuntimeConfig type manages dynamic configuration with assignment overrides from WHOOSH.

RuntimeConfig Structure

type RuntimeConfig struct {
    Base     *Config           // Base configuration from environment
    Override *AssignmentConfig // Assignment overrides from WHOOSH
    mu       sync.RWMutex      // Concurrent access protection
    reloadCh chan struct{}     // Reload trigger channel
}

Creating Runtime Configuration

// Load base configuration
baseConfig, err := config.LoadFromEnvironment()
if err != nil {
    return err
}

// Create runtime configuration manager
runtimeConfig := config.NewRuntimeConfig(baseConfig)

Getting Effective Configuration

The GetConfig() method returns a merged configuration with overrides applied:

// Get merged configuration (base + overrides)
effectiveConfig := runtimeConfig.GetConfig()

// Use effective configuration
agentID := effectiveConfig.Agent.ID
role := effectiveConfig.Agent.Role

Merge Behavior

Runtime configuration merges base and override values:

1. Override takes precedence: If a field is set in the assignment override, it replaces the base value
2. Base as fallback: If a field is not set in the override, the base value is used
3. Non-zero values: Only non-zero/non-empty override values are applied

Example Merge:

Base Config:
  Agent.ID: "chorus-default"
  Agent.Role: "backend_developer"
  Agent.MaxTasks: 3

Assignment Override:
  Agent.ID: "chorus-task-12345"
  Agent.Role: "frontend_developer"
  (MaxTasks not specified)

Effective Config:
  Agent.ID: "chorus-task-12345"      (from override)
  Agent.Role: "frontend_developer"   (from override)
  Agent.MaxTasks: 3                  (from base)

Dynamic Assignments

CHORUS agents can fetch task-specific configuration from the WHOOSH API, enabling dynamic role assignment and configuration updates.

Assignment Configuration Structure

type AssignmentConfig struct {
    // Assignment metadata
    AssignmentID   string    // Unique assignment identifier
    TaskSlot       string    // Docker Swarm task slot
    TaskID         string    // WHOOSH task ID
    ClusterID      string    // Cluster identifier
    AssignedAt     time.Time // Assignment timestamp
    ExpiresAt      time.Time // Optional expiration

    // Agent configuration overrides
    Agent     *AgentConfig   // Agent config overrides
    Network   *NetworkConfig // Network config overrides
    AI        *AIConfig      // AI config overrides
    Logging   *LoggingConfig // Logging config overrides

    // Bootstrap configuration for scaling
    BootstrapPeers []string   // Bootstrap peer list
    JoinStagger    int        // Join stagger delay (ms)

    // Runtime capabilities
    RuntimeCapabilities []string // Additional capabilities

    // Key derivation for encryption
    RoleKey       string // Role encryption key
    ClusterSecret string // Cluster secret

    // Custom fields
    Custom map[string]interface{} // Custom configuration
}

Loading Assignments from WHOOSH

ctx := context.Background()
assignURL := "https://whoosh.chorus.services/api/v1/assignments"

// Fetch and apply assignment
if err := runtimeCfg.LoadAssignment(ctx, assignURL); err != nil {
    log.Printf("Failed to load assignment: %v", err)
} else {
    log.Println("Assignment loaded successfully")
}

Assignment Request

CHORUS sends the following information when requesting an assignment:

type AssignmentRequest struct {
    ClusterID  string    // Cluster identifier
    TaskSlot   string    // Docker task slot (from TASK_SLOT env var)
    TaskID     string    // Task ID (from TASK_ID env var)
    AgentID    string    // Agent identifier
    NodeID     string    // Node identifier (from NODE_ID env var)
    Timestamp  time.Time // Request timestamp
}

HTTP Request:

GET /api/v1/assignments?cluster_id=prod-cluster&agent_id=chorus-agent-1&node_id=node-001&task_slot=1&task_id=task-12345
Accept: application/json
User-Agent: CHORUS-Agent/0.1.0

Assignment Response

WHOOSH should return a JSON response matching the AssignmentConfig structure:

{
  "assignment_id": "assign-67890",
  "task_slot": "1",
  "task_id": "task-12345",
  "cluster_id": "prod-cluster",
  "assigned_at": "2025-09-30T10:00:00Z",
  "expires_at": "2025-09-30T18:00:00Z",
  "agent": {
    "id": "chorus-frontend-specialist",
    "role": "frontend_developer",
    "specialization": "react_specialist",
    "max_tasks": 5,
    "capabilities": ["frontend", "ui", "react", "typescript"],
    "models": ["claude-sonnet-3.5"],
    "project": "web-redesign",
    "expertise": ["react", "tailwind", "accessibility"],
    "reports_to": "project_manager",
    "deliverables": ["component_library", "responsive_layouts"]
  },
  "bootstrap_peers": [
    "/ip4/10.0.1.10/tcp/9000/p2p/12D3KooWPeer1",
    "/ip4/10.0.1.11/tcp/9000/p2p/12D3KooWPeer2"
  ],
  "join_stagger": 2000,
  "runtime_capabilities": ["hot_reload", "fast_refresh"],
  "role_key": "age1xxxxxx...",
  "cluster_secret": "cluster-secret-xyz",
  "custom": {
    "build_target": "production",
    "enable_profiling": true
  }
}

SIGHUP Configuration Reload

CHORUS agents can reload configuration dynamically by sending a SIGHUP signal:

# Find the CHORUS agent process
docker ps | grep chorus-agent

# Send SIGHUP to reload configuration
docker exec <container-id> kill -SIGHUP 1

# Or use Docker kill command
docker kill --signal=SIGHUP <container-id>

The reload handler automatically:

1. Fetches the latest assignment from WHOOSH
2. Merges the new assignment with base configuration
3. Applies the updated configuration without restart

Reload Handler Setup:

// Start SIGHUP reload handler
ctx := context.Background()
assignURL := "https://whoosh.chorus.services/api/v1/assignments"
runtimeCfg.StartReloadHandler(ctx, assignURL)

// Agent continues running with updated configuration
// Log output on SIGHUP:
// 📡 Received SIGHUP, reloading assignment configuration...
// ✅ Assignment configuration reloaded successfully

Manual Reload Trigger

// Trigger manual reload (without SIGHUP signal)
runtimeCfg.Reload()

Bootstrap Peers with Assignment Override

Bootstrap peers can be configured from multiple sources with priority:

// Get bootstrap peers with override support
peers := runtimeCfg.GetBootstrapPeers()

// Priority order:
// 1. Assignment override from WHOOSH (highest priority)
// 2. JSON bootstrap configuration (BOOTSTRAP_JSON env var)
// 3. Environment variable CSV (CHORUS_BOOTSTRAP_PEERS)

Bootstrap JSON Format (BOOTSTRAP_JSON env var):

{
  "peers": [
    {
      "address": "/ip4/10.0.1.10/tcp/9000/p2p/12D3KooWPeer1",
      "priority": 100,
      "region": "us-east",
      "roles": ["coordinator"],
      "enabled": true
    },
    {
      "address": "/ip4/10.0.1.11/tcp/9000/p2p/12D3KooWPeer2",
      "priority": 90,
      "region": "us-west",
      "roles": ["worker"],
      "enabled": true
    }
  ],
  "metadata": {
    "generated_at": "2025-09-30T10:00:00Z",
    "cluster_id": "prod-cluster",
    "version": "1.0",
    "notes": "Production bootstrap peers"
  }
}

Join Stagger with Assignment Override

Join stagger prevents thundering herd problems during scaling:

// Get join stagger delay with override support
stagger := runtimeCfg.GetJoinStagger()
if stagger > 0 {
    time.Sleep(stagger)
}

// Priority order:
// 1. Assignment override (join_stagger field)
// 2. Environment variable (CHORUS_JOIN_STAGGER_MS)

Role Definitions

CHORUS uses predefined roles for access control and capability management.

Authority Levels

const (
    AuthorityMaster       AuthorityLevel = "master"       // Highest authority
    AuthorityAdmin        AuthorityLevel = "admin"        // Administrative
    AuthorityDecision     AuthorityLevel = "decision"     // Can make decisions
    AuthorityCoordination AuthorityLevel = "coordination" // Can coordinate
    AuthorityFull         AuthorityLevel = "full"         // Full execution
    AuthoritySuggestion   AuthorityLevel = "suggestion"   // Suggestion only
    AuthorityReadOnly     AuthorityLevel = "readonly"     // Read-only access
)

Predefined Roles

Role	Description	Authority Level	Access Level	Capabilities
project_manager	Project coordination and management	Master	High	coordination, planning, oversight
backend_developer	Backend development and API work	Decision	Medium	backend, api, database
frontend_developer	Frontend UI development	Coordination	Medium	frontend, ui, components
devops_engineer	Infrastructure and deployment	Decision	High	infrastructure, deployment, monitoring
security_engineer	Security oversight and hardening	Master	High	security, audit, compliance
security_expert	Advanced security analysis	Master	High	security, policy, response
senior_software_architect	Architecture governance	Decision	High	architecture, design, coordination
qa_engineer	Quality assurance and testing	Coordination	Medium	testing, validation
readonly_user	Read-only observer	ReadOnly	Low	observation
suggestion_only_role	Propose suggestions only	Suggestion	Low	recommendation

Role Definition Structure

type RoleDefinition struct {
    Name           string         // Role name
    Description    string         // Role description
    Capabilities   []string       // Role capabilities
    AccessLevel    string         // Access level: "low", "medium", "high"
    AuthorityLevel AuthorityLevel // Authority level
    Keys           *AgeKeyPair    // Encryption keys
    CanDecrypt     []string       // Roles this role can decrypt
}

Using Role Definitions

// Get all predefined roles
roles := config.GetPredefinedRoles()

// Get specific role
pmRole := roles["project_manager"]

// Get role authority level from configuration
authority, err := cfg.GetRoleAuthority("backend_developer")
if err != nil {
    log.Fatalf("Unknown role: %v", err)
}

// Check if agent can decrypt content for target role
canDecrypt, err := cfg.CanDecryptRole("frontend_developer")
if err != nil || !canDecrypt {
    log.Println("Cannot decrypt content for frontend_developer")
}

Encryption Key Management

Roles support Age encryption key pairs for secure communication:

type AgeKeyPair struct {
    PublicKey  string // Age public key
    PrivateKey string // Age private key
}

Hybrid Configuration

The HybridConfig manages feature flags for Phase 2 hybrid mode, supporting gradual migration from mock to real implementations.

Hybrid Configuration Structure

type HybridConfig struct {
    DHT        HybridDHTConfig    // DHT configuration
    UCXL       HybridUCXLConfig   // UCXL configuration
    Discovery  DiscoveryConfig    // Discovery configuration
    Monitoring MonitoringConfig   // Monitoring configuration
}

Hybrid DHT Configuration

type HybridDHTConfig struct {
    Backend             string        // "mock", "real", or "hybrid"
    BootstrapNodes      []string      // Bootstrap nodes for real DHT
    FallbackOnError     bool          // Fallback to mock on error (default: true)
    HealthCheckInterval time.Duration // Health check interval (default: 30s)
    MaxRetries          int           // Max retries (default: 3)
    RetryBackoff        time.Duration // Retry backoff (default: 1s)
    OperationTimeout    time.Duration // Operation timeout (default: 10s)
}

DHT Backend Modes:

• "mock": Use mock DHT only (default)
• "real": Use real libp2p DHT only
• "hybrid": Try real DHT, fallback to mock on error

Hybrid UCXL Configuration

type HybridUCXLConfig struct {
    CacheEnabled    bool          // Enable caching (default: true)
    CacheTTL        time.Duration // Cache TTL (default: 5m)
    UseDistributed  bool          // Use distributed UCXL (default: false)
    MaxCacheSize    int           // Max cache entries (default: 10000)
}

Discovery Configuration

type DiscoveryConfig struct {
    MDNSEnabled        bool          // Enable mDNS (default: true)
    DHTDiscovery       bool          // Enable DHT discovery (default: false)
    AnnounceInterval   time.Duration // Announce interval (default: 30s)
    ServiceName        string        // Service name (default: "CHORUS")

    // Rate limiting for scaling
    DialsPerSecond     int           // Dials per second (default: 5)
    MaxConcurrentDHT   int           // Max concurrent DHT ops (default: 16)
    MaxConcurrentDials int           // Max concurrent dials (default: 10)
    JoinStaggerMS      int           // Join stagger (default: 0)
}

Monitoring Configuration

type MonitoringConfig struct {
    Enabled           bool          // Enable monitoring (default: true)
    MetricsInterval   time.Duration // Metrics interval (default: 15s)
    HealthEndpoint    string        // Health endpoint (default: "/health")
    MetricsEndpoint   string        // Metrics endpoint (default: "/metrics")
}

Loading Hybrid Configuration

// Load hybrid configuration from environment
hybridCfg, err := config.LoadHybridConfig()
if err != nil {
    log.Fatalf("Failed to load hybrid configuration: %v", err)
}

// Check DHT mode
if hybridCfg.IsRealDHTEnabled() {
    log.Println("Real DHT is enabled")
}

if hybridCfg.IsMockDHTEnabled() {
    log.Println("Mock DHT is enabled")
}

if hybridCfg.IsFallbackEnabled() {
    log.Println("Fallback to mock DHT is enabled")
}

// Get bootstrap nodes
bootstrapNodes := hybridCfg.GetDHTBootstrapNodes()

Security Configuration

Security settings for key rotation, audit logging, and election behavior.

Security Configuration Structure

type SecurityConfig struct {
    KeyRotationDays int            // Key rotation interval (default: 30)
    AuditLogging    bool           // Enable audit logging (default: true)
    AuditPath       string         // Audit log path (default: "/tmp/chorus-audit.log")
    ElectionConfig  ElectionConfig // Election configuration
}

Election Configuration

type ElectionConfig struct {
    DiscoveryTimeout  time.Duration      // Discovery timeout (default: 15s)
    HeartbeatTimeout  time.Duration      // Heartbeat timeout (default: 30s)
    ElectionTimeout   time.Duration      // Election timeout (default: 60s)
    DiscoveryBackoff  time.Duration      // Discovery backoff (default: 5s)
    LeadershipScoring *LeadershipScoring // Leadership scoring weights
}

type LeadershipScoring struct {
    UptimeWeight     float64 // Uptime weight (default: 0.4)
    CapabilityWeight float64 // Capability weight (default: 0.3)
    ExperienceWeight float64 // Experience weight (default: 0.2)
    LoadWeight       float64 // Load weight (default: 0.1)
}

Environment Variables Reference

Required Variables

Variable	Type	Description
CHORUS_LICENSE_ID or CHORUS_LICENSE_ID_FILE	string	License identifier (required)

Agent Configuration

Variable	Type	Default	Description
CHORUS_AGENT_ID	string	auto-generated	Unique agent identifier
CHORUS_SPECIALIZATION	string	"general_developer"	Agent specialization
CHORUS_MAX_TASKS	int	3	Maximum concurrent tasks
CHORUS_CAPABILITIES	[]string	["general_development", "task_coordination"]	Agent capabilities (CSV)
CHORUS_MODELS	[]string	["meta/llama-3.1-8b-instruct"]	Available AI models (CSV)
CHORUS_ROLE	string	""	Agent role (see Role Definitions)
CHORUS_PROJECT	string	"chorus"	Project assignment
CHORUS_EXPERTISE	[]string	[]	Domain expertise (CSV)
CHORUS_REPORTS_TO	string	""	Reporting hierarchy
CHORUS_DELIVERABLES	[]string	[]	Expected deliverables (CSV)
CHORUS_MODEL_SELECTION_WEBHOOK	string	""	Model selection webhook URL
CHORUS_DEFAULT_REASONING_MODEL	string	"meta/llama-3.1-8b-instruct"	Default AI model

Network Configuration

Variable	Type	Default	Description
CHORUS_P2P_PORT	int	9000	P2P network port
CHORUS_API_PORT	int	8080	API server port
CHORUS_HEALTH_PORT	int	8081	Health check port
CHORUS_BIND_ADDRESS	string	"0.0.0.0"	Bind address

License Configuration

Variable	Type	Default	Description
CHORUS_LICENSE_ID	string	-	Required: License identifier
CHORUS_LICENSE_ID_FILE	path	-	Path to file containing license ID
CHORUS_CLUSTER_ID	string	"default-cluster"	Cluster identifier
CHORUS_ORGANIZATION_NAME	string	""	Organization name
CHORUS_KACHING_URL	string	"https://kaching.chorus.services"	License validation URL
CHORUS_GRACE_PERIOD_HOURS	int	72	Grace period in hours

AI Configuration

Variable	Type	Default	Description
CHORUS_AI_PROVIDER	string	"resetdata"	AI provider ("ollama" or "resetdata")
OLLAMA_ENDPOINT	string	"http://localhost:11434"	Ollama endpoint
OLLAMA_TIMEOUT	duration	30s	Ollama request timeout
RESETDATA_BASE_URL	string	"https://models.au-syd.resetdata.ai/v1"	ResetData API URL
RESETDATA_API_KEY	string	-	ResetData API key
RESETDATA_API_KEY_FILE	path	-	Path to file containing API key
RESETDATA_MODEL	string	"meta/llama-3.1-8b-instruct"	ResetData model name
RESETDATA_TIMEOUT	duration	30s	ResetData request timeout

Logging Configuration

Variable	Type	Default	Description
LOG_LEVEL	string	"info"	Log level: debug, info, warn, error
LOG_FORMAT	string	"structured"	Log format: structured or text

DHT Configuration

Variable	Type	Default	Description
CHORUS_DHT_ENABLED	bool	true	Enable DHT
CHORUS_BOOTSTRAP_PEERS	[]string	[]	Bootstrap peer multiaddrs (CSV)
CHORUS_MDNS_ENABLED	bool	true	Enable mDNS discovery
BOOTSTRAP_JSON	path	-	Path to bootstrap JSON config
CHORUS_JOIN_STAGGER_MS	int	0	Join stagger delay in milliseconds

UCXL Configuration

Variable	Type	Default	Description
CHORUS_UCXL_ENABLED	bool	true	Enable UCXL
CHORUS_UCXL_SERVER_ENABLED	bool	true	Enable UCXL server
CHORUS_UCXL_SERVER_PORT	int	8082	UCXL server port
CHORUS_UCXL_SERVER_BASE_PATH	string	""	UCXL server base path
CHORUS_UCXL_STORAGE_DIRECTORY	string	"/tmp/chorus-ucxi-storage"	UCXL storage directory
CHORUS_UCXL_CACHE_TTL	duration	1h	UCXL cache TTL

SLURP Configuration

Variable	Type	Default	Description
CHORUS_SLURP_ENABLED	bool	false	Enable SLURP integration
CHORUS_SLURP_API_BASE_URL	string	"http://localhost:9090"	SLURP API URL
CHORUS_SLURP_API_KEY	string	-	SLURP API key
CHORUS_SLURP_API_KEY_FILE	path	-	Path to file containing API key
CHORUS_SLURP_API_TIMEOUT	duration	15s	SLURP request timeout
CHORUS_SLURP_API_RETRY_COUNT	int	3	SLURP retry count
CHORUS_SLURP_API_RETRY_DELAY	duration	2s	SLURP retry delay
CHORUS_SLURP_MAX_DECISION_HOPS	int	5	Max decision hops
CHORUS_SLURP_STALENESS_CHECK_INTERVAL	duration	5m	Staleness check interval
CHORUS_SLURP_MAX_CONCURRENT_RESOLUTIONS	int	4	Max concurrent resolutions
CHORUS_SLURP_METRICS_COLLECTION_INTERVAL	duration	1m	Metrics collection interval

WHOOSH API Configuration

Variable	Type	Default	Description
WHOOSH_API_URL	string	"http://localhost:3000"	WHOOSH API URL
WHOOSH_API_BASE_URL	string	"http://localhost:3000"	WHOOSH base URL
WHOOSH_API_TOKEN	string	-	WHOOSH API token
WHOOSH_API_ENABLED	bool	false	Enable WHOOSH integration

Security Configuration

Variable	Type	Default	Description
CHORUS_KEY_ROTATION_DAYS	int	30	Key rotation interval in days
CHORUS_AUDIT_LOGGING	bool	true	Enable audit logging
CHORUS_AUDIT_PATH	string	"/tmp/chorus-audit.log"	Audit log file path
CHORUS_DISCOVERY_TIMEOUT	duration	15s	Discovery timeout
CHORUS_HEARTBEAT_TIMEOUT	duration	30s	Heartbeat timeout
CHORUS_ELECTION_TIMEOUT	duration	60s	Election timeout
CHORUS_DISCOVERY_BACKOFF	duration	5s	Discovery backoff

Hybrid Configuration

Variable	Type	Default	Description
CHORUS_DHT_BACKEND	string	"mock"	DHT backend: "mock", "real", or "hybrid"
CHORUS_DHT_BOOTSTRAP_NODES	[]string	[]	DHT bootstrap nodes (CSV)
CHORUS_FALLBACK_ON_ERROR	bool	true	Fallback to mock on error
CHORUS_HEALTH_CHECK_INTERVAL	duration	30s	Health check interval
CHORUS_DHT_MAX_RETRIES	int	3	DHT max retries
CHORUS_DHT_RETRY_BACKOFF	duration	1s	DHT retry backoff
CHORUS_DHT_OPERATION_TIMEOUT	duration	10s	DHT operation timeout
CHORUS_UCXL_CACHE_ENABLED	bool	true	Enable UCXL caching
CHORUS_UCXL_CACHE_TTL	duration	5m	UCXL cache TTL
CHORUS_UCXL_USE_DISTRIBUTED	bool	false	Use distributed UCXL
CHORUS_UCXL_MAX_CACHE_SIZE	int	10000	Max UCXL cache size
CHORUS_MDNS_ENABLED	bool	true	Enable mDNS discovery
CHORUS_DHT_DISCOVERY	bool	false	Enable DHT discovery
CHORUS_ANNOUNCE_INTERVAL	duration	30s	Announce interval
CHORUS_SERVICE_NAME	string	"CHORUS"	Service name
CHORUS_DIALS_PER_SEC	int	5	Dials per second rate limit
CHORUS_MAX_CONCURRENT_DHT	int	16	Max concurrent DHT operations
CHORUS_MAX_CONCURRENT_DIALS	int	10	Max concurrent dials
CHORUS_JOIN_STAGGER_MS	int	0	Join stagger in milliseconds
CHORUS_MONITORING_ENABLED	bool	true	Enable monitoring
CHORUS_METRICS_INTERVAL	duration	15s	Metrics collection interval
CHORUS_HEALTH_ENDPOINT	string	"/health"	Health endpoint path
CHORUS_METRICS_ENDPOINT	string	"/metrics"	Metrics endpoint path

Docker-specific Variables

Variable	Description
HOSTNAME	Container hostname (set by Docker)
TASK_SLOT	Docker Swarm task slot number
TASK_ID	Docker Swarm task ID
NODE_ID	Docker Swarm node ID

Assignment Schema

Full Assignment JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "assignment_id": {
      "type": "string",
      "description": "Unique assignment identifier"
    },
    "task_slot": {
      "type": "string",
      "description": "Docker Swarm task slot number"
    },
    "task_id": {
      "type": "string",
      "description": "WHOOSH task identifier"
    },
    "cluster_id": {
      "type": "string",
      "description": "Cluster identifier"
    },
    "assigned_at": {
      "type": "string",
      "format": "date-time",
      "description": "Assignment timestamp"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time",
      "description": "Optional expiration timestamp"
    },
    "agent": {
      "type": "object",
      "properties": {
        "id": {"type": "string"},
        "specialization": {"type": "string"},
        "max_tasks": {"type": "integer"},
        "capabilities": {"type": "array", "items": {"type": "string"}},
        "models": {"type": "array", "items": {"type": "string"}},
        "role": {"type": "string"},
        "project": {"type": "string"},
        "expertise": {"type": "array", "items": {"type": "string"}},
        "reports_to": {"type": "string"},
        "deliverables": {"type": "array", "items": {"type": "string"}},
        "model_selection_webhook": {"type": "string"},
        "default_reasoning_model": {"type": "string"}
      }
    },
    "network": {
      "type": "object",
      "properties": {
        "p2p_port": {"type": "integer"},
        "api_port": {"type": "integer"},
        "health_port": {"type": "integer"},
        "bind_address": {"type": "string"}
      }
    },
    "ai": {
      "type": "object",
      "properties": {
        "provider": {"type": "string"},
        "ollama": {
          "type": "object",
          "properties": {
            "endpoint": {"type": "string"},
            "timeout": {"type": "string"}
          }
        },
        "resetdata": {
          "type": "object",
          "properties": {
            "base_url": {"type": "string"},
            "model": {"type": "string"},
            "timeout": {"type": "string"}
          }
        }
      }
    },
    "logging": {
      "type": "object",
      "properties": {
        "level": {"type": "string"},
        "format": {"type": "string"}
      }
    },
    "bootstrap_peers": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Bootstrap peer multiaddrs"
    },
    "join_stagger": {
      "type": "integer",
      "description": "Join stagger delay in milliseconds"
    },
    "runtime_capabilities": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Additional runtime capabilities"
    },
    "role_key": {
      "type": "string",
      "description": "Role encryption key"
    },
    "cluster_secret": {
      "type": "string",
      "description": "Cluster secret"
    },
    "custom": {
      "type": "object",
      "description": "Custom configuration fields",
      "additionalProperties": true
    }
  },
  "required": ["assignment_id", "cluster_id", "assigned_at"]
}

Example Assignment Scenarios

Scenario 1: Frontend Developer Assignment

{
  "assignment_id": "frontend-task-001",
  "task_slot": "1",
  "task_id": "web-redesign-homepage",
  "cluster_id": "prod-cluster",
  "assigned_at": "2025-09-30T10:00:00Z",
  "expires_at": "2025-09-30T18:00:00Z",
  "agent": {
    "id": "chorus-frontend-1",
    "role": "frontend_developer",
    "specialization": "react_specialist",
    "max_tasks": 3,
    "capabilities": ["frontend", "ui", "react", "typescript"],
    "models": ["claude-sonnet-3.5"],
    "project": "web-redesign",
    "expertise": ["react", "tailwind", "accessibility"],
    "reports_to": "project_manager",
    "deliverables": ["responsive_homepage", "mobile_navigation"]
  },
  "logging": {
    "level": "debug"
  }
}

Scenario 2: DevOps Engineer with Bootstrap Peers

{
  "assignment_id": "devops-scaling-001",
  "task_slot": "5",
  "task_id": "scale-infrastructure",
  "cluster_id": "prod-cluster",
  "assigned_at": "2025-09-30T11:00:00Z",
  "agent": {
    "id": "chorus-devops-5",
    "role": "devops_engineer",
    "specialization": "kubernetes_specialist",
    "max_tasks": 5,
    "capabilities": ["infrastructure", "deployment", "monitoring", "kubernetes"],
    "models": ["claude-sonnet-3.5", "gpt-4"],
    "project": "infrastructure-modernization"
  },
  "bootstrap_peers": [
    "/ip4/10.0.1.10/tcp/9000/p2p/12D3KooWCoordinator1",
    "/ip4/10.0.1.11/tcp/9000/p2p/12D3KooWCoordinator2"
  ],
  "join_stagger": 3000,
  "custom": {
    "deployment_region": "us-east-1",
    "enable_autoscaling": true,
    "max_replicas": 10
  }
}

Scenario 3: Minimal Assignment

{
  "assignment_id": "minimal-001",
  "cluster_id": "test-cluster",
  "assigned_at": "2025-09-30T12:00:00Z",
  "agent": {
    "role": "backend_developer"
  }
}

Configuration Validation

Validation Rules

The Validate() method checks configuration for:

1. Required Fields:

   • License.LicenseID must be provided

2. Agent ID Auto-generation:

   • If Agent.ID is empty, it's auto-generated from hostname or container ID
   • Format: chorus-<hostname> or chorus-<container-id>

3. Hybrid Configuration Validation:

   • DHT backend must be one of: "mock", "real", "hybrid"
   • Health check interval must be >= 1 second
   • Operation timeout must be >= 100 milliseconds
   • Cache size must be non-negative

Validation Examples

// Validate configuration
cfg, err := config.LoadFromEnvironment()
if err != nil {
    log.Fatalf("Failed to load config: %v", err)
}

if err := cfg.Validate(); err != nil {
    log.Fatalf("Invalid configuration: %v", err)
}

// Validate hybrid configuration
hybridCfg, err := config.LoadHybridConfig()
if err != nil {
    log.Fatalf("Failed to load hybrid config: %v", err)
}

if err := hybridCfg.Validate(); err != nil {
    log.Fatalf("Invalid hybrid configuration: %v", err)
}

Common Validation Errors

Error	Cause	Solution
"CHORUS_LICENSE_ID is required"	Missing license ID	Set CHORUS_LICENSE_ID or CHORUS_LICENSE_ID_FILE
"invalid DHT backend 'xyz'"	Invalid DHT backend	Use "mock", "real", or "hybrid"
"health check interval too short"	Health check < 1s	Increase CHORUS_HEALTH_CHECK_INTERVAL
"operation timeout too short"	Operation timeout < 100ms	Increase CHORUS_DHT_OPERATION_TIMEOUT
"max cache size must be non-negative"	Negative cache size	Set CHORUS_UCXL_MAX_CACHE_SIZE >= 0

Usage Examples

Example 1: Basic Configuration Loading

package main

import (
    "log"
    "github.com/chorus/pkg/config"
)

func main() {
    // Load configuration from environment
    cfg, err := config.LoadFromEnvironment()
    if err != nil {
        log.Fatalf("Failed to load configuration: %v", err)
    }

    log.Printf("Agent ID: %s", cfg.Agent.ID)
    log.Printf("Agent Role: %s", cfg.Agent.Role)
    log.Printf("API Port: %d", cfg.Network.APIPort)
}

Example 2: Runtime Configuration with WHOOSH

package main

import (
    "context"
    "log"
    "os"
    "github.com/chorus/pkg/config"
)

func main() {
    ctx := context.Background()

    // Load runtime configuration
    runtimeCfg, err := config.LoadRuntimeConfig()
    if err != nil {
        log.Fatalf("Failed to load runtime config: %v", err)
    }

    // Fetch assignment from WHOOSH (if enabled)
    whooshURL := os.Getenv("WHOOSH_API_URL")
    if whooshURL != "" {
        assignURL := whooshURL + "/api/v1/assignments"
        if err := runtimeCfg.LoadAssignment(ctx, assignURL); err != nil {
            log.Printf("No assignment available: %v", err)
        } else {
            log.Println("Assignment loaded successfully")
        }
    }

    // Start SIGHUP reload handler
    go runtimeCfg.StartReloadHandler(ctx, assignURL)

    // Get effective configuration
    cfg := runtimeCfg.GetConfig()
    log.Printf("Effective Agent ID: %s", cfg.Agent.ID)
    log.Printf("Effective Role: %s", cfg.Agent.Role)

    // Check assignment info
    if assignment := runtimeCfg.GetAssignmentInfo(); assignment != nil {
        log.Printf("Assignment ID: %s", assignment.AssignmentID)
        log.Printf("Task ID: %s", assignment.TaskID)
        log.Printf("Assigned At: %s", assignment.AssignedAt)
    }
}

Example 3: Bootstrap Peers with Priority

package main

import (
    "log"
    "os"
    "github.com/chorus/pkg/config"
)

func main() {
    // Set bootstrap JSON path
    os.Setenv("BOOTSTRAP_JSON", "/etc/chorus/bootstrap.json")

    // Load runtime configuration
    runtimeCfg, err := config.LoadRuntimeConfig()
    if err != nil {
        log.Fatalf("Failed to load config: %v", err)
    }

    // Get bootstrap peers (assignment > JSON > env var)
    peers := runtimeCfg.GetBootstrapPeers()
    log.Printf("Bootstrap peers: %v", peers)

    // Get join stagger
    stagger := runtimeCfg.GetJoinStagger()
    log.Printf("Join stagger: %s", stagger)
}

Example 4: Role-Based Access Control

package main

import (
    "log"
    "github.com/chorus/pkg/config"
)

func main() {
    // Load configuration
    cfg, err := config.LoadFromEnvironment()
    if err != nil {
        log.Fatalf("Failed to load config: %v", err)
    }

    // Get role authority level
    authority, err := cfg.GetRoleAuthority(cfg.Agent.Role)
    if err != nil {
        log.Fatalf("Invalid role: %v", err)
    }
    log.Printf("Authority level: %s", authority)

    // Check decryption capability
    canDecrypt, err := cfg.CanDecryptRole("frontend_developer")
    if err != nil {
        log.Fatalf("Error checking decrypt capability: %v", err)
    }
    if canDecrypt {
        log.Println("Can decrypt frontend_developer content")
    } else {
        log.Println("Cannot decrypt frontend_developer content")
    }

    // Get all predefined roles
    roles := config.GetPredefinedRoles()
    for name, role := range roles {
        log.Printf("Role: %s, Authority: %s, Access: %s",
            name, role.AuthorityLevel, role.AccessLevel)
    }
}

Example 5: Hybrid Configuration Mode

package main

import (
    "log"
    "os"
    "github.com/chorus/pkg/config"
)

func main() {
    // Set hybrid mode environment variables
    os.Setenv("CHORUS_DHT_BACKEND", "hybrid")
    os.Setenv("CHORUS_FALLBACK_ON_ERROR", "true")
    os.Setenv("CHORUS_UCXL_USE_DISTRIBUTED", "true")

    // Load hybrid configuration
    hybridCfg, err := config.LoadHybridConfig()
    if err != nil {
        log.Fatalf("Failed to load hybrid config: %v", err)
    }

    // Check DHT mode
    log.Printf("Real DHT enabled: %v", hybridCfg.IsRealDHTEnabled())
    log.Printf("Mock DHT enabled: %v", hybridCfg.IsMockDHTEnabled())
    log.Printf("Fallback enabled: %v", hybridCfg.IsFallbackEnabled())

    // Get DHT bootstrap nodes
    nodes := hybridCfg.GetDHTBootstrapNodes()
    log.Printf("Bootstrap nodes: %v", nodes)
}

Example 6: Docker Secrets Support

package main

import (
    "log"
    "os"
    "github.com/chorus/pkg/config"
)

func main() {
    // Use Docker secrets for sensitive values
    os.Setenv("CHORUS_LICENSE_ID_FILE", "/run/secrets/chorus_license")
    os.Setenv("RESETDATA_API_KEY_FILE", "/run/secrets/resetdata_api_key")
    os.Setenv("CHORUS_SLURP_API_KEY_FILE", "/run/secrets/slurp_api_key")

    // Load configuration (reads from files automatically)
    cfg, err := config.LoadFromEnvironment()
    if err != nil {
        log.Fatalf("Failed to load config: %v", err)
    }

    // License ID read from file
    log.Printf("License ID loaded from file")

    // API keys read from files
    if cfg.AI.ResetData.APIKey != "" {
        log.Println("ResetData API key loaded")
    }
    if cfg.Slurp.APIKey != "" {
        log.Println("SLURP API key loaded")
    }
}

Example 7: Configuration Watcher

package main

import (
    "log"
    "time"
    "github.com/chorus/pkg/config"
)

func main() {
    // Load hybrid configuration
    hybridCfg, err := config.LoadHybridConfig()
    if err != nil {
        log.Fatalf("Failed to load config: %v", err)
    }

    // Create configuration watcher
    watcher := config.NewConfigWatcher(hybridCfg)
    defer watcher.Close()

    // Start watching for configuration changes
    go func() {
        for event := range watcher.Events() {
            log.Printf("Configuration changed: %s (%v -> %v)",
                event.Component, event.Old, event.New)
        }
    }()

    // Simulate configuration change
    time.Sleep(2 * time.Second)
    if err := watcher.UpdateDHTBackend("real"); err != nil {
        log.Printf("Failed to update DHT backend: %v", err)
    }

    // Keep running
    select {}
}

Related Documentation

• BZZZ Integration: /home/tony/chorus/project-queues/active/BZZZ/docs/api.md
• WHOOSH API: /home/tony/chorus/project-queues/active/WHOOSH/docs/api.md
• SLURP Integration: /home/tony/chorus/project-queues/active/CHORUS/docs/slurp-integration.md
• UCXL Protocol: /home/tony/chorus/project-queues/active/RUSTLE/docs/ucxl-spec.md
• Docker Deployment: /home/tony/chorus/project-queues/active/CHORUS/docs/deployment.md

Summary

The CHORUS configuration package provides:

1. Environment-based Configuration: All configuration via environment variables for containerized deployments
2. Runtime Assignment Support: Dynamic configuration from WHOOSH with SIGHUP reload
3. Role-Based Access Control: Predefined roles with authority levels and encryption keys
4. Hybrid Mode Support: Feature flags for gradual migration from mock to real implementations
5. Docker Secrets Support: Read sensitive values from files for Docker secrets integration
6. Comprehensive Validation: Required field checks and constraint validation
7. Bootstrap Configuration: Multiple sources with priority (assignment > JSON > env var)
8. Configuration Merging: Clean merge semantics for base + override configuration

For questions or issues, refer to the test file at /home/tony/chorus/project-queues/active/CHORUS/pkg/config/config_test.go for additional usage examples.