# Pull relay: no VPN and no inbound GPU port

The relay topology is:

```text
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`:

```dotenv
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:

```bash
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:

```powershell
$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:

```powershell
$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.