### Start ComfyUI Deploy Development Server

Source: https://github.com/bennykok/comfyui-deploy/blob/main/README.md

Start the Next.js development server for ComfyUI Deploy using Bun. This command should be executed after all setup and migration steps are completed.

```bash
bun dev
```

--------------------------------

### Install Flyctl on Mac/Linux

Source: https://github.com/bennykok/comfyui-deploy/blob/main/builder/modal-builder/README.md

Install the Fly.io command-line interface (flyctl) using Homebrew or the provided install script.

```shell
brew install flyctl // mac only
```

```shell
curl -L https://fly.io/install.sh | sh
```

--------------------------------

### Install Flyctl on Windows

Source: https://github.com/bennykok/comfyui-deploy/blob/main/builder/modal-builder/README.md

Install the Fly.io command-line interface (flyctl) on Windows using the PowerShell install script.

```powershell
pwsh -Command "iwr https://fly.io/install.ps1 -useb | iex"
```

--------------------------------

### Run Development Server

Source: https://github.com/bennykok/comfyui-deploy/blob/main/web/README.md

Use one of these commands to start the Next.js development server. Open http://localhost:3000 to view the result.

```bash
npm run dev
```

```bash
yarn dev
```

```bash
pnpm dev
```

```bash
bun dev
```

--------------------------------

### Install ComfyUI Deploy via Git

Source: https://github.com/bennykok/comfyui-deploy/blob/main/web/src/app/(docs)/docs/install/page.mdx

Clone the ComfyUI Deploy repository into your custom_nodes directory to install the plugin.

```bash
cd custom_nodes
git clone https://github.com/BennyKok/comfyui-deploy.git
```

--------------------------------

### Clone and Install ComfyUI Deploy Web

Source: https://github.com/bennykok/comfyui-deploy/blob/main/README.md

Clone the ComfyUI Deploy repository and navigate to the web directory to install dependencies using Bun. Ensure Docker is running and configure environment variables.

```bash
git clone https://github.com/BennyKok/comfyui-deploy
cd web
bun i
```

--------------------------------

### Install ComfyUI Deploy via ComfyUI Manager

Source: https://github.com/bennykok/comfyui-deploy/blob/main/web/src/app/(docs)/docs/install/page.mdx

Install the ComfyUI Deploy plugin by searching for it within the ComfyUI Manager.

```js
// Install with ComfyUI Manager
Search `ComfyUI Deploy`
```

--------------------------------

### ComfyUI Deploy Production Install

Source: https://github.com/bennykok/comfyui-deploy/blob/main/README.md

Install production dependencies for ComfyUI Deploy using Bun. This command is typically used during the deployment process on platforms like Vercel.

```bash
npx bun@1.0.16 install
```

--------------------------------

### Get Model Inventory

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

Returns the full model inventory from ComfyUI's `folder_paths`, including all installed checkpoints, LoRAs, VAEs, embeddings, and their filesystem paths.

```APIDOC
## GET /comfyui-deploy/models

### Description
Returns the full model inventory from ComfyUI's `folder_paths`, including all installed checkpoints, LoRAs, VAEs, embeddings, and their filesystem paths. Used by the ComfyDeploy dashboard to detect installed models before a deployment snapshot.

### Method
GET

### Endpoint
/comfyui-deploy/models

### Response
#### Success Response
- **checkpoints** (array) - List of checkpoints.
- **loras** (array) - List of LoRAs.
- **vae** (array) - List of VAEs.
- ... (other model types)

#### Response Example
```json
{
  "checkpoints": [["/workspace/models/checkpoints"], [".ckpt",".safetensors"], ["v1-5-pruned.ckpt","sdxl-base.safetensors"]],
  "loras":       [["/workspace/models/loras"],       [".safetensors"],          ["style-lora-v1.safetensors"]],
  "vae":         [["/workspace/models/vae"],          [".pt",".safetensors"],   ["vae-ft-mse.pt"]],
  ...
}
```
```

--------------------------------

### Get ComfyUI Model Inventory

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

Fetch the complete model inventory from ComfyUI's `folder_paths`. This includes details on installed checkpoints, LoRAs, VAEs, and embeddings, along with their file system paths. This is useful for the ComfyDeploy dashboard to identify available models.

```bash
curl http://localhost:8188/comfyui-deploy/models
```

--------------------------------

### Get File Hash

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

Computes and caches the SHA-256 checksum of a ComfyUI-managed file. The hash is used by the dashboard for deduplication when uploading model snapshots.

```APIDOC
## GET /comfyui-deploy/get-file-hash

### Description
Computes and caches the SHA-256 checksum of a ComfyUI-managed file. The hash is used by the dashboard for deduplication when uploading model snapshots.

### Method
GET

### Endpoint
/comfyui-deploy/get-file-hash

### Query Parameters
- **file_path** (string) - Required - The path to the file for which to compute the hash.

### Request Example
```bash
curl "http://localhost:8188/comfyui-deploy/get-file-hash?file_path=models/checkpoints/v1-5-pruned.ckpt"
```
```

--------------------------------

### Deploy to Fly.io

Source: https://github.com/bennykok/comfyui-deploy/blob/main/builder/modal-builder/README.md

Deploy your application to Fly.io. Use 'fly launch' for the initial deployment and 'fly deploy' for subsequent updates.

```shell
fly launch
```

```shell
fly deploy
```

--------------------------------

### Database Migration for ComfyUI Deploy

Source: https://github.com/bennykok/comfyui-deploy/blob/main/README.md

Execute local database migrations to set up the initial data schema for ComfyUI Deploy. This command should be run after setting up the environment and environment variables.

```bash
bun run db-dev
bun run migrate-local
```

--------------------------------

### Run Modal Builder Locally

Source: https://github.com/bennykok/comfyui-deploy/blob/main/builder/modal-builder/README.md

Build the Docker image and run the Modal Builder application locally. Ensure you have a .env file with your Modal credentials.

```shell
docker build -t bennykok/comfydeploy-builder:dev . && docker run --env-file .env -p 8080:8080 bennykok/comfydeploy-builder:dev
```

--------------------------------

### Set Modal Environment Variables

Source: https://github.com/bennykok/comfyui-deploy/blob/main/builder/modal-builder/README.md

Configure your Modal account credentials by setting these environment variables. Obtain your token ID and secret from your Modal account settings.

```shell
MODAL_TOKEN_ID=
MODAL_TOKEN_SECRET=
```

--------------------------------

### Configure Fly.io App Name

Source: https://github.com/bennykok/comfyui-deploy/blob/main/builder/modal-builder/README.md

Specify the application name for your deployment in the fly.toml configuration file.

```toml
// model-builder/fly.toml
app = <APP_NAME>
```

--------------------------------

### JavaScript Plugin: deployWorkflow()

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

Serializes the current ComfyUI graph, calls backend routes to deploy the workflow, and updates the in-graph ComfyDeploy metadata node.

```APIDOC
## JavaScript Plugin: deployWorkflow()

### Description
The `deployWorkflow()` function in `web-plugin/index.js` serializes the current ComfyUI graph, calls the `/comfyui-deploy/workflow` or `/comfyui-deploy/workflow/version` backend routes (which proxy to the ComfyDeploy API), and updates the in-graph `ComfyDeploy` metadata node with the assigned `workflow_id` and version number.

### Method
POST

### Endpoint
/comfyui-deploy/workflow

### Parameters
#### Request Body
- **name** (string) - Required - Name of the workflow, from ComfyDeploy node widget.
- **workflow_json** (object) - Required - Full graph JSON.
- **workflow_api** (object) - Required - API-format for execution.
- **api_url** (string) - Required - Plugin configuration API URL.
- **machine_id** (string) - Optional - Pre-selected machine ID.

### Request Example
```javascript
const body = {
  name: "My Img2Img Workflow",
  workflow_json: prompt.workflow,
  workflow_api: prompt.output,
  api_url: "https://api.comfydeploy.com",
  machine_id: "45ac5f85-b7b6-436f-8d97-...",
};

fetch("/comfyui-deploy/workflow", {
  method: "POST",
  body: JSON.stringify(body),
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <apiKey>",
  },
})
.then(r => r.json())
.then(data => {
  console.log("Deployed workflow ID:", data.workflow_id);
});
```

### Response
#### Success Response (200)
- **workflow_id** (string) - The ID assigned to the deployed workflow.

#### Response Example
```json
{
  "workflow_id": "some-workflow-id"
}
```

---

### Endpoint
POST /comfyui-deploy/workflow/version

### Description
Saves a new version of an existing workflow.

### Parameters
#### Request Body
- **api_url** (string) - Required - API URL of the ComfyDeploy service.
- **workflow** (object) - Required - The workflow JSON.
- **workflow_id** (string) - Required - The ID of the workflow to update.
- **workflow_api** (object) - Required - The API-formatted workflow.
- **comment** (string) - Optional - A comment describing the changes for this version.

### Response
#### Success Response (200)
- **workflow_id** (string) - The ID of the workflow.
- **version** (integer) - The new version number.

#### Response Example
```json
{
  "workflow_id": "some-workflow-id",
  "version": 3
}
```
```

--------------------------------

### Generate Schema and Migrate Local Database

Source: https://github.com/bennykok/comfyui-deploy/blob/main/README.md

Update the database schema and apply local migrations for ComfyUI Deploy. Run 'bun run generate' to update the schema based on your models, followed by 'bun run migrate-local' to apply changes.

```bash
bun run generate
bun run migrate-local
```

--------------------------------

### ComfyUI Deploy Production Build

Source: https://github.com/bennykok/comfyui-deploy/blob/main/README.md

Build the Next.js application for production deployment and run production database migrations. This command is used in self-hosting scenarios with Vercel.

```bash
next build && bun run migrate-production
```

--------------------------------

### Deploy ComfyUI Workflow using JavaScript Plugin

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

This JavaScript code demonstrates how to deploy a ComfyUI workflow by sending its JSON representation to the ComfyDeploy backend. It also shows how to create new versions of existing workflows.

```javascript
// Triggered by the "Deploy" button in the ComfyUI menu or sidebar
// Internally calls app.graphToPrompt() then POST /comfyui-deploy/workflow
const body = {
  name: "My Img2Img Workflow",           // from ComfyDeploy node widget
  workflow_json: prompt.workflow,         // full graph JSON
  workflow_api: prompt.output,            // API-format for execution
  api_url: "https://api.comfydeploy.com", // from plugin config
  machine_id: "45ac5f85-b7b6-436f-8d97-...", // optional pre-selected machine
};

fetch("/comfyui-deploy/workflow", {
  method: "POST",
  body: JSON.stringify(body),
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <apiKey>",
  },
})
.then(r => r.json())
.then(data => {
  // data.workflow_id assigned; written back into the ComfyDeploy node widget
  console.log("Deployed workflow ID:", data.workflow_id);
});

// Subsequent saves create a new version:
// POST /comfyui-deploy/workflow/version
// Body: { api_url, workflow, workflow_id, workflow_api, comment: "fix cfg scale" }
// Response: { workflow_id, version: 3 }
```

--------------------------------

### Queue a ComfyUI Prompt for Execution

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

Queues a ComfyUI prompt for execution. Accepts the raw workflow API, optional `inputs` overrides, a `prompt_id`, and callbacks for status and file-upload. Returns the ComfyUI prompt queue response.

```APIDOC
## POST /comfyui-deploy/run

### Description
Queues a ComfyUI prompt for execution. Accepts the raw workflow API, optional `inputs` overrides, a `prompt_id` (generated by ComfyDeploy), and callbacks for status and file-upload. Returns the ComfyUI prompt queue response.

### Method
POST

### Endpoint
/comfyui-deploy/run

### Request Body
- **prompt_id** (string) - Required - A unique identifier for the prompt.
- **workflow_api_raw** (object) - Required - The raw ComfyUI workflow API definition.
- **workflow** (object) - Optional - A more structured representation of the workflow.
- **inputs** (object) - Optional - Overrides for workflow inputs.
- **status_endpoint** (string) - Optional - URL for status updates.
- **file_upload_endpoint** (string) - Optional - URL for file uploads.
- **gpu_event_id** (string) - Optional - Identifier for GPU events.

### Request Example
```json
{
  "prompt_id": "550e8400-e29b-41d4-a716-446655440000",
  "workflow_api_raw": {
    "4": {"class_type": "CheckpointLoaderSimple", "inputs": {"ckpt_name": "v1-5-pruned.ckpt"}},
    "6": {"class_type": "CLIPTextEncode", "inputs": {"text": "a cat", "clip": ["4",1]}},
    "10": {"class_type": "ComfyUIDeployExternalText", "inputs": {"input_id": "prompt", "default_value": "a cat"}}
  },
  "workflow": {"nodes": [...], "links": [...]},
  "inputs": {"prompt": "a golden retriever"},
  "status_endpoint": "https://api.comfydeploy.com/api/run/update-run",
  "file_upload_endpoint": "https://api.comfydeploy.com/api/upload",
  "gpu_event_id": "gpu-evt-abc123"
}
```

### Response
#### Success Response (200)
- **prompt_id** (string) - The ID of the queued prompt.
- **number** (integer) - The queue number.
- **node_errors** (object) - Any errors encountered by nodes.

#### Response Example
```json
{
  "prompt_id": "550e8400-...",
  "number": 1,
  "node_errors": {}
}
```

#### Error Response (400)
- **node_errors** (object) - Errors related to specific nodes.
- **error** (string) - A general error message.

#### Error Response (500)
- A reason string on critical error.
```

--------------------------------

### Queue ComfyUI Prompt Execution

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

Use this endpoint to queue a ComfyUI prompt for execution. It accepts the raw workflow API, optional input overrides, a prompt ID, and callback endpoints for status and file uploads. Ensure you include a valid authorization token.

```bash
curl -X POST http://localhost:8188/comfyui-deploy/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <cd_token>" \
  -d '{
    "prompt_id": "550e8400-e29b-41d4-a716-446655440000",
    "workflow_api_raw": {
      "4": {"class_type": "CheckpointLoaderSimple", "inputs": {"ckpt_name": "v1-5-pruned.ckpt"}},
      "6": {"class_type": "CLIPTextEncode", "inputs": {"text": "a cat", "clip": ["4",1]}},
      "10": {"class_type": "ComfyUIDeployExternalText", "inputs": {"input_id": "prompt", "default_value": "a cat"}}
    },
    "workflow": {"nodes": [...], "links": [...]},
    "inputs": {"prompt": "a golden retriever"},
    "status_endpoint": "https://api.comfydeploy.com/api/run/update-run",
    "file_upload_endpoint": "https://api.comfydeploy.com/api/upload",
    "gpu_event_id": "gpu-evt-abc123"
  }'
```

--------------------------------

### File Output Node

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

ComfyDeployOutputFile handles arbitrary file paths within ComfyUI's allowed directories, copying or symlinking them to the output folder for upload. Supports various file types and includes security checks against path traversal.

```json
{
  "22": {
    "class_type": "ComfyDeployOutputFile",
    "inputs": {
      "file_path": ["17", 0],   # path string from upstream node
      "output_id": "output_zip"
    }
  }
}
# Security: rejects ".." traversal and paths outside ComfyUI base/temp dirs
# Returns: {"ui": {"files": [{"filename": "...", "subfolder": "temp", "type": "output", "output_id": "output_zip"}]}}
```

--------------------------------

### Connect to ComfyDeploy WebSocket for Real-time Workflows

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

Use this WebSocket endpoint to stream workflow sessions, send text and binary inputs, and receive real-time events. Ensure you provide the necessary authentication token and endpoint URLs.

```javascript
const ws = new WebSocket(
  "ws://localhost:8188/comfyui-deploy/ws" +
  "?token=<auth_token>" +
  "&workflow_endpoint=https://api.comfydeploy.com/api/workflow-version/abc/stream" +
  "&realtime_id=rt-session-001" +
  "&status_endpoint=https://api.comfydeploy.com/api/run/update-run" +
  "&file_upload_endpoint=https://api.comfydeploy.com/api/upload"
);

// Send text inputs
ws.send(JSON.stringify({ event: "input", inputs: { my_prompt: "a sunset over the ocean" } }));

// Trigger generation
ws.send(JSON.stringify({ event: "queue_prompt" }));

// Send a binary image input (format: 4B event_type=0 + 4B image_type + 24B input_id + image_bytes)
const inputIdBuffer = new TextEncoder().encode("input_image".padEnd(24, "\0"));
const imageData = new Uint8Array(await imageBlob.arrayBuffer());
const header = new Uint8Array(8);
new DataView(header.buffer).setUint32(0, 0, true);  // event type 0 = image
new DataView(header.buffer).setUint32(4, 1, true);  // 1 = JPEG
ws.send(new Uint8Array([...header, ...inputIdBuffer, ...imageData]));

// Receive SSE-like events over WebSocket
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  // msg.event: "status" | "progress" | "executing" | "executed" | "execution_start" | "execution_error"
  if (msg.event === "status" && msg.data.status === "success") {
    console.log("Generation complete");
  }
};
```

--------------------------------

### Stream ComfyUI Workflow Execution with SSE

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

Execute a ComfyUI workflow and receive real-time updates via Server-Sent Events (SSE). The connection remains open until the run completes or fails. Requires 'Accept: text/event-stream' header.

```bash
curl -X POST http://localhost:8188/comfyui-deploy/run/streaming \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <cd_token>" \
  -H "Accept: text/event-stream" \
  -d '{
    "prompt_id": "run-stream-001",
    "workflow_api_raw": { ... },
    "workflow": { ... },
    "inputs": {"prompt": "cyberpunk city"},
    "status_endpoint": "https://api.comfydeploy.com/api/run/update-run"
  }'
```

--------------------------------

### ComfyUI Deploy Environment Variables

Source: https://github.com/bennykok/comfyui-deploy/blob/main/README.md

Configuration for environment variables required for self-hosting ComfyUI Deploy, including database connection strings, authentication keys, and object storage settings for various providers like Digital Ocean and S3.

```dotenv
POSTGRES_URL=

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
CLERK_SECRET_KEY=

SPACES_ENDPOINT="http://localhost:4566"
SPACES_ENDPOINT_CDN="http://localhost:4566"
SPACES_BUCKET="comfyui-deploy"
SPACES_KEY="xyz"
SPACES_SECRET="aaa"

# generate using -> openssl rand -hex 32
JWT_SECRET=

# r2 settings
SPACES_REGION="auto"
SPACES_CDN_FORCE_PATH_STYLE="true"
SPACES_CDN_DONT_INCLUDE_BUCKET="true"

# digital ocean settings
SPACES_REGION="nyc3"
SPACES_CDN_FORCE_PATH_STYLE="false"

# s3 settings
SPACES_REGION="nyc3"
SPACES_CDN_DONT_INCLUDE_BUCKET="false"
SPACES_CDN_FORCE_PATH_STYLE="true"
```

--------------------------------

### Trigger ComfyUI Workflow Run

Source: https://github.com/bennykok/comfyui-deploy/blob/main/web/src/app/(docs)/docs/endpoints/page.mdx

Use this endpoint to trigger a ComfyUI workflow run. Ensure you have the correct deployment ID and any required authentication tokens.

```bash
curl -G https://api.protocol.chat/v1/attachments \
  -H "Authorization: Bearer {token}" \
  -d conversation_id="xgQQXg3hrtjh7AvZ" \
  -d limit=10
```

```js
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.attachments.list()
```

```python
from protocol_api import ApiClient

client = ApiClient(token)

client.attachments.list()
```

```php
$client = new \Protocol\ApiClient($token);

$client->attachments->list();
```

--------------------------------

### ComfyUIDeployExternalImage Node Definition and Runtime Input

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

Defines an image input node that accepts URLs or base64 data URIs, and demonstrates how to pass these values at runtime.

```json
# Node definition in workflow JSON
{
  "5": {
    "class_type": "ComfyUIDeployExternalImage",
    "inputs": {
      "input_id": "input_image",
      "display_name": "Source Image",
      "description": "Input image for img2img",
      "default_value_url": ""
    }
  }
}

```

```json
# Passing a URL at run time:
{
  "inputs": {
    "input_image": "https://example.com/source.png"
  }
}

# Passing a base64 PNG at run time:
{
  "inputs": {
    "input_image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  }
}

```

--------------------------------

### ComfyUI Workflow Run Response

Source: https://github.com/bennykok/comfyui-deploy/blob/main/web/src/app/(docs)/docs/endpoints/page.mdx

This is a sample JSON response structure for a successful workflow run or attachment listing. It includes metadata and a list of data objects.

```json
{
  "has_more": false,
  "data": [
    {
      "id": "Nc6yKKMpcxiiFxp6",
      "message_id": "LoPsJaMcPBuFNjg1",
      "filename": "Invoice_room_service__Plaza_Hotel.pdf",
      "file_url": "https://assets.protocol.chat/attachments/Invoice_room_service__Plaza_Hotel.pdf",
      "file_type": "application/pdf",
      "file_size": 21352,
      "created_at": 692233200
    },
    {
      "id": "hSIhXBhNe8X1d8Et"
      // ...
    }
  ]
}
```

--------------------------------

### Upload ComfyUI File to Cloud Storage

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

Upload a local ComfyUI file (e.g., model, image) to cloud object storage. This involves obtaining a pre-signed PUT URL from the `file_upload_endpoint` and then streaming the file directly to the storage provider.

```bash
curl -X POST http://localhost:8188/comfyui-deploy/upload-file \
  -H "Content-Type: application/json" \
  -d '{
    "file_path": "models\\checkpoints\\v1-5-pruned.ckpt",
    "token": "<bearer-token>",
    "url": "https://api.comfydeploy.com/api/upload?file_size=4265878528&type=application/octet-stream"
  }'
```

--------------------------------

### JavaScript Plugin: PostMessage Bridge (sendEventToCD / dispatchAPIEventData)

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

Use `sendEventToCD` to emit events from the plugin to the parent ComfyDeploy dashboard. Listen for messages from the dashboard using `window.addEventListener('message', ...)` to receive commands like 'graph_load' or 'deploy'.

```javascript
// Outbound: plugin → dashboard
sendEventToCD("cd_plugin_setup");
sendEventToCD("cd_plugin_onAfterChange", { workflow, output });
sendEventToCD("cd_plugin_onDeployChanges", prompt);
sendEventToCD("assets", { node: nodeId, inputName: "default_value_url" });
sendEventToCD("file_drop", { files, x: e.clientX, y: e.clientY, timestamp: Date.now() });

// Inbound: dashboard → plugin (via window.addEventListener("message", ...))
// "graph_load"       – loads a workflow JSON into the canvas
// "deploy"           – triggers deployWorkflow() → cd_plugin_onDeployChanges
// "queue_prompt"     – queues the current prompt → cd_plugin_onQueuePrompt
// "update_widget"    – { nodeId, widgetName, value } → updates widget live
// "add_node"         – { type, widgets_values } → adds a node at cursor
// "zoom_to_node"     – { nodeId, position } → animated pan/zoom to node
// "configure_queue_buttons" – adds custom icon buttons to the queue toolbar
// "event"            – forwards a ComfyUI execution event (progress, executed, etc.)

// Example: dashboard sends workflow, plugin loads it
window.parent.postMessage(JSON.stringify({
  type: "graph_load",
  data: workflowJson,   // standard ComfyUI workflow object
}), "*");
```

--------------------------------

### ComfyUIDeployExternalSeed Node Definition and Runtime Override

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

Defines a seed input node that can be fixed or randomized. Shows how to force a specific seed value at runtime.

```json
{
  "9": {
    "class_type": "ComfyUIDeployExternalSeed",
    "inputs": {
      "input_id": "generation_seed",
      "default_value": -1,      # -1 → randomize
      "min_value": 1,
      "max_value": 4294967295,
      "display_name": "Seed"
    }
  }
}

```

```json
# Force a fixed seed:
{ "inputs": { "generation_seed": "42" } }
# -> node returns int 42 and caches it (IS_CHANGED returns stable hash)

```

--------------------------------

### Text Output Node

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

ComfyDeployOutputText saves string data to disk as .txt, .json, or .md files. It returns a file reference for the upload pipeline. Specify the 'file_type' and 'filename_prefix'.

```json
{
  "21": {
    "class_type": "ComfyDeployOutputText",
    "inputs": {
      "text": ["18", 0],
      "filename_prefix": "caption",
      "file_type": "txt",       # "txt" | "json" | "md"
      "output_id": "output_caption"
    }
  }
}
# Returns: {"ui": {"text_file": [{"filename": "caption_00001_.txt", ...}]}}
```

--------------------------------

### WebSocket Endpoint

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

Opens a persistent WebSocket for real-time (streaming) workflow sessions. Supports binary image frames as inputs and SSE-like events over WebSocket.

```APIDOC
## WebSocket Endpoint: GET /comfyui-deploy/ws

### Description
Opens a persistent WebSocket for real-time (streaming) workflow sessions. On connection, ComfyDeploy optionally fetches the workflow definition from `workflow_endpoint`, initializes a `StreamingPrompt` session, and begins accepting `input` and `queue_prompt` messages. Supports binary image frames as inputs.

### Method
GET

### Endpoint
/comfyui-deploy/ws

### Parameters
#### Query Parameters
- **token** (string) - Required - Authentication token.
- **workflow_endpoint** (string) - Optional - URL to fetch the workflow definition.
- **realtime_id** (string) - Optional - Identifier for the real-time session.
- **status_endpoint** (string) - Optional - URL for status updates.
- **file_upload_endpoint** (string) - Optional - URL for file uploads.

### Request Example
```javascript
const ws = new WebSocket(
  "ws://localhost:8188/comfyui-deploy/ws" +
  "?token=<auth_token>" +
  "&workflow_endpoint=https://api.comfydeploy.com/api/workflow-version/abc/stream" +
  "&realtime_id=rt-session-001" +
  "&status_endpoint=https://api.comfydeploy.com/api/run/update-run" +
  "&file_upload_endpoint=https://api.comfydeploy.com/api/upload"
);

// Send text inputs
ws.send(JSON.stringify({ event: "input", inputs: { my_prompt: "a sunset over the ocean" } }));

// Trigger generation
ws.send(JSON.stringify({ event: "queue_prompt" }));

// Send a binary image input (format: 4B event_type=0 + 4B image_type + 24B input_id + image_bytes)
const inputIdBuffer = new TextEncoder().encode("input_image".padEnd(24, "\0"));
const imageData = new Uint8Array(await imageBlob.arrayBuffer());
const header = new Uint8Array(8);
new DataView(header.buffer).setUint32(0, 0, true);  // event type 0 = image
new DataView(header.buffer).setUint32(4, 1, true);  // 1 = JPEG
ws.send(new Uint8Array([...header, ...inputIdBuffer, ...imageData]));
```

### Response
#### Success Response
Receives SSE-like events over WebSocket.

#### Response Example
```json
{
  "event": "status",
  "data": {
    "status": "success"
  }
}
```

### Error Handling
- `execution_error`: Indicates an error during workflow execution.
```

--------------------------------

### Trigger a run

Source: https://github.com/bennykok/comfyui-deploy/blob/main/web/src/app/(docs)/docs/endpoints/page.mdx

Trigger a run with a deployment id. Optional attributes include conversation_id and limit.

```APIDOC
## POST /api/run

### Description
Trigger a run with a deployment id.

### Method
POST

### Endpoint
/api/run

### Parameters
#### Request Body
- **conversation_id** (string) - Optional - Limit to attachments from a given conversation.
- **limit** (integer) - Optional - Limit the number of attachments returned.
```

--------------------------------

### Set Modal Secrets in Fly.io

Source: https://github.com/bennykok/comfyui-deploy/blob/main/builder/modal-builder/README.md

Set your Modal account credentials as secrets within your Fly.io application configuration.

```shell
fly secrets set MODAL_TOKEN_ID=
fly secrets set MODAL_TOKEN_SECRET=
```

--------------------------------

### External Checkpoint Input Node

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

ComfyUIDeployExternalCheckpoint accepts local checkpoint filenames or HTTPS URLs. URLs are streamed to the checkpoints folder before workflow execution. Use 'input_id' for identification and 'default_value' for initial selection.

```json
{
  "13": {
    "class_type": "ComfyUIDeployExternalCheckpoint",
    "inputs": {
      "input_id": "base_model",
      "default_value": "v1-5-pruned-emaonly.ckpt",
      "display_name": "Base Model"
    }
  }
}
```

```json
# Pass a remote model URL:
{
  "inputs": {
    "base_model": "https://huggingface.co/runwayml/stable-diffusion-v1-5/resolve/main/v1-5-pruned-emaonly.safetensors"
  }
}
# -> downloads to checkpoints/ and returns saved filename
```

--------------------------------

### Python: apply_random_seed_to_workflow() for Seed Randomization

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

This function randomizes 'seed' and 'noise_seed' fields for specific node types (KSampler, etc.) unless their seed mode is set to 'fixed'. It operates on both `workflow_api` and `workflow` structures.

```python
from custom_routes import apply_random_seed_to_workflow

workflow_api = {
    "3": {
        "class_type": "KSampler",
        "inputs": {"seed": 12345, "cfg": 7.0, "steps": 20, ...}
    },
}
workflow = {
    "nodes": [
        {"id": 3, "type": "KSampler", "widgets_values": [12345, "randomize", 20, ...]}
    ]
}

apply_random_seed_to_workflow(workflow_api, workflow)
# workflow_api["3"]["inputs"]["seed"] is now a fresh 15-digit random integer
# because widgets_values[1] == "randomize"

# Fixed seed example (no change):
workflow["nodes"][0]["widgets_values"][1] = "fixed"
apply_random_seed_to_workflow(workflow_api, workflow)
# workflow_api["3"]["inputs"]["seed"] remains 12345
```

--------------------------------

### Execute Workflow and Stream Server-Sent Events

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

Executes a workflow and streams Server-Sent Events (SSE) back to the caller for real-time status updates. The connection remains open until the run reaches `success` or `failed`.

```APIDOC
## POST /comfyui-deploy/run/streaming

### Description
Executes a workflow and streams Server-Sent Events (SSE) back to the caller for real-time status updates (progress, executing, status, executed). The connection remains open until the run reaches `success` or `failed`.

### Method
POST

### Endpoint
/comfyui-deploy/run/streaming

### Headers
- **Accept**: text/event-stream

### Request Body
- **prompt_id** (string) - Required - A unique identifier for the streaming run.
- **workflow_api_raw** (object) - Required - The raw ComfyUI workflow API definition.
- **workflow** (object) - Optional - A more structured representation of the workflow.
- **inputs** (object) - Optional - Overrides for workflow inputs.
- **status_endpoint** (string) - Optional - URL for status updates.

### Request Example
```json
{
  "prompt_id": "run-stream-001",
  "workflow_api_raw": { ... },
  "workflow": { ... },
  "inputs": {"prompt": "cyberpunk city"},
  "status_endpoint": "https://api.comfydeploy.com/api/run/update-run"
}
```

### Response
Server-Sent Events (SSE) stream. Example events:
```
event: event_update
data: {"prompt_id": "run-stream-001", "number": 1, "node_errors": {}}

event: event_update
data: {"event": "progress", "data": {"value": 5, "max": 20, "prompt_id": "run-stream-001"}}

event: event_update
data: {"event": "status", "data": {"status": "success"}}
```
```

--------------------------------

### Python: apply_inputs_to_workflow() for Runtime Input Injection

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

This function modifies a workflow dictionary by replacing node input values based on a provided `inputs` dictionary. It's used before queuing to inject runtime parameters.

```python
from custom_routes import apply_inputs_to_workflow

workflow_api = {
    "6":  {"class_type": "ComfyUIDeployExternalText",   "inputs": {"input_id": "prompt",    "default_value": "a cat"}},
    "10": {"class_type": "ComfyUIDeployExternalNumber", "inputs": {"input_id": "cfg",        "default_value": 7.5}},
    "11": {"class_type": "ComfyUIDeployExternalEnum",   "inputs": {"input_id": "style",      "default_value": "photorealistic"}},
}

inputs = {
    "prompt": "a dog on the moon",
    "cfg":    "9.0",
    "style":  "anime",
}

apply_inputs_to_workflow(workflow_api, inputs)

# After call:
# workflow_api["6"]["inputs"]["input_id"]      == "a dog on the moon"
# workflow_api["6"]["inputs"]["default_value"] == "a dog on the moon"
# workflow_api["10"]["inputs"]["input_id"]     == "9.0"
# workflow_api["11"]["inputs"]["default_value"]== "anime"
```

--------------------------------

### Upload a ComfyUI File

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

Uploads a local ComfyUI file (model, image, etc.) to cloud object storage by first requesting a pre-signed PUT URL from `file_upload_endpoint`, then streaming the file directly to the storage provider.

```APIDOC
## POST /comfyui-deploy/upload-file

### Description
Uploads a local ComfyUI file (model, image, etc.) to cloud object storage by first requesting a pre-signed PUT URL from `file_upload_endpoint`, then streaming the file directly to the storage provider (S3/R2/DigitalOcean Spaces).

### Method
POST

### Endpoint
/comfyui-deploy/upload-file

### Request Body
- **file_path** (string) - Required - The path to the local file to upload.
- **token** (string) - Required - A bearer token for authentication.
- **url** (string) - Required - The pre-signed URL obtained from the `file_upload_endpoint`.

### Request Example
```json
{
  "file_path": "models\\checkpoints\\v1-5-pruned.ckpt",
  "token": "<bearer-token>",
  "url": "https://api.comfydeploy.com/api/upload?file_size=4265878528&type=application/octet-stream"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
- **download_url** (string) - The URL to access the uploaded file.

#### Response Example
```json
{
  "message": "File uploaded successfully",
  "download_url": "https://cdn.comfydeploy.com/..."
}
```

#### Error Response (404)
- **error** (string) - Error message indicating the file was not found.
```

--------------------------------

### ComfyUIDeployExternalText Node Definition and API Call

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

Defines a text input node for ComfyUI workflows and shows how to override its default value via the /comfyui-deploy/run API endpoint.

```json
{
  "10": {
    "class_type": "ComfyUIDeployExternalText",
    "inputs": {
      "input_id": "my_prompt",
      "default_value": "a photo of a cat",
      "display_name": "Prompt",
      "description": "Main generation prompt"
    }
  }
}

```

```json
# Overriding the value at run time via the /comfyui-deploy/run endpoint:
# POST /comfyui-deploy/run
{
  "workflow_api_raw": { ... },   # full workflow API dict
  "workflow": { ... },           # full workflow (for seed handling)
  "prompt_id": "run-uuid-1234",
  "inputs": {
    "my_prompt": "a photo of a golden retriever on the beach"
  },
  "status_endpoint": "https://api.comfydeploy.com/api/run/update-run",
  "file_upload_endpoint": "https://api.comfydeploy.com/api/upload"
}

```

--------------------------------

### Check ComfyUI Prompt Status

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

Retrieve the current status of a ComfyUI prompt by providing its `prompt_id`. The status is tracked in the in-process metadata store. Possible statuses include 'not-started', 'running', 'success', 'failed', 'uploading', and 'cancelled'.

```bash
curl "http://localhost:8188/comfyui-deploy/check-status?prompt_id=550e8400-e29b-41d4-a716-446655440000"
```

--------------------------------

### Image Output Node

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

ComfyDeployOutputImage saves generated images in various formats (PNG, JPEG, WEBP) and includes metadata for upload pipelines. Configure filename prefix, file type, and quality.

```json
{
  "20": {
    "class_type": "ComfyDeployOutputImage",
    "inputs": {
      "images": ["19", 0],
      "filename_prefix": "ComfyUI",
      "file_type": "webp",      # "png" | "jpg" | "webp"
      "quality": 85,
      "output_id": "generated_images"
    }
  }
}
# Returns: {"ui": {"images": [{"filename": "ComfyUI_00001_.webp", "subfolder": "", "type": "output", "output_id": "generated_images"}]}}
```

--------------------------------

### External LoRA Input Node

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

ComfyUIDeployExternalLora handles LoRA weights from local files, HTTP URLs, or direct paths. Supports authenticated downloads via a 'bearer_token' input. The 'lora_save_name' ensures caching.

```json
{
  "14": {
    "class_type": "ComfyUIDeployExternalLora",
    "inputs": {
      "input_id": "style_lora",
      "lora_url": "",
      "lora_save_name": "my-style-v1.safetensors",
      "display_name": "Style LoRA"
    }
  }
}
```

```json
# Pass a URL at runtime (downloaded and cached by lora_save_name):
{
  "inputs": {
    "style_lora": "https://civitai.com/api/download/models/12345"
  }
}
# bearer_token input also available for private downloads
```

--------------------------------

### ComfyUIDeployExternalNumberInt Node Definition and Runtime Override

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

Defines an integer number input node and demonstrates overriding its default value with a string at runtime, which is coerced to an integer.

```json
{
  "8": {
    "class_type": "ComfyUIDeployExternalNumberInt",
    "inputs": {
      "input_id": "steps",
      "default_value": 20,
      "display_name": "Sampling Steps"
    }
  }
}

```

```json
# Override:
{ "inputs": { "steps": "30" } }

```

--------------------------------

### Compute and Cache File SHA-256 Checksum

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

Calculate and cache the SHA-256 checksum for a ComfyUI-managed file. This hash is used by the dashboard for deduplication purposes when uploading model snapshots.

```bash
curl "http://localhost:8188/comfyui-deploy/get-file-hash?file_path=models/checkpoints/v1-5-pruned.ckpt"
```

--------------------------------

### ComfyUIDeployExternalNumber Node Definition and Runtime Override

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

Defines a float number input node and shows how to override its default value with a string at runtime, which is automatically cast to float.

```json
# Node definition
{
  "7": {
    "class_type": "ComfyUIDeployExternalNumber",
    "inputs": {
      "input_id": "cfg_scale",
      "default_value": 7.5,
      "display_name": "CFG Scale",
      "description": "Classifier-free guidance scale"
    }
  }
}

```

```json
# Override at runtime:
{ "inputs": { "cfg_scale": "9.0" } }
# -> node receives float 9.0

```

--------------------------------

### Check Prompt Status

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

Returns the current `Status` enum value for a given `prompt_id` tracked in the in-process metadata store.

```APIDOC
## GET /comfyui-deploy/check-status

### Description
Returns the current `Status` enum value for a given `prompt_id` tracked in the in-process metadata store.

### Method
GET

### Endpoint
/comfyui-deploy/check-status

### Query Parameters
- **prompt_id** (string) - Required - The ID of the prompt to check.

### Response
#### Success Response
- **status** (string) - The current status of the prompt. Possible values: `"not-started"`, `"running"`, `"success"`, `"failed"`, `"uploading"`, `"cancelled"`.

#### Response Example
```json
{
  "status": "running"
}
```
```

--------------------------------

### External Boolean Input Node

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

Use ComfyUIDeployExternalBoolean to expose a toggleable boolean input for controlling workflow branches. Set the default value and display name in the node configuration.

```json
{
  "11": {
    "class_type": "ComfyUIDeployExternalBoolean",
    "inputs": {
      "input_id": "enable_upscale",
      "default_value": false,
      "display_name": "Enable Upscaling"
    }
  }
}
```

```json
# Toggle on at runtime:
{ "inputs": { "enable_upscale": "true" } }
```

--------------------------------

### External Enum (Dropdown) Input Node

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

ComfyUIDeployExternalEnum provides a dropdown input with options defined as a JSON-serialized string. The frontend renders a DYNAMIC_ENUM widget populated from the 'options' field. Runtime selection overrides the default.

```json
{
  "12": {
    "class_type": "ComfyUIDeployExternalEnum",
    "inputs": {
      "input_id": "style_preset",
      "default_value": "photorealistic",
      "options": "[\"photorealistic\", \"anime\", \"oil painting\", \"watercolor\"]",
      "display_name": "Style Preset"
    }
  }
}
```

```json
# Select a different option at runtime:
{ "inputs": { "style_preset": "anime" } }
```

--------------------------------

### Cancel a Running Prompt

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

Cancels a currently queued or running prompt by its `prompt_id` and reports the run as `cancelled` to the status endpoint.

```APIDOC
## POST /comfyui-deploy/interrupt

### Description
Cancels a currently queued or running prompt by its `prompt_id` and reports the run as `cancelled` to the status endpoint.

### Method
POST

### Endpoint
/comfyui-deploy/interrupt

### Request Body
- **prompt_id** (string) - Required - The ID of the prompt to interrupt.

### Request Example
```json
{
  "prompt_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

### Response
#### Success Response
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Prompt interrupted"
}
```
```

--------------------------------

### Interrupt ComfyUI Prompt Execution

Source: https://context7.com/bennykok/comfyui-deploy/llms.txt

Cancel a queued or running ComfyUI prompt using its unique `prompt_id`. This action also reports the cancellation to the specified status endpoint.

```bash
curl -X POST http://localhost:8188/comfyui-deploy/interrupt \
  -H "Content-Type: application/json" \
  -d '{"prompt_id": "550e8400-e29b-41d4-a716-446655440000"}'
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.