Getting started

TongFlow runs as a Next.js dev server on your own machine. You’ll have your first workflow running in about five minutes.

What you need

  • Node.js 20 or later, with pnpm
  • A Modal account and tokens — sign up at modal.com. The free tier (USD 30 / month) includes meaningful H100 time and covers most of TongFlow’s GPU work.
  • At least one LLM API key — pick one: OpenRouter, Gemini, OpenAI, or DeepSeek. OpenRouter has a free routing tier; the others charge per request.

Optional: a Discord account to ping us in #tongflow if anything is unclear.

1. Clone

git clone https://github.com/tong-io/tongflow
cd tongflow

2. Configure environment variables

Copy the example and edit it:

cp .env.example .env

The variables you must fill in:

VariablePurpose
MODAL_TOKEN_IDModal worker auth
MODAL_TOKEN_SECRETModal worker auth
At least one of: OPENROUTER_API_KEY / GEMINI_API_KEY (or GOOGLE_API_KEY) / OPENAI_API_KEY / DEEPSEEK_API_KEYThe “Generate text” node and other LLM-routed transforms

Optional:

  • OPENROUTER_FREE_MODEL — pin a specific free OpenRouter route
  • OPENAI_CHAT_MODEL — defaults to gpt-4o-mini when unset
  • NEXT_PUBLIC_FILE_BASE_URL — base URL for file storage if you front the app with a CDN

3. Authorize Modal once

This writes tokens to ~/.modal.toml and is only needed before the first run:

pnpm modal:setup

4. Run

Requires Node.js 20 or later.

pnpm install
pnpm dev

Open http://localhost:3000. You’ll land on /workspace.

Data persists locally: SQLite at data/tongflow.db, uploads at data/uploads/.

5. Your first workflow

Once /workspace loads:

  1. The page opens in Create mode (Sparkles icon in the mode switch — see Workflow modes).
  2. The Smart Island at the bottom shows seven Add icons: 3D / Document / Image / Text / Video / Audio / Link.
  3. Click the Text icon (Type letterform) to drop a text node. Type a prompt like “a watercolor portrait of a cat in a library”.
  4. Drag from the text node’s output handle to empty canvas → choose Image generation → an image node appears wired in.
  5. Switch to Execute mode (toggle the Sparkles → Play icon) and click the Play button on the Smart Island.
  6. The task runs through your Modal account; results appear on the image node.

That’s the whole loop. From here you can chain another transform (image → video, image → 3D, image upscale), branch into a Combine node (e.g. lip sync), or save the workflow.

Where things live

  • Workflows — saved in data/tongflow.db. Open them with the Workflow button (top-left, three-button left sidebar).
  • Materials / Portfolio — uploaded files appear in the Portfolio dialog (top-left FolderOpen icon, not on the Smart Island).
  • Tasks — execution history is in the Task panel (top-left Zap icon).

Next