Environment Variables

Environment variables are the standard way to pass configuration and secrets (database credentials, API keys, feature flags) to your app without hardcoding them.

Running a 1-Click App? Use instapods env set - it writes to the app’s own config file and restarts the app automatically. The .env-in-app-directory approach below is for custom-code pods (Static, PHP, Node.js, Python, Go).

Setting Environment Variables

Option 1: The `instapods env` command (Recommended)

Set one or more variables straight from the CLI:

instapods env set my-app DATABASE_URL=postgres://instapod:secret@localhost:5432/instapod API_KEY=sk-your-api-key-here

List or remove them later (values are masked unless you pass --show-values):

instapods env list my-app
instapods env list my-app --show-values
instapods env unset my-app API_KEY

For custom-code pods this writes to /home/instapod/app/.env and restarts the app service. For 1-Click Apps it targets the app’s own config file and restarts the app. Either way you do not need to run reload or restart afterwards.

Setting a variable does not put it in your app’s process environment. It writes a line into a .env file, and your app has to read that file. If instapods env list shows the variable but your app still says it is unset, that is the reason - see How your app reads them below.

Option 2: Create a `.env` File

The manual approach — create a .env file in your app directory via the CLI:

instapods exec my-app -- "cat > /home/instapod/app/.env << 'EOF'
DATABASE_URL=postgres://instapod:secret@localhost:5432/instapod
API_KEY=sk-your-api-key-here
NODE_ENV=production
EOF"

Nothing restarts your app when you write the file this way, so reload afterwards:

instapods pods reload my-app

Option 1 is still the better choice for anything with a #, a quote or a newline in it: env set quotes the value so it reads back exactly as typed, and a heredoc does not.

Option 3: Set at Pod Creation (API)

Pass environment variables when creating a pod via the API:

curl -X POST https://app.instapods.com/api/pods \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app",
    "preset": "nodejs",
    "customizations": {
      "env_vars": {
        "NODE_ENV": "production",
        "LOG_LEVEL": "info"
      }
    }
  }'

Variables set this way are written to /etc/environment, which login shells read. Systemd does not read /etc/environment, so your app service does not inherit them. For anything your app needs to see, use instapods env set (Option 1) — those land in .env and reach your app.

How your app reads them

instapods env set writes KEY=value into /home/instapod/app/.env and restarts your app. Your app then gets those values two ways, and either one is enough:

We put them in the process environment for you. The app’s systemd unit reads a copy of your .env that InstaPods generates, so process.env.API_KEY / os.environ["API_KEY"] / os.Getenv("API_KEY") work with no library and no code.
Your app reads the file itself, with dotenv, load_dotenv(), godotenv.Load(), or the support already built into Laravel, Symfony, Next and Vite.

If your app does both, they agree - a dotenv loader never overwrites a variable that is already set, and we generate our copy with the same parser your loader uses, so the value is the same either way.

Preset	Env file	What your app needs
`nodejs`	`/home/instapod/app/.env`	Nothing. `require('dotenv').config()` also works
`python`	`/home/instapod/app/.env`	Nothing. `load_dotenv()` also works
`go`	`/home/instapod/app/.env`	Nothing. `godotenv.Load()` also works
`php`	`/home/instapod/app/.env`	Nothing. Laravel and Symfony read the file too
`static`	n/a	No server-side code, so nothing reads env vars. Use a `config.js` file
1-Click Apps	The app’s own file	Nothing. The app already reads it

Three cases where you still need to read the file yourself

The generated copy is deliberately conservative. It leaves a variable out rather than risk handing your app a value that is subtly different from what you typed. A variable is skipped when:

It is one we manage. PORT, HOST, HOSTNAME and NODE_ENV are set by InstaPods so the proxy can reach your app. Setting them yourself is ignored on purpose - if it were not, your app would bind somewhere we do not route to and stop serving traffic.
Its value contains both an apostrophe and a newline (or a carriage return). That combination is the one shape we cannot guarantee systemd reads identically to dotenv, so we leave it out rather than risk corrupting it. A multi-line key or JSON credential with no apostrophe is passed through fine.
You edited .env by hand - over SSH, in the Web IDE, or with instapods exec. We cannot tell what changed, so we switch the generated copy off for that pod until your next env set or dashboard save. Your app keeps working; it just has to read the file itself until then.

In all three cases the value is still in /home/instapod/app/.env, so a dotenv.config() or load_dotenv() in your app covers you. Adding one is never wrong. The rest of this section shows that code for each stack.

Node.js

The systemd service sets NODE_ENV=production by default. That one comes from the unit itself, and a value you set for it in .env is ignored. process.env.DATABASE_URL already works with no library. Use the dotenv package if you also want the file read directly (see the three cases above):

// At the top of your entry point (index.js)
require('dotenv').config();

// Access variables
const dbUrl = process.env.DATABASE_URL;
const apiKey = process.env.API_KEY;

npm install dotenv

On Node 20 and newer you can skip the package and start your app with the flag instead:

{
  "scripts": {
    "start": "node --env-file=.env index.js"
  }
}

If your pod was created before mid-2026, some values may still live in /home/instapod/app/.env.local from an older layout. instapods env set keeps both files in step for the keys you set, so a stale .env.local cannot shadow them at build time. New keys go to .env.

Python

Use python-dotenv:

# app.py
from dotenv import load_dotenv
import os

load_dotenv()  # loads .env from current directory

db_url = os.environ.get('DATABASE_URL')
api_key = os.environ.get('API_KEY')

# requirements.txt
python-dotenv>=1.0
flask>=3.0

PHP

PHP-FPM provides access to system environment variables via getenv(). For .env files, parse them manually or use a library:

<?php
// Simple .env loading (no library needed)
$envFile = __DIR__ . '/../.env';
if (file_exists($envFile)) {
    foreach (file($envFile, FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES) as $line) {
        if ($line[0] === '#') continue;
        if (strpos($line, '=') !== false) putenv(trim($line));
    }
}

$dbPass = getenv('DB_PASS') ?: '';
$apiKey = getenv('API_KEY') ?: '';

For Laravel and Symfony the framework reads .env for you, so there is nothing to add.

PHP pods have no app service, so instapods env set has nothing to restart - PHP re-reads the file on the next request. The exception is a cached Laravel config: if you have run php artisan config:cache, run it again after changing a variable, or the cached values keep winning.

Go

Use godotenv:

// main.go
package main

import (
    "log"
    "os"

    "github.com/joho/godotenv"
)

func main() {
    // Loads /home/instapod/app/.env; the app runs with that as its working directory.
    if err := godotenv.Load(); err != nil {
        log.Println("no .env file, using process environment")
    }

    dbURL := os.Getenv("DATABASE_URL")
    _ = dbURL
}

go get github.com/joho/godotenv

Static

Static sites don’t run server-side code. For JavaScript apps that need configuration, use a config.js file:

// config.js (served as a static file)
window.APP_CONFIG = {
  API_URL: 'https://api.example.com',
  ENV: 'production'
};

Common Pattern: Database Credentials

After installing a database service, get the credentials and set them as env vars:

# Install MySQL
instapods services add my-app -s mysql -w

# Get the auto-generated password
instapods services creds my-app -s mysql

# Set them (this writes .env and restarts the app)
instapods env set my-app \
  DB_HOST=localhost \
  DB_PORT=3306 \
  DB_NAME=instapod \
  DB_USER=instapod \
  DB_PASS='<password from creds command>'

Variables InstaPods sets itself

Four keys belong to the platform, and a value you set for them is not applied:

Key	Why
`PORT`, `HOST`, `HOSTNAME`	InstaPods sets these so the proxy can reach your app. An app that binds somewhere else stops serving traffic
`NODE_ENV`	Already set to `production` in the app’s service unit

The write still goes through - the file is yours - but instapods env set and the dashboard both warn you at the moment you save, rather than leaving you to discover it as a 502 later:

$ instapods env set my-app PORT=8080
Set 1 variable(s) in /home/instapod/app/.env on my-app (app restarted)
  * PORT

! PORT is set by InstaPods so the proxy can reach your app; we do not apply a value
  set here, and an app that reads it from the file itself will stop serving traffic

Over the API, the same text comes back in a warnings array on the response.

Read the port from the environment with a fallback (process.env.PORT || 3000) and let InstaPods supply it. If your app must listen somewhere specific, change the port your app is proxied on instead - the Deploy Doctor’s wrong port fix does exactly that.

File permissions

.env holds secrets, so it is not readable by other accounts on the pod: InstaPods keeps it at mode 600, owned by instapod. On a PHP pod it is 640 and group www-data, because php-fpm reads the file as that group. If you create the file yourself over SSH, set the mode yourself - chmod 600 .env. InstaPods re-applies the safe mode on every env set, so the simplest way to fix a file you wrote by hand is to set one variable through the CLI.

Updating Variables

instapods env set merges: the keys you pass are updated or added, everything else in the file is left alone, and comments and blank lines survive.

instapods env set my-app DATABASE_URL=postgres://new-credentials@localhost/db DEBUG=false
instapods env unset my-app OLD_KEY

Both restart the app service for you. If you edited /home/instapod/app/.env by hand instead - over SSH, in the Web IDE, or with instapods exec - nothing restarts your app, so run instapods pods reload my-app yourself. See Deploy, Reload, Restart. A hand edit also switches off the copy we put in the process environment for that pod, because we cannot tell what you changed. Your app has to read .env itself until your next instapods env set or dashboard save, which regenerates it.

The .env file is stored inside your pod. If you delete the pod, the file is lost. Keep a copy of your environment variables in a secure location.

Multi-line values - a private key, a service-account JSON - are supported. Quote the value in your shell and instapods env set stores it whole, newlines and all, so it reads back exactly as you typed it:

instapods env set my-app FIREBASE_KEY="$(cat service-account.json)"

Best Practices

Never commit secrets to git — always use .env files or environment variables
Use defaults in code — Always provide fallback values (process.env.PORT || 3000)
Load the file anyway — Your app gets the variables from the process environment without any code, but a load_dotenv() / dotenv.config() also covers the three cases above where we deliberately leave a variable out of the generated copy. It costs one line and never hurts
Prefer instapods env set over editing the file — it restarts the app for you and quotes values that contain #, quotes or newlines so they read back exactly as typed
Separate configs — Use different .env files for development vs production

Getting Started

Dashboard

Presets

Services

SSH & Files

Guides

Partners

Support

Environment Variables

Setting Environment Variables

Option 1: The `instapods env` command (Recommended)

Option 2: Create a `.env` File

Option 3: Set at Pod Creation (API)

How your app reads them

Three cases where you still need to read the file yourself

Node.js

Python

PHP

Go

Static

Common Pattern: Database Credentials

Variables InstaPods sets itself

File permissions

Updating Variables

Best Practices

​Setting Environment Variables

​Option 1: The instapods env command (Recommended)

​Option 2: Create a .env File

​Option 3: Set at Pod Creation (API)

​How your app reads them

​Three cases where you still need to read the file yourself

​Node.js

​Python

​PHP

​Go

​Static

​Common Pattern: Database Credentials

​Variables InstaPods sets itself

​File permissions

​Updating Variables

​Best Practices

Setting Environment Variables

Option 1: The `instapods env` command (Recommended)

Option 2: Create a `.env` File

Option 3: Set at Pod Creation (API)

How your app reads them

Three cases where you still need to read the file yourself

Node.js

Python

PHP

Go

Static

Common Pattern: Database Credentials

Variables InstaPods sets itself

File permissions

Updating Variables

Best Practices