The Grida FX guide

Grida FX builds generated assets the way a build system builds code: you describe the steps in a workflow file, FX plans the run offline with its price, runs only what changed, and keeps every result with a record of how it was made.

This guide describes FX for the people who use it. The contracts are in spec/, which is normative: where this guide and spec/ disagree, spec/ wins. The repository's llms.txt puts FX on one page for agents, checked against the engine; where it and this guide disagree, it wins. Where the guide describes something designed but not built yet, it says planned. Stable FX releases start at 0.1.0; the overview records the decisions, what shipped and what comes later.

The local FX service gives a project a stable address, a run/plan index, and a read-only node canvas. Start with grida fx init and grida fx start --background; standalone workflows remain supported. These service commands describe current source behavior: check your installed version's help before using them. Custom step pages remain planned. Portable recorded-run exports are described in the sharing chapter; check installed help for these source capabilities.

How FX is built

FX is a workflow engine for asset pipelines, implemented in Rust. YAML declares the dependency graph; the Python and JavaScript SDKs provide programmatic authoring and execution APIs, and host custom node bodies and workflow builders: Python's on Python, TypeScript's on Node.

The engine owns planning, scheduling, result identities, caching, spending limits, provider retries, and run records. SDKs and node bodies use that engine rather than implementing their own execution or billing layer. AI generation is one application; ordinary code can run as workflow steps too. The bundled viewer is a read-only canvas for plans and recorded runs.

Chapters

1. Getting started
2. The workflow file
3. Nodes: built-in, and your own in Python or TypeScript
4. Cost, cache and takes
5. Running: CLI, Python, JavaScript, agents
6. Annotations and judges: marks as artifacts, verdicts as decisions
7. Viewing workflows and runs: the bundled local node canvas
8. Stopping and continuing a run: exact targeting, cancellation and verified local cleanup
9. Working with runs from an SDK: names, saved records and independent observation
10. Cleaning up runs: listing a project's runs, removing the ones you no longer need, and pruning the cache
11. Share a recorded run: portable inspection, disclosure and immutable content
12. Images from your own Codex: no API key, with your ChatGPT plan, and its caveats
13. AI providers: no provider, your own Codex or Grok Build, Grida Gateway or your own keys, and what each serves
14. Images from your own Grok Build: no API key, with your Grok subscription, and its caveats
15. Community providers: a provider of your own, from a declaration, the OpenAI-compatible family or an adapter in Python or TypeScript

Example projects

The examples are complete FX projects, written from scratch the way a user would write them, with original settings and characters. Their routes are FX's built-in ones (rigged-character adds one illustrative route, for a capability FX does not serve yet), so their plans price at the built-in allowances, and a live run uses your own keys. Each plans offline; without --live a run does every free step and refuses each paid call at $0.

Project	What it shows	What runs
hello	your own nodes, built-in local steps, a judge, a keyed repeat, the cache	everything, offline, at $0
hello-ts	hello with every node in TypeScript: types from the declaration, a judge and the source closure	everything, offline, at $0
looping-parallax	plan-time facts, fallbacks, a paid call inside your own node	offline when every layer mirrors; a repaint is live
item-icons	a TypeScript builder reading a web game's own item table, a TypeScript stand-in, and delivery into the game	the stand-in offline; the icons live
concept-gallery	propose a world, review it, one reviewed image per entity: YAML plus judges you write	live
game-build	a game repo that builds its art with FX from its own level files: Python builder	the sky offline; the rest live
rigged-character	agents, Blender, parts × review rounds, a recovery loop, resume	plans and prices; its reviews use vision.review, which has no adapter yet, and its Blender steps use tool scripts (ctx.tool(...).script) and version constraints, which are planned

Every other example has Python nodes or built-in local types, so it needs a Python with grida and Pillow (Getting started); hello-ts and item-icons need Node 24 or later instead (Getting started). The examples' README says how to run them from a clone of the repository.