---
title: "StackMachine SDK"
description: "Deploy and manage apps on StackMachine with JavaScript/TypeScript or Python."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.stackmachine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# StackMachine SDK

Examples are pulled from [`stackmachine/sdks`](https://github.com/stackmachine/sdks); every SDK example includes a **JavaScript / Python** toggle.

## Quickstart

### Install the SDK

```bash
npm install stackmachine
```

```bash
pip install stackmachine
```

### Set your workspace API token

Prefer a token for one workspace (called a namespace in GraphQL). Follow [Agent authentication](/getting-started/agent-authentication) to sign in, choose a workspace, and get its API token:

```bash
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:

```javascript
// 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);
```

```python
# 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](/apps/deployments/from-zip): StackMachine automatically detects the project, installs dependencies, and builds it for you. See [Redeploy](/apps/deployments/redeploy) to update an app and [Watch builds](/apps/deployments/builds#watch-builds) to observe an existing build.

### List what's running

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

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

[List apps](/apps/list) — full paging examples.

## Explore the docs

- [Getting Started](/getting-started/installation): Install the SDK, set your API key, and pick sync or async Python.
- [Deployments](/apps): Deploy sites from files, ZIP, or Git, then manage apps, domains, and SSH.
- [Volumes](/volumes): Attach persistent filesystem storage and access files through S3.
- [Databases](/databases): Create app databases and connect through environment variables.
- [Mails](/mails): Send transactional emails and check delivery status.
- [Jobs](/jobs): Schedule commands or HTTP calls and manage recurring jobs.
- [Usage](/usage): Inspect usage analytics, metrics, and build or runtime logs.
- [Guides](/guides/wordpress): WordPress, demos, and end-to-end walkthroughs.

Source: https://docs.stackmachine.com/index.mdx