TongFlow: a plugin-based multimodal GenAI studio you can self-host

What TongFlow solves, and who it is actually for

TongFlow's premise is that an AI model is a modality transform. An LLM is text to text, an image model is text to image, a speech model is text to audio. The project wraps each capability as a node on a canvas, and the README describes three operations for arranging them: add, transform, combine. That framing is the product. Instead of learning per-model parameter sets, you place nodes and connect them.

The audience is people who want a visual workflow that spans modalities rather than a single-purpose generator. The README's demo table shows the intended progression: a basic workflow adds text, generates images, then blends them; an intermediate one writes a script, generates speech, generates a character image, and produces a lip-synced talking-head video; an advanced one generates lyrics, a song, characters, scenes and a storyboard into a music video. Those are the shapes of work the project is built around.

It is not aimed at someone who wants a library to call from code. There is a Python SDK on PyPI and a packages/tongflow directory in the repository, but the README's first instruction is to install a desktop app and sign in. The canvas is the entry point.

The node model: add, transform, combine

The README splits the node catalogue into two groups. Add nodes bring material in: text input, local image, camera photo, canvas sketch, local audio, mic recording, local video, camera recording, document, URL fetch, and 3D model file. Transform nodes do the work. Text has generate and rewrite. Image has generation, editing, understanding, upscaling, pose detection at 308 keypoints, 29-class body-part segmentation, surface normals, and matting. Video has generation, image-to-video, first and last frame interpolation, multi-image reference fusion, and omni-reference video that mixes image, video and audio references.

The README's availability table uses a checkmark for nodes with an official plugin and an open square for nodes that exist in the canvas but have no official plugin yet, marked as planned. That distinction matters more than the feature list. A node appearing on the canvas does not mean it runs without you supplying an implementation.

The plugin architecture is the reason for that gap. The README states that the plugin-based design lets every platform package its own independent plugins, with at least one official implementation per capability node, and that the core stays small while the ecosystem stays open. The repository reflects this: there is a plugins/ directory, a scripts/install-official-plugins.mjs invoked by pnpm plugins:install, and a verify:plugins script. The runtime is split between a TypeScript application and Python plugins, which is the source of most of the operational friction described later.

Installing the desktop app, and the macOS Gatekeeper step

The README frames the desktop app as a lightweight shell, roughly 10 MB, around the cloud studio at app.tongflow.com. You download an installer, install it, open it, and sign in with Google or WeChat. macOS builds are universal across Apple Silicon and Intel; Windows ships an x64 MSI. Both are linked from the latest release.

The README is explicit that the macOS builds are not yet notarized with Apple, so Gatekeeper blocks the first launch with a message that the app is damaged and cannot be opened. The documented fix is to move the app to Applications and clear the quarantine flag once:

xattr -cr /Applications/TongFlow.app

After that, the README says it opens normally. It also warns to download from the release page directly, because installers passed through chat apps may be renamed or re-flagged. That warning is worth taking literally: a re-flagged installer will hit the same Gatekeeper path again.

Signing in is the end of the setup for this route. The README says the cloud studio manages plugins and execution for you, so there is no local plugin installation to do. If you want an account-free setup, the README points to self-hosting instead, and notes that desktop app versions up to v0.1.13 bundled the local runtime.

Running TongFlow with Docker Compose

The self-host path uses the prebuilt image from GHCR. The compose file publishes port 3000 and mounts two named volumes, one for data and one for plugins:

services:
  tongflow:
    image: ghcr.io/tong-io/tongflow:latest
    ports:
      - "3000:3000"
    volumes:
      - tongflow-data:/data
      - tongflow-plugins:/plugins
    restart: unless-stopped

The compose file's header comment gives the command and the expected result: docker compose up -d, then http://localhost:3000. Every API key is optional at this stage because they can also be set in-app under Settings, persisted to /data/settings.json. The compose file passes MODAL_TOKEN_ID, MODAL_TOKEN_SECRET, OPENROUTER_API_KEY, GEMINI_API_KEY and OPENAI_API_KEY through from the environment, each defaulting to empty.

The .env.example explains what those keys route to. Text generation's default route goes through OpenRouter's free router, with optional OPENROUTER_FREE_MODEL, OPENROUTER_HTTP_REFERER and OPENROUTER_APP_TITLE overrides. Gemini is used by gen_text_gemini and the combine_text default path, and the handler accepts either GEMINI_API_KEY or GOOGLE_API_KEY. OpenAI has its own node, gen_text_openai, with an optional OPENAI_CHAT_MODEL default. DeepSeek appears as a commented-out key used for batch arrange and group logic in the arrange-texts handler. Modal credentials are for GPU and CPU workers.

The Dockerfile carries a constraint worth reading before you change anything. Both stages use debian-bookworm because the native modules better-sqlite3 and sharp are compiled against glibc in the builder and traced into the standalone bundle; the comment states that loading them under musl crashes. The runtime stage installs python3, python3-venv and python3-pip, and the comment explains why: the first plugin run creates a venv under /data and pip-installs the SDK and each plugin's requirements. That means the first invocation is slower than later ones, and it means the container needs working outbound access to a package index.

Where TongFlow is the wrong tool

The clearest limitation is the notarization gap. Shipping unsigned macOS builds is a deliberate trade-off for a young project, but it puts a manual terminal step in front of every new macOS user, and it will not survive a managed-fleet deployment where users cannot run xattr.

The second is the plugin venv. Because plugins are pip-installed on first run into a venv under /data, the container is not fully self-contained at startup. On a host with restricted egress, or behind a proxy that needs configuration the Dockerfile does not mention, the first plugin execution fails rather than the build. The failure arrives late, which is the worst time.

The third is coverage. The README's own table marks some canvas nodes as having no official plugin yet. If your workflow depends on one of those, you are writing the plugin, not using the product.

Finally, consider what you are actually adopting. The desktop app is a shell around a hosted service. If your requirement is that prompts and media never leave your infrastructure, the desktop route does not satisfy it by design, and you need the Docker path plus your own provider keys, which still send inference requests to OpenRouter, Google, OpenAI or Modal.

How TongFlow differs from ComfyUI

The obvious comparison is ComfyUI, and the difference is in the graph model rather than the feature list. ComfyUI exposes the internals of diffusion pipelines as nodes: samplers, schedulers, latent spaces, VAE decode steps, CFG values. Its users tune those. TongFlow's README states the opposite intent, describing a low barrier and high ceiling with no complex AI parameters to learn and no manual node connecting, reduced to add, transform and combine.

That is a real design fork. A TongFlow image node is a capability, not a pipeline stage, so you trade control over sampling for a canvas a non-specialist can operate. The plugin boundary follows from this: ComfyUI's ecosystem is custom nodes inside one Python process, while TongFlow's README describes each platform packaging its own independent plugins against a small core, with the Python SDK published separately on PyPI.

If you need deterministic control over a diffusion pipeline, ComfyUI's approach is the one that exposes it. If you need a workflow that moves between text, image, audio, video and 3D without you writing orchestration code, TongFlow's node vocabulary is closer to the task.

Licence and upgrade cost

TongFlow is AGPL-3.0-only per package.json, and the LICENSE file carries the same identifier. There is also a CLA.md and a COMMERCIAL-LICENSE.md at the repository root, which tells you the maintainers anticipate a commercial track alongside the open one. The AGPL's network clause is the part that matters for a self-hosted deployment: if you modify the software and let users interact with it over a network, the licence's source-availability obligation is generally understood to apply. That is a description of the licence, not legal advice, and the specific facts of your deployment decide it. If you plan to embed TongFlow in a product, read COMMERCIAL-LICENSE.md before you build on it.

On upgrades, the release cadence visible in the repository is three releases in about three weeks: v0.3.3 and v0.3.4 on 2026-08-19, and v0.3.5 on 2026-09-10. The last push to the repository was on 2026-09-10. Frequent releases at a 0.x version number mean the plugin ABI is the thing to watch. The build runs pnpm gen:abi before next build, reading packages/tongflow/abi/tongflow.abi.json, which suggests plugins are typed against a generated ABI. Pin your image tag rather than tracking latest if you depend on a specific plugin, because a new image can change the ABI your plugin was built against.

For the desktop route, upgrade cost is low: download the new installer. For Docker, it is a pull plus whatever the plugin venv does on the next run.

Editorial conclusion

Adopt TongFlow if you want a canvas where text, image, audio, video and 3D nodes are wired through add, transform and combine operations, and you are willing to run the Docker image with your own OpenRouter, Gemini or OpenAI keys. Skip it if you need a notarized macOS build out of the box or an officially supported plugin for every node on the canvas, since the README marks several as planned. Verify two things before committing: that the node you need has a checkmark rather than a planned marker, and that the plugin venv installs cleanly in your environment, because the Dockerfile notes that the first plugin run creates a venv under /data and pip-installs each plugin's requirements.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. tong-io/tongflow on GitHub