sNora

Public video generation for snail3d.com. A prompt enters through a Cloudflare Worker, is rate-limited at the edge, tunneled to a render service on the Mac, queued into the H3 farm, and the finished clip comes back through R2. This page is the map.

System diagram

EDGE — CLOUDFLARE TUNNEL + MAC — 127.0.0.1:7789 RENDER FARM — ~/h3_queue Browser snail3d.com UI prompt → poll → play Cloudflare Worker snail3d-polar · /api/sora/* rate limits · upload · video range R2 snail-sora videos/<id>.mp4 ≤ 25 MB KV snail_sora_kv RL counters · gallery cache cloudflared sora.snail3d.com.tealclaw.ai managed tunnel → :7789 sora_service.py :7789 X-Sora-Secret auth · per-IP + global caps backend auto-pick · poller every 20 s state: sora_state.json (atomic) h3 queue ~/h3_queue · FIFO runner jobs.json · runner_state.json dashboard :8741 Mac · MPS default backend Spark · blacksnail1 SGLang, when idle ≥ 10 min clips land in out/ · verified > 5 KB before upload 1 · POST /api/sora {prompt} 2 · POST /jobs · secret + X-Forwarded-For 3 · caps + backend pick 4 · h3 queue "…" --square --fast 5 · render 6 · poll 20 s: done? clip > 5 KB? 7 · POST /api/sora/upload/<id> → R2 8 · /status/<id> → done · /video/<id> (Range)

One render's journey

  1. Prompt in. The UI on snail3d.com posts POST /api/sora with {prompt}. Same-origin in production; the worker sets CORS headers for dev.
  2. Edge rate limit. The Worker checks four KV counters per calendar window: 3/min and 10/day per IP, 5/min and 40/day global. Any cap hit → 429 with a human message. Counters get a 120 s / 24 h TTL.
  3. Forward through the tunnel. The Worker POSTs /jobs to the tunnel hostname sora.snail3d.com.tealclaw.ai (cloudflared managed tunnel → 127.0.0.1:7789; the SORA_SERVICE_URL secret points here, plain http while the CF cert for the hostname is pending — the hop is secret-authenticated), sending X-Sora-Secret and X-Forwarded-For. A 10 s timeout; any 5xx or edge code (520–530) becomes 503 "render farm is offline".
  4. Service re-checks caps. Defense in depth, keyed on the forwarded IP: 2 rendering + 5 pending per IP, 12 pending global. Exceeded → 429 (yours) or 503 (farm busy). Prompt must be ≤ 2000 chars.
  5. Backend auto-pick. The service SSHes to blacksnail1 and tails the SGLang log for the newest Prefill batch line. Idle ≥ 10 min (or unreadable/unknown) → spark; otherwise → mac.
  6. Enqueue. h3 queue "<prompt>" --square --fast [--backend spark] adds the job to ~/h3_queue/jobs.json. The service records YYYYMMDD_<sha1[:8]> → h3 job name in sora_state.json and returns 201 with the job id.
  7. Render. The FIFO runner works the queue (Mac via MPS, Spark via SGLang). The service's poller thread wakes every 20 s, flips a job to rendering when it reaches the front, and on completion verifies the clip exists and is > 5 KB — otherwise the job is failed.
  8. Clip out. The service uploads the mp4 to POST /api/sora/upload/<id>; the Worker stores it in R2 at snail-sora/videos/<id>.mp4 (≤ 25 MB, secret-checked). Uploads retry every poll tick until the Worker acks. The UI then sees done from /status/<id> and plays /video/<id>, which is Range-aware for hover previews.

Components

ComponentWhereRole
Frontend UI/sora/ on snail3d.com (public/sora/index.html, standalone page)Prompt form, live “in the oven” jobs, clip gallery with hover previews.
snail3d-polar WorkerCloudflare (routes snail3d.com/api/sora*)Public API: submit + edge rate limits, gallery with KV fallback, status, secret-checked upload → R2, Range-aware clip serving. worker/sora.js + routing in worker/polar-webhook.js.
KV snail_sora_kvCloudflareRate-limit counters (per-IP min/day, global min/day) and 1 h gallery cache fallback when the Mac service is down.
R2 snail-soraCloudflareStores finished clips as videos/<id>.mp4 (max 25 MB per upload).
cloudflared tunnelMac (managed, id 26e359aa…)Exposes sora.snail3d.com.tealclaw.ai → 127.0.0.1:7789.
sora_service.pyMac, 127.0.0.1:7789 (launchd)Secret auth (HMAC), queue caps, backend auto-pick, job state, 20 s completion poller + clip upload. Config in sora/sora_config.json (gitignored).
h3 queue~/h3_queueFIFO MiniMax H3 runner: jobs.json manifest, runner_state.json (done/failed), per-job logs, dashboard on :8741. Wrapper: h3 (status/queue/stitch/play/logs).
Mac backendApple Silicon, MPSH3 render fallback when Spark is busy.
Spark (blacksnail1)Remote GPUH3 render via SGLang when idle ≥ 10 min — chosen automatically.

Failure modes

  • Mac service / tunnel down → Worker returns 503 "render farm is offline" for submit/status; gallery falls back to the KV-cached list (1 h TTL).
  • Upload retry → if the Worker 4xx/5xxs the clip upload, the poller retries on the next 20 s tick; the job stays rendering until the Worker acks.
  • Bad clip → runner reports done but output missing or < 5 KB → job marked failed.
  • Spark health check fails (ssh/log error) → treated as idle → job routes to Spark.
  • Worker→service timeout → 10 s; any Cloudflare edge code (520–530) or empty 5xx body → 503.
  • Upload > 25 MB → 413; prompt > 2000 chars → 400 at both edges.

Rate limits

  • Worker edge (KV, per calendar minute/day): 3/min and 10/day per IP · 5/min and 40/day global.
  • Service caps (state file, per IP): 2 rendering · 5 queued+rendering · 12 total pending farm-wide.
  • Prompt: ≤ 2000 characters.
  • Clip: ≤ 25 MB to R2; must be > 5 KB to count as a real render.

Status — verified live 2026-08-25 ~06:10

ItemStatus
Worker deployed on snail3d.com (/api/sora* routes live)✅ done — submit + gallery verified end-to-end
R2 bucket + KV namespace bound✅ done
h3 runner + dashboard on the Mac (:8741)✅ running
sora_service.py under launchd (com.snail3d.sora)✅ running — sora/sora_config.json + shared SORA_SECRET in place
Tunnel: ingress entry + CNAME sora.snail3d.com.tealclaw.ai✅ live — /health verified through the public hostname
Video page at /sora/✅ live
TLS for the tunnel hostname⬜ CF cert not issued yet — worker→service hop is plain http (secret-protected)
Clean sora.snail3d.com CNAME⬜ needs a token with DNS write on the snail3d.com zone; then flip SORA_SERVICE_URL to https://sora.snail3d.com