Getting started
FX builds generated assets the way a build system builds code:
- You describe the steps in a workflow file.
- FX resolves models and plans the run, with a cost estimate and no paid model calls.
- It runs only what changed.
- Every result is kept with a record of how it was made.
Install
npm install -g grida # the grida command, with FX as grida fx (Node.js 24 or later)
pip install grida # the Python SDK, for nodes and builders you write in Python
npm install @grida/fx # in a project: the SDK for nodes and builders you write in TypeScript
grida fx doctor # checks the keys and tools your workflows need
grida carries the FX version it was released with; updating grida updates FX. No repository
clone or Rust toolchain is needed. FX runs on macOS, and on Linux with glibc 2.28 or later, on x64
and arm64. On Windows, use WSL 2. Install the SDK of the language you write your own nodes in:
one language per project is the usual choice, though a project may mix them.
This guide writes grida fx. You may also meet FX as grida-fx or python -m grida.fx: these are
the same FX, started another way, and take the same commands (grida-fx plan is grida fx plan).
grida-fxis FX on its own, from the@grida/fxpackage, which is also the JavaScript SDK. Projects that depend on@grida/fx, and servers or CI images that need only FX, use it.python -m grida.fxis FX from the Python package, for Python users who don't want Node (Running).
They share project files, the cache and run records. --version prints the FX version under any
of them, so you can tell two installations apart. Setting them up, and source development, are in
CONTRIBUTING.md.
One key for everything: Grida Gateway. Create a key at
console.grida.co and set it as GG_API_KEY. It serves every route on
Grida Gateway (@gg): text, agent turns, images, video, 3D models and rigs, billed to your
organization's Grida AI credits, so there is no provider account to open for each model. Set it in
the environment, or put it in a .env file in your project (GG_API_KEY=…, and keep the file
out of version control). FX builds with saved-key support can also use a standalone GG key saved
in Grida as a fallback on macOS and Linux. Keys stay out of fx.yaml and workflows. Paid calls
require --live. When preparing a selected GG or OpenRouter image model missing from the local
catalog, FX may make a bounded, read-only metadata request. The OpenRouter lookup can use its key.
grida fx doctor reports which keys it found, their sources, and which routes they make usable.
See Keys and live runs.
Already have provider accounts? FX also reads each provider's own key under its usual name
(OPENAI_API_KEY, OPENROUTER_API_KEY, FAL_KEY, TRIPO_API_KEY, ELEVENLABS_API_KEY) for the
routes on that provider; sound, speech and music need one, since GG has no route for them yet. No
key at all? With Codex signed in to your ChatGPT account, or Grok Build signed in to a Grok
subscription, images can come from your own Codex or
your own Grok Build. AI providers compares the ways.
When FX needs Python
The engine itself runs the paid built-in types (image.generate, structured.generate, …),
fx/select@1 and every file fact. Your own nodes, builders and
adapters run in their language: TypeScript ones on Node
(below), Python ones on Python. Python runs:
- your own Python nodes and builders, which import
from grida.fx import node, Ctx; - your own Python adapters, which import
from grida.fx import adapter: planning loads each one a project declares, and a live call on a route its provider serves runs in it; - the built-in local types, whatever language your own nodes are in:
image.resize,image.crop,image.pad,image.mirror_repeat,image.check_alpha,image.check_size,json.merge,files.copyandpackage.
A project that uses any of them needs Python 3.11 or later with grida and Pillow installed
(pip install grida, which brings Pillow). FX uses GRIDA_FX_PYTHON when it is set, else
the .venv of the workflow's project, else the .venv of the project you run from, else the Python
that runs the SDK when you run through it (Running), else python3
on PATH. An older Python is refused before FX starts it (macOS's own /usr/bin/python3 is
3.9): run uv sync or pip install grida in the project, or set GRIDA_FX_PYTHON. A project
whose steps are all paid built-ins, select and nodes of your own in TypeScript needs no Python,
unless it declares a Python adapter of its own.
The first workflow below uses image.check_alpha, so it needs Python.
When FX needs Node
Your own nodes, builders, stand-ins and
adapters in TypeScript (or JavaScript) run on Node, in the
node host that @grida/fx carries; planning loads a project's adapters too. A project with any of
them needs Node 24 or later (Bun and Deno cannot host nodes), and should install @grida/fx
(npm install @grida/fx): your modules import node (or adapter) from it, and tsc checks
them against it. FX hosts them with the @grida/fx the workflow's project would import, else the
one the project you run from would import, else the one that started FX, such as the one
grida fx carries. FX uses GRIDA_FX_NODE when it is set, else the Node that runs grida fx or
the JavaScript SDK (Running), else node on PATH. An older Node
is refused before FX starts it: install Node 24 or later, or set GRIDA_FX_NODE.
A project
A project is a folder with an fx.yaml in it. Start a new one with:
npx grida fx init my-assets
cd my-assets
grida fx start --background
grida fx status --json
init writes a starter project into a new or empty folder: fx.yaml, a README.md that says how
to install the CLI and connect an AI provider, an AGENTS.md and the FX skills
(.agents/skills/) for coding agents, a .gitignore that keeps runs, the cache, .env and what
Python and npm install out of git, an .env.example listing the key names, and
workflows/icon.yaml, a one-step workflow that draws an icon once you pick a route. It installs
nothing and starts nothing.
On a terminal it asks which template to start from; --template NAME names one without asking, and
grida fx init --list-templates lists them. A named init template is one of the
examples, downloaded from the FX release you
have, with the same agent files added. In a folder that already has an fx.yaml, it checks that file and
writes nothing. It refuses any other folder that has files in it: to make an existing folder (a
game repository, say) a project, write its fx.yaml yourself, holding fx: project/v1.
start serves the bundled
dashboard at http://127.0.0.1:8787/. Add --open to open it, or omit
--background to keep the service in your terminal. grida fx stop stops the
service without stopping workflows or deleting their records. Background mode
survives the launching command; it does not install crash or login supervision.
These commands need FX 0.2 or later; grida fx --version names yours.
As you author workflows and run them, a project can look like this:
my-assets/
fx.yaml # project settings
workflows/ # your workflow files
nodes/ # your own node types (optional)
prompts/ # prompt templates (optional)
inputs/ # files you feed in
package.json # "type": "module" and @grida/fx (TypeScript nodes only)
runs/ # every run, one folder each (created by FX)
.fx/cache/ # content-addressed results (created by FX)
.fx/service/ # local service state and catalog (created by FX)
The starter leaves routes and budgets commented out for you to choose. For the paid example below, set them:
# fx.yaml
fx: project/v1
budget:
max_usd: 10 # the ceiling for any one run; --max-usd overrides it
routes: # which model serves each capability by default
image.generate: openai/gpt-image-2.5-sunburst@gg
# workflows: [workflows, ../tools/art/workflows] # where a workflow id is looked for
grida fx nodes image.generate lists the routes that can serve a capability: FX's built-in
route table, plus the tables your project lists under route_tables: (read after it, so their
entries win).
Where workflows are found. A workflow named by its id (grida fx run icon) is looked for among
the .yaml and .yml files at the project root, then in workflows/ and every folder below it. A
monorepo that keeps its workflows elsewhere lists their folders under workflows:, searched in the
order given; each is relative to the project or absolute, and may lie outside the project. The list
replaces the default, so name workflows too if you keep workflows there as well. The project root
itself, or a folder above it, is refused, since it would search your runs and cache. A workflow in a
folder with an fx.yaml of its own keeps that project as its home: its ./ paths, node modules and
route defaults are that project's, with your routes: winning. The runs, the cache, the budget, the
route tables, the provider declarations and the takes file (<id>.takes.yaml at your root) stay
those of the project you run from.
Keep runs/, .fx/, .venv/ and node_modules/ out of source control. A project file is
recommended, not required for execution. For a one-off workflow, call run directly; use
--standalone inside an existing project to request an independent viewer for that invocation.
See Viewing.
Start from a template
add is available from FX 0.10.0. Use grida fx --version to check your installed engine.
To make your own animated pet, run this from the workspace where you want to keep it.
grida fx init --list-templates
grida fx add pet fox-pet
cd fox-pet
add creates a new, editable project with its own fx.yaml. Without a destination, add pet
creates ./pet. Pass a destination to name the new folder yourself. Its parent must already
exist. If the destination already exists, FX exits 2 and leaves your edits in place. Use a
different destination for a second copy. Run subsequent commands from the new folder to use its
project settings.
FX downloads its own examples from the release that matches your engine version. Setup checks the project configuration and the advertised workflow and preset. It reports prerequisites without installing them, running the workflow, or starting a service.
For Pet, edit the description in inputs/pebble.yaml and work with workflows/pet.yaml. The
preset starts from text. Follow the copied README to set up Python or try the stand-in, which
substitutes simple drawings for provider calls. Once the Python environment is ready, plan
the workflow and use doctor to check live-run prerequisites such as signed-in Codex.
grida fx plan workflows/pet.yaml --inputs inputs/pebble.yaml
grida fx doctor workflows/pet.yaml
For automation, grida fx init --list-templates --json lists FX's own templates from the embedded
index without a download. Entries with a workflow_entry are available to add.
grida fx add pet fox-pet --json returns an absolute project_root, a project-relative
workflow_entry and, for Pet, inputs_file. It also reports missing declared input files and
prerequisites for the entry. Use the returned folder as the working directory.
For example, adding image-recolor reports inputs/source.png in missing_inputs. The copied
README shows how to create that file with python make_input.py or supply your own image.
Community templates
To copy a public GitHub repository, pass its owner, name, and a tag or full 40-character commit SHA.
For example, a repository named acme/studio could offer a workflow in workflows/posters.yaml.
grida fx add acme/studio@v1.2.0 --workflow posters --json
This copies the project to ./studio. Pass a destination after the repository reference to name a
different folder. The repository must have fx.yaml at its root. FX downloads the source archive
for the requested tag or commit. Use a full commit SHA to pin the exact revision.
FX looks for an optional fx-template.json at the repository root. If present, it declares the
default starter. Otherwise FX uses the sole .yaml or .yml file directly inside workflows/
or fx/ that declares fx: workflow/v1. If the scan finds several workflows, choose one with
--workflow NAME. The name is a unique filename stem such as posters. You can also use the
flag to choose a different workflow from either directory when the project declares a default.
The receipt reports the selected path in workflow_entry and the full repository reference in
template.name, with template.source set to github.
To publish a default workflow or recommend an input preset, commit a root fx-template.json.
Paths are relative to the project root. workflow_entry is required. The other entries are
optional. These input paths and prerequisites apply when the installer selects the workflow
named in the file.
{
"workflow_entry": "workflows/posters.yaml",
"inputs_file": "inputs/sample.yaml",
"required_inputs": ["assets/reference.png"],
"prerequisites": ["Python 3.11 or later with the dependencies in pyproject.toml"]
}
Commit the referenced workflow and preset with the project. The installer reports an absent path
from required_inputs in missing_inputs. Setup copies files and checks the chosen entry.
Review the copied project before planning or running it, since those commands can load its code.
Your first workflow
Generate one item icon on a transparent background. If the background isn't actually clean, draw it again.
# workflows/icon.yaml
fx: workflow/v1
id: icon
title: One item icon
inputs:
name: { type: string, description: "What the item is" }
steps:
draw:
uses: fx/image.generate@1
with:
prompt: "A single ${{ inputs.name }} game icon, centered, no text."
background: transparent
size: 1024x1024
clean:
uses: fx/image.check_alpha@1 # a built-in, deterministic judge
judges: draw
with: { image: "${{ steps.draw.outputs.image }}", expect: transparent }
on_reject:
regenerate: { max: 3 } # draw again, at most three takes
outputs:
icon: ${{ steps.draw.outputs.image }}
Plan, then run
grida fx plan workflows/icon.yaml --name "copper lantern"
icon · 1 phase
phase 1 6 steps 1–3 provider calls $0.21 – $0.87
cached 0 of 3 known steps
estimate $0.21 – $0.87 ceiling $10.00
The plan counts every take regeneration may draw: three drawings and their three checks. The low
end is the one drawing that surely runs, at the low price of its size's tier; the high end is all
three, at the tier's high. The prices are the allowances of FX's built-in route table, in tiers by
size (openai/gpt-image-2.5-sunburst@gg at 1024x1024: 0.29 a call), which a project's own
tables can override.
grida fx run workflows/icon.yaml --live -- --name "copper lantern"
--live is required whenever a run may call a paid provider. Without it nothing is spent: local
steps still run, a paid call the cache already answered is replayed, and any other paid call
fails its step (image.generate on openai/gpt-image-2.5-sunburst@gg is a paid call; run with --live). A live
run also needs a ceiling, here the project's budget:. The run's folder holds its outputs;
grida fx inspect summarises it.
With the local service running, add --open to a plan or run to open its canvas.
The run URL stays available after execution finishes. A missing service does not
prevent execution; start it explicitly when you want browser inspection.
Run it again
Run the same command again and nothing is generated: every step is answered from the cache. Change
the workflow input name (after --) and only draw and clean run again. Rename a step, reorder your file, or change a
title, and nothing re-runs. Cost, cache and takes has the exact rule.
Don't like the icon? Ask for another take of that one step:
grida fx reroll runs/icon/2026-10-02-1 draw # take 2 from now on; take 1 stays in the cache
grida fx run workflows/icon.yaml --live -- --name "copper lantern" # draws take 2
grida fx pick runs/icon/2026-10-02-2 draw 1 # changed your mind: back to take 1, free
reroll and pick write your choice into icon.takes.yaml beside the workflow; every run
reads it.