Apps

client.apps deploys image apps: apps that run an image from a Cosmoner container registry. Apps built from a repository deploy by pushing to their branch, and the API refuses to deploy them this way.

Listing apps and reading deployments needs apps:read. Starting a deployment needs apps:write.

Deploy and wait

const { data: apps } = await client.apps.list();
const web = apps.find((app) => app.name === "web");
if (!web) throw new Error("No app named web");

const { data: started } = await client.apps.deploy(web.id, { tag: "v2" });

const finished = await client.apps.waitForDeployment(web.id, started.id, {
  onPoll: (d) => console.log(d.phase),
});

if (finished.phase !== "ACTIVE") {
  throw new Error(finished.error ?? `Deployment ended ${finished.phase}`);
}

In a CI pipeline, cosmoner deploy does the same in one line, with no code to maintain.

deploy(appId, ...)

Starts a deployment and returns it straight away, without waiting.

Pass tag or digest, not both. Pass neither to pull the image the app already names again — useful when a tag such as latest has been pushed over.

waitForDeployment(appId, deploymentId, ...)

Polls the deployment until it finishes, then returns it. wait_for_deployment in Python.

interval and timeout are in milliseconds in JavaScript and seconds in Python and PHP.

It returns for every finished phase, successful or not, so check phase yourself:

It raises only when a request fails or timeout passes. A timeout stops the wait, not the deployment — the rollout carries on, and you can pick it up again with getDeployment.

Other methods

A deployment carries its phase, the imageRef and imageDigest it deployed, an error when it failed, and its startedAt and finishedAt times.