Environment Variables

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

Platform defaults

On every deploy, the builder automatically injects environment variables based on your deploy target. You never need to set these yourself — the platform handles them.

Variable	Sandbox	UAT	Production	Purpose
`NODE_ENV`	`development`	`production`	`production`	Controls Node.js runtime behavior (module caching, error detail, etc.)

Why this matters: Many Node.js frameworks behave differently based on NODE_ENV. For example, Express hides stack traces in production, Next.js enables optimizations, and most ORMs skip dev-only features like data seeding. Deploying to production without NODE_ENV=production can cause unexpected behavior, slower performance, and data leaks.

Auto-provisioned variables

The builder also injects variables from services declared in your catalog-info.yaml. These are generated during each deploy and injected into your pod.

Source	Variable	Example value
Databases	`MONGODB_URI`	`mongodb://host:27017/my-svc-prod`
Databases	`REDIS_URL`	`redis://host:6379/0`
Databases	`NEO4J_URI`	`bolt://host:7687`
OAuth	`BIO_CLIENT_ID`	`my-svc-prod`
OAuth	`BIO_CLIENT_SECRET`	`secret_abc123...`
Internal deps	`{SERVICE}_URL`	`http://api.api-prod.svc.cluster.local:3000`

You do not need to set any of these manually. They are created fresh on every deploy based on the current environment and your catalog declarations.

Managed config & secrets

For variables that are not auto-provisioned (API keys, feature flags, custom URLs), use the CLI to set them:

# 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

When the same variable is defined in multiple places, the last one wins. Here is the order from lowest to highest precedence:

Platform defaults — NODE_ENV and other platform-injected vars
Managed config — vars set via tawa config set
Auto-provisioned — database URIs, OAuth credentials, internal dependency URLs
Managed secrets — mounted via Kubernetes Secret (tawa config set --secret)

This means your tawa config set values always override platform defaults, and secrets always override everything else.

Overriding platform defaults

You can override any platform default using tawa config set. If you do, the builder will log a warning in your build output to make sure the override is intentional:

# Override NODE_ENV for a sandbox deploy (not common, but allowed)
tawa config set NODE_ENV=production

Build log output:

Warning: NODE_ENV is set to "production" but deploying to "sandbox"
(expected "development"). User override will be used.

When would you override? Rarely. The most common case is testing production behavior in sandbox. If you are seeing this warning and did not set it intentionally, run tawa config unset NODE_ENV to go back to the platform default.

Local development

For 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)

Your app should load .env.local (most frameworks do this automatically). The platform defaults like NODE_ENV are not included in the pull — your local environment handles those naturally.