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

# Create Runner

> Register a new ComfyUI runner instance

## Overview

Register a new ComfyUI runner instance to execute workflows. Runners represent your own ComfyUI installations that ComfyControl can communicate with.

<Note>
  Your ComfyUI instance must be accessible via HTTP/HTTPS and have the ComfyUI API enabled.
</Note>

## Request Body

<ParamField body="name" type="string" required>
  A descriptive name for your runner (1-100 characters).
</ParamField>

<ParamField body="endpoint" type="string" required>
  The URL where your ComfyUI instance is accessible. Must be a valid HTTP or HTTPS URL.

  Example: `https://my-comfy.example.com` or `http://192.168.1.100:8188`
</ParamField>

<ParamField body="headers" type="object">
  Custom HTTP headers to include when communicating with your runner. Use this for authentication or other custom headers. Optional - can be an empty object if no headers are needed.

  Example: `{"Authorization": "Bearer token123", "X-Custom-Header": "value"}`
</ParamField>

<ParamField body="tags" type="string[]">
  Array of tags for organizing and selecting runners (maximum 10 tags). Tags are used to match runners with workflows. Optional - can be an empty array.

  Example: `["production", "gpu-a100", "image-generation"]`
</ParamField>

## Response

<ResponseField name="id" type="string" required>
  Unique identifier (UUID) for the runner.
</ResponseField>

<ResponseField name="user_id" type="string" required>
  UUID of the user who owns this runner.
</ResponseField>

<ResponseField name="name" type="string" required>
  The runner's name.
</ResponseField>

<ResponseField name="status" type="string" required>
  Current status of the runner. Values: `active`, `disabled`
</ResponseField>

<ResponseField name="endpoint" type="string" required>
  The URL where the runner is accessible.
</ResponseField>

<ResponseField name="tags" type="string[]" required>
  Array of tags associated with the runner.
</ResponseField>

<ResponseField name="headers" type="object" required>
  The custom headers configured for this runner.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp when the runner was created.
</ResponseField>

<ResponseField name="updated_at" type="string" required>
  ISO 8601 timestamp when the runner was last updated.
</ResponseField>

## Example Response

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "Production GPU Runner",
  "status": "active",
  "endpoint": "https://my-comfy.example.com",
  "tags": ["production", "gpu-a100"],
  "headers": {
    "Authorization": "Bearer secret_token"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
```

**Example with empty headers and tags:**

```json theme={null}
{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "Development Runner",
  "status": "active",
  "endpoint": "http://192.168.1.100:8188",
  "tags": [],
  "headers": {},
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
```

## Error Responses

<ResponseField name="400" type="error">
  Bad request - validation error in the request body.

  Common causes:

  * Name is empty or too long
  * Invalid endpoint URL format
  * Too many tags (max 10)
  * Invalid headers format
</ResponseField>

<ResponseField name="401" type="error">
  Unauthorized - invalid or missing authentication token.
</ResponseField>

<ResponseField name="403" type="error">
  Forbidden - runner limit exceeded for your tier.
</ResponseField>

## Notes

* Runners are created with `active` status by default
* The endpoint URL must be reachable from ComfyControl's infrastructure