Operations

TOML Configuration Reference


Pass a TOML file with --config or ORCHER_ORCHESTRATOR_CONFIG. All sections are optional — unspecified values use defaults.

[server]

1
[server]
2
grpc_addr = "0.0.0.0:50051" # gRPC bind address
3
http_addr = "0.0.0.0:8001" # HTTP bind address (metrics + health)
4
max_concurrent_streams = 1000 # Maximum concurrent gRPC streams

[orchestrator]

1
[orchestrator]
2
max_workers = 100 # Maximum registered workers
3
max_concurrent_tasks = 1000 # Maximum concurrent task executions
4
heartbeat_timeout_secs = 90 # Worker heartbeat timeout

[storage]

1
[storage]
2
database_url = "postgresql://orcher:orcher@localhost:6432/orcher"
3
redis_url = "redis://localhost:6379" # Optional

Environment variables DATABASE_URL and REDIS_URL override these values.

[logging]

1
[logging]
2
level = "info" # trace, debug, info, warn, error
3
format = "json" # compact, json, pretty, bunyan

[health]

1
[health]
2
readiness_enabled = true # Enable /health/ready endpoint
3
liveness_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: 300
4
claim_timeout_secs = 300
5
6
# PostgreSQL claim query timeout (milliseconds). How long to wait for the claim query to execute.
7
claim_query_timeout_ms = 2000
8
9
# Long-poll timeout (seconds). Workers wait up to this duration for work to become available.
10
poll_timeout_secs = 60
11
12
# Background reclaim interval (seconds). How often to check for expired claims.
13
# Must be less than claim_timeout_secs.
14
reclaim_interval_secs = 10
15
16
# Enable notification-based wake-ups. Workers are notified immediately when work is available,
17
# so a worker need not wait out poll_timeout_secs.
18
enable_notifications = true
19
20
# Batch claim size. Claims multiple workflow executions in a single query.
21
# Reduces database contention with multiple workers. Recommended: 5-20.
22
batch_claim_size = 10
23
24
# Redis Streams (opt-in). Uses XADD/XREADGROUP instead of LPUSH/BRPOP.
25
# Enables zero-config horizontal scaling with consumer groups.
26
use_streams = false
27
28
# Sync-match dispatch (opt-in, requires use_streams = true and redis_url).
29
# Routes work directly to waiting workers via in-memory channels.
30
use_sync_match = false
31
32
# Maximum waiters per queue for sync-match. Limits memory usage.
33
max_waiters_per_queue = 10000
34
35
# Worker affinity for cache locality. Routes consecutive tasks from the same
36
# workflow to the same worker.
37
affinity_enabled = true
38
affinity_lease_secs = 30 # Affinity mapping duration
39
affinity_max_lease_secs = 300 # Maximum affinity duration (prevents imbalance)
40
41
# Cleanup interval for expired waiters and affinity leases (seconds)
42
routing_cleanup_interval_secs = 30

Validation rules:

  • claim_timeout_secs must be greater than reclaim_interval_secs
  • use_sync_match requires use_streams = true and redis_url to be configured
  • affinity_max_lease_secs must be >= affinity_lease_secs

[timeout_watcher]

Detects and handles task and workflow timeouts.

1
[timeout_watcher]
2
enabled = true # Enable timeout detection
3
poll_interval_secs = 30 # How often to check for timeouts
4
batch_size = 100 # Tasks to process per poll
5
grace_period_secs = 5 # Grace period before marking timeout
6
7
# Individual timeout types (all enabled by default)
8
enable_schedule_to_start = true # Tasks scheduled but never claimed
9
enable_start_to_close = true # Tasks started but never completed
10
enable_heartbeat = true # Long-running tasks that stopped heartbeating
11
enable_workflow_timeout = true # Workflows exceeding configured timeout

[workflow_retry]

Automatic retry scheduling for failed workflows with exponential backoff.

1
[workflow_retry]
2
enabled = true # Enable automatic retry scheduling
3
poll_interval_secs = 30 # How often to poll for failed workflows
4
batch_size = 50 # Workflows to process per poll
5
enable_realtime_notifications = false # LISTEN/NOTIFY for immediate retry
6
7
# Default retry policy (used when workflow doesn't specify its own)
8
default_max_attempts = 3 # Maximum retry attempts
9
default_initial_backoff_secs = 1 # First retry delay
10
default_backoff_multiplier = 2.0 # Exponential multiplier (must be >= 1.0)
11
default_max_backoff_secs = 300 # Maximum backoff cap (5 minutes)

[background_jobs]

Periodic maintenance tasks.

1
[background_jobs]
2
metrics_enabled = true # Enable metrics aggregation
3
metrics_interval_secs = 3600 # Aggregation interval (1 hour)
4
retention_enabled = true # Enable data retention cleanup
5
retention_interval_secs = 86400 # Cleanup interval (1 day)
6
7
[background_jobs.retention_days]
8
workflow_executions = 90 # Keep completed workflows for 90 days
9
execution_logs = 30 # Keep execution logs for 30 days
10
journal_entries = 90 # Keep journal entries for 90 days
11
task_executions = 90 # Keep task executions for 90 days
12
outbox_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"
3
auth_mode = "none"
4
5
# API key validation cache
6
api_key_cache_ttl_secs = 300 # Cache TTL (5 minutes)
7
api_key_cache_max_entries = 10000 # Maximum cached entries
8
9
# TLS configuration (required when auth_mode includes "mtls")
10
[security.tls]
11
cert_path = "/etc/orchestrator/tls/server.crt"
12
key_path = "/etc/orchestrator/tls/server.key"
13
ca_cert_path = "/etc/orchestrator/tls/ca.crt" # Required for client cert verification
14
require_client_cert = true

[queue] (Optional)

Queue-based task dispatch. Uncomment to enable.

1
[queue]
2
enabled = true
3
dispatch_strategy = "direct" # "direct", "queue", or "hybrid"
4
5
# Queue provider — choose one:
6
7
# Redis Streams
8
[queue.provider]
9
type = "redis"
10
url = "redis://localhost:6379"
11
pool_size = 10
12
consumer_group = "orchestrator"
13
14
# PostgreSQL-based queue
15
# [queue.provider]
16
# type = "postgres"
17
# url = "postgresql://localhost:5432/orcher"
18
# pool_size = 10
19
# table_name = "task_queue"

Next Steps