Code-first video & image, rendered natively on WebGPU.
name: framefields-cloud
description: Render framefields projects on framefields cloud GPUs (api.framefields.dev) or a self-hosted render worker. Use when running framefields render --cloud, calling renderCloud from framefields/cloud, planning cost and workers, splitting a long film across several GPUs, starting renders from the framefields dashboard, getting a project render-ready (push, lockfile, pinned assets, private repos), or fixing a cloud render error code such as ASSET_NOT_FOUND or LOCKFILE_MISSING.
framefields-cloud
The cloud renders the pushed commit of a project on framefields' GPUs and can split a long film across several. Local rendering, checks and named renders in framefields.json are in framefields-render; project setup is in framefields.
Make the project render-ready
The worker clones the repo, installs from the lockfile, fetches assets and calls the render's export. So:
- Commit and push first. Uncommitted changes aren't rendered (the CLI warns); a commit not on the remote, a folder outside git, or a repo without a remote is refused.
- Commit the lockfile and pin
packageManager. The worker renders with the project's own framefields version (2.11+ for split renders, 2.12+ for named renders). bun lockfiles can't be installed by the worker. - Every input must reach the worker: pinned with
framefields assets add(preferred), tracked in Git LFS and pushed, or committed. Other.gitignored files don't exist there. - Build asset paths from
import.meta.url, neverprocess.cwd(). Nothing may write intonode_moduleswhile rendering. - Builders stay pure: no rendering, generation or writes while building.
npx framefields check <name>runs the same import locally; run it before every cloud render. - Private repos: the user connects GitHub once at https://framefields.dev/dashboard/settings#connections (the framefields GitHub App, ideally on all repositories). Public repos need nothing.
- Key: it bills the account behind
FRAMEFIELDS_API_KEY(https://framefields.dev/dashboard/keys), the same key as the AI gateway. Ask the user to set it in the environment; never print, write or embed it.
Pinned assets: the CLI and renderCloud upload any the bucket lacks and sign reads for remotes without a publicUrl (24 h; keys stay local). Workers download and cache them by hash; R2 downloads are free, unlike LFS bandwidth. Dashboard renders have nobody to sign, so they only read remotes with a publicUrl.
CLI
Run from the project folder (where framefields.json and package.json are; in a monorepo that folder is sent as the workdir).
npx framefields render film --cloud --plan # workers, time, estimated cost; renders nothing
npx framefields render film --cloud # render, then download to the render's output
npx framefields render --cloud # the only named render
npx framefields render src/film.ts --cloud --export buildFilm --workers auto # a module, no manifest
- Flags override the named render's fields:
--workers <n|auto>,--max-workers <n>,--codec h264|vp9,--quality,--select,--output,--export,--json(final status as JSON). --workersdefaults to the render'sworkers, else 1.automeasures frame cost on one worker, then adds workers only while they stay efficient: a 5-minute film stays on one, a 3-hour film spreads to--max-workers(API cap 10).- Show the user
--planbefore a long or expensive render. It prints e.g.Plan: 4 workers, 1 h 50 min of render work, ready in about 35 min, estimated $1.20. - Output is one line per phase (
probing, rendering N chunks and the audio,stitching,Done in …: <file>, <GPU seconds>, <cost>.), with progress and cost so far at most every 10 s. Run it in the background and let it finish; Ctrl-C cancels (used GPU time is charged).
From code
No GPU needed locally:
import { CloudRenderError, renderCloud } from "framefields/cloud";
try {
const result = await renderCloud({
render: "film", // or { entry: "src/film.ts", export: "buildFilm", workers: "auto" }
outputPath: "output/film.mp4",
onProgress: (s) => console.log(s.status, s.progress.frames, s.progress.totalFrames, s.costUsd),
// dryRun: true // plan only: result.plan, result.estimateUsd
});
console.log(result.filePath, result.gpuSeconds, result.costUsd);
} catch (err) {
if (err instanceof CloudRenderError) console.error(err.code, err.message);
else throw err;
}
Options override the named render's; signal cancels. cloudClient({ apiKey }) exposes start, status, cancel. HTTP: POST /v1/render (source, target, render, workers, max_workers, dry_run, name, title), GET / DELETE /v1/render/:id, Authorization: Bearer <key>.
Billing and the dashboard
- A credit hold is placed at start (raised to the estimate once planned); the charge is the GPU seconds used, the rest is released. Failed and cancelled renders charge what they used.
insufficient_credits: the user adds funds at https://framefields.dev/dashboard/billing. Don't retry.- https://framefields.dev/dashboard/renders shows every render with live progress, cost, Cancel and the video. New render lists the named renders of a connected repo's branch (greyed out when
entryisn't on that branch), with Plan and Render.
Errors
The error carries the worker's code. Fix the project, commit, push, render again.
| Code | Fix |
|---|---|
REPO_NOT_FOUND, GIT_AUTH_FAILED |
Connect GitHub (Settings → Connections) with access to this repo. |
REF_NOT_FOUND, COMMIT_MISMATCH |
git push. |
LOCKFILE_MISSING, INSTALL_FAILED |
Commit a lockfile that installs cleanly. |
ENTRY_NOT_FOUND, EXPORT_NOT_FOUND, EXPORT_INVALID |
Fix entry/export; framefields check <name>. |
COMPOSITION_BUILD_FAILED, EXPORT_SIDE_EFFECT |
The builder throws or renders/writes; framefields check reproduces it. |
ASSET_NOT_FOUND, LFS_OBJECT_MISSING, LFS_POINTER_UNRESOLVED |
git lfs ls-files, git lfs push --all origin; un-ignore needed assets. |
ASSET_NOT_UPLOADED, ASSET_HASH_MISMATCH |
npx framefields assets push from the machine with the right file. |
ASSET_PRIVATE, ASSET_FORBIDDEN |
Dashboard render of a remote without a working publicUrl: render from the CLI or fix publicUrl. |
ASSET_MANIFEST_INVALID |
npx framefields assets status shows the error. |
ENGINE_UNSUPPORTED |
Upgrade framefields (2.11+) or use --workers 1. |
RENDER_TIMEOUT, RENDER_OOM |
--workers auto or more workers. |
Infrastructure errors (GIT_NETWORK, RENDER_STALLED, a lost worker) are retried by the API, and a straggling chunk gets a backup worker.
A stitched video with a jump at a chunk seam means a stateful effect reads wall-clock time; keep effects deterministic in the frame number.
Self-hosted render worker
The same worker runs on your own GPU (Docker, RunPod pod or serverless): it renders a pushed commit with the rules above and uploads the result. A failed job returns { code, hint, retryable }; resubmit unchanged only when retryable is true. Job format: https://framefields.dev/docs/guides/render-service/
To split a render yourself, see Splitting a long render in framefields-render.