Run workflows headlessly

Design a workflow in the editor, hit 💾 to download noodle-graph.json, then load and re-run it from Node.js or Python. Both packages are named nanoodle, ship a library and a CLI, have zero runtime dependencies (Node ≥ 20 with built-in fetch; Python ≥ 3.9, stdlib only), and implement the same contract — same graphs, same semantics.

JavaScript (Node ≥ 20)

npm install nanoodle     # library + CLI
npx nanoodle --help      # or run the CLI without installing

Library

import { Workflow } from "nanoodle";

const wf = await Workflow.load("noodle-graph.json");           // key from NANOGPT_API_KEY
const result = await wf.run({ Text: "a cozy ramen shop on a rainy night" });
await result.get("Image").save("ramen.png");                   // media: MediaRef (url + bytes()/save())
console.log(result.costUsd, result.remainingBalance);

With the app's starter graph (text → LLM prompt-writer → image), that's the whole program.

CLI

Inspect first — offline; shows inputs, outputs, and settings:

npx nanoodle inspect graph.json

Then run (calls NanoGPT and spends from your balance):

export NANOGPT_API_KEY=...   # or --key K, or --env-file .env
npx nanoodle run graph.json --input Text="a cozy ramen shop" --out ./out
npx nanoodle run graph.json --input n2.system=@style.txt --set n3.size=1k --json

• --env-file path — load NANOGPT_API_KEY from a .env-style file (--key wins if both are set)
• --input k=@path — read a file (media as media; .txt / .md / .json as text)
• --out dir — save media outputs to disk
• --json — machine-readable result

Python (≥ 3.9, stdlib only)

pip install nanoodle
export NANOGPT_API_KEY=...   # nano-gpt.com API key (or OAuth access token)

Library

from nanoodle import Workflow

wf = Workflow.load("noodle-graph.json")
result = wf.run({"Text": "a cozy ramen shop on a rainy night"})
result["Image"].save("ramen.png")            # media: MediaRef (url + bytes()/save())
print(result.cost_usd, result.remaining_balance)

CLI

Installed as nanoodle-py (and python -m nanoodle always works):

nanoodle-py inspect graph.json
nanoodle-py run graph.json --input Text="a cozy ramen shop" --set n3.size=1k --out ./out
nanoodle-py run graph.json --input n2.system=@style.txt --json
nanoodle-py run graph.json --env-file .env --input Text="hello"

Inputs, outputs, settings

Both packages expose the workflow's interface before you run it — wf.inputs, wf.outputs, wf.settings. Input keys are flexible (case-insensitive): the node's custom name ("Text"), nodeId.field ("n2.system"), or the input's label. A workflow with exactly one required input also accepts a bare value: wf.run("hello"). Settings use nodeId.field keys ("n3.model").

Media inputs take a local file (mediaFromFile / media_from_file), a hosted URL, or raw bytes (MIME sniffed). Media is sent inline as base64 (NanoGPT has no upload endpoint); files over ~4.4 MB (~3.5 MB for transcription) are refused locally with a clear error before any paid call.

What runs where

Pure-logic nodes (text, uploads, choice, join, comment) run locally; generation nodes (llm, image, edit, inpaint, vision, video, lipsync, music, remix, tts, transcribe) call NanoGPT. The 6 media-processing nodes (resize, vframes, combine, soundtrack, trim, extractaudio) also run headlessly. They do their work on your machine and never spend. Some of them need ffmpeg and ffprobe on PATH:

ffmpeg is a soft dependency, not a package dependency. Install it with apt install ffmpeg or brew install ffmpeg. If a node needs it and it is absent, that node stops the run with a clear error that names it. The error arrives when the node's turn comes, so paid nodes earlier in the graph have already spent — run a media-only graph once to prove your setup before you wire a paid node in front of it.

Only an unknown node type is refused up front: the libraries warn at load and throw at run() before any network call. That is how a graph saved before 2026-07-22 with the retired draw node behaves. The full node table is on the format page.

No account: pay per run in Nano (x402)

Skip the API key entirely. With --pay (or a library payment callback), each paid call returns an HTTP 402 Nano (XNO) invoice — scan/pay from a self-custody wallet; nanoodle waits for the deposit and continues. The library never holds funds or keys.

# JavaScript
npx nanoodle run graph.json --input Text="hello" --pay

# Python
python -m nanoodle run graph.json --input Text="hello" --pay

Worked examples (QR / print invoice, wallet stub, bare chat) live in both packages: nanoodle-js/examples/x402 · nanoodle-py/examples/x402.

Use a workflow as an agent skill

A saved workflow plus a short SKILL.md playbook is a skill any coding agent can run — anything that reads markdown and runs shell. Recipe, template and a working example (idea → LLM prompt → poster image) ship in both repos: docs/agent-skills.md.