Builds

Deploy your app from source and let StackMachine build it for you. StackMachine automatically detects the language and framework, installs dependencies, and builds the app. Send source files or a ZIP archive, watch build progress, and receive the live app URL when the version is ready.

Features

Files and ZIP uploads

For small deploys, pass a files map directly to client.deployments.create. For larger bundles, upload a ZIP with client.files.upload and deploy from the returned uploadUrl.

Automatic detection

Include your source, dependency manifests, and lockfiles. StackMachine detects how to install, build, and run the project, so you can omit install/build/start commands. Use installCmd / install_cmd, buildCmd / build_cmd, or startCmd / start_cmd when you need to override the detected commands.

Streaming progress

The returned deployment is created immediately with a build ID. Call deployment.wait and attach onProgress to watch stdout, stderr, runtime messages, and build lifecycle events.

Repeatable releases

Use allowExistingApp when pushing a new version of an existing app. StackMachine creates a fresh app version while preserving the app identity and domains.

Common workflow

Prepare source files and optional environment variables.
Create a deployment with inline files or an uploaded ZIP URL.
Wait for the build to finish and inspect progress logs.
Use the returned app version to open the live URL or fetch runtime logs later.

SDK examples

Deploy source and watch the build

Both SDKs deploy this Node.js app from source. StackMachine detects its package.json and scripts; no command overrides or local build are needed.

builds.jsbuilds.py

const deployment = await client.deployments.create(
  {
    appName: "edge-storefront",
    owner: "stackmachine",
    files: {
      "package.json": JSON.stringify({
        type: "module",
        scripts: {
          build: "node build.js",
          start: "node server.js",
        },
        dependencies: {},
        devDependencies: {},
      }),
      "build.js": [
        'import { mkdirSync, writeFileSync } from "node:fs";',
        'mkdirSync("dist", { recursive: true });',
        'writeFileSync("dist/index.html", "<h1>Hello from StackMachine</h1>");',
      ].join("\n"),
      "server.js": [
        'import { createServer } from "node:http";',
        'import { readFileSync } from "node:fs";',
        "",
        "createServer((req, res) => {",
        '  res.setHeader("content-type", "text/html");',
        '  res.end(readFileSync("dist/index.html"));',
        "}).listen(Number(process.env.PORT || 3000));",
      ].join("\n"),
    },
    envVars: [{ name: "NODE_ENV", value: "production", sensitive: false }],
  },
  {
    onUploadProgress: ({ percent }) => console.log("upload", percent),
  },
);

const appVersion = await deployment.wait({
  onProgress: ({ datetime, stream, message }) => {
    console.log(datetime, stream, message);
  },
});

console.log(appVersion.app.url);

import json

deployment = client.deployments.create(
    app_name="edge-storefront",
    owner="stackmachine",
    files={
        "package.json": json.dumps({
            "type": "module",
            "scripts": {"build": "node build.js", "start": "node server.js"},
        }),
        "build.js": '\n'.join([
            'import { mkdirSync, writeFileSync } from "node:fs";',
            'mkdirSync("dist", { recursive: true });',
            'writeFileSync("dist/index.html", "<h1>Hello from StackMachine</h1>");',
        ]),
        "server.js": '\n'.join([
            'import { createServer } from "node:http";',
            'import { readFileSync } from "node:fs";',
            'createServer((req, res) => {',
            '  res.setHeader("content-type", "text/html");',
            '  res.end(readFileSync("dist/index.html"));',
            '}).listen(Number(process.env.PORT || 3000));',
        ]),
    },
    env_vars=[{"name": "NODE_ENV", "value": "production", "sensitive": False}],
    on_upload_progress=lambda event: print("upload", event.percent),
)
app_version = deployment.wait(
    on_progress=lambda event: print(event.datetime, event.stream, event.message),
)
print(app_version.app.url)

Watch builds

Save the build ID returned when a deployment starts. Use client.deployments.retrieve to inspect that existing build, including after your process restarts. This observes the build; it does not restart execution or create a new deployment.

retrieveDeployment.jsretrieve_deployment.py

const buildId = "your-build-id";
const deployment = await client.deployments.retrieve(buildId);
// Should return: {
//   "buildId": "your-build-id",
//   "status": "RUNNING",
//   "appVersion": null
// }
console.log(deployment.buildId, deployment.status);

build_id = "your-build-id"
deployment = client.deployments.retrieve(build_id)
# Should return: {
#   "build_id": "your-build-id",
#   "status": "RUNNING",
#   "app_version": null
# }
print(deployment.build_id, deployment.status)

Wait for the watched build

Call wait() on the retrieved deployment to stream progress until it finishes. A successful build returns its app version; a failed build raises an error. To start a new build, create a new deployment.