Getting started

TongFlow runs as a Docker container on your own machine, or as a Next.js dev server if you have pnpm set up. Pick one. The Docker path is the recommended way for non-Node users.

What you need

  • Docker (with Compose v2)
  • 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

If you don’t have pnpm, you can run the equivalent modal token set from inside the Docker container after step 4.

4. Run

Option A — Docker Compose (recommended)

docker compose up --build

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

Data persists in Docker volumes: SQLite at data/tongflow.db, uploads at data/uploads/.

Option B — Pre-built image from GHCR

CI publishes ghcr.io/tong-io/tongflow on every push to main, and tagged releases (e.g. v0.1.0).

docker pull ghcr.io/tong-io/tongflow:latest
docker run --rm -p 3000:3000 --env-file .env -v tongflow_data:/app/data ghcr.io/tong-io/tongflow:latest

For private fork workflows you may need docker login ghcr.io with a read:packages-scoped token.

Option C — Local development with pnpm

Requires Node.js 20 or later.

pnpm install
pnpm dev

Same URL: http://localhost:3000.

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