Configuration

This page defines runtime configuration for orlojd, orlojworker, and client-side defaults for orlojctl (see also CLI reference).

Precedence

1. CLI flags
2. Environment variable fallback
3. Code defaults

Example:

• --model-gateway-provider overrides ORLOJ_MODEL_GATEWAY_PROVIDER.
• If neither is set, default is mock.

Core Environment Variables

Server Flags

Print full options:

go run ./cmd/orlojd -h

High-impact groups:

• API/server: --addr
• storage: --storage-backend, --postgres-dsn, pool sizing flags
• execution: --task-execution-mode, embedded worker/lease controls, --embedded-worker-max-concurrent-tasks
• model gateway: provider, API key, timeout, base URL, default model
• tool runtime: isolation mode, container and wasm controls
• buses: server event bus and runtime message bus flags

Worker Flags

Print full options:

go run ./cmd/orlojworker -h

High-impact groups:

• identity/capacity: --worker-id, --region, --gpu, --supported-models, --max-concurrent-tasks
• storage: same postgres flags as server
• execution: --task-execution-mode, --agent-message-consume, runtime consumer controls
• model/tool runtime: provider and isolation flags

Secret Resolution

Model endpoints and tools reference secrets via secretRef fields. The runtime resolves secrets using a chain of resolvers:

1. Resource store -- looks up a Secret resource by name.
2. Environment variables -- looks up ORLOJ_SECRET_<name> (prefix is configurable with --model-secret-env-prefix and --tool-secret-env-prefix).

Encryption at Rest

Pass --secret-encryption-key (or set ORLOJ_SECRET_ENCRYPTION_KEY) on both orlojd and orlojworker to encrypt Secret.spec.data values in the database using AES-256-GCM. The same key must be used by all processes sharing the database. See Security and Isolation -- Encryption at Rest for key generation and usage.

Postgres Tuning

Connection Pool (main store)

The main Postgres pool is configured via CLI flags:

Idle connections are evicted after 5 minutes to avoid stale TCP connections behind firewalls or load balancers.

Connection Pool (pgvector memory backend)

The pgvector memory backend uses a separate pgxpool connection pool created from the Memory resource's spec.endpoint DSN. Pool behavior can be tuned by appending query parameters to the endpoint URL:

postgres://user:pass@host:5432/db?pool_max_conns=10&pool_min_conns=2&pool_max_conn_idle_time=5m&pool_health_check_period=1m

Statement Timeout

Neither the main store nor the pgvector backend sets a statement_timeout by default. To protect against runaway queries, add it to the DSN:

# Main store (30-second statement timeout)
--postgres-dsn="postgres://user:pass@host:5432/db?options=-c%20statement_timeout%3D30000"
 
# pgvector memory endpoint (in the Memory resource spec.endpoint)
postgres://user:pass@host:5432/db?options=-c%20statement_timeout%3D30000&pool_max_conns=10

The statement_timeout value is in milliseconds. Postgres cancels any single statement that exceeds this limit.

Recommended Production Baseline

• orlojd: --storage-backend=postgres, --task-execution-mode=message-driven, --agent-message-bus-backend=nats-jetstream
• orlojworker: --storage-backend=postgres, --task-execution-mode=message-driven, --agent-message-consume
• Enable --secret-encryption-key on all processes if using Secret resources
• Set provider keys via ORLOJ_SECRET_* environment variables or an external secret manager
• Set OTEL_EXPORTER_OTLP_ENDPOINT to your tracing backend (Jaeger, Tempo, etc.) for distributed trace collection
• See Observability for the full tracing, metrics, and logging setup

Verification

curl -s http://127.0.0.1:8080/healthz | jq .
go run ./cmd/orlojctl get workers
go run ./cmd/orlojctl get tasks