メインコンテンツへスキップ

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-fx is FX on its own, from the @grida/fx package, 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.fx is 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.copy and package.

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.21–0.21 – 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.