Configuration
Environment variables and config files for the proxy service.
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 docs/ENVIRONMENT_VARIABLES.md §9.
Required variables
| Parameter | Type | Description |
|---|---|---|
IBEX_AUTH_GRPC_ADDRRequired | string (host:port) | Auth service gRPC target for ValidateToken and ValidateAgent. Default: 127.0.0.1:9091 |
REDIS_URLRequired | string (URL) | Redis connection for org-level rate limiting. Required for /ready when set. |
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.
Correlation and errors
| Parameter | Type | Description |
|---|---|---|
IBEX_REQUEST_ID_HEADER | string | Inbound/outbound request ID header name. Default: X-Request-ID |
IBEX_TRACE_ID_HEADER | string | Trace ID response header name. Default: X-Trace-ID |
IBEX_ERROR_DOCS_BASE | string (URL) | Optional prefix for docs_url in JSON error envelopes. |
Observability
| Parameter | Type | Description |
|---|---|---|
OTEL_SERVICE_NAME | string | OpenTelemetry service.name resource attribute. Default: ibex-proxy |
OTEL_EXPORTER_OTLP_ENDPOINT | string (URL) | OTLP exporter endpoint; unset = no-op tracer. |
IBEX_LOG_LEVEL | string | Structured log verbosity (debug, info, warn, error). Default: info |
Example .env excerpt
IBEX_PORT=8080
IBEX_AUTH_GRPC_ADDR=127.0.0.1:9091
IBEX_AUTH_VALIDATE_TIMEOUT=2s
REDIS_URL=redis://localhost:6379/0
IBEX_MAX_REQUEST_BODY_BYTES=1048576
IBEX_RATE_LIMIT_DEFAULT_RPM=60
IBEX_LOG_LEVEL=debugSmoke-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 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 (auth), Redis (proxy rate limit).
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 Auth configuration.
Proxy
go run ./services/proxy/cmd/proxy with env from .env.
Verify configuration
curl -s http://localhost:8080/health | jq
curl -s http://localhost:8080/ready | jqExpected: /health returns {"status":"ok"}. /ready returns ok when auth gRPC and Redis are reachable.
Related
- Overview — middleware order and endpoint table
- Rate limiting — how RPM config maps to Redis
- Docker Compose — production-like local stack
- Environment variables — full cross-service registry
Was this page helpful?
Last updated on