Environment variables

IBEX services load configuration from environment variables at startup via packages/config. Missing required values fail fast with a clear message — there are no checked-in .env files, only .env.example per service.

Conventions

Prefix IBEX_ for project-wide settings; POSTGRES_ / REDIS_ / CLICKHOUSE_ / OPENAI_ for infrastructure and providers.
Secrets (DSNs, API keys, Redis passwords) never belong in git — inject via your secret manager.
Precedence: process env → .env file (local only) → documented defaults.

Proxy

Parameter	Type	Description
`IBEX_AUTH_GRPC_ADDR`Required	`string (host:port)`	Auth gRPC target for ValidateToken and ValidateAgent. Default: 127.0.0.1:9091
`REDIS_URL`	`string (URL)`	Redis for rate limiting, auth-cache revocation subscribe, idempotency, and /ready. Empty uses Noop limiter. Default: (empty)
`POSTGRES_DSN`	`string (postgres://…)`	Enables directives and sessions on the proxy. Empty → Noop stores. Default: (empty)
`IBEX_LLM_MODE`	`enum`	`mock` (default stub) or `live` (requires OPENAI_API_KEY). Mock forbidden in production. Default: mock
`OPENAI_API_KEY`	`string`	Required when IBEX_LLM_MODE=live.
`OPENAI_BASE_URL`	`string (URL)`	OpenAI-compatible API base URL. Default: https://api.openai.com/v1
`IBEX_AUTH_CACHE_ENABLED`	`boolean`	Enable bloom+LRU auth cache when Redis is healthy. Default: true
`IBEX_PORT`	`integer`	HTTP listen port for /health, /ready, /metrics, and /v1/* routes. Default: 8080
`IBEX_AUTH_VALIDATE_TIMEOUT`	`duration`	Per-request auth gRPC budget. Use 2s locally; production target is 50ms. Default: 50ms (code); 2s in .env.example
`IBEX_RATE_LIMIT_DEFAULT_RPM`	`integer`	Default org requests-per-minute when Redis is available. Default: 60
`IBEX_MAX_REQUEST_BODY_BYTES`	`integer`	Max chat POST body size (see ADR-0013). Default: 1048576
`IBEX_IDEMPOTENCY_TTL`	`duration`	Idempotency-Key retention for non-streaming chat. Default: 24h
`CLICKHOUSE_DSN`	`string`	Enables async llm_traces. Empty disables writer (fail-open). Default: (empty)
`IBEX_ERROR_DOCS_BASE`	`string (URL)`	Optional base for error envelope docs_url fields. Default: (omit in dev)

Copy services/proxy/.env.example and services/auth/.env.example before running services. More knobs (session sweep, OpenAI retries, cache bloom size): Proxy configuration.

Auth

Parameter	Type	Description
`POSTGRES_DSN`Required	`string (postgres://…)`	Postgres for tokens and agents. Compose: postgres://ibex:ibex@localhost:5432/ibex
`REDIS_URL`	`string (URL)`	Publish token revocations (`ibex:token:revocations`) and ValidateToken RPM. Empty → Noop publisher. Default: (empty)
`IBEX_PORT`	`integer`	HTTP port for /health, /ready, and /metrics. Default: 8081
`IBEX_GRPC_PORT`	`integer`	gRPC listen port for AuthService (internal only). Default: 9091
`IBEX_AUTH_VALIDATE_RPM`	`integer`	ValidateToken rate limit when Redis is set. Default: 6000
`POSTGRES_TEST_DSN`	`string`	Integration tests on compose test port 5433. Default: postgres://ibex:ibex@localhost:5433/ibex_test?sslmode=disable

Run make db-migrate after compose is healthy.

Redis

Parameter	Type	Description
`REDIS_URL`	`string (URL)`	Primary connection string, e.g. redis://localhost:6379/0. Default: redis://localhost:6379/0
`REDIS_CONNECT_TIMEOUT_MS`	`integer`	Connection timeout on the critical path. Default: 200
`REDIS_TLS_ENABLED`	`boolean`	Enable TLS for managed Redis in staging/production. Default: false

ClickHouse (optional traces)

Parameter	Type	Description
`CLICKHOUSE_DSN`	`string`	HTTP DSN for async llm_traces inserts. Default: (empty / disabled)
`CLICKHOUSE_INSERT_BATCH_SIZE`	`integer`	Rows per insert batch. Default: 500
`CLICKHOUSE_INSERT_FLUSH_MS`	`integer`	Flush interval in milliseconds. Default: 200

Every analytics query must filter org_id — see Traces and ClickHouse.

Local `.env` layout

bash

cp services/proxy/.env.example services/proxy/.env
cp services/auth/.env.example services/auth/.env

Was this page helpful?

Proxy

Parameter	Type	Description
`IBEX_AUTH_GRPC_ADDR`Required	`string (host:port)`	Auth gRPC target for ValidateToken and ValidateAgent. Default: 127.0.0.1:9091
`REDIS_URL`	`string (URL)`	Redis for rate limiting, auth-cache revocation subscribe, idempotency, and /ready. Empty uses Noop limiter. Default: (empty)
`POSTGRES_DSN`	`string (postgres://…)`	Enables directives and sessions on the proxy. Empty → Noop stores. Default: (empty)
`IBEX_LLM_MODE`	`enum`	`mock` (default stub) or `live` (requires OPENAI_API_KEY). Mock forbidden in production. Default: mock
`OPENAI_API_KEY`	`string`	Required when IBEX_LLM_MODE=live.
`OPENAI_BASE_URL`	`string (URL)`	OpenAI-compatible API base URL. Default: https://api.openai.com/v1
`IBEX_AUTH_CACHE_ENABLED`	`boolean`	Enable bloom+LRU auth cache when Redis is healthy. Default: true
`IBEX_PORT`	`integer`	HTTP listen port for /health, /ready, /metrics, and /v1/* routes. Default: 8080
`IBEX_AUTH_VALIDATE_TIMEOUT`	`duration`	Per-request auth gRPC budget. Use 2s locally; production target is 50ms. Default: 50ms (code); 2s in .env.example
`IBEX_RATE_LIMIT_DEFAULT_RPM`	`integer`	Default org requests-per-minute when Redis is available. Default: 60
`IBEX_MAX_REQUEST_BODY_BYTES`	`integer`	Max chat POST body size (see ADR-0013). Default: 1048576
`IBEX_IDEMPOTENCY_TTL`	`duration`	Idempotency-Key retention for non-streaming chat. Default: 24h
`CLICKHOUSE_DSN`	`string`	Enables async llm_traces. Empty disables writer (fail-open). Default: (empty)
`IBEX_ERROR_DOCS_BASE`	`string (URL)`	Optional base for error envelope docs_url fields. Default: (omit in dev)

Copy services/proxy/.env.example and services/auth/.env.example before running services. More knobs (session sweep, OpenAI retries, cache bloom size): Proxy configuration.

Auth

Parameter	Type	Description
`POSTGRES_DSN`Required	`string (postgres://…)`	Postgres for tokens and agents. Compose: postgres://ibex:ibex@localhost:5432/ibex
`REDIS_URL`	`string (URL)`	Publish token revocations (`ibex:token:revocations`) and ValidateToken RPM. Empty → Noop publisher. Default: (empty)
`IBEX_PORT`	`integer`	HTTP port for /health, /ready, and /metrics. Default: 8081
`IBEX_GRPC_PORT`	`integer`	gRPC listen port for AuthService (internal only). Default: 9091
`IBEX_AUTH_VALIDATE_RPM`	`integer`	ValidateToken rate limit when Redis is set. Default: 6000
`POSTGRES_TEST_DSN`	`string`	Integration tests on compose test port 5433. Default: postgres://ibex:ibex@localhost:5433/ibex_test?sslmode=disable

Run make db-migrate after compose is healthy.

Redis

Parameter	Type	Description
`REDIS_URL`	`string (URL)`	Primary connection string, e.g. redis://localhost:6379/0. Default: redis://localhost:6379/0
`REDIS_CONNECT_TIMEOUT_MS`	`integer`	Connection timeout on the critical path. Default: 200
`REDIS_TLS_ENABLED`	`boolean`	Enable TLS for managed Redis in staging/production. Default: false

ClickHouse (optional traces)

Parameter	Type	Description
`CLICKHOUSE_DSN`	`string`	HTTP DSN for async llm_traces inserts. Default: (empty / disabled)
`CLICKHOUSE_INSERT_BATCH_SIZE`	`integer`	Rows per insert batch. Default: 500
`CLICKHOUSE_INSERT_FLUSH_MS`	`integer`	Flush interval in milliseconds. Default: 200

Every analytics query must filter org_id — see Traces and ClickHouse.