Documentation

Quick Start

5 minutes

Prerequisites

At least one ComfyUI instance running and accessible over the internet.

1. Sign in and Set up a Runner

  • • Sign in with GitHub and you will be redirected to the ComfyControl dashboard
  • • Head to the Runners page
  • • Click the "New Runner" button at the top
  • • Give your runner a friendly name
  • • Specify the endpoint where your ComfyUI instance is reachable
  • • You can add authentication headers if your runner is behind an authenticated endpoint
  • • Click "Save" to confirm

2. Create Your First Workflow

  • • Navigate to the Worflows page
  • • Click "New Workflow"
  • • Give your workflow a name
  • • Choose your ComfyUI workflow JSON file (exported as API format)
  • • Keep tags empty for now
  • • Click "Create" to start execution

3. Monitor & View Results

  • • Your workflow will start executing on the registered runner
  • • Click on the newly created workflow on the workflows page to view details
  • • Once execution is complete, generated images will be available under Workflow Outputs
  • • You can also view all generated images on the Gallery page

Concepts

How ComfyControl Works

1. Setup Runners ComfyUI instances
2. Create Templates Reusable workflows
3. Run Workflows Execute on runners
4. View Gallery All outputs

Runners

Runners are ComfyUI instances that execute your workflows.

Each runner has a state that determines its availability - an active runner can accept new workflows for execution, while inactive runners will not receive new tasks. The number of runners you can add is limited by your current plan.

Runners can be assigned one or more tags which serve two purposes: grouping runners logically and controlling workflow placement. Tags allow you to create specialized runners for different types of workloads or hardware configurations.

Authentication headers can be added to runners, allowing ComfyControl to authenticate with protected ComfyUI endpoints. You can update a runner's name, tags, headers, or state after it has been created. ComfyControl automatically tries to establish connection to runners when accessing the runner details page or when sending workflows for execution.

Important: You manage the required models and nodes required for execution on your workflow. As of now we don't auto-install nodes or manage your ComfyUI instance.

Templates

Templates are ComfyUI Workflows exported as JSON with optional placeholders for dynamic values.

A placeholder is a special JSON value that gets replaced before execution. Placeholders are only replaced when the entire JSON value contains only the placeholder - partial values like "ComfyUI_$timestamp()" will not be replaced and are passed as-is.

Placeholder Types:

  • $file(name) - File upload reference
  • $text(key) - Text input parameter
  • $random() - 64-bit random value (useful for noise seeding)
  • $timestamp() - Current timestamp in Unix milliseconds format

During execution from templates, values for these placeholders must be specified. Multiple random placeholders can be added to a workflow, and each gets uniquely replaced with a new value. All timestamp placeholders within the same workflow are replaced with the same timestamp value. File and text placeholders with the same name or key are replaced consistently - for example, $file(name.png) appearing multiple times gets replaced with the same file reference, and $text(key) is replaced everywhere the key matches.

Workflows

Workflows are execution entities created from templates or standalone JSON files.

Workflows are the execution entities that can be created from a template or standalone from a JSON file containing placeholders. Placeholder replacement happens just prior to submitting to the runner. Once execution is finished, outputs are copied from the runner, meaning outputs are unaffected by the runner lifecycle.

Workflows have tags that control scheduling behavior. A workflow with tags can only execute on runners with matching tags - for example, a workflow tagged "gpu" can only run on runners that also have the "gpu" tag. If a workflow has no tags, it can execute on any available runner. When multiple runners share matching tags, the workflow can execute on any of those runners.

Workflows can be re-run, which allows you to change placeholder parameters such as text and file inputs. However, you cannot change tags during re-run, which means the workflow might execute on a different runner than where it previously ran if multiple matching runners are available.

Gallery

Centralized view of all generated outputs from workflow executions across all runners.

The Gallery provides a single centralized location to view all outputs generated by runners across all your workflows. You can view and download outputs directly from the gallery, with the same functionality available from individual workflow details pages.

To delete an output, you need to navigate to the specific workflow and delete it from there - deletion is not available directly from the gallery view.

Placeholder Replacement Demo

How Placeholders Get Replaced:

Placeholder in TemplateParameter ProvidedFinal Value
$text(prompt)"A beautiful sunset""A beautiful sunset"
$file(image.png)file_upload_abc123"processed_image.png" >
$random()auto-generated8547392816
$timestamp()auto-generated1705316400000

📝 Template (Before)

{
  "6": {
    "inputs": {
      "text": "$text(prompt)",
      "seed": "$random()"
    }
  },
  "10": {
    "inputs": {
      "image": "$file(image.png)"
    }
  }
}

✅ Executed (After)

{
  "6": {
    "inputs": {
      "text": "A beautiful sunset",
      "seed": 8547392816
    }
  },
  "10": {
    "inputs": {
      "image": "processed_image.png"
    }
  }
}

Parameters You Provide:

{
  "parameters": {
    "prompt": "A beautiful sunset",
    "image.png": "file_upload_abc123"
  }
}

💡 $random() and $timestamp() are automatically generated - no parameters needed!