Configuration

CloudGrid is configured with environment variables. Start with the smallest mode that works, then add deployed-mode hardening only when the deployment needs shared users, invite-only access, or production boundaries.

Configuration has two main branches:

• Local mode is for one developer or one local workstation. It uses local auth, local project routing, and safe defaults.
• Deployed mode is for shared access. It uses SSO, invite-controlled membership, explicit SMTP delivery, and hardened infrastructure settings.

Configuration Storyline

diagram

Sections

Topic	Page
Runtime modes and validation	Runtime environment
Local mode setup	Local configuration and setup script
Local token routing	Local project-token routing
Local self-observability	Local self-observability
Deployed mode setup	Deployed configuration
Kubernetes readiness	Kubernetes and deployment status
SSO provider setup	SSO overview
Organization invitations	Invitations
Invitation email delivery	Invitation email delivery
AI provider secrets	Provider secrets
Deployed self-observability	Deployed self-observability
Storage	SurrealDB storage

Safe Defaults

Local development:

CLOUDGRID_DEPLOYMENT_MODE=local
CLOUDGRID_AUTH_MODE=local
CLOUDGRID_NATS_URL=nats://localhost:4222
CLOUDGRID_STORAGE_ADAPTER=surrealdb
CLOUDGRID_SURREALDB_URL=http://localhost:8000/rpc

Deployed shared mode:

CLOUDGRID_DEPLOYMENT_MODE=deployed
CLOUDGRID_AUTH_MODE=sso
CLOUDGRID_AUTH_PROVIDERS=github
CLOUDGRID_AUTH_COMPANY_ID=acme
CLOUDGRID_SESSION_SECRET='<32-plus-byte-secret>'
CLOUDGRID_PUBLIC_URL=https://cloudgrid.example.com
CLOUDGRID_PROVIDER_SECRET_ENCRYPTION_KEY='<long-random-secret>'
CLOUDGRID_INVITATION_EMAIL_MODE=smtp
CLOUDGRID_INVITATION_EMAIL_REQUIRE_DELIVERY=true
CLOUDGRID_INVITATION_EMAIL_FROM='CloudGrid <noreply@example.com>'
CLOUDGRID_INVITATION_EMAIL_SMTP_HOST=smtp.example.com
CLOUDGRID_INVITATION_EMAIL_SMTP_PORT=587

Invite And Email Boundary

In deployed mode, other users reach a project through invitations. A user may authenticate with a configured SSO provider, but project membership is still controlled by invitation acceptance and control-plane membership state.

Invitation email delivery is intentionally separate from SSO:

1. SSO proves identity.
2. The invitation links the identity to a company and project role.
3. SMTP delivery decides whether CloudGrid can send the invite email itself.
4. CLOUDGRID_INVITATION_EMAIL_REQUIRE_DELIVERY=true makes failed email delivery fail the invite operation instead of silently relying on manual link sharing.

Boundary Rules

• SurrealDB credentials belong only to storage and control-plane services.
• AI provider API keys entered in CloudGrid are encrypted by control-plane and returned only as managed: references.
• The frontend never receives SurrealDB credentials, raw provider tokens, session secrets, or project API key secrets.
• The BFF owns browser SSO sessions and public GraphQL.
• The collector owns OTLP ingest authorization before payload decode.
• Unknown production-scale variables must not be partially applied until their spec and tests exist.

Next Step

For a laptop, continue with Local configuration. For shared mode, continue with Deployed configuration.