StackMachine SDK | StackMachine Docs

Examples are pulled from stackmachine/sdks; every SDK example includes a JavaScript / Python toggle.

Quickstart

Install the SDK

ShellShell

npm install stackmachine

pip install stackmachine

Set your workspace API token

Prefer a token for one workspace (called a namespace in GraphQL). Follow Agent authentication to sign in, choose a workspace, and get its API token:

export STACKMACHINE_API_TOKEN=your_workspace_api_token_here

Deploy your first app

Pass a files map to deployments.create, wait for the build, then open the app URL:

deploy-from-files.jsdeploy_from_files.py

// Request: appName, owner, files (required); optional envVars, region
const deployment = await client.deployments.create(
  {
    appName: "hello-stackmachine",
    owner: "stackmachine",
    files: {
      "index.html": "<html><body><h1>Hello StackMachine</h1></body></html>",
    },
    envVars: [{ name: "NODE_ENV", value: "production", sensitive: false }], // sensitive: hide value in the dashboard
    region: "iad", // region slug where the app is deployed
  },
  {
    onUploadProgress: ({ percent }) => {
      console.log("Upload progress %:", percent * 100);
    },
  },
);
// Should return: {
//   "buildId": "build_abc123",
//   "status": "QUEUED",
//   "appVersion": null
// }
console.log(deployment.buildId, deployment.status);

const appVersion = await deployment.wait({
  onProgress: ({ datetime, stream, kind, message }) => {
    // Should log: {
    //   "kind": "LOG",
    //   "message": "Building...",
    //   "datetime": "2024-01-15T12:00:00.000Z",
    //   "stream": "STDOUT"
    // }
    console.log(datetime, stream, kind, message);
  },
});
// Should return: {
//   "id": "dv_xyz789",
//   "app": {
//     "id": "da_abc123",
//     "name": "hello-stackmachine",
//     "url": "https://hello-stackmachine.stackmachine.app",
//     "adminUrl": "https://stackmachine.com/app/da_abc123"
//   }
// }
console.log(appVersion.id, appVersion.app.url, appVersion.app.adminUrl);

# Request: app_name, owner, files; optional env_vars, region
deployment = client.deployments.create(
    app_name="hello-stackmachine",
    owner="stackmachine",
    files={
        "index.html": "<html><body><h1>Hello StackMachine</h1></body></html>",
    },
    env_vars=[{"name": "NODE_ENV", "value": "production", "sensitive": False}],  # sensitive: hide value in the dashboard
    region="iad",  # region slug where the app is deployed
    on_upload_progress=lambda p: print("Upload progress %:", p.percent * 100),
)
# Should return: {
#   "build_id": "build_abc123",
#   "status": "QUEUED",
#   "app_version": null
# }
print(deployment.build_id, deployment.status)

app_version = deployment.wait(
    on_progress=lambda e: print(e.datetime, e.stream, e.kind, e.message),
)
# Should return: {
#   "id": "dv_xyz789",
#   "app": {
#     "id": "da_abc123",
#     "name": "hello-stackmachine",
#     "url": "https://hello-stackmachine.stackmachine.app",
#     "admin_url": "https://stackmachine.com/app/da_abc123"
#   }
# }
print(app_version.id, app_version.app.url, app_version.app.admin_url)

Deploy existing apps from source with Deploy from ZIP: StackMachine automatically detects the project, installs dependencies, and builds it for you. See Redeploy to update an app and Watch builds to observe an existing build.

List what’s running

for await (const app of client.apps.list({ limit: 10 })) {
  console.log(app.name, app.url);
}

for app in client.apps.list(limit=10):
    print(app.name, app.url)

List apps — full paging examples.

Explore the docs

Getting StartedInstall the SDK, set your API key, and pick sync or async Python.DeploymentsDeploy sites from files, ZIP, or Git, then manage apps, domains, and SSH.VolumesAttach persistent filesystem storage and access files through S3.DatabasesCreate app databases and connect through environment variables.MailsSend transactional emails and check delivery status.JobsSchedule commands or HTTP calls and manage recurring jobs.UsageInspect usage analytics, metrics, and build or runtime logs.GuidesWordPress, demos, and end-to-end walkthroughs.