Environment Variables
Every environment variable Cardinal UI and the MCP Gateway read at runtime. Set these via maestro.env, mcpGateway.env, or global.env in your values.yaml.
Most of the really important knobs are here: OIDC, the public URL, and the AWS region for Bedrock. Per-provider LLM credentials and per-org integration credentials are not env vars — they live in the database and are managed through the admin UI.
Cardinal UI
Database
Usually set automatically by the chart — see the Helm chart reference.
| Variable | Required | Default | Notes |
|---|---|---|---|
MAESTRO_DATABASE_URL | Yes | — | Full PostgreSQL URL. The chart composes this from database.* values |
MAESTRO_DB_HOST | — | — | Set by chart from database.host |
MAESTRO_DB_PORT | — | 5432 | |
MAESTRO_DB_NAME | — | maestro | |
MAESTRO_DB_USER | — | maestro | |
MAESTRO_DB_PASSWORD | — | — | Sourced from the database secret |
MAESTRO_DB_SSLMODE | — | require |
Public URL
| Variable | Required | Default | Notes |
|---|---|---|---|
MAESTRO_BASE_URL | Yes in prod | — | Full URL the browser hits (e.g. https://ui.example.com). Must match your OIDC redirect URI |
MAESTRO_INGEST_ENDPOINT | For Agent Outcomes | — | Absolute OTLP/HTTP endpoint of your Cardinal Data Lake intake (e.g. https://intake.example.internal). Returned in the cardinal-connect bundle so the Claude Code / Codex plugins send session telemetry to your Cardinal Data Lake instead of Cardinal Cloud. When unset, connect bundles omit the telemetry side entirely and the Agent Outcomes dashboard stays empty |
PORT | — | 4200 | HTTP listen port |
SPA_ROOT | — | /app/ui | Path to the UI static bundle inside the image |
OIDC / authentication
See OIDC setup for a walkthrough.
| Variable | Required | Default | Notes |
|---|---|---|---|
OIDC_ISSUER_URL | Yes | — | Issuer URL of your IdP. JWKS is discovered from it |
OIDC_AUDIENCE | — | maestro-ui | Expected aud claim on incoming tokens. For many IdPs this equals the OAuth client ID |
OIDC_CLIENT_ID | — | OIDC_AUDIENCE | OAuth client ID the SPA sends in /authorize requests. Set separately when the token’s aud is a resource identifier distinct from the client ID (e.g. Okta with a custom authorization server) |
OIDC_JWKS_URL | — | derived | Override if your IdP’s JWKS lives outside the standard discovery path |
OIDC_SUPERADMIN_GROUP | — | maestro-superadmin | Users in this OIDC group are promoted to superadmin |
OIDC_SUPERADMIN_EMAILS | — | — | Comma-separated email allowlist. Matched case-insensitively. Use this to bootstrap the first superadmin before you’ve wired groups |
OIDC_TRUST_UNVERIFIED_EMAILS | — | false | Treat all OIDC emails as verified regardless of the email_verified claim. Only set this if you trust your IdP to gate email ownership itself (some Okta setups) |
OIDC_EMAIL_CLAIM | — | email | Token claim Cardinal UI reads the user’s email from. See Claim mapping |
OIDC_EMAIL_VERIFIED_CLAIM | — | email_verified | Token claim Cardinal UI reads the email-verified boolean from |
OIDC_DISPLAY_NAME_CLAIMS | — | name,preferred_username,email | Comma-separated fallback chain for the UI display name |
OIDC_GROUPS_CLAIM | — | groups | Token claim Cardinal UI reads the group array from |
OIDC_EXTERNAL_ID_CLAIM | — | sub | Token claim Cardinal UI uses as the persistent account key. Must be stable per user. Changing this on a populated deployment is a migration event |
Cardinal UI always requires email_verified: true in the token unless OIDC_TRUST_UNVERIFIED_EMAILS=true.
LLM providers (env var form)
In normal operation you configure LLMs through the superadmin UI; those credentials live in the database. These env vars are only read by CLI provisioning helpers and the gateway’s embedding path.
| Variable | Used by | Notes |
|---|---|---|
ANTHROPIC_API_KEY | CLI provisioning | |
OPENAI_API_KEY | CLI provisioning, gateway embeddings | |
AWS_REGION | Bedrock client default | When Bedrock creds are empty in the DB, the SDK falls back to the pod’s credential chain and uses this region |
GCP_PROJECT, GCP_REGION | Vertex AI embeddings | |
GOOGLE_APPLICATION_CREDENTIALS | Vertex AI embeddings (gateway) | Path to GCP service account key file |
MCP Gateway integration
| Variable | Required | Default | Notes |
|---|---|---|---|
MCP_GATEWAY_URL | — | http://localhost:8080 | The chart sets this to the in-cluster service URL |
MCP_GATEWAY_API_KEY | — | — | If set, sent as X-CardinalHQ-API-Key to the gateway |
Investigation Storyboards
Visualization authoring runs in the agent session after user consent. STORYBOARD_PROJECTION_* generation settings are retired and ignored by this release.
All optional. See Storyboards: self-hosted setup for how they fit together.
| Variable | Default | Notes |
|---|---|---|
INVESTIGATION_OWNER_INPUT_ENABLED | false | Optional owner-input capture capability; independent of session-owned visualization authoring |
SHARE_HOST | — | Bare host[:port] (e.g. share.example.com) that serves public storyboard links at https://<SHARE_HOST>/s/<token>. On that host Cardinal UI serves only the public viewer, its read API, the abuse-report POST and static assets, and never reads or sets a cookie. Unset: links use MAESTRO_BASE_URL’s origin, or can’t be created without it. An invalid value stops Cardinal UI at startup |
STORYBOARD_SIGNUP_URL | https://app.cardinalhq.io | Where the public viewer’s Make your own with Claude link goes. Must be an absolute http(s) URL |
PERSONAL_WORKSPACE_MAX_PUBLISHES_PER_DAY | 20 | Personal-workspace quota |
PERSONAL_WORKSPACE_MAX_EVIDENCE_BYTES_PER_DAY | 52428800 | Personal-workspace quota (50 MiB of captured and reported evidence) |
PERSONAL_WORKSPACE_MAX_PUBLIC_VIEWS_PER_DAY | 5000 | Personal-workspace quota |
Default Cardinal Data Lake bucket
Used by the Cardinal Data Lake provisioner when auto-configuring a new org’s bucket. All four must be set together or all omitted.
| Variable | Notes |
|---|---|
DEFAULT_BUCKET_NAME | |
DEFAULT_BUCKET_CLOUD_PROVIDER | aws, gcp, azure |
DEFAULT_BUCKET_REGION | |
DEFAULT_BUCKET_COLLECTOR_NAME |
Observability
| Variable | Default | Notes |
|---|---|---|
OTEL_SERVICE_NAME | maestro | |
OTEL_TRACING_ENABLED | true if endpoint set | Set to false to disable |
OTEL_EXPORTER_OTLP_ENDPOINT | http://localhost:4318 | HTTP OTLP endpoint |
OTEL_EXPORTER_OTLP_HEADERS | — | Key=value,Key2=value2 |
Notifications
| Variable | Default | Notes |
|---|---|---|
MAESTRO_ALLOW_INSECURE_WEBHOOKS | false | Allow http:// (not just https://) for webhook notification destinations. Only relaxes the protocol check — private/link-local/metadata addresses are still blocked regardless |
Misc
| Variable | Default | Notes |
|---|---|---|
DEBUG | false | Enables /api/debug/tools. Do not set in prod |
MCP Gateway
The gateway runs alongside Cardinal UI and inherits most of its env from global.env. Unique vars:
| Variable | Default | Notes |
|---|---|---|
MCP_HOST | 0.0.0.0 | |
MCP_PORT | 8080 | Chart sets this from mcpGateway.port |
MCP_DEBUG_PORT | 9090 | Chart sets this from mcpGateway.debugPort |
MCP_API_KEY | — | If set, requests must carry X-CardinalHQ-API-Key |
GATEWAY_AGGREGATOR_ENABLED | false | true mounts the aggregated MCP endpoint (/api/orgs/<orgId>/mcp on Cardinal UI) that the plugins use. Required for storyboard evidence receipts |
MCP_TRANSPORT | stdio | Chart runs the gateway in HTTP mode; set to http if you ever override the entrypoint |
MAESTRO_DATABASE_URL | — | Same connection string as Cardinal UI — required for per-org routing |
DOCSTORE_DB_PATH | auto-discovered | Path to docstore.db |
WORKING_DIRECTORY | cwd | Used for the embeddings cache |
OTEL_SERVICE_NAME | mcp-gateway |
Where to set what
| Scope | Use |
|---|---|
| Public URL, OIDC, Postmark, superadmin email | maestro.env |
| Bedrock region, OTel endpoint, trace headers | global.env (both workloads need them) |
| MCP gateway specifics (API key in-container, docstore path) | mcpGateway.env or set on the chart-level field (mcpGateway.apiKey) |
Reach out to support@cardinalhq.io for support or to ask questions not answered in our documentation.
Last updated on