Operations

Configuration Reference


The orchestrator is configured through environment variables, CLI flags, and an optional TOML config file. CLI flags take highest priority, then environment variables, then config file values, then built-in defaults.

  • Environment-first — All essential settings available as environment variables
  • TOML config file — Optional file-based configuration for complex deployments
  • Validation on startup — Invalid configuration fails fast with clear error messages
  • Sensible defaults — Works out of the box for development; tune for production

Orchestrator

The orchestrator is the central service that coordinates workflow execution, task scheduling, and worker polling. It is one process that serves both the gRPC API (SDKs, workers, CLI) and the REST API under /api/v1; there is no separate API service to deploy.

CLI Flags

1
orchestrator [OPTIONS]
2
3
Options:
4
-c, --config <FILE> TOML configuration file path [env: ORCHER_ORCHESTRATOR_CONFIG]
5
--grpc-addr <ADDR> gRPC server bind address [env: GRPC_BIND_ADDR]
6
--http-addr <ADDR> HTTP server bind address (REST API, health, metrics) [env: HTTP_BIND_ADDR]
7
--insecure Allow a non-loopback listener without authentication [env: ORCHER_INSECURE]
8
--database-url <URL> Database URL [env: DATABASE_URL]
9
--coordination-mode <MODE> Workflow coordination mode [env: COORDINATION_MODE]
10
--log-level <LEVEL> Log level [default: info] [env: LOG_LEVEL]
11
--log-format <FORMAT> Log format [default: compact] [env: LOG_FORMAT]
12
-V, --version Print version
13
-h, --help Print help

Environment Variables

Required

VariableDescription
DATABASE_URLPostgreSQL or PgBouncer connection string. Example: postgresql://orcher:orcher@localhost:6432/orcher

Server

VariableDefaultDescription
GRPC_BIND_ADDR127.0.0.1:50051gRPC server bind address for SDKs, workers and the CLI (the Docker image uses 0.0.0.0:50051)
HTTP_BIND_ADDR127.0.0.1:8080HTTP server: REST API (/api/v1), health (/health, /health/ready, /health/live) and metrics (/metrics). The Docker image uses 0.0.0.0:8080
ORCHER_ORCHESTRATOR_CONFIG—Path to the TOML config file (also --config)
ORCHER_INSECUREfalseAllow listening on a non-loopback address without authentication (also --insecure)

Storage

VariableDefaultDescription
DATABASE_URL—PostgreSQL connection string (required). PostgreSQL is the only data store the orchestrator uses

Logging

VariableDefaultDescription
LOG_LEVELinfoLog level: trace, debug, info, warn, error
LOG_FORMATcompactOutput format: compact, json, pretty, bunyan
RUST_LOG—Fine-grained per-crate filter (overrides LOG_LEVEL when set)

Polling

VariableDefaultDescription
ORCHER_USE_SYNC_MATCHfalseEnable sync-match dispatch for lower hand-off latency

Authentication

REST and gRPC share one authentication layer, configured in the [security] section of the TOML config:

1
[security]
2
auth_mode = "api-key" # none | api-key | oidc | mtls | api-key-and-mtls
3
tenancy = "single" # single | multi

For auth_mode = "oidc", add a [security.oidc] table with issuer, audience, organization_claim and scopes_claim.

  • Without authentication the orchestrator refuses to listen on a non-loopback gRPC or HTTP address unless you pass --insecure or set ORCHER_INSECURE=true.
  • When auth_mode requires a client certificate (mtls, api-key-and-mtls), the orchestrator serves no REST API.
  • Create the first API key with orchestrator api-key create --name admin --scope '*' (the key is printed once on stdout). Scopes: workflows:read, workflows:write, workers:run, namespaces:manage, api-keys:manage, *.

Scaling the REST API

Every orchestrator serves the REST API, so to scale it, run several orchestrator replicas behind a load balancer. See High Availability.


Next Steps