Configuration

This page is the canonical reference for runtime environment variables and flag-to-env precedence for orlojd, orlojworker, and orlojctl.

See also CLI reference for exhaustive flag definitions.

Precedence

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

Example:

• --task-execution-mode overrides ORLOJ_TASK_EXECUTION_MODE.
• If neither is set, code defaults apply.

Runtime Environment Matrix

Server and Worker Flags

Use CLI reference as the exhaustive list for all flags and defaults.

Quick grouping:

• Server (orlojd): auth, storage, embedded worker, control-plane event bus, runtime message bus, model secret resolution, tool isolation.
• Worker (orlojworker): identity/capacity, storage, runtime inbox consumers, model secret resolution, tool isolation.

Web Console Path

By default, orlojd serves the built-in web console at the root path (/). The REST API lives under /v1/..., /healthz, and /metrics, so there is no collision.

To mount the console at a subpath instead (useful when multiple services share a single reverse proxy hostname):

# Serve the console at https://tools.example.com/orloj/
orlojd --ui-path=/orloj/
# or
ORLOJ_UI_PATH=/orloj/ orlojd

The value is normalized to always have a leading and trailing /. Client-side routes (e.g. /tasks/my-task) are served via SPA fallback so browser refreshes work at any depth.

When using a custom DNS (e.g. console.example.com), you typically do not need to set ORLOJ_UI_PATH — the default / means the console is at https://console.example.com/. Point your DNS and reverse proxy at orlojd and everything works.

Secret Resolution

Model endpoints and tools resolve secretRef values in this order:

1. Secret resources in the control-plane store.
2. Environment variables with configurable prefixes (ORLOJ_SECRET_<name> by default).

Encryption at Rest

Set --secret-encryption-key (or ORLOJ_SECRET_ENCRYPTION_KEY) on every process sharing the same backing store.

• Use one consistent key for all orlojd/orlojworker processes against the same database.
• On orlojd, the same key also protects the persisted SealedSecret private key.
• Rotating keys requires a migration procedure (see security/upgrade runbooks).

Postgres Tuning

Connection Pool (main store)

The main Postgres pool is configured via CLI flags:

Idle connections are evicted after 5 minutes to reduce stale TCP connection risk behind firewalls/load balancers.

Connection Pool (pgvector memory backend)

The pgvector backend uses a separate pgxpool created from the Memory resource spec.endpoint DSN. Tune it with DSN params:

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 pgvector backend sets statement_timeout by default. Add it via DSN options:

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

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 when using Secret resources
• Configure model/tool credentials via ORLOJ_SECRET_<name> or external secret management
• Set OTEL_EXPORTER_OTLP_ENDPOINT for distributed tracing
• See Observability for tracing, metrics, and logs setup

Verification

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