Skip to main content

​
What is the configuration file?

The configuration file tells Square Cloud how to run your application: which file to start, how much memory to reserve, which runtime version to use and, for a website, which subdomain to publish. It is a plain text file with one KEY=VALUE pair per line.
squarecloud.app

​
Creating the configuration file

Create a file named squarecloud.app or squarecloud.config at the root of your project. Both names work the same way. When you upload a zip, the file must sit at the top level of the zip, not inside a subfolder, or the deploy fails with MISSING_CONFIG.
On macOS, we recommend the squarecloud.config name.
The VS Code extension autocompletes every key below and underlines invalid values as you type.

​
Configuration parameters

MEMORY, VERSION and DISPLAY_NAME are always required. MAIN is required unless you set RUNTIME. Editable parameters can be changed in the dashboard after the deploy. Changing a non-editable parameter requires uploading the application again.

​
MAIN

The file that starts your application, relative to the project root.
  • The file extension selects the runtime: .js runs on Node.js, .ts on TypeScript, .py on Python, and so on.
  • The file must exist in your upload and can’t be empty.
  • Up to 32 characters: letters, digits, _, ., / and -, no spaces.
A missing MAIN (without RUNTIME) fails with MISSING_MAIN; a file that doesn’t exist, has no extension or breaks the rules above fails with INVALID_MAIN.

​
MEMORY

The RAM reserved for your application, in megabytes. It also sets your application’s vCPUs and bandwidth.
The value must be at least the minimum for your project type, and no more than the RAM your plan still has free. Otherwise the deploy fails with INSUFFICIENT_MEMORY.

​
VERSION

The runtime version: recommended or latest. Any other value, including an exact version number, fails the deploy with INVALID_VERSION.
Use recommended unless you need a feature that only the newest release has. The versions behind each value are listed in the runtime versions table.

​
DISPLAY_NAME

The name shown in the dashboard, the CLI and the API.
Up to 32 characters: letters without accents, digits, spaces, - and _. Anything else, such as accented letters or emoji, fails with INVALID_DISPLAY_NAME.

​
DESCRIPTION

A short description of the application, up to 280 characters (INVALID_DESCRIPTION beyond that).

​
AUTORESTART

Restarts the application automatically after a crash. Accepts true or false, and defaults to false, so turn it on for bots and anything that must stay online.
An automatic restart happens only when all of these are true:
  • The application exited with status 1, the usual exit code of an unhandled error in Node.js and Python.
  • It had been running for at least 60 seconds, so an app that crashes right at boot isn’t restarted in a loop.
  • It hasn’t been restarted automatically in the last hour.
  • The logs don’t show an error a restart can’t fix: an invalid bot token, a missing module, a syntax or TypeScript type error, or a failed dependency install.
A restart keeps the app online through a transient error, but the underlying bug still needs a fix in your code. See also the help center article on auto restart.

​
SUBDOMAIN

Publishes the application as a website at https://<subdomain>.squareweb.app.
  • Up to 63 characters: letters, digits and hyphens, not starting or ending with a hyphen. The name is stored in lowercase.
  • A name that is already in use, reserved (such as admin or api) or invalid fails with INVALID_SUBDOMAIN.
  • A website needs more RAM than a bot: see the minimum RAM.
  • Your server must listen on port 80 and host 0.0.0.0 (see website doesn’t load).
Decide at the first upload whether the application is a website. On a website you can change the subdomain later, but you can’t remove it (CANNOT_SET_SUBDOMAIN). An application deployed without SUBDOMAIN can’t become a website: upload it again as a new application with SUBDOMAIN set.
To serve the site on your own domain, see how to set up your own domain in the help center.

​
RUNTIME

Sets the runtime explicitly, instead of deriving it from the extension of MAIN. An unknown value fails with INVALID_RUNTIME.
With RUNTIME set you can leave out MAIN. In that case, also set START: most runtimes start the application by running the MAIN file.

​
START

A custom start command. It replaces the default command, which runs your MAIN file.
  • Up to 256 characters (INVALID_START beyond that).
  • Dependencies are still installed before the command runs.
  • The command is read from the file on every start, so you can change it by editing squarecloud.app in the dashboard and restarting.
Only call scripts that exist in your project. START=npm run build && npm run start, for example, fails on an Express app without a build script in package.json. Leave START out when the default command is enough.

​
ID

You don’t write this key yourself. After squarecloud upload, the Square Cloud CLI adds ID=<app ID> to the file, so later commands such as squarecloud commit know which application to target. Square Cloud ignores it when deploying.

​
Examples

​
Bot

squarecloud.app

​
Website or API

squarecloud.app
The site answers at https://mysite.squareweb.app.

​
Next.js

A framework that needs a build step uses START. Here MAIN only selects the Node.js runtime, so point it at your actual config file (such as next.config.mjs); the build and start scripts come from package.json.
squarecloud.app

​
Next steps

Environment variables

Keep tokens and connection strings out of your code and your zip.

squarecloud.ignore

Choose which files the CLI and VS Code leave out of the upload.

Runtimes

Versions, dependency files and how each runtime starts your app.

Troubleshooting

What each deploy error means and how to fix it.