# Toonflow: an Electron workbench that turns novels into animated short dramas

> Toonflow is an Apache-2.0 desktop app from HBAI-Ltd that chains scriptwriting, storyboarding, character and video generation into one canvas. The repository's own instructions are the only install path, and the default login is admin / admin123.

**HBAI-Ltd/Toonflow-app** — Toonflow 是开源一站式 AI 短剧创作工具，将小说、剧本快速转化为动画短剧。集成 AI 编剧、智能分镜、角色与视频生成，跨平台桌面端轻量部署，助力创作者低成本批量产出视觉内容。Toonflow is an open-source AI tool that turns stories and scripts into animated short dramas. Features AI scriptwriting, storyboarding, character and video generation. A cross-platform desktop app for efficient content creation.

- Repository: https://github.com/HBAI-Ltd/Toonflow-app
- Website: https://toonflow.net
- Stars: 16,285 · Forks: 2,909
- Language: TypeScript
- License: MIT
- Published: 2026-09-09 · Updated: 2026-09-09 · Language: en
- Canonical page: https://hysenlabs.com/projects/hbai-ltd-toonflow-app

## What Toonflow actually replaces in a short drama pipeline

The problem Toonflow targets is not generation itself. Text models, image models and video models all exist and all have APIs. The problem is that a short drama needs the same characters to look the same across dozens of shots, and that consistency breaks the moment you move between tools. A script written in one app, storyboarded in a second, rendered in a third, has no shared memory of who the protagonist is.

Toonflow is aimed at creators and small studios producing vertical short dramas in volume, and at people adapting novels into screen form. The README describes it as a workbench built around a 策划 → 编剧 → 分镜 → 出片 loop, planning through script, storyboard and finished video. The package.json description narrows the same claim: an AI short drama and comic drama tool that converts novels into scripts automatically and combines AI-generated images and video.

That is a narrower audience than "anyone making video". If your output is a talking-head explainer or a screen recording, the storyboard and character-consistency machinery is overhead you will pay for and never use.

## The infinite canvas, the three agent layers and the ONNX memory

The README lists six capabilities, and three of them describe the mechanism rather than the promise.

The first is an infinite canvas workbench. Script, characters, storyboard panels, assets and video are organised as nodes rather than as a linear wizard, so a project can be reordered, rolled back and produced in parallel. This is the architectural decision that separates Toonflow from a step-by-step generator: the project state is a graph, and the UI is an editor over that graph.

The second is a three-layer agent structure, described as decision, execution and supervision layers that together handle task decomposition, content generation, quality review and revision feedback. The supervision layer is the interesting part. Most generation tools let the model produce and move on; here the README claims a review pass feeds corrections back before output is accepted.

The third is persistent agent memory, implemented with local ONNX vector retrieval and split into short-term messages, long-term summaries and semantic recall. Because the retrieval runs locally through @huggingface/transformers, the memory index does not require a hosted vector database, which matters for anyone running this offline or on a private network.

Two further mechanisms are worth naming. Chapter event extraction builds a structured event graph from the source novel, and script adaptation queries that graph rather than re-reading the whole text, which is the stated answer to context loss in long inputs. And the Skill system externalises the core prompts of ScriptAgent and ProductionAgent into Markdown files that can be edited in the app.

## Installing Toonflow and running a first project end to end

The repository does not ship a documented installer walkthrough in the README. What it gives is the login and the six-step workflow, plus a Dockerfile for the backend dev server. The README states the default account is admin / admin123, so treat that as the first thing to change.

The Dockerfile installs with yarn, strips the Electron-only packages before installing, and runs the backend dev server on port 10588. It sets the npm registry to registry.npmmirror.com, which will be slow or blocked for some networks; expect to edit the registry lines if you are not in that region.

```dockerfile
FROM node:24-bookworm-slim
WORKDIR /app
COPY . .
RUN yarn install --frozen-lockfile && yarn cache clean
ENV NODE_ENV=dev
ENV PORT=10588
EXPOSE 10588
CMD ["yarn", "dev"]
```

The container runs the backend only. For the desktop application, the package.json exposes the full set of scripts, and the build chain is TypeScript plus Vite plus electron-builder.

```bash
yarn install
yarn dev:gui-vite
yarn dist:win
yarn dist:mac
yarn dist:linux
```

yarn dev:gui-vite starts the Electron shell against the Vite dev server, which is the fastest way to see the canvas while you are still reading the code. The dist targets produce platform packages through electron-builder. Note that package.json declares engines.node as >=1.0.0 and packageManager as yarn@1.0.0, both of which are looser than what an Electron 24 base image implies; do not read them as a supported version range.

Once the app is open, the README's six steps are the tutorial. Log in. Configure text, image and video model providers in the settings centre. Create a project, import the source novel, and run chapter event extraction. Move to ScriptAgent to generate the story skeleton, the adaptation strategy and the structured script. Switch to ProductionAgent and arrange storyboard, asset and video nodes on the canvas. Then refine the storyboard images node by node, return them to the workbench, and export the assembled video.

The provider system is where the real configuration cost sits, and it is also the feature with the least documentation here. The README says you can write provider TypeScript logic directly in the settings centre and have it take effect immediately, without changing source or restarting. The dependency list confirms the intended vendors: @ai-sdk/openai, @ai-sdk/anthropic, @ai-sdk/google, @ai-sdk/deepseek, @ai-sdk/xai and @ai-sdk/openai-compatible for everything else. What the README does not give is a worked example of a provider definition, so plan on reading src/ before you write one.

## Where Toonflow breaks down

The honest limitation is that the README describes an end-to-end pipeline and documents almost none of its failure modes. There is no section on what happens when a video model returns a corrupt clip, when the event graph extraction mislabels a chapter, or when a provider call times out halfway through a batch. axios-retry is in the dependency list, so retries exist at the HTTP layer, but nothing in the README explains how a partially completed canvas node is recovered.

The second limitation is cost opacity. Toonflow orchestrates external models; it does not include them. A twelve-shot episode means twelve or more image generations plus video generations, billed by whichever vendors you configured. The README's claim of a demo produced in about two hours says nothing about what that demo cost, and the app itself has no documented budget or quota control.

The third is the desktop constraint. This is an Electron application with a Docker path that only runs the backend. If you want to generate episodes on a schedule from a CI runner, or expose the pipeline to other services, the repository layout does not show a documented API for that. The infinite canvas is a UI over project state; the README never presents it as a headless engine.

Finally, the release cadence. The most recent release listed is v1.1.8 from 2026-06-08, and the last push to the default branch was on 2026-08-26. That is recent enough that the project is not dormant, but the gap between the last tagged release and the last commit means the code on master is ahead of anything you can pin to a version.

## Toonflow against a node-based editor you already run

The obvious alternative for anyone reading this is ComfyUI, and the difference is not quality, it is where the domain knowledge lives. ComfyUI is a general node graph for diffusion models. You assemble the pipeline: you choose the checkpoint, you wire the conditioning, you build the character consistency yourself with whatever IP-Adapter or reference workflow you prefer. Nothing in it knows what a chapter is, or what a storyboard panel is.

Toonflow inverts that. The nodes are domain objects (script, character, storyboard, asset, video), the event graph is extracted from your novel automatically, and the agent layers decide what to generate next. You give up control over the generation graph and get a workflow that already understands serialised fiction.

The trade-off is real in both directions. A ComfyUI workflow you built is portable, versionable and runs headless on a server. A Toonflow project lives inside an Electron app whose provider logic you write in a settings panel. If your team already has a working ComfyUI pipeline with character LoRAs, Toonflow is not an upgrade; it is a different product with a different abstraction level.

If you only need script adaptation and no visual output, a plain LLM workflow with your own prompt templates does the job with fewer moving parts. The canvas and the video nodes are the reason to choose Toonflow, and if you do not need them, you are paying for a lot of Electron.

## Licence, upgrade cost and what the repository does not promise

Toonflow is Apache-2.0, confirmed in both the LICENSE file and the package.json license field. That is a permissive licence with an explicit patent grant and a NOTICES.txt at the repository root, which is the file to read before redistributing a build. Apache-2.0 does not cover the models you connect: the licence on the text, image and video models you configure in the provider system is a separate question, and Toonflow's licence says nothing about it. This is not legal advice; check your own obligations.

The upgrade path is the practical concern. The app stores project data, and better-sqlite3 plus @rmp135/sql-ts appear in the dependency list, which points to a SQLite-backed schema with TypeScript types generated from it. The README does not document schema migrations, so back up the data directory before moving between versions. There is also no documented rollback procedure, which is why pinning a release tag rather than tracking master is the safer default.

The build chain is heavy. Electron, Vite, TypeScript, better-sqlite3 (a native module) and @huggingface/transformers for local ONNX inference all have to be rebuilt per platform. The dist scripts run electron-builder, and the Dockerfile's comment about stripping Electron packages exists precisely because those binaries are large. Budget for a build environment, not just a runtime.

## Conclusion

Adopt Toonflow if you already have model provider keys and want a single desktop workspace that keeps script, characters, storyboard nodes and video in one project, and if you accept that the default admin / admin123 login must be changed before anything else. Skip it if you need a headless pipeline you can call from CI, or if you want a browser-based tool with no Electron download. Verify first that the model vendors you pay for are reachable from the provider system, that the Dockerfile's backend-only dev server on port 10588 is enough for what you plan to automate, and that the last push on 2026-08-26 means the code you pull is the code you reviewed.

## FAQ

### Is the Toonflow app free to use?

The application itself is Apache-2.0 licensed, so the code is free to use and redistribute under that licence. The models you connect through the provider system are billed by their own vendors, and Toonflow does not include them.

### How do I log in to Toonflow for the first time?

The README states the default account is admin with the password admin123. Change it before the app is reachable by anyone else.

### Can I run Toonflow on a server without a desktop?

The Dockerfile builds a container that runs only the backend dev server on port 10588, with the Electron packages stripped out. The README does not document a headless API for driving the full canvas pipeline.

### Which model providers does Toonflow support?

The dependency list includes the AI SDK packages for OpenAI, Anthropic, Google, DeepSeek, xAI and openai-compatible endpoints. The README also says you can write provider TypeScript logic in the settings centre and have it apply without restarting.

## Sources

- [HBAI-Ltd/Toonflow-app on GitHub](https://github.com/HBAI-Ltd/Toonflow-app)
- [License: Apache-2.0](https://github.com/HBAI-Ltd/Toonflow-app/blob/master/LICENSE)
- [Project website](https://toonflow.net)
- [README](https://github.com/HBAI-Ltd/Toonflow-app/blob/master/README.md)
- [Releases](https://github.com/HBAI-Ltd/Toonflow-app/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hbai-ltd-toonflow-app