Environment Variables and Secrets

Store tokens, API keys and connection strings as environment variables on Square Cloud from the dashboard, the CLI or the API, and read them in your code.

Keep bot tokens, API keys and database passwords out of your source code. Set them as environment variables on the application, and your code reads them at runtime like any other variable.

Set variables

Environment variables belong to one application. They survive restarts and commits, but a new upload creates a new application without them, so set them again there.

Dashboard

1. Open your application in the dashboard and go to Settings → Environment Variables.
2. Add each key and value, or import an existing .env file.
3. Click Save. The dashboard asks whether to restart the application: restart it so the app picks up the new values.

When you upload a new application in the dashboard, you can also add variables on the upload screen, before the first start.

CLI

Run the commands from your project folder. The CLI targets the application whose ID is in your squarecloud.app. To target another one, pass --app <app ID> (for list, pass the ID as its argument).

# Add or update variables (the others stay as they are)
squarecloud app env set DISCORD_TOKEN=your-token LOG_LEVEL=info

# Send every line of a local .env file
squarecloud app env set --from-file .env

# List the current variables
squarecloud app env list

# Remove one variable
squarecloud app env remove LOG_LEVEL

# Restart to apply the changes
squarecloud app restart

squarecloud app env replace swaps the whole set for the one you pass, after a confirmation. Every command and flag is covered in environment variables from the CLI; to install the CLI and log in, see the CLI quickstart.

VS Code

In the Square Cloud extension, right-click your application in the side bar and choose Environment variables to list, add, edit or delete them. Restart the application afterwards to apply the changes.

API

Send the variables to POST /v2/apps/{app_id}/envs with an API key that has the envs:write scope:

curl -X POST "https://api.squarecloud.app/v2/apps/YOUR_APP_ID/envs" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"envs": {"DISCORD_TOKEN": "your-token"}}'

The same path also lists (GET), replaces (PUT) and removes (DELETE) variables. The API doesn’t restart the application: call the restart endpoint afterwards.

Variables are loaded when the application starts. After any change, restart the application, or it keeps running with the old values.

Read them in your code

Node.js

const token = process.env.DISCORD_TOKEN;

if (!token) {
  throw new Error("DISCORD_TOKEN is not set");
}

Failing fast when a variable is missing gives you a clear message in the logs instead of a confusing error later, such as an invalid token.

Variables Square Cloud sets for you

Your application starts with these variables already defined:

Variable	Value	Use it to
PORT	80	Choose the port your web server listens on.
HOST	0.0.0.0	Choose the address your web server binds to.
SQUARECLOUD_APP_ID	Your application ID	Identify the application at runtime.
NODE_ENV	production	Tell Node.js libraries they run in production (Node.js and TypeScript runtimes).

Don’t override PORT or HOST on a website: the platform only reaches a server on port 80 and host 0.0.0.0.

Because NODE_ENV is production, npm install skips devDependencies. If your START command builds the project (for example with typescript or vite), list those build tools under dependencies in package.json.

How variables reach your app

Square Cloud stores the variables in a .squarecloud/.env file inside the application and loads them with a shell every time the application starts, before dependencies are installed and your START command or MAIN file runs. Two consequences:

• Names should use letters, digits and underscores, and not start with a digit.
• Values with spaces or shell characters such as $, &, ; or | must be quoted, or the shell cuts or expands them. The dashboard and squarecloud app env set quote them for you. In the VS Code extension or the API, wrap such a value in single quotes yourself: type 'p@ss word$1', or send "PASSWORD": "'p@ss word$1'" in the API body.

The limits are 256 variables per application, 1,024 characters per name and 4,096 characters per value. Static websites (HTML/CSS) don’t support environment variables and return STATIC_APP_ENV_NOT_SUPPORTED.

Keep secrets out of your upload

If your code loads a .env file itself (for example with dotenv), that file has to be in the upload. Listing .env in squarecloud.ignore then starts the app without its secrets, and a bot fails with an invalid token.

The safer setup: move each value from your .env into the application’s environment variables, as shown above. Once they are set, you can leave .env out of the upload and out of your Git repository. dotenv doesn’t overwrite variables that already exist, so the same code keeps working on your machine and on Square Cloud.

Never commit tokens or passwords to a public repository. If one leaks, revoke it at the provider (for example, reset the bot token in the Discord Developer Portal) and set the new value here.

Next steps

Configuration file

Set MAIN, MEMORY, START and the other fields of squarecloud.app.

Host a Discord bot

Deploy a bot that reads its token from an environment variable.

Discord bot errors

Fix an invalid token, missing intents and bots that go offline.

Database connection errors

Connect with a DATABASE_URL and the right SSL settings.