Environment Variables

Environment variables let you pass configuration to your application at runtime. Common uses include API keys, database connection strings, feature flags, and external service credentials.

Setting environment variables

In the Build Configuration step of the deployment wizard, add variables in KEY=value format, one per line:

DATABASE_URL=postgresql://user:pass@host:5432/db
API_KEY=sk_live_abc123
NODE_ENV=production

Naming rules

• Variable names must match [A-Z_][A-Z0-9_]* — uppercase letters, digits, and underscores.
• Maximum 50 variables per application.
• Maximum 1000 characters per value.

Automatically injected variables

Convoy Cloud injects the following automatically:

If you define PORT yourself, your value takes precedence.

Important: bind to all interfaces

Your application must bind to 0.0.0.0 (all interfaces), not 127.0.0.1 (localhost only). Most frameworks do this by default when reading PORT from the environment, but confirm if traffic does not reach your app.

// Correct
app.listen(process.env.PORT || 8080, '0.0.0.0');

// Incorrect — traffic will not reach this
app.listen(process.env.PORT || 8080, '127.0.0.1');

Build-time and runtime

All environment variables you configure are available at both build time (during the container build) and runtime (inside the running container). This means NEXT_PUBLIC_* variables and other compile-time constants work without any special treatment.

Security

Environment variables are stored as Kubernetes Secrets in your isolated namespace:

• Encrypted at rest
• Not visible in build logs (unless your app explicitly prints them)
• Scoped to your namespace — other tenants cannot access them

Editing variables on a running app

Open the Edit drawer from the app detail page to update variables without creating a new deployment from scratch:

Common patterns

Connecting to a database

DATABASE_URL=postgresql://user:[email protected]:5432/mydb

Next.js

NEXT_PUBLIC_API_URL=https://api.example.com
NODE_ENV=production

Django

DJANGO_SECRET_KEY=your-secret-key
DJANGO_ALLOWED_HOSTS=myapp.convoy-tech.com
DATABASE_URL=postgresql://user:pass@host:5432/db
DEBUG=False