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.

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.

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

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

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. The builder will log a warning:

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

If you see this warning 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.