Skip to main content
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.
  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.
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

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:
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.