# External GPU worker

SpriteForge uses ComfyUI's HTTP API as its first remote GPU protocol. The Studio
and compiler stay on the game-development machine; only inputs and generated
PNGs cross the network.

## Prepare ComfyUI

In ComfyUI, build and test a workflow, then choose **Save (API Format)**. The
workflow JSON may contain these SpriteForge placeholders:

| Placeholder | Value |
|---|---|
| `{{PROMPT}}` | combined style, asset and shot prompt |
| `{{NEGATIVE_PROMPT}}` | combined negative prompt |
| `{{SEED}}` | deterministic integer seed |
| `{{WIDTH}}`, `{{HEIGHT}}` | source canvas size |
| `{{BATCH_SIZE}}` | requested candidate count |
| `{{MODEL}}` | model/checkpoint label from Studio |
| `{{STEPS}}`, `{{CFG}}`, `{{DENOISE}}` | diffusion controls |
| `{{SAMPLER}}`, `{{SCHEDULER}}` | ComfyUI sampler names |
| `{{REFERENCE_0}}` | uploaded canonical reference filename |
| `{{CONTROL_CONTROL}}` | uploaded pose/depth control filename |
| `{{CONTROL_MASK}}` | uploaded inpainting mask filename |
| `{{CONTROL_PREVIOUS}}` | previous approved animation frame for low-denoise img2img |

Placeholders can replace a complete JSON value or occur inside a string. Use an
IP-Adapter node for `REFERENCE_0`; use the appropriate ControlNet image loader
for `CONTROL_CONTROL`; use `CONTROL_MASK` in the inpaint branch.

Configure the local client:

```powershell
$null = sf gpu workflow-check C:\workflows\spriteforge_api.json
$env:SF_GPU_TOKEN = "secret-if-the-server-needs-one"
sf gpu add renderbox --url https://gpu.example --workflow C:\workflows\spriteforge_api.json --token-env SF_GPU_TOKEN
sf gpu test renderbox
sf studio C:\art\my_game --gpu-profile renderbox
```

The profile stores the endpoint, workflow path and environment-variable name.
It never stores the token. Use HTTPS or a private VPN/Tailscale network; an
unprotected public ComfyUI endpoint allows arbitrary outsiders to consume the
GPU.

The exact hosting vendor is intentionally irrelevant. A rented VM, a friend's
machine, a future local NVIDIA GPU and a managed ComfyUI service all expose the
same Studio workflow.