Configuration Reference

Every Eparch service is configured entirely through environment variables, read at startup by each service’s config.Load(). This page consolidates the meaningful variables across all services, grouped by concern, with defaults and which services read each one.

Conventions

Defaults shown are the code defaults. In the compose files most inter-service values are set to container DNS names (e.g. postgres:5432, redis:6379, http://opa:8181); the code defaults target localhost for local dev.
Required means config.Load() returns an error (the service refuses to start) if the value is missing.
“All services” = gateway, identity, agent-runtime, rag, eval, tool-registry, tenant, event-broker, audit, agent-config.

General

Variable	Default	Services	Description
`ENV`	`local`	All	Runtime environment. `local` relaxes several checks: the gateway may use its built-in mock upstream (see `LLM_USE_MOCK`) and does not require `LLM_EMBEDDING_URL`; identity allows insecure cookies. Any other value (`prod`, `stage`) enables fail-fast validation.
`EPARCH_SERVICES`	—	monolith only	Comma-separated list of data-plane services to run in the single `eparch` process (monolith deployment). Excludes `identity`.

Database (PostgreSQL)

Variable	Default	Services	Description
`POSTGRES_URL`	— (required)	All except agent-runtime¹	Postgres DSN. Runtime services connect as the non-superuser `eparch_app` role so RLS is enforced; `identity` and the migration job connect as the `eparch` superuser (identity’s login flow resolves a user’s tenant before RLS can scope it). Local dev uses database `eparch_dev`; the compose deployments use `eparch`.
`AGENT_RUNTIME_DB_READONLY_URL`	—	agent-runtime	Optional read-only DSN for the native `platform-postgres-query` tool. When set, it authenticates as the SELECT-only `eparch_readonly` role so agent/LLM-driven SQL is read-only at the DB-privilege level. Unset → falls back to the read-write pool.

¹ agent-runtime treats POSTGRES_URL as optional and starts without it (it persists execution state in a later phase); every other service requires it.

Ports

Variable	Default	Services	Description
`GRPC_PORT`	per service²	All	gRPC listen port.
`HTTP_PORT`	`8031` (gateway), `8011` (identity)	gateway, identity	HTTP listen port. Gateway HTTP serves the public REST API, chat/SSE, `/healthz`, `/readyz`, `/metrics`. Identity HTTP serves OIDC login and JWKS.
`METRICS_PORT`	`9090`	gateway	Prometheus metrics endpoint port.

² gRPC defaults: gateway 8030, identity 8010, agent-runtime 8001, rag 8040, eval 8045, tool-registry 8050, tenant 8055, event-broker 8060, audit 8070, agent-config 8086.

Platform JWT validation (all services)

Every service validates inbound platform JWTs and authorizes via OPA.

Variable	Default	Services	Description
`JWT_ISSUER`	`http://localhost:8011`	All	Expected `iss` claim. Must match the identity issuer exactly. Required at the gateway.
`JWKS_URL`	`http://localhost:8011/.well-known/jwks.json`	All	Identity’s public-key endpoint for verifying JWT signatures. Required at the gateway.
`OPA_ADDR`	`http://localhost:8181`	All	Base URL of the OPA policy server.

The identity service mints the platform’s own RS256 JWTs and brokers user login.

Signing keys

Variable	Default	Description
`JWT_RSA_PRIVATE_KEY`	—	PEM PKCS#1 RSA private key used to sign platform JWTs. Empty disables signing (OIDC login returns 500).
`JWT_KID`	`dev-1`	Key ID embedded in issued token headers for JWKS lookup.
`JWT_AUDIENCE`	—	Expected/issued `aud` claim. Empty omits `aud` on issue and disables `aud` validation. Set it on the issuer and validators together to enable audience checks.
`JWT_RSA_PRIVATE_KEY_NEXT`	—	Optional second signing key for zero-downtime JWKS rotation. Its public key is published in the JWKS; signing stays on the current key until promoted.
`JWT_KID_NEXT`	—	Key ID for the rotation key above.
`JWT_ACCESS_TTL`	`15m`	Access-token lifetime (Go duration, e.g. `15m`, `1h`).
`SECURE_COOKIES`	`true`	Set `false` only on plain-HTTP localhost.

Dev note: make dev-local generates infra/dev/jwt-dev-key.pem and the Makefile loads it into JWT_RSA_PRIVATE_KEY via JWT_RSA_PRIVATE_KEY_FILE in .env.local.

Variable	Default	Description
`WORKOS_API_KEY`	—	WorkOS secret API key. Required where login is exercised; empty disables AuthKit calls.
`WORKOS_CLIENT_ID`	—	WorkOS project client ID.
`WORKOS_REDIRECT_URI`	`http://localhost:8011/oidc/callback`	Must match the callback URL registered in the WorkOS dashboard.

Local auth (coming). A self-hosted local-auth mode is being added in parallel so login does not require an external provider. Until it lands, WorkOS AuthKit is the default; leave the WORKOS_* values blank in local dev to run without a real upstream login.

Self-serve onboarding (identity)

Variable	Default	Description
`PUBLIC_EMAIL_DOMAINS`	—	Comma-separated domains that always get a personal workspace (extends the built-in consumer list).
`SELF_SERVE_SIGNUP`	`true`	Gate org-less first logins.
`SELF_SERVE_DOMAIN_MODE`	`open`	`open` or `deny-corporate`.
`WORKOS_ADMIN_ROLE_SLUG`	`admin`	Role slug granted to an org creator.
`WORKOS_MEMBER_ROLE_SLUG`	`member`	Role slug granted to a joiner.

Generic upstream OIDC (identity)

The generic OIDC brokering path (used before/alongside WorkOS). Set these when brokering to a standards OIDC IdP instead of WorkOS.

Variable	Default	Description
`IDP_ISSUER`	`http://localhost:5556/dex`	OIDC issuer URL for container-internal calls (token, introspection).
`IDP_ISSUER_BROWSER`	(falls back to `IDP_ISSUER`)	Browser-resolvable issuer for the authorization redirect.
`IDP_CLIENT_ID`	`eparch-identity`	OAuth2 client ID registered with the IdP.
`IDP_CLIENT_SECRET`	`eparch-identity-secret`	OAuth2 client secret.
`IDP_REDIRECT_URI`	`http://localhost:8011/oidc/callback`	Must match the URI registered with the IdP.
`IDP_JWKS_URL`	`${IDP_ISSUER}/keys`	IdP JWKS endpoint for verifying `id_token` signatures.
`IDP_AUTH_URL`	—	Override the authorization endpoint path (some IdPs use non-standard paths).
`IDP_TOKEN_URL`	—	Override the token endpoint path.

LLM gateway

Configured on the gateway service (the OpenAI-compatible upstream) and the rag/tool-registry services (which call the gateway internally). See model-providers.md for how to point these at a self-hosted vLLM/Ollama backend.

Variable	Default	Services	Description
`LLM_CONFIG`	—	gateway	Path to a `models.yaml` for multi-provider routing. When empty, a single upstream is synthesized from the vars below. See model-providers.md.
`LLM_GATEWAY_URL`	`http://localhost:8000/v1/chat/completions`	gateway	Upstream chat/completions endpoint (OpenAI-compatible). Point at your vLLM/Ollama/TGI/DigitalOcean/OpenAI server.
`LLM_EMBEDDING_URL`	—	gateway	Upstream embeddings endpoint (OpenAI-compatible). Empty returns stub zero-vectors in `local`; required when `ENV != local`.
`LLM_RERANK_URL`	—	gateway	Upstream reranker endpoint. Empty falls back to score-based ordering.
`LLM_API_KEY`	—	gateway	Optional bearer key for the single synthesized upstream. For per-provider keys use a `models.yaml` instead.
`LLM_USE_MOCK`	`auto`	gateway	Built-in mock upstream. `auto` enables it in `local` env; `true`/`false` force it. Set `false` when pointing local dev at a real backend.
`LLM_MODELS`	—	gateway	Optional model allow-list / registry. Comma-separated `alias` or `alias=deployment` entries. See model-providers.md.
`LLM_DEFAULT_MODEL`	—	gateway	Model used when the caller omits `model` on chat.
`LLM_DEFAULT_EMBEDDING_MODEL`	`text-embedding-3-large`	gateway, rag	Default embedding model.
`LLM_DEFAULT_RERANK_MODEL`	`rerank-v2`	gateway, rag	Default rerank model.
`LLM_MODEL_FALLBACKS`	—	gateway	Comma-separated ordered fallback models tried on upstream 429/5xx.
`LLM_GATEWAY_BASE_URL`	`http://localhost:8031`	rag	Internal base URL RAG calls for `/v1/embeddings` and `/v1/rerank`.
`GATEWAY_URL`	`http://gateway:8080`	tool-registry	Base URL of the LLM gateway used by the tool registry.
`LLM_GATEWAY_ADDR`	`localhost:9091`	eval	gRPC address of the LLM gateway used by the eval runner.

Upstream auth is optional. A self-hosted OpenAI-compatible backend on a trusted network needs none — leave LLM_API_KEY empty. For a keyed endpoint (DigitalOcean/OpenAI) set LLM_API_KEY, or use a models.yaml with per-provider api_key_env for multiple providers.

RAG & object storage

Configured on the rag service. The backend is selected by OBJECT_STORAGE_BACKEND.

Variable	Default	Description
`RAG_EMBEDDING_DIM`	`3072`	Vector dimension for pgvector columns. Must match your embedding model’s output dimension.
`OBJECT_STORAGE_BACKEND`	`minio`	`minio` (local/self-host) or `gcs` (requires the `gcs` build tag).
`MINIO_BUCKET`	`eparch-rag`	Destination bucket/container.
`MINIO_ENDPOINT`	`localhost:9000`	MinIO/S3 endpoint (host:port).
`MINIO_ACCESS_KEY`	`minioadmin`	Access key.
`MINIO_SECRET_KEY`	`minioadmin`	Secret key.
`MINIO_USE_SSL`	`false`	Enable TLS for the object-store connection.
`GCS_PROJECT_ID`	—	GCP project owning the GCS bucket (GCS backend only).

For S3-compatible object storage at scale, set OBJECT_STORAGE_BACKEND to a MinIO-compatible S3 endpoint and supply the corresponding credentials.

Redis

Variable	Default	Services	Description
`REDIS_ADDR`	`localhost:6379`	gateway, identity, rag	Redis address (host:port). The gateway refuses to start if Redis is unreachable — it will not run without rate-limit/budget controls. Identity falls back to in-memory OIDC state when unset (single-replica only).
`REDIS_PASSWORD`	—	gateway, identity, rag	Redis AUTH password. Empty = no auth (dev default).

Budgets, rate limits & cache (gateway)

Variable	Default	Description
`BUDGET_DEFAULT_DAILY_USD`	`100`	Per-tenant daily spend cap. `-1` disables.
`BUDGET_DEFAULT_MONTHLY_USD`	`2000`	Per-tenant monthly spend cap. `-1` disables.
`BUDGET_ON_EXHAUSTION`	`block`	`block` returns HTTP 429 on limit; `alert_only` logs but allows.
`CACHE_TTL_HOURS`	`24`	TTL for semantic response cache entries.

Secret store & service tokens

Variable	Default	Services	Description
`EPARCH_SECRET_KEY`	—	tool-registry (+ monolith)	Base64-encoded 32-byte AES-256 key for the Postgres-backed secret store. Empty disables the secret store. Generate with `openssl rand -base64 32`.
`RUNTIME_SVC_TOKEN`	—	agent-runtime, eval	Static service-account Bearer token for internal service-to-service calls. Blank in local dev.

Inter-service addresses

Used for gRPC dialing between services. Compose sets these to container DNS names; defaults target localhost for local dev.

Variable	Default	Read by	Target service
`AGENT_RUNTIME_ADDR`	`localhost:8001`	gateway, eval	agent-runtime
`AGENT_CONFIG_ADDR`	`localhost:8086`	gateway, agent-runtime	agent-config
`TOOL_REGISTRY_ADDR`	`localhost:8050`	gateway, agent-runtime	tool-registry
`RAG_ADDR`	`localhost:8040`	gateway, agent-runtime	rag
`EVAL_ADDR`	`localhost:8045` (gateway), — (agent-config)	gateway, agent-config	eval. On agent-config, setting it enables the server-side eval gate for canary promotion.
`GATEWAY_ADDR`	`localhost:8030`	agent-runtime	gateway
`EVENT_BROKER_ADDR`	`localhost:8060`	agent-runtime	event-broker
`AUDIT_ADDR`	`localhost:8070`	agent-runtime	audit
`IDENTITY_ADDR`	`localhost:8010`	agent-runtime	identity
`EVAL_MAX_PARALLEL_CASES`	`5`	eval	Caps concurrent eval-case execution.

Observability (OTEL)

Variable	Default	Services	Description
`OTEL_EXPORTER_OTLP_ENDPOINT`	`localhost:4317`	All	OTLP gRPC endpoint for traces. No-op in `local`. In production point at a managed OTLP backend (Grafana Cloud, Honeycomb, …).
`OTEL_SERVICE_NAME`	service name	All	Service name reported in traces (defaults to each service’s own name).

TLS / mTLS (gateway gRPC)

Variable	Default	Description
`GRPC_TLS_ENABLED`	`false`	When `true`, the gateway gRPC server requires client certificates signed by `GRPC_TLS_CA_FILE`.
`GRPC_TLS_CERT_FILE`	—	Path to the server TLS certificate PEM.
`GRPC_TLS_KEY_FILE`	—	Path to the server TLS private key PEM.
`GRPC_TLS_CA_FILE`	—	Path to the CA certificate for verifying client certs (mTLS).