Environment variables give your App Platform app its configuration and secrets, such as API keys, connection strings and feature flags, without putting them in your code or your repository. You manage them in the app's Env Vars tab, and your app reads them at runtime.
Open your app, go to Configure › Env Vars, and click Add Variable with a name and a value. Saving restarts your app so it picks up the change. Values are encrypted at rest and masked in the dashboard, showing only the last four characters. DATABASE_URL is a system variable you can't edit or delete, and the platform tells your app which port to use in PORT.
1. Add or change a variable
- Open your appfrom Services › App Platform and go to Configure › Env Vars.
- Enter a name, for example
STRIPE_SECRET_KEY. Names may contain only letters, numbers and underscores, and can't start with a number. - Enter the valueand click Add Variable.
- Check the Logs tab.Your app restarts so the new value takes effect; confirm it started cleanly.
To change a value, add the same name again with the new value; it replaces the old one. The list never shows a saved value in full, so if you've lost it, set a new value rather than trying to read the old one back.
2. Delete a variable
Click the delete button on the variable's row and confirm. The app restarts without it, and any code reading that variable sees it unset. Make sure nothing still depends on it first.
3. How values are protected
- Encrypted at rest in our database.
- Masked in the dashboard. Only the last four characters are shown, so nobody can read a secret over your shoulder or from a screenshot.
- Private to the app. Each app has its own set of variables; another app on your plan doesn't see them.
Your app itself receives the full values at runtime, so treat your own logs with care: don't print secrets to the console, because the Logs tab shows your app's output.
4. System variables
| Variable | Set by | Can you change it? |
|---|---|---|
DATABASE_URL | The platform, for your app's PostgreSQL database | No: it is a system variable |
PORT | The platform, the port your app must listen on | Don't set it yourself; read it in your code |
If you try to change or delete DATABASE_URL, you'll see "Cannot modify system variable". That's deliberate: it protects your app's database connection, and it isn't a fault. See PostgreSQL database.
Using an external database
To connect to a database you host elsewhere, don't try to overwrite DATABASE_URL. Add your own variable under a different name, such as EXTERNAL_DATABASE_URL, and read that in your code.
5. Read variables in your code
Your app must read its port from PORT and bind to 0.0.0.0, never localhost. An app listening on localhost can't be reached from outside its container.
// Node.js
const port = process.env.PORT || 3000;
const apiKey = process.env.STRIPE_SECRET_KEY;
app.listen(port, '0.0.0.0');# Python (runs from your Dockerfile)
import os
port = int(os.environ.get('PORT', 5000))
api_key = os.environ['STRIPE_SECRET_KEY']
app.run(host='0.0.0.0', port=port)Node.js apps are detected automatically; Python, PHP and other languages run from a Dockerfile. See the App Platform overview.
Scheduled jobs you create in Data › Scheduled start with your environment variables already set, so they read configuration the same way.
6. Good practice
- Never commit secrets to Git. Keep them in Env Vars. If a secret has been committed, rotate it at its source, then update the variable.
- Use clear names:
STRIPE_SECRET_KEY, notKEY1. - Names are case-sensitive:
API_KEYandapi_keyare different variables. - Watch for stray spaces or line breaks when you paste a value.
- Keep a local
.envfile out of your repository and your deploy archive. Add it to.gitignore, and exclude it when you package code for a deploy token.
7. If a variable doesn't seem to apply
| Check | Why |
|---|---|
| The name is listed in Env Vars | A typo creates a second, unused variable |
| Spelling and capitalisation match your code | Names are case-sensitive |
| The Logs tab shows a restart after your change | The app must restart to see new values |
| The value has no trailing space | Pasted values often carry one |
If the variable is listed, the app has restarted and your code still sees the old value, open a ticket with your app name and the variable's name. Never send us the value.
How do I add an environment variable to an App Platform app?
Open the app, go to the Env Vars tab, enter a name and value, and click Add Variable. The app restarts so the new value takes effect.
Are environment variable values stored securely?
Yes. Values are encrypted at rest and masked in the dashboard, where only the last four characters are shown. Each app's variables are private to that app.
Why can't I change DATABASE_URL?
DATABASE_URL is a system variable that connects your app to its PostgreSQL database, so it can't be edited or deleted. To use another database, add your own variable under a different name.
Do I need to redeploy after changing a variable?
No. Saving or deleting a variable restarts the app so the change takes effect. Check the Logs tab to confirm it restarted cleanly.
Can I see a secret's full value after saving it?
No. The dashboard shows only the last four characters. If you have lost a value, set a new one.
Ready to configure your app? Open your App Platform apps, see App Platform plans, or ask us in a support ticket.
Encrypted environment variables, PostgreSQL and free SSL are included in every App Platform plan.
See App Platform plans