spriteforge/docs/pull-relay.md

Pull relay: no VPN and no inbound GPU port

The relay topology is:

SpriteForge Studio --short outbound HTTPS--> public relay
GPU worker         --short outbound HTTPS--> public relay
GPU worker         --localhost HTTP--------> ComfyUI

There is no Tailscale, port forwarding, direct connection between the two PCs, WebSocket or permanently open request. The worker performs a short poll when it is idle. During generation it periodically sends a short heartbeat so a crashed worker's lease can be recovered.

The relay needs a small public host because two NATed computers cannot discover each other without an intermediary. It does not need a GPU. SQLite and a Docker volume are sufficient. Inputs, workflows and outputs are content-addressed by SHA-256 and expired completed jobs are eligible for cleanup after 72 hours.

Deploy the relay on a VPS

Copy the SpriteForge repository to a server with Docker and a DNS name pointing to it. In deploy/relay, create .env:

RELAY_DOMAIN=sprite-relay.example.com
SF_RELAY_CLIENT_TOKEN=long-random-client-secret
SF_RELAY_WORKER_TOKEN=different-long-random-worker-secret

Generate secrets locally with python -c "import secrets; print(secrets.token_urlsafe(48))". Start it:

docker compose up -d --build
curl https://sprite-relay.example.com/health

Caddy obtains and renews TLS automatically. Never reuse the client token as the worker token, commit .env, or expose the relay over plaintext Internet HTTP.

Start the GPU computer

ComfyUI remains local and should show http://127.0.0.1:8188. On the GPU PC, install SpriteForge (a checkout or wheel), then:

$env:SF_RELAY_WORKER_TOKEN = "worker secret"
sf relay worker `
  --url https://sprite-relay.example.com `
  --comfy-url http://127.0.0.1:8188

The terminal may stay minimized. It creates no listening port. --once leases at most one job and exits, which is useful for diagnostics or Task Scheduler.

Connect Studio

On the development PC:

$env:SF_RELAY_CLIENT_TOKEN = "client secret"
sf gpu add renderbox `
  --kind relay `
  --url https://sprite-relay.example.com `
  --workflow C:\Users\uuu\Documents\spriteforge\examples\comfyui\txt2img_api.json `
  --token-env SF_RELAY_CLIENT_TOKEN `
  --timeout 1800
sf gpu test renderbox
sf studio C:\art\my_game --gpu-profile renderbox

gpu test checks only the relay. A real Pipeline/Generate job verifies the GPU worker and local ComfyUI.