Quickstart: Deploy Your First App

This guide deploys a small Node.js web server so you can see the whole flow end to end: three files, one zip and one upload. The steps are the same for a bot or for another language.

Before you begin

Square Cloud is a paid platform: an active plan is required to deploy, so your project runs on production-grade infrastructure from day one. Create your account, then select the plan that’s right for you (see what each plan includes).

Sign Up

If you’ve never used Square before, sign up to get started.

Log in

If you already have an account, log in to get started.

Create the project

Create a folder with these three files.

Write the app

index.js answers every request with a short message. It reads the port and host from the PORT and HOST environment variables, which Square Cloud sets to 80 and 0.0.0.0:

index.js

const http = require("node:http");

const port = process.env.PORT || 3000;
const host = process.env.HOST || "0.0.0.0";

http
  .createServer((req, res) => {
    res.writeHead(200, { "Content-Type": "text/plain" });
    res.end("Hello from Square Cloud!");
  })
  .listen(port, host, () => {
    console.log(`Listening on http://${host}:${port}`);
  });

List the dependencies

Every Node.js project needs a package.json: Square Cloud installs the packages it lists before starting your app. This example has none, but the file must exist and can’t be empty.

package.json

{
  "name": "hello-square",
  "version": "1.0.0",
  "private": true,
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  }
}

Add the configuration file

squarecloud.app tells Square Cloud which file to run, how much memory to reserve and which runtime version to use. SUBDOMAIN publishes the app as a website at https://<subdomain>.squareweb.app, so pick a name nobody has taken yet.

squarecloud.app

MAIN=index.js
MEMORY=512
VERSION=recommended
DISPLAY_NAME=Hello Square
SUBDOMAIN=hello-square-yourname

Every field is explained in the configuration file reference. The VS Code extension autocompletes and checks this file as you type.

A website must listen on port 80 and host 0.0.0.0. A server bound to localhost, 127.0.0.1 or another port (such as 3000 or 8080) can’t be reached, and the site shows a timeout page. Reading PORT and HOST, as index.js does, gets this right on Square Cloud and still runs on port 3000 on your machine.

Deploying a bot instead? Leave out SUBDOMAIN, add AUTORESTART=true, and keep the token in an environment variable, never in the code. The Discord bot tutorial walks through a complete bot.

Zip the project

Deploying with the CLI? Skip this section: squarecloud upload zips the folder for you.

Select the files, not the folder

Open the project folder and select everything inside it. squarecloud.app must sit at the top level of the zip: if you compress the folder itself, the files end up inside a subfolder and the deploy fails with MISSING_CONFIG.

Create the zip

Windows
macOS
Linux

Right-click the selected files and choose Compress to ZIP file (Windows 11) or Send to → Compressed (zipped) folder.

Right-click the selected files and choose Compress, or run zip -r ../app.zip . inside the folder.

Check the size

The zip can be up to 100 MB. Leave out node_modules, virtual environments and build caches: dependencies are installed on the server, and those folders are deleted on deploy anyway.

Deploy

Upload the zip in the dashboard, or deploy with one command from the CLI.

Via dashboard

Access the Upload Page

Access the upload page and upload your project zip file.

Configure Your Environment

After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.
If you are uploading a web project, make sure to select “Web Publication” and set a subdomain to your project.

Deploy Your Project

Finally, click on the “Deploy” button to host your project on Square Cloud.
After deployment, you can monitor your project’s status and logs from the dashboard.

Confirm Your App Is Live

Your first deploy usually takes less than a minute. In the dashboard, wait for your application status to show as running and check the logs for any startup errors.
If you deployed a website or API, open https://<your-subdomain>.squareweb.app in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online.

App not starting? See the Troubleshooting guide for the most common causes and fixes.

Via CLI

To use this method, your project needs a configuration file named squarecloud.app at its root. It tells Square Cloud how to run your application.

Configuration file guide

Learn how to create the squarecloud.app configuration file that defines your application’s environment.

Install the CLI

Install the Square Cloud CLI. If you already have it, run the same command to update it:

curl -fsSL https://cli.squarecloud.app/install | bash

npm install -g @squarecloud/cli@latest

Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see CLI authentication.

squarecloud auth login

Upload Your Project

From your project folder, run the command below. The CLI zips the current folder, leaving out what squarecloud.ignore lists, and uploads it:

squarecloud upload

To upload a zip you created yourself, pass it with --file:

squarecloud upload --file <path/to/zip>

Confirm Your App Is Live

Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal:

squarecloud app status
squarecloud app logs

If you deployed a website or API, open https://<your-subdomain>.squareweb.app in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online.

App not starting? See the Troubleshooting guide for the most common causes and fixes.

Once the app is running, https://hello-square-yourname.squareweb.app (with your subdomain) answers Hello from Square Cloud!.

Want a deploy on every push? Connect a GitHub repository or use the GitHub Actions workflow.

Next steps

Configuration file

Every squarecloud.app field: memory, start command, subdomain and automatic restarts.

Environment variables

Store tokens and connection strings outside your code.

Troubleshooting

Fix upload errors, sites that don’t load and apps that won’t start.

VS Code extension

Upload, commit and follow logs without leaving your editor.

Guides for your language

Each guide covers the dependency file, the start command and the common pitfalls of its runtime.

Services

Troubleshooting

Runtimes

Platform

Changelog

Quickstart: Deploy Your First App

Before you begin

Sign Up

Log in

Create the project

Zip the project

Deploy

Via dashboard

Via CLI

Configuration file guide

Next steps

Configuration file

Environment variables

Troubleshooting

VS Code extension

Guides for your language

JavaScript

Bun

Deno

Python

Java

Rust

Elixir

PHP

Go

C#

Ruby

HTML/CSS

​Before you begin

Sign Up

Log in

​Create the project

​Zip the project

​Deploy

​Via dashboard

​Via CLI

Configuration file guide

​Next steps

Configuration file

Environment variables

Troubleshooting

VS Code extension

​Guides for your language

JavaScript

Bun

Deno

Python

Java

Rust

Elixir

PHP

Go

C#

Ruby

HTML/CSS

Before you begin

Create the project

Zip the project

Deploy

Via dashboard

Via CLI

Next steps

Guides for your language