TOML Configuration Reference
Pass a TOML file with --config or ORCHER_ORCHESTRATOR_CONFIG. All sections are optional — unspecified values use defaults.
[server]
1[server]2grpc_addr = "0.0.0.0:50051" # gRPC bind address3http_addr = "0.0.0.0:8001" # HTTP bind address (metrics + health)4max_concurrent_streams = 1000 # Maximum concurrent gRPC streams[orchestrator]
1[orchestrator]2max_workers = 100 # Maximum registered workers3max_concurrent_tasks = 1000 # Maximum concurrent task executions4heartbeat_timeout_secs = 90 # Worker heartbeat timeout[storage]
1[storage]2database_url = "postgresql://orcher:orcher@localhost:6432/orcher"3redis_url = "redis://localhost:6379" # OptionalEnvironment variables DATABASE_URL and REDIS_URL override these values.
[logging]
1[logging]2level = "info" # trace, debug, info, warn, error3format = "json" # compact, json, pretty, bunyan[health]
1[health]2readiness_enabled = true # Enable /health/ready endpoint3liveness_enabled = true # Enable /health/live endpoint[polling]
Controls how SDK workers poll for and execute workflow/task work.
1[polling]2# Claim lease duration (seconds). If a worker crashes, claims are reclaimed after this timeout.3# Development: 60, Production: 3004claim_timeout_secs = 30056# PostgreSQL claim query timeout (milliseconds). How long to wait for the claim query to execute.7claim_query_timeout_ms = 200089# Long-poll timeout (seconds). Workers wait up to this duration for work to become available.10poll_timeout_secs = 601112# Background reclaim interval (seconds). How often to check for expired claims.13# Must be less than claim_timeout_secs.14reclaim_interval_secs = 101516# Enable notification-based wake-ups. Workers are notified immediately when work is available,17# so a worker need not wait out poll_timeout_secs.18enable_notifications = true1920# Batch claim size. Claims multiple workflow executions in a single query.21# Reduces database contention with multiple workers. Recommended: 5-20.22batch_claim_size = 102324# Redis Streams (opt-in). Uses XADD/XREADGROUP instead of LPUSH/BRPOP.25# Enables zero-config horizontal scaling with consumer groups.26use_streams = false2728# Sync-match dispatch (opt-in, requires use_streams = true and redis_url).29# Routes work directly to waiting workers via in-memory channels.30use_sync_match = false3132# Maximum waiters per queue for sync-match. Limits memory usage.33max_waiters_per_queue = 100003435# Worker affinity for cache locality. Routes consecutive tasks from the same36# workflow to the same worker.37affinity_enabled = true38affinity_lease_secs = 30 # Affinity mapping duration39affinity_max_lease_secs = 300 # Maximum affinity duration (prevents imbalance)4041# Cleanup interval for expired waiters and affinity leases (seconds)42routing_cleanup_interval_secs = 30Validation rules:
claim_timeout_secsmust be greater thanreclaim_interval_secsuse_sync_matchrequiresuse_streams = trueandredis_urlto be configuredaffinity_max_lease_secsmust be >=affinity_lease_secs
[timeout_watcher]
Detects and handles task and workflow timeouts.
1[timeout_watcher]2enabled = true # Enable timeout detection3poll_interval_secs = 30 # How often to check for timeouts4batch_size = 100 # Tasks to process per poll5grace_period_secs = 5 # Grace period before marking timeout67# Individual timeout types (all enabled by default)8enable_schedule_to_start = true # Tasks scheduled but never claimed9enable_start_to_close = true # Tasks started but never completed10enable_heartbeat = true # Long-running tasks that stopped heartbeating11enable_workflow_timeout = true # Workflows exceeding configured timeout[workflow_retry]
Automatic retry scheduling for failed workflows with exponential backoff.
1[workflow_retry]2enabled = true # Enable automatic retry scheduling3poll_interval_secs = 30 # How often to poll for failed workflows4batch_size = 50 # Workflows to process per poll5enable_realtime_notifications = false # LISTEN/NOTIFY for immediate retry67# Default retry policy (used when workflow doesn't specify its own)8default_max_attempts = 3 # Maximum retry attempts9default_initial_backoff_secs = 1 # First retry delay10default_backoff_multiplier = 2.0 # Exponential multiplier (must be >= 1.0)11default_max_backoff_secs = 300 # Maximum backoff cap (5 minutes)[background_jobs]
Periodic maintenance tasks.
1[background_jobs]2metrics_enabled = true # Enable metrics aggregation3metrics_interval_secs = 3600 # Aggregation interval (1 hour)4retention_enabled = true # Enable data retention cleanup5retention_interval_secs = 86400 # Cleanup interval (1 day)67[background_jobs.retention_days]8workflow_executions = 90 # Keep completed workflows for 90 days9execution_logs = 30 # Keep execution logs for 30 days10journal_entries = 90 # Keep journal entries for 90 days11task_executions = 90 # Keep task executions for 90 days12outbox_queue = 7 # Keep completed outbox entries for 7 days[security]
Authentication and TLS configuration.
1[security]2# Authentication mode: "none", "api-key", "mtls", "api-key-and-mtls"3auth_mode = "none"45# API key validation cache6api_key_cache_ttl_secs = 300 # Cache TTL (5 minutes)7api_key_cache_max_entries = 10000 # Maximum cached entries89# TLS configuration (required when auth_mode includes "mtls")10[security.tls]11cert_path = "/etc/orchestrator/tls/server.crt"12key_path = "/etc/orchestrator/tls/server.key"13ca_cert_path = "/etc/orchestrator/tls/ca.crt" # Required for client cert verification14require_client_cert = true[queue] (Optional)
Queue-based task dispatch. Uncomment to enable.
1[queue]2enabled = true3dispatch_strategy = "direct" # "direct", "queue", or "hybrid"45# Queue provider — choose one:67# Redis Streams8[queue.provider]9type = "redis"10url = "redis://localhost:6379"11pool_size = 1012consumer_group = "orchestrator"1314# PostgreSQL-based queue15# [queue.provider]16# type = "postgres"17# url = "postgresql://localhost:5432/orcher"18# pool_size = 1019# table_name = "task_queue"Next Steps
- Configuration Overview — Orchestrator CLI flags and environment variables
- Environments — Configuration priority and development vs production settings