Python SDK: manage applications

Every method on this page lives on client.apps and takes the app id first. An app_id can also be the composite <appId>-<workspaceId> of an app shared through a workspace.

import os

from squarecloud import SquareCloud

client = SquareCloud(os.environ["SQUARECLOUD_API_KEY"])
app_id = "abc123def456abc123def456"

With AsyncSquareCloud, every call below is the same with await in front. To list your apps, use client.account.me(): its applications list has every app the key can see.

Getting an application

app = client.apps.get(app_id)

print(app["id"], app["name"], app["language"], app["ram"], app["cluster"], app["created_at"])

Field	Type	Description
`id`	`str`	App id
`name`	`str`	Display name
`desc`	`str`, optional	Description
`owner`	`str`	Owner’s user id
`cluster`	`str`	Cluster the app runs on
`ram`	`int`	Allocated RAM in MB
`language`	`str`	Runtime language
`domain`	`str \| None`, optional	Default `<subdomain>.squareweb.app` host; absent or `None` for non-web apps
`custom`	`str \| None`, optional	Custom domain; absent or `None` when none is set
`created_at`	`str`	Creation date (ISO 8601)

Optional fields may be missing from the dict: read them with app.get("domain").

Status

status(app_id) returns the live state with formatted values:

status = client.apps.status(app_id)

print(status["status"])   # e.g. "running", "exited"
print(status["running"])  # True
print(status["cpu"])      # "0.5%"
print(status["ram"])      # "120.4MB" (RAM in use)
print(status["storage"], status["network"]["total"], status["network"]["now"])
print(status["uptime"])   # Unix ms of the last start, None when stopped

Pass raw=True to get numbers instead (cpu in %, ram in MB, network["total"] and network["now"] as [in, out] byte pairs):

raw = client.apps.status(app_id, raw=True)

print(raw["cpu"], raw["ram"], raw["network"]["total"])  # 0.5 120.4 [1024, 2048]

uptime is a timestamp (when the app started), not a duration. Use time.time() * 1000 - status["uptime"] for how long it has been up, in ms.

Status of every application

status_all() returns one summary per app the key can see, in a single request. cpu and ram are only present while the app runs.

for item in client.apps.status_all():
    print(item["id"], f"{item['cpu']} {item['ram']}" if item["running"] else "stopped")

# Only the apps of one workspace
shared = client.apps.status_all(workspace_id=workspace_id)

Start, stop and restart

client.apps.start(app_id)
client.apps.stop(app_id)
client.apps.restart(app_id)

The server holds these calls open until the container acts, so they wait at least 120 s before timing out. When the platform refuses the action, the call raises a SquareCloudAPIError with status 409, a code and an empty message (''):

Code	Meaning
`CONTAINER_ALREADY_STARTED`	`start` on a running app
`CONTAINER_ALREADY_STOPPED`	`stop` on a stopped app
`CONTAINER_TEMPORARILY_SUSPENDED`	The app is suspended
`CONTAINER_NOT_FOUND`	The container does not exist on the cluster
`CONTAINER_INSUFFICIENT_DISK_SPACE`	Not enough disk to start
`CONTAINER_NETWORK_CONFLICT`	Network conflict on the cluster
`ACTION_FAILED`	The cluster could not perform the action

“Already started” and “already stopped” are errors too. If they mean success for you, handle them:

from squarecloud import SquareCloudAPIError

try:
    client.apps.start(app_id)
except SquareCloudAPIError as error:
    if error.code != "CONTAINER_ALREADY_STARTED":
        raise

Logs

logs(app_id) returns the latest console output as one string ('' when there is none).

print(client.apps.logs(app_id))

For a live stream of logs, use Realtime.

Metrics

metrics(app_id) returns the last 24 hours, one point every 5 minutes, newest first.

latest = client.apps.metrics(app_id)[0]

print(latest["date"], latest["cpu"], latest["ram"], latest["net"])

Domains and load balancers

domains() lists the default and custom hostnames of every app. load_balancers() lists the domains shared by several apps, with your plan’s limit.

for domain in client.apps.domains():
    print(domain["app_id"], domain["hostname"], domain["type"])  # type: "subdomain" | "custom"

balancers = client.apps.load_balancers()
print(balancers["limit"])
for balancer in balancers["balancers"]:
    print(balancer["hostname"], [app["id"] for app in balancer["apps"]])

To set a custom domain, see Network.

Deleting an application

client.apps.delete(app_id)

Deletion is permanent. Create a snapshot first if you may need the files again.

Next steps

Commit and upload

Create an app from a zip or send files to one.

Application API reference

The REST endpoints behind these methods.

Manage apps from the CLI

The same actions from the terminal.

CLI

VS Code

SDKs

Python SDK: manage applications

Getting an application

Status

Status of every application

Start, stop and restart

Logs

Metrics

Domains and load balancers

Deleting an application

Next steps

Commit and upload

Application API reference

Manage apps from the CLI

​Getting an application

​Status

​Status of every application

​Start, stop and restart

​Logs

​Metrics

​Domains and load balancers

​Deleting an application

​Next steps

Commit and upload

Application API reference

Manage apps from the CLI

Getting an application

Status

Status of every application

Start, stop and restart

Logs

Metrics

Domains and load balancers

Deleting an application

Next steps