Configuration

The proxy loads configuration from environment variables at startup via packages/config. There is no config.yaml — missing required values panic with a clear message so misconfiguration surfaces before the first request, not during traffic.

Copy services/proxy/.env.example to services/proxy/.env for local development. The canonical registry is web/engineering/ENVIRONMENT_VARIABLES.md §9–10.

Required variables

Parameter	Type	Description
`IBEX_AUTH_GRPC_ADDR`Required	`string (host:port)`	Auth service gRPC target for ValidateToken and ValidateAgent. Default: 127.0.0.1:9091
`REDIS_URL`Required	`string (URL)`	Redis for rate limiting, auth-cache revocation subscribe, idempotency, and /ready.

Provider modes

Parameter	Type	Description
`IBEX_LLM_MODE`	`enum`	`mock` (in-process stub, default) or `live` (OpenAI-compatible forward). Mock is forbidden when IBEX_ENV=production. Default: mock
`OPENAI_API_KEY`	`string`	Required when IBEX_LLM_MODE=live.
`OPENAI_BASE_URL`	`string (URL)`	OpenAI-compatible API base. Default: https://api.openai.com/v1
`IBEX_LLM_EXTRA_MODELS`	`string`	Comma-separated extra model ids registered for routing.

Postgres features (directives / sessions)

Parameter	Type	Description
`POSTGRES_DSN`	`string (postgres://…)`	Enables directive load and session store. Empty → Noop directive/session behavior.
`IBEX_DIRECTIVE_CACHE_TTL`	`duration`	Directive Redis cache TTL. Default: 60s
`IBEX_SESSION_CACHE_TTL`	`duration`	Session Redis cache TTL. Default: 60s
`IBEX_SESSION_IDLE_TIMEOUT`	`duration`	Idle session sweeper threshold. Default: 45m

Auth cache

Parameter	Type	Description
`IBEX_AUTH_CACHE_ENABLED`	`boolean`	Wrap ValidateToken with bloom+LRU when Redis is healthy. Skipped (WARN) if Redis URL empty or Ping fails. Default: true

See Auth caching.

Idempotency and traces

Parameter	Type	Description
`IBEX_IDEMPOTENCY_TTL`	`duration`	Redis Idempotency-Key TTL for non-streaming chat. Default: 24h
`CLICKHOUSE_DSN`	`string`	Empty disables async llm_traces writer (fail-open).
`CLICKHOUSE_INSERT_BATCH_SIZE`	`integer`	Trace batch size before flush. Default: 500
`CLICKHOUSE_INSERT_FLUSH_MS`	`integer`	Max flush interval in milliseconds. Default: 200

HTTP and auth tuning

Parameter	Type	Description
`IBEX_PORT`	`integer`	HTTP listen port. Default: 8080
`IBEX_AUTH_VALIDATE_TIMEOUT`	`duration`	Per-request ValidateToken deadline. Default: 50ms (2s in .env.example)
`IBEX_MAX_REQUEST_BODY_BYTES`	`integer`	Maximum chat completion JSON body size. Default: 1048576 (1 MiB)
`IBEX_SHUTDOWN_TIMEOUT`	`duration`	Graceful drain window on SIGTERM. Default: 30s

Rate limiting

Parameter	Type	Description
`IBEX_RATE_LIMIT_DEFAULT_RPM`	`integer`	Requests per minute for orgs without an override. Default: 60
`IBEX_RATE_LIMIT_ORG_OVERRIDES`	`string`	Comma-separated org_uuid=rpm pairs for tenant-specific budgets.

Redis keys follow ratelimit:{org_id}:rpm:{unix_minute} — org_id is always the second segment per Tenant isolation.

Example `.env` excerpt

services/proxy/.env

IBEX_PORT=8080
IBEX_AUTH_GRPC_ADDR=127.0.0.1:9091
IBEX_AUTH_VALIDATE_TIMEOUT=2s
IBEX_LLM_MODE=mock
REDIS_URL=redis://localhost:6379/0
POSTGRES_DSN=postgres://ibex:ibex@localhost:5432/ibex?sslmode=disable
IBEX_MAX_REQUEST_BODY_BYTES=1048576
IBEX_RATE_LIMIT_DEFAULT_RPM=60
IBEX_LOG_LEVEL=debug

Smoke-test convenience variables (IBEX_DEV_TOKEN, IBEX_DEV_AGENT_ID) are documented in .env.example but are not read by the proxy binary — they exist for make dev-smoke only.

Readiness dependencies

GET /ready reports critical dependency health:

Check	When evaluated	Failure impact
`auth_grpc`	Always	Orchestrator should not route traffic
`redis`	When `REDIS_URL` is set	Rate limiter / cache degraded; requests still allowed

Liveness (GET /health) does not probe dependencies — use it for process-up checks only. Details: ADR-0022.

Boot order

Infrastructure

make compose-dev-up — Postgres, Redis, optional ClickHouse.

Migrations and seed

make db-migrate && make db-seed — org, agent, and dev PAT for smoke tests.

Auth first

Start auth on gRPC 9091 before the proxy. See Environment variables.

Proxy

go run ./services/proxy/cmd/proxy with env from .env.

Verify configuration

bash

curl -s http://localhost:8080/health | jq
curl -s http://localhost:8080/ready | jq

Expected: /health returns {"status":"ok"}. /ready returns ok when auth gRPC and Redis are reachable.

Overview — middleware order and endpoint table
Rate limiting — how RPM config maps to Redis
Docker Compose — production-like local stack
Environment variables — integrator registry

Was this page helpful?

Copy services/proxy/.env.example to services/proxy/.env for local development. The canonical registry is web/engineering/ENVIRONMENT_VARIABLES.md §9–10.

Required variables

Parameter	Type	Description
`IBEX_AUTH_GRPC_ADDR`Required	`string (host:port)`	Auth service gRPC target for ValidateToken and ValidateAgent. Default: 127.0.0.1:9091
`REDIS_URL`Required	`string (URL)`	Redis for rate limiting, auth-cache revocation subscribe, idempotency, and /ready.

Provider modes

Parameter	Type	Description
`IBEX_LLM_MODE`	`enum`	`mock` (in-process stub, default) or `live` (OpenAI-compatible forward). Mock is forbidden when IBEX_ENV=production. Default: mock
`OPENAI_API_KEY`	`string`	Required when IBEX_LLM_MODE=live.
`OPENAI_BASE_URL`	`string (URL)`	OpenAI-compatible API base. Default: https://api.openai.com/v1
`IBEX_LLM_EXTRA_MODELS`	`string`	Comma-separated extra model ids registered for routing.

Postgres features (directives / sessions)

Parameter	Type	Description
`POSTGRES_DSN`	`string (postgres://…)`	Enables directive load and session store. Empty → Noop directive/session behavior.
`IBEX_DIRECTIVE_CACHE_TTL`	`duration`	Directive Redis cache TTL. Default: 60s
`IBEX_SESSION_CACHE_TTL`	`duration`	Session Redis cache TTL. Default: 60s
`IBEX_SESSION_IDLE_TIMEOUT`	`duration`	Idle session sweeper threshold. Default: 45m

Auth cache

Parameter	Type	Description
`IBEX_AUTH_CACHE_ENABLED`	`boolean`	Wrap ValidateToken with bloom+LRU when Redis is healthy. Skipped (WARN) if Redis URL empty or Ping fails. Default: true

See Auth caching.

Idempotency and traces

Parameter	Type	Description
`IBEX_IDEMPOTENCY_TTL`	`duration`	Redis Idempotency-Key TTL for non-streaming chat. Default: 24h
`CLICKHOUSE_DSN`	`string`	Empty disables async llm_traces writer (fail-open).
`CLICKHOUSE_INSERT_BATCH_SIZE`	`integer`	Trace batch size before flush. Default: 500
`CLICKHOUSE_INSERT_FLUSH_MS`	`integer`	Max flush interval in milliseconds. Default: 200

HTTP and auth tuning

Parameter	Type	Description
`IBEX_PORT`	`integer`	HTTP listen port. Default: 8080
`IBEX_AUTH_VALIDATE_TIMEOUT`	`duration`	Per-request ValidateToken deadline. Default: 50ms (2s in .env.example)
`IBEX_MAX_REQUEST_BODY_BYTES`	`integer`	Maximum chat completion JSON body size. Default: 1048576 (1 MiB)
`IBEX_SHUTDOWN_TIMEOUT`	`duration`	Graceful drain window on SIGTERM. Default: 30s

Rate limiting

Parameter	Type	Description
`IBEX_RATE_LIMIT_DEFAULT_RPM`	`integer`	Requests per minute for orgs without an override. Default: 60
`IBEX_RATE_LIMIT_ORG_OVERRIDES`	`string`	Comma-separated org_uuid=rpm pairs for tenant-specific budgets.

Redis keys follow ratelimit:{org_id}:rpm:{unix_minute} — org_id is always the second segment per Tenant isolation.

Example `.env` excerpt

services/proxy/.env

IBEX_PORT=8080
IBEX_AUTH_GRPC_ADDR=127.0.0.1:9091
IBEX_AUTH_VALIDATE_TIMEOUT=2s
IBEX_LLM_MODE=mock
REDIS_URL=redis://localhost:6379/0
POSTGRES_DSN=postgres://ibex:ibex@localhost:5432/ibex?sslmode=disable
IBEX_MAX_REQUEST_BODY_BYTES=1048576
IBEX_RATE_LIMIT_DEFAULT_RPM=60
IBEX_LOG_LEVEL=debug

Smoke-test convenience variables (IBEX_DEV_TOKEN, IBEX_DEV_AGENT_ID) are documented in .env.example but are not read by the proxy binary — they exist for make dev-smoke only.

Readiness dependencies

GET /ready reports critical dependency health:

Check	When evaluated	Failure impact
`auth_grpc`	Always	Orchestrator should not route traffic
`redis`	When `REDIS_URL` is set	Rate limiter / cache degraded; requests still allowed

Liveness (GET /health) does not probe dependencies — use it for process-up checks only. Details: ADR-0022.

Boot order

Infrastructure

make compose-dev-up — Postgres, Redis, optional ClickHouse.

Migrations and seed

make db-migrate && make db-seed — org, agent, and dev PAT for smoke tests.

Auth first

Start auth on gRPC 9091 before the proxy. See Environment variables.

Proxy

go run ./services/proxy/cmd/proxy with env from .env.

Verify configuration

bash

curl -s http://localhost:8080/health | jq
curl -s http://localhost:8080/ready | jq

Expected: /health returns {"status":"ok"}. /ready returns ok when auth gRPC and Redis are reachable.

Overview — middleware order and endpoint table
Rate limiting — how RPM config maps to Redis
Docker Compose — production-like local stack
Environment variables — integrator registry

Was this page helpful?