Orchestrator Configuration
Orchestrator Environment Variables
The orchestrator is one process that serves both the gRPC API and the REST API, so there is a single set of settings.
| Variable | Default | Description |
|---|---|---|
DATABASE_URL | (required) | PostgreSQL connection string |
GRPC_BIND_ADDR | 127.0.0.1:50051 | gRPC listener (SDKs, workers, CLI); also --grpc-addr. The Docker image uses 0.0.0.0:50051 |
HTTP_BIND_ADDR | 127.0.0.1:8080 | HTTP listener: REST API under /api/v1, /health, /health/ready, /health/live, /metrics; also --http-addr. The Docker image uses 0.0.0.0:8080 |
ORCHER_ORCHESTRATOR_CONFIG | — | Path to the TOML config file; also --config |
ORCHER_INSECURE | false | Allow listening on a non-loopback address without authentication; also --insecure |
LOG_LEVEL | info | Log level: trace, debug, info, warn, error |
LOG_FORMAT | pretty | Log format: json, pretty |
Authentication
REST and gRPC share one authentication layer, configured in the [security] section of the TOML config:
1[security]2auth_mode = "api-key" # none | api-key | oidc | mtls | api-key-and-mtls3tenancy = "single" # single | multi45# Only for auth_mode = "oidc"6# [security.oidc]7# issuer = "https://auth.example.com"8# audience = "orcher"9# organization_claim = "org_id"10# scopes_claim = "scope"- Without authentication, the orchestrator refuses to listen on a non-loopback gRPC or HTTP address unless you pass
--insecureor setORCHER_INSECURE=true. - When
auth_moderequires a client certificate (mtlsorapi-key-and-mtls), the orchestrator serves no REST API. - Create the first API key with
orchestrator api-key create --name admin --scope '*'; it prints the key once on stdout. After that, manage keys withorcher api-key create|list|get|revokeor the/api/v1/api-keysendpoints (scopeapi-keys:manage).
Database Connection
PostgreSQL is the exclusive backend. For production, use PgBouncer for connection multiplexing:
1# Direct connection2DATABASE_URL=postgresql://orcher:orcher@localhost:5432/orcher34# Via PgBouncer (recommended for production)5DATABASE_URL=postgresql://orcher:orcher@localhost:6432/orcherThe orchestrator uses a pool of up to 80 connections with a statement cache of 256 prepared statements.
Next Steps
- Orchestrator Overview — Architecture and components
- Deployment — Starting the server in development, Docker, and systemd
- High Availability — Multi-instance deployment and load balancing
- Monitoring — Health checks, performance tuning, and troubleshooting