Every idea in this repo leans on one of four fly.io Sprites primitives. Each one runs against api.sprites.dev/v1 with a single token, so you ship a real public micro-VM demo with zero infra and no provider-shopping.
Primitive: a `POST https://api.sprites.dev/v1/sprites` with `{ name, url_settings: { auth: "public" } }` — fly.io mints a fresh isolated micro-VM and returns a public URL you can hand straight to a user
UI: a launch button that spins up a disposable, shareable sandbox on demand
Primitive: `PUT https://api.sprites.dev/v1/sprites/{name}/fs/write?path=/root/www/index.html` with an octet-stream body — writes files (index.html, JSON, generated assets) straight into the sandbox and auto-creates parent dirs
UI: a compose surface that pushes freshly-authored HTML, JSON, or media into the live sandbox
Primitive: `PUT /sprites/{name}/services/{svc}` with `{ cmd, args, dir: "/root/www", http_port: 8080, needs: [] }` then `POST /services/{svc}/start` — runs any long-running process (python http.server, ffmpeg loop, socket relay) that wakes on the first request
UI: a launcher that boots a running process — HTTP server, streaming loop, playback engine — and hands the user its public URL
Primitive: `POST /sprites/{name}/exec?cmd=bash&cmd=-lc&cmd=<script>` with only an `Authorization` header — runs a shell command inside the sandbox and streams stdout back, terminated by 0x03 + exit code
UI: a prompt-driven console that runs a shell command in the sandbox and streams the output back to the user
Add this to your Lovable project (Project Settings → Secrets). It stays on the server, read by your TanStack server function via process.env.SPRITES_TOKEN.
SPRITES_TOKENThe 4-part token (org-slug/org-id/token-id/token-value) from sprites.dev/account. One token unlocks create, filesystem writes, long-running services, and exec across every Sprite you spin up. A raw Fly.io org token returns 401 — always use the 4-part sprites.dev token.
The Sprites docs leave a few edges ambiguous. These five bite hardest in a one-shot Lovable build.
Set `dir: "/root/www"` on every service. `/home/sprite` may not exist and the service fails to start with `cd: No such file or directory`.
Sprites wake on the first request only when a service declares `http_port`. Omit it and the sprite reports "Running" but every request 502s.
`POST /sprites` creates. `PUT /sprites/{name}` returns 404 — create-via-PUT is not supported. Match on `409` for idempotent re-runs.
`POST /sprites/{name}/exec?cmd=...` needs only an `Authorization` header. Adding `Accept: application/octet-stream` returns 406 Not Acceptable.
After start, poll the public URL up to ~12× at 1s with a 4s fetch timeout so the first user hits a warm sprite, not a cold-boot 502.