Skip to main content

Cloud UI configuration

This guide covers the environment variables and OIDC settings that the ToolHive Cloud UI reads at startup. For end-to-end deployment steps on Kubernetes, see Deploy the Cloud UI.

Environment variables​

The Cloud UI is configured entirely through environment variables. In a Kubernetes deployment, supply them through a Kubernetes Secret referenced from envFrom (recommended) or through the chart's env values.

Required variables​

VariableDescription
OIDC_ISSUER_URLIssuer URL of your OIDC provider (for example, https://your-org.okta.com)
OIDC_CLIENT_IDOAuth2 client ID registered with your OIDC provider
OIDC_CLIENT_SECRETOAuth2 client secret for the registered client
BETTER_AUTH_SECRETSecret used to encrypt session tokens. Generate one with openssl rand -base64 32
BETTER_AUTH_URLPublic URL where the Cloud UI is reachable (for example, https://cloud-ui.example.com)
API_BASE_URLURL of the Registry Server API (for example, http://my-registry-api.toolhive-system.svc.cluster.local:8080)

Optional variables​

VariableDescription
DATABASE_URLPostgreSQL connection string for the auth database. When omitted, the Cloud UI uses an in-memory SQLite database
TRUSTED_ORIGINSComma-separated list of allowed CORS origins
warning

The default in-memory SQLite database is not suitable for production. Sessions are lost on pod restart and can't be shared across replicas. For multi-replica deployments or any non-evaluation environment, set DATABASE_URL to point at a managed PostgreSQL instance.

Configure OIDC authentication​

The Cloud UI delegates authentication to an external OIDC provider using Better Auth. It works with any standards-compliant provider, including Okta, Microsoft Entra ID, Auth0, and Keycloak.

To configure your provider:

  1. Register a new OAuth2 / OIDC application in your identity provider.
  2. Set the redirect URI to <BETTER_AUTH_URL>/api/auth/callback/oidc (for example, https://cloud-ui.example.com/api/auth/callback/oidc).
  3. Request the openid, profile, and email scopes.
  4. Copy the issuer URL, client ID, and client secret into a Kubernetes Secret as described in Deploy the Cloud UI.

Helm chart values​

The chart in toolhive-cloud-ui/helm supports the following customizations beyond environment variables:

  • Replica count and horizontal pod autoscaling (HPA)
  • Resource requests and limits
  • Liveness, readiness, and startup probes
  • Pod and container security contexts
  • Image pull secrets for private registries
  • Custom Service types (ClusterIP, NodePort)
  • Additional volumes and volume mounts

Refer to the chart's values.yaml for the full set of configurable parameters and their defaults.

info

The chart does not ship an Ingress template. To expose the Cloud UI outside the cluster, create an Ingress resource separately or use a Service of type NodePort or LoadBalancer. See Step 5 of the deployment guide for an Ingress example.

Next steps​