Environment Variables

All environment variables auto-injected by the platform, plus how to add your own.

How environment variables are managed on the Tawa platform — what gets auto-injected, what you can override, and how to set your own.

Core Platform Variables (Always Injected)

The following variables are injected into every pod on every deploy. You never need to declare or configure them — they are always present regardless of what's in your catalog-info.yaml.

NOTE: BIO_ID_URL is always available. You do NOT need to add bio-id to internalDependencies to get this variable — doing so is incorrect. Use auth: mode: sso in spec to provision BIO_CLIENT_ID and BIO_CLIENT_SECRET.

Many Node.js frameworks behave differently based on NODE_ENV. Express hides stack traces in production, Next.js enables optimizations, and most ORMs skip dev-only features like data seeding.

Auto-Provisioned Variables

The builder also injects variables from services declared in your catalog-info.yaml:

You do not need to set any of these manually. They are created fresh on every deploy.

Build-Time vs Runtime Variables

Environment variables on Tawa fall into two categories:

Runtime variables (the default for everything) are injected into the running pod at start time. This includes all database URIs, OAuth credentials, tawa config set values, secrets, and core platform vars. Your app reads these from process.env at runtime.

Build-time variables are injected during the Docker build phase, before your app starts. These are needed for frameworks like Next.js that bake values into the build output (e.g. NEXT_PUBLIC_* vars).

To expose a build-time variable, declare it in catalog-info.yaml using the insureco.io/env-vars annotation, then set its value with tawa config set:

metadata:
  annotations:
    insureco.io/env-vars: "NEXT_PUBLIC_API_URL,NEXT_PUBLIC_FEATURE_FLAG"

tawa config set NEXT_PUBLIC_API_URL=https://my-api.tawa.insureco.io

The builder injects only the vars listed in insureco.io/env-vars into the Docker build. All other vars remain runtime-only (more secure).

WARNING: Never put secret values in build-time vars — they may be baked into the image layer and visible in the registry. Use build-time vars only for public/non-sensitive configuration.

Managed Config & Secrets

For variables not auto-provisioned (API keys, feature flags, custom URLs), use the CLI:

# Plain config vars (visible in logs)
tawa config set LOG_LEVEL=debug API_TIMEOUT=30000

# Secrets (encrypted at rest, never returned by API)
tawa config set STRIPE_SECRET_KEY=sk_live_... --secret

# List all config and secret key names
tawa config list

# Pull all config + decrypted secrets to .env.local
tawa config pull

Config vars and secrets are injected into your pod on every deploy. After setting or changing config, you must redeploy for changes to take effect.

Precedence Order

From lowest to highest precedence (highest wins on conflict):

1. Platform core vars — KOKO_URL, JANUS_URL, IEC_WALLET_URL, BIO_ID_URL, SERVICE_NAMESPACE, NODE_ENV
2. Managed secrets — set via tawa config set KEY=VALUE --secret (encrypted at rest)
3. Plain config vars — set via tawa config set KEY=VALUE
4. Annotation-driven vars — from insureco.io/env-vars (build-time only)

NOTE: Platform core vars cannot be silently overridden — the builder logs a warning if you attempt to override KOKO_URL, JANUS_URL, BIO_ID_URL, or SERVICE_NAMESPACE. NODE_ENV can be overridden without a warning.

Overriding Platform Defaults

You can override NODE_ENV using tawa config set:

# Override NODE_ENV (not common, but allowed)
tawa config set NODE_ENV=production

If you set this unintentionally, run tawa config unset NODE_ENV to revert.

Local Development

Pull your deployed config into a .env.local file:

tawa config pull
# Writes .env.local with all config + decrypted secrets
# File permissions: 0600 (owner read/write only)

Platform defaults like NODE_ENV are not included in the pull — your local environment handles those naturally.

WARNING: Add .env.local to your .gitignore. This file contains decrypted secrets — never commit it.