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

# Serverless API

> Build a versioned ComfyUI environment, deploy it as a managed endpoint, and run workflows through the API.

<Warning>
  Serverless API is in beta. Sign up for access at [platform.comfy.org](https://platform.comfy.org).
</Warning>

Serverless API gives a ComfyUI workflow a managed URL and on-demand GPU capacity. The new Build and Deploy CLI keeps the build definition in your project, creates releases from that definition, and deploys a release when it is ready to serve traffic.

<CardGroup cols={2}>
  <Card title="1. Build" icon="box">
    Create a local build specification from your ComfyUI install.
  </Card>

  <Card title="2. Release" icon="tag">
    Cut an immutable Linux/NVIDIA release from the Build.
  </Card>

  <Card title="3. Deploy" icon="cloud-arrow-up">
    Give the release a URL and managed GPU capacity.
  </Card>

  <Card title="4. Run" icon="code">
    Submit an API-format workflow to the active deployment.
  </Card>
</CardGroup>

## Quick start

Use these commands when the local install and API-format workflow are ready:

Use the compute output to choose a valid region and GPU. Replace `<region>` and `l4` if needed; copy the deployment ID that `deploy up` prints into the final command.

```bash theme={null}
comfy build init --name "my-comfy-build" --models-dir ./models --custom-nodes-dir ./custom_nodes

comfy build push --release --target linux/nvidia
comfy deploy refs compute # get available regions and GPU classes
comfy deploy up --gpu l4 --region <region> --min 1 --max 4 --watch # prints the deployment ID
comfy deploy run --workflow workflow_api.json --deployment <deployment-id> --output-dir ./results
```

<Steps>
  <Step title="Initialize">
    ```bash theme={null}
    comfy build init --name "my-comfy-build" --models-dir ./models --custom-nodes-dir ./custom_nodes
    ```
  </Step>

  <Step title="Create a release">
    ```bash theme={null}
    comfy build push --release --target linux/nvidia
    ```

    This syncs the Build and creates a release for the target.
  </Step>

  <Step title="Start a deployment">
    If you do not already know where the selected GPU is available, check first:

    ```bash theme={null}
    comfy deploy refs compute --region <region>
    ```

    Then create or reconcile the deployment:

    ```bash theme={null}
    comfy deploy up --gpu <gpu> --region <region> --min 1 --max 4 --watch
    ```

    `deploy up` prints the new deployment ID. If you need to retrieve it later, list this Build's ready deployments:

    ```bash theme={null}
    comfy deploy ls --status ready
    ```

    Use the returned `dep_...` value with `--deployment`.
  </Step>

  <Step title="Run the workflow">
    ```bash theme={null}
    comfy deploy run \
      --workflow workflow_api.json \
      --deployment <deployment-id> \
      --output-dir ./results
    ```

    The CLI submits the API-format workflow and downloads its outputs into `./results`.
  </Step>
</Steps>

## The build file

`comfy-build.yaml` is the local source of truth for a Build. It stores the build definition and the last known remote state, so the CLI can choose the right Build automatically and warn before local changes overwrite a newer remote definition.

Keep this file with the project. It describes the Build; it does not contain the model bytes themselves.

## 1. Initialize a Build

Start from a local ComfyUI install. This scans the models and custom nodes, then writes `comfy-build.yaml`.

```bash theme={null}
comfy build init --name "my-comfy-build" --models-dir ./models --custom-nodes-dir ./custom_nodes
```

Before pushing, check how the local spec compares with the install and the remote Build:

```bash theme={null}
comfy build status
```

## 2. Update and release

After changing the local ComfyUI install, refresh the local build definition:

```bash theme={null}
comfy build update --yes
```

For the quick path, push the definition and release it for a target in one command:

```bash theme={null}
comfy build push --release --target linux/nvidia
```

When you need to create another release from an existing Build, inspect the supported targets and cut one explicitly:

```bash theme={null}
comfy build refs build-targets
comfy build release create --target linux/nvidia --watch
```

Follow one release's build log with:

```bash theme={null}
comfy build release logs rel_123456 --target linux/nvidia --follow
```

## Regions and GPU availability

Region capacity changes, so do not copy a static list into a script. Query the platform catalog when you choose a deployment target:

```bash theme={null}
comfy deploy refs compute
```

Use `--region <region>` to filter the results:

```bash theme={null}
comfy deploy refs compute --region <region>
```

Copy a returned `region` and `gpu` pair into `comfy deploy up`:

```bash theme={null}
comfy deploy up --gpu <gpu> --region <region> --min 1 --max 4 --watch
```

The catalog is the source of truth for which GPU classes are available in each region at deployment time.

## 3. Deploy a release

Discover the available compute in a region, then create or reconcile a deployment for the selected release:

```bash theme={null}
comfy deploy refs compute --region US-MO-2

comfy deploy up \
  --gpu l4 \
  --region US-MO-2 \
  --min 1 \
  --max 4 \
  --watch
```

`--min` and `--max` set the worker bounds. Use `comfy deploy status --watch` to follow deployment health, release freshness, and serving activity.

## 4. Run a workflow

Submit an [API-format workflow](/development/api-development/workflow-api-format) to a ready deployment:

```bash theme={null}
comfy deploy run \
  --workflow workflow_api.json \
  --deployment dep_123456 \
  --output-dir ./results
```

The endpoint can also be called from the [Comfy SDKs](/development/api-development/sdks) by setting `COMFY_BASE_URL` to the deployment URL. The SDK request still needs an API key: see [Choosing a base URL](/development/api-development/sdks#choosing-a-base-url).

## Operate a deployment

```bash theme={null}
# Change the worker bounds
comfy deploy scale --deployment dep_123456 --min 2 --max 5

# Pause or resume while retaining the deployment record
comfy deploy stop --deployment dep_123456
comfy deploy start --deployment dep_123456
```

## Inspect and clean up

```bash theme={null}
# Build state
comfy build ls
comfy build show --id bld_123456
comfy build release ls
comfy build release show rel_123456

# Deployment state
comfy deploy ls --workspace --status ready
comfy deploy logs --deployment dep_123456
comfy deploy events --deployment dep_123456
```

<Warning>
  Deleting a deployment and deleting a Build are separate irreversible operations. Confirm the target before using `comfy deploy delete --yes` or `comfy build delete --id bld_123456 --yes`.
</Warning>

## Next steps

* [Comfy SDKs](/development/api-development/sdks)
* [Comfy API v2 Overview](/api-reference/v2/overview)
* [Workflow API Format](/development/api-development/workflow-api-format)
* [Comfy CLI Reference](/comfy-cli/reference)