Skip to main content

Environment Variables & Secrets

Environment variables are how you pass configuration and secrets to your app at runtime — API keys, database URLs, feature flags, and anything else that shouldn't be hardcoded.

Managing variables​

Go to your app → Variables tab. From here you can:

  • Add a variable — click Add Environment Variable, enter the key and value, then click Save.
  • Edit a variable — click the key or value to edit inline, then save.
  • Delete a variable — click the trash icon next to the variable, then save.
Values are write-only

Once a variable is saved, its value is no longer visible in the UI — it's masked for security. If you lose a value, you'll need to replace it. This applies to all variables you set manually.

Changes take effect on the next deploy. After saving, you'll see a reminder: "Save first, then redeploy to apply." Trigger a redeploy from the Deployments tab (or just push a new commit if auto-deploy is on).

Importing from a .env file​

If you have a .env file locally, you can import it directly:

  1. Click Import .env in the Variables tab.
  2. Select your .env file from your computer.
  3. Vessl shows you which variables are new and asks you to confirm before merging them into the existing list.
  4. Click Save to persist, then redeploy.

Vessl also detects if your repo has a .env.example file and offers to import it as a starting point.

${VAR} references are not interpolated

If your .env file contains KEY=${OTHER_VAR}, Vessl passes that string literally — it doesn't expand references. Set the actual value directly.

Add-on variables (injected automatically)​

When you attach a database or cache add-on to your app, Vessl injects its connection credentials automatically — you don't add these yourself. They appear as a separate read-only section in the Variables tab labeled Linked Add-on Variables.

These are injected at deploy time and follow standard naming conventions so most frameworks connect without any extra mapping. See Databases & add-ons for the full list of variable names.

Build-time vs runtime variables​

All variables set in the Variables tab are runtime environment variables — they're available inside your running container but not during the Docker build process.

If you need variables available at build time (e.g. NEXT_PUBLIC_* for Next.js static builds, or ARG values for a Dockerfile), use Build Args instead. See Build args & custom build command for details.

Best practices​

  • Don't commit secrets to your repository. Use the Variables tab for anything sensitive.
  • Use distinct variable names per environment if you run multiple apps (staging, production) — each app has its own independent variable set.
  • After rotating a secret (API key, token), update the variable and redeploy to apply it.