Handbook - Configuration

Runtime Environment

Runtime configuration is service-owned. Each service validates only the variables it uses and fails startup with ERR-009 CONFIGINVALID when required.

On this page
On this page

Runtime configuration is service-owned. Each service validates only the variables it uses and fails startup with ERR-009 CONFIG_INVALID when required values are missing or invalid.

Shared Variables

VariableDefaultPurpose
CLOUDGRID_DEPLOYMENT_MODElocallocal or deployed. Must match CLOUDGRID_AUTH_MODE.
CLOUDGRID_AUTH_MODElocallocal or sso.
CLOUDGRID_NATS_URLnats://localhost:4222Private message bridge endpoint.
CLOUDGRID_STORAGE_ADAPTERsurrealdbMust match the compiled storage adapter.

BFF Variables

VariableDefaultPurpose
CLOUDGRID_BFF_HOST0.0.0.0BFF bind host.
CLOUDGRID_BFF_PORT3000BFF HTTP, GraphQL, auth, health, and static serving port.
CLOUDGRID_FRONTEND_SERVE_STATICtrue in production, otherwise falseServe built frontend from the BFF.
CLOUDGRID_FRONTEND_STATIC_DIR./apps/backend/publicStatic frontend directory used by the BFF.
CLOUDGRID_SESSION_SECRETunsetRequired when CLOUDGRID_AUTH_MODE=sso.
CLOUDGRID_SESSION_TTL_SECONDS28800Browser session lifetime in seconds.

Collector Variables

VariableDefaultPurpose
CLOUDGRID_OTLP_HTTP_ADDR0.0.0.0:4318OTLP/HTTP bind address for traces, logs, and metrics.
CLOUDGRID_OTLP_GRPC_ADDR0.0.0.0:4317OTLP/gRPC bind address.
CLOUDGRID_OTLP_MAX_REQUEST_BYTES4194304Maximum OTLP/HTTP request body size.
CLOUDGRID_OTLP_GRPC_MAX_MESSAGE_BYTESHTTP body limitMaximum OTLP/gRPC message size.
CLOUDGRID_OTLP_GRPC_COMPRESSIONgzipOTLP/gRPC compression mode, gzip or none.
CLOUDGRID_OTLP_LOCAL_PROJECT_IDdefaultLocal single-project fallback when token routing is not configured.
CLOUDGRID_OTLP_LOCAL_PROJECT_TOKENSunsetJSON token-to-project map for local multi-project ingest.
CLOUDGRID_AUTH_ISSUERunsetCollector-only issuer for deployed OTLP ingest bearer tokens when CLOUDGRID_AUTH_MODE=sso.
CLOUDGRID_AUTH_AUDIENCEunsetCollector-only audience for deployed OTLP ingest bearer tokens when CLOUDGRID_AUTH_MODE=sso.
CLOUDGRID_AUTH_JWKS_URLunsetCollector-only JWKS endpoint for deployed OTLP ingest bearer-token validation when CLOUDGRID_AUTH_MODE=sso.

Storage And Control-Plane Variables

VariableDefaultPurpose
CLOUDGRID_SURREALDB_URLhttp://localhost:8000/rpcSurrealDB RPC endpoint.
CLOUDGRID_SURREALDB_NAMESPACEobservabilitySurrealDB namespace.
CLOUDGRID_SURREALDB_DATABASEdevSurrealDB database.
CLOUDGRID_SURREALDB_USERNAMElocal rootStorage/control-plane credential.
CLOUDGRID_SURREALDB_PASSWORDlocal rootStorage/control-plane credential.
CLOUDGRID_STORAGE_READ_MAX_METRIC_POINTS5000Maximum points returned by one metric series query.

Self-Observability Variables

VariableDefaultPurpose
CLOUDGRID_SELF_OBSERVABILITY_ENABLEDtrue in local, false in deployedEnable CloudGrid service telemetry export.
CLOUDGRID_SELF_OBSERVABILITY_COMPANY_IDlocal in local modeRequired in deployed mode when enabled.
CLOUDGRID_SELF_OBSERVABILITY_PROJECT_IDcloudgrid-systemProject receiving CloudGrid service telemetry.
CLOUDGRID_SELF_OBSERVABILITY_OTLP_ENDPOINThttp://localhost:4318 in local modeOTLP HTTP base endpoint.
CLOUDGRID_SELF_OBSERVABILITY_OTLP_BEARER_TOKENunsetRequired whenever self-observability is enabled; in local mode it must map to cloudgrid-system.
CLOUDGRID_SELF_OBSERVABILITY_EXPORT_INTERVAL_SECONDS10Export interval, 1..300.

Boolean parsing is strict for self-observability variables: use true or false, not 1 or 0.

Invalid Combinations

diagram
local deployment + sso auth ERR-009 deployed mode + local auth sso auth without providers enabled provider missing required env deployed self-observability without company/project/endpoint/token
Mermaid diagram rendered with beautiful-mermaid.

Reference

For a lookup-only table, use Environment variables.

Last updated .