Environment Variables

Configure your apps with environment variables for secrets, feature flags, and runtime settings.

Overview

Environment variables let you pass configuration to your app without hardcoding values in source code. They're the standard way to manage secrets (API keys, database URLs) and per-environment settings (debug mode, log level).

On Kapable, environment variables are:

• Encrypted at rest and only decrypted when injected into your app's process
• Scoped per app — each app has its own set of variables
• Applied on deploy — changes take effect on the next deployment

Setting Variables via Console

1. Go to Apps > {your app} > Settings
2. Scroll to the Environment section
3. Enter a key and value, then click Add
4. Click Rebuild to apply changes

Variables are key-value pairs. Keys must be uppercase letters, digits, and underscores (e.g. DATABASE_URL, STRIPE_SECRET_KEY).

Bulk Import

You can paste a .env file format in the bulk import section:

DATABASE_URL=postgres://user:pass@host:5432/db
REDIS_URL=redis://localhost:6379
SECRET_KEY=your-secret-here

Each KEY=VALUE line will be parsed and added. Lines starting with # are ignored.

Setting Variables via API

# Set a single variable
curl -X POST https://api.kapable.ai/v1/apps/{app_id}/env \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "DATABASE_URL", "value": "postgres://..."}'

# List all variables (values are masked)
curl https://api.kapable.ai/v1/apps/{app_id}/env \
  -H "Authorization: Bearer YOUR_API_KEY"

# Delete a variable
curl -X DELETE https://api.kapable.ai/v1/apps/{app_id}/env/DATABASE_URL \
  -H "Authorization: Bearer YOUR_API_KEY"

Built-in Variables

Kapable automatically provides these variables to every app:

const port = process.env.PORT || 3000;
app.listen(port);

let port = std::env::var("PORT").unwrap_or_else(|_| "3000".into());

Best Practices

Never Commit Secrets

Add .env to your .gitignore. Use environment variables for all sensitive values:

• Database connection strings
• API keys and tokens
• Encryption keys
• OAuth client secrets

Use Descriptive Names

Prefix variables by purpose:

DB_HOST=...
DB_PORT=...
DB_NAME=...
STRIPE_SECRET_KEY=...
STRIPE_WEBHOOK_SECRET=...
SMTP_HOST=...
SMTP_PORT=...

Separate Environments

Don't reuse the same variables across dev, staging, and production. Each Kapable app has its own environment, so create separate apps for each stage:

• my-app-dev — development config, debug logging
• my-app-staging — staging database, test payment keys
• my-app — production config, live keys

Secret Rotation

To rotate a secret:

1. Generate the new secret value
2. Update the environment variable in App Settings > Environment
3. Click Rebuild to redeploy with the new value
4. Revoke the old secret in the external service

Variable Size Limits

• Key length: 1–256 characters
• Value length: up to 32 KB
• Total variables per app: 100
• Total env size per app: 1 MB

Troubleshooting

• Variable not available at runtime — ensure you redeployed after adding it. Variables are injected at process start, not live.
• Value appears empty — check for trailing whitespace or newlines in the value. Use the console UI to verify.
• Build-time vs runtime — some frameworks need variables at build time (e.g. NEXT_PUBLIC_* in Next.js). These must be set before the build step runs.

Next Steps