Submitted by entreprise7pro on Thu, 09/24/2026 - 21:50

Ubuntu 24.04 lts

Movie Factory Blackwell

A non-destructive orchestration layer for the proven ComfyUI/MiniMax H3 workflow, with both an existing-workstation path and a portable clean-machine deployment bundle.

Stack: PydanticAI for planning/director work, Prefect for durable Python flows/state, and ComfyUI as the existing headless GPU renderer. OpenClaw is intentionally optional and is not required for the core Movie Factory pipeline.

Quick start: run `movie-factory-deploy.tar.gz`

If you are standing in front of a fresh Ubuntu 24.04 machine and have the deployment archive, this is the normal path.

Important: run the installer as your normal Linux user. Do not run sudo ./install.sh. The installer calls sudo itself only when it needs apt or systemd access.

1. Put the archive on the target machine

If the file is already on the machine, go to the directory that contains it.

For example:

cd ~/Downloads
ls -lh movie-factory-deploy.tar.gz

If you are copying it from another computer:

scp movie-factory-deploy.tar.gz user@target-host:~/
ssh user@target-host
cd ~

2. Extract it

tar -xzf movie-factory-deploy.tar.gz
cd movie-factory-deploy

You should now see files such as:

install.sh
verify.sh
uninstall.sh
README.md
PACKAGE-MANIFEST.txt
config/
lib/
payload/

Optional sanity check:

ls -la
cat PACKAGE-MANIFEST.txt

3. Make sure the GPU driver and Ollama already work

The deployment bundle does not install the host NVIDIA/AMD kernel driver and assumes Ollama is already installed.

For NVIDIA:

nvidia-smi

For AMD:

rocminfo | head

Check Ollama:

ollama --version
ollama list

If the GPU driver itself is not working, fix that before running the deployment installer.

4. Optional: customize the deployment

The defaults are suitable for an automatic hardware-based deployment. To override them:

cp config/local.env.example config/local.env
nano config/local.env

Typical values are:

MODEL_PROFILE=auto
DOWNLOAD_REF2VA=1
DOWNLOAD_TURBO=1
OLLAMA_MODELS="gemma4:31b-it-qat qwen3.6:35b"
DIRECTOR_MODEL=ollama:gemma4:31b-it-qat

With MODEL_PROFILE=auto, the installer chooses the H3 model profile from the detected GPU and VRAM.

If Hugging Face requires authentication:

export HF_TOKEN='your-token-here'

Do not store the token in the archive.

5. Run the installer

Interactive/recommended:

./install.sh

The installer first prints what it detected and what it intends to change. It then asks:

Continue? [y/N]

Answer y to proceed.

If the archive has lost executable permissions during transfer:

chmod +x install.sh verify.sh uninstall.sh
./install.sh

For an installation you have already reviewed and want to run without the confirmation prompt:

./install.sh --yes

The installer will:

detect GPU
→ install Ubuntu/Python prerequisites
→ install ComfyUI
→ install the correct CUDA/ROCm PyTorch build
→ select the H3 model profile
→ install Movie Factory
→ download H3 models
→ pull configured Ollama models
→ install systemd services
→ start the stack

The model downloads are large. The full profile can exceed 90 GB before Ollama caches, while pruned profiles are still tens of gigabytes.

6. Verify the installation

When install.sh finishes:

./verify.sh

Then check the aggregate service:

sudo systemctl status movie-factory.target

And run the Movie Factory diagnostic directly if desired:

cd ~/movie-factory-blackwell
source .venv/bin/activate
movie-factory doctor

The expected final state is:

Workflow    : OK
Nodes       : OK
Wf models   : OK
Status      : READY

7. After a reboot

The deployment enables Movie Factory through systemd. Check it with:

sudo systemctl status movie-factory.target
sudo systemctl status movie-factory-comfyui.service
sudo systemctl status movie-factory-prefect.service

Useful controls:

sudo systemctl restart movie-factory-comfyui.service
sudo systemctl restart movie-factory-prefect.service

sudo systemctl stop movie-factory.target
sudo systemctl start movie-factory.target

Logs:

journalctl -u movie-factory-comfyui.service -f
journalctl -u movie-factory-prefect.service -f

8. First Movie Factory test

cd ~/movie-factory-blackwell
source .venv/bin/activate



movie-factory plan \
  "Test Movie" \
  examples/treatment.txt \
  --id test_movie

Review:

projects/test_movie/project.yaml

Set at least one shot to:

approved: true

Then:

movie-factory render \
  projects/test_movie/project.yaml \
  --dry-run

If the dry run is correct:

movie-factory render projects/test_movie/project.yaml

The short version

For a normal automatic deployment with defaults:

tar -xzf movie-factory-deploy.tar.gz
cd movie-factory-deploy
./install.sh
./verify.sh

That is the intended way to run the deployment archive.

Safety / no-sorcery policy

For the existing-machine/project bootstrap path, setup.sh does not use sudo, apt, PPAs, third-party package repositories, Git remotes, systemd, CUDA/driver changes, ComfyUI updates, OpenClaw installation, or model downloads.

The separate movie-factory-deploy.tar.gz bundle is intentionally different: its install.sh is a reviewed clean-machine installer that uses sudo for Ubuntu packages and systemd, installs ComfyUI/Python dependencies, selects CUDA or ROCm PyTorch, downloads configured H3 models, and pulls configured Ollama models. It still does not install or replace host GPU kernel drivers.

It creates only the local project virtual environment, .env, and Python package metadata inside this project. Python dependencies come from normal PyPI.

If a future step needs a new apt repository, Git remote, external installer, system service, model download, or similar machine-wide change, treat that as a separate explicit step and review it first.

Portable deployment strategy (`.tar.gz` / `.tgz`)

There are now two different archives with different purposes:

movie-factory-blackwell-source.tgz
movie-factory-deploy.tar.gz

`movie-factory-blackwell-source.tgz`

This is a source/project snapshot. It preserves the working Movie Factory code, workflow JSON, examples, project files, and helper scripts.

Use it when you want to:

back up or move the current Movie Factory project
inspect or modify the source
restore the project onto a machine where the supporting stack already exists

It is not the preferred clean-machine bootstrap package. By itself it does not install Ubuntu packages, Python, ComfyUI, GPU-specific PyTorch, MiniMax H3 models, Ollama models, or systemd integration.

`movie-factory-deploy.tar.gz`

This is the portable deployment bundle for a new Ubuntu machine. Use this archive when reproducing the stack on another server or workstation.

The current deployment target is:

Ubuntu 24.04 LTS
x86_64
one NVIDIA or AMD GPU
working host GPU driver
Ollama already installed
Python may be absent
ComfyUI may be absent

The deployment installer deliberately does not install or replace NVIDIA/AMD kernel drivers. The host GPU driver must already work before deployment begins.

The bundle installs or configures:

Ubuntu/Python prerequisites
ComfyUI in its own virtual environment
NVIDIA CUDA or AMD ROCm PyTorch runtime selection
MiniMax H3 models from Hugging Face
optional FL2V/Ref2V Turbo LoRAs
configured Ollama model pulls
Movie Factory
PydanticAI and Prefect
hardware-aware H3 workflow checkpoint selection
movie-factory-comfyui.service
movie-factory-prefect.service
movie-factory.target
post-install verification

Ollama itself is assumed to be installed already. The deployment bundle can pull the configured Ollama models, but it does not replace the Ollama installation.

Deploy on another machine

Copy the archive to the target machine, for example:

scp movie-factory-deploy.tar.gz user@target-host:~/

Then on the target machine:

cd ~
tar -xzf movie-factory-deploy.tar.gz
cd movie-factory-deploy

Review the package before installation:

less README.md
cat PACKAGE-MANIFEST.txt

For custom settings:

cp config/local.env.example config/local.env
nano config/local.env

Important configurable values include:

MODEL_PROFILE=auto
DOWNLOAD_REF2VA=1
DOWNLOAD_TURBO=1
OLLAMA_MODELS="gemma4:31b-it-qat qwen3.6:35b"
DIRECTOR_MODEL=ollama:gemma4:31b-it-qat
COMFYUI_ROOT=/home/YOU/comfy/ComfyUI
MOVIE_FACTORY_ROOT=/home/YOU/movie-factory-blackwell

If Hugging Face authentication or license acceptance is required, export the token in the shell instead of storing it in the deployment archive:

export HF_TOKEN='...'

Start the interactive installation:

./install.sh

The installer shows the planned machine changes before proceeding.

For an already-reviewed unattended installation:

./install.sh --yes

After installation:

./verify.sh

You can also run the Movie Factory diagnostic directly:

cd ~/movie-factory-blackwell
source .venv/bin/activate
movie-factory doctor

A healthy baseline should end with:

Workflow    : OK
Nodes       : OK
Wf models   : OK
Status      : READY

Automatic GPU/model profiles

With:

MODEL_PROFILE=auto

the deployment bundle currently selects:

Hardware	Automatic profile	H3 baseline
NVIDIA with at least 48 GiB VRAM	`nvidia-full-int8`	full INT8 ConvRot
NVIDIA with less than 48 GiB VRAM	`nvidia-pruned-int8`	pruned INT8 ConvRot
AMD	`amd-pruned-int8`	pruned INT8 ConvRot

Examples:

RTX PRO 6000 96 GB -> nvidia-full-int8
RTX 5090 32 GB     -> nvidia-pruned-int8
RX 7900 XTX 24 GB  -> amd-pruned-int8

For the RTX PRO 6000 96 GB profile, ComfyUI uses --highvram. Lower-VRAM NVIDIA and AMD profiles use normal ComfyUI VRAM/offload behavior.

The installer patches only the hardware-appropriate model filenames in the proven exported API workflow. It does not reconstruct or dynamically rewire the H3 graph.

For AMD RDNA3, especially the RX 7900 XTX, the deployment path is available but MiniMax H3 image/reference workflows should currently be treated as experimental because upstream ComfyUI/ROCm issues can affect I2V/R2V behavior. A successful movie-factory doctor confirms installation/workflow compatibility, not complete NVIDIA/AMD feature parity.

Installed locations

Default application locations are:

~/comfy/ComfyUI
~/movie-factory-blackwell

ComfyUI receives a dedicated environment:

~/comfy/ComfyUI/.venv

Movie Factory receives a separate environment:

~/movie-factory-blackwell/.venv

Keeping these environments separate is intentional.

Boot and service control

The deployment installer creates and enables:

movie-factory.target
movie-factory-comfyui.service
movie-factory-prefect.service

If an existing ollama.service is detected, movie-factory.target also includes it.

Useful commands:

sudo systemctl status movie-factory.target
sudo systemctl status movie-factory-comfyui.service
sudo systemctl status movie-factory-prefect.service

sudo systemctl restart movie-factory-comfyui.service
sudo systemctl restart movie-factory-prefect.service

sudo systemctl stop movie-factory.target
sudo systemctl start movie-factory.target

Logs:

journalctl -u movie-factory-comfyui.service -f
journalctl -u movie-factory-prefect.service -f

Do not run a legacy comfyui.service on port 8188 at the same time as movie-factory-comfyui.service.

If you explicitly want the deployment installer to disable an existing conflicting ComfyUI service, set this in config/local.env before installation:

DISABLE_EXISTING_COMFYUI_SERVICE=1

Re-running and uninstalling

The deployment installer is designed to be reasonably idempotent. Existing apt packages, virtual environments, model files, and a ComfyUI checkout can be reused. It does not automatically git pull an existing ComfyUI checkout.

To remove only the Movie Factory systemd integration while leaving application and model data in place:

./uninstall.sh

To also remove the installed ComfyUI and Movie Factory directories:

PURGE=1 ./uninstall.sh

Ollama and Ollama models are not removed by the deployment uninstall script.

Recommended deployment rule

For a new machine, use:

movie-factory-deploy.tar.gz

For a source backup, development handoff, or restore onto an already prepared machine, use:

movie-factory-blackwell-source.tgz

Keep the deployment bundle versioned alongside the source snapshot so a working Movie Factory release can be reproduced without depending on the state of the original workstation.

1. Existing-machine install

From the project directory:

cd ~/movie-factory-blackwell
./setup.sh
source .venv/bin/activate

The setup finishes with a read-only diagnostic. You can repeat it at any time:

movie-factory doctor

Current proven local environment

The workstation currently uses:

ComfyUI URL : http://127.0.0.1:8188
ComfyUI root: /home/bruce/comfy/ComfyUI
GPU         : NVIDIA RTX PRO 6000 Blackwell Workstation Edition
VRAM        : ~94.9 GiB reported by ComfyUI

The project virtual environment includes:

PydanticAI  2.49.0
Prefect     3.8.6

Doctor behavior

movie-factory doctor now validates the actual exported ComfyUI API workflow, rather than relying on guessed or hard-coded H3 custom-node names.

It checks:

ComfyUI connectivity at COMFYUI_URL
GPU/device information reported by ComfyUI
COMFYUI_ROOT
model files under COMFYUI_ROOT/models
whether workflows/h3_fl2va.api.json exists
every unique class_type referenced by the workflow against live ComfyUI /object_info
every model filename referenced by the workflow against the local ComfyUI model inventory

A healthy baseline currently reports:

Workflow    : OK
Nodes       : OK
Wf models   : OK
Status      : READY

If ComfyUI is running but the local path cannot be found automatically, edit .env:

COMFYUI_ROOT=/home/bruce/comfy/ComfyUI

2. Current H3 model inventory

The baseline H3 stack currently includes:

diffusion_models/
  minimax_h3_fl2va_int8_convrot.safetensors
  minimax_h3_ref2va_int8_convrot.safetensors

text_encoders/
  qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors

vae/
  minimax_h3_video_vae_int8_convrot.safetensors
  minimax_h3_audio_vae_fp32.safetensors

loras/
  minimax_h3_fl2v_turbo_4step_v0.1.safetensors

The known-good baseline workflow does not depend on the Turbo LoRA. Turbo remains an optional acceleration path to test after the baseline pipeline renders successfully end-to-end.

The REF2VA model is installed and will be useful for future reference-image / identity-consistency workflows.

3. Optional Prefect UI/server

Movie Factory can execute Prefect flows locally without a Prefect server.

For the Prefect dashboard and persistent orchestration API, open another terminal:

cd ~/movie-factory-blackwell
./scripts/start-prefect.sh

The server should bind only to:

127.0.0.1:4200

To record Movie Factory runs in the Prefect server, set in .env:

PREFECT_API_URL=http://127.0.0.1:4200/api

Leave it commented or unset when the Prefect server is not running.

4. Proven H3 workflow

Do not rebuild the H3 graph from scratch.

The known-good ComfyUI UI workflow is preserved as:

workflows/reference/H3_FULL_INT8_20STEP_FLAT.ui.json

The corresponding API-format workflow used by Movie Factory is:

workflows/h3_fl2va.api.json

The current API workflow contains:

18 API nodes
17 unique node types

and all required node types are currently available in the live ComfyUI instance.

Current baseline workflow characteristics

The exported baseline currently uses:

Model        : minimax_h3_fl2va_int8_convrot.safetensors
Text encoder : qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors
Video VAE    : minimax_h3_video_vae_int8_convrot.safetensors
Audio VAE    : minimax_h3_audio_vae_fp32.safetensors
Sampler      : res_multistep
Scheduler    : simple
Steps        : 20
FPS          : 24
Duration     : 5 seconds
Aspect ratio : 16:9
Megapixels   : 0.4

The workflow is currently prompt-driven. The MiniMaxH3ImageToVideo node exists in the graph, but no external image input is connected in this baseline export.

That is intentional for now: first prove the original baseline pipeline end-to-end, then add a separate image-to-video workflow without disturbing this known-good graph.

5. Safe workflow parameters

Movie Factory should only modify a small, documented set of workflow inputs.

For the current exported API workflow, the relevant node mappings are:

Prompt        -> node 131 / inputs.prompt
Aspect ratio  -> node 115 / inputs.aspect_ratio
Megapixels    -> node 115 / inputs.megapixels
Duration      -> node 133 / inputs.value
Steps         -> node 137 / inputs.value
Seed          -> node 129 / inputs.noise_seed
FPS           -> node 130 / inputs.fps
Output prefix -> node 92  / inputs.filename_prefix

The orchestration layer should not arbitrarily rewrite node connections, model selection, sampler wiring, scheduler wiring, VAEs, or decoder internals during the first release.

6. Plan a movie with PydanticAI

The default director backend uses the local Ollama service.

Example .env values:

OLLAMA_BASE_URL=http://127.0.0.1:11434/v1
DIRECTOR_MODEL=ollama:qwen3.6:35b

Use whichever local model is actually installed and selected for director work.

Check available models:

ollama list

Test planning:

movie-factory plan \
  "Edmonton Championship Parade" \
  examples/treatment.txt \
  --id edmonton_parade

Expected output:

projects/edmonton_parade/project.yaml

Every generated shot starts with:

approved: false

Review the YAML and explicitly change only the shots you want rendered to:

approved: true

If you do not want the director model involved yet, copy:

examples/project-manual.yaml

and edit it manually.

7. Compile before rendering

Compile one concrete ComfyUI request without spending GPU time:

movie-factory compile \
  projects/edmonton_parade/project.yaml \
  --shot s01_001 \
  --output /tmp/s01_001.api.json

Inspect:

/tmp/s01_001.api.json

Before rendering, confirm that:

the workflow structure remains intact
only approved Movie Factory parameters changed
the model names still match the proven baseline
the sampler/scheduler wiring remains unchanged
the output filename is sane

8. Dry-run the approved project

movie-factory render \
  projects/edmonton_parade/project.yaml \
  --dry-run

The dry-run should compile every approved shot but submit nothing to ComfyUI.

Use this to verify project parsing, shot approval, parameter injection, and generated API payloads before spending GPU time.

9. Render

When the compiled graph is verified:

movie-factory render \
  projects/edmonton_parade/project.yaml

The intended execution path is:

project.yaml
    ↓
Movie Factory validation
    ↓
Prefect flow
    ↓
safe workflow parameter injection
    ↓
POST /prompt to ComfyUI :8188
    ↓
poll ComfyUI history
    ↓
SaveVideo output
    ↓
renders/

Movie Factory submits one shot at a time to the existing ComfyUI service.

For each completed prompt, it stores the ComfyUI history record under:

renders/

The first release intentionally keeps concurrency at one.

The RTX PRO 6000 has far more VRAM than a 12 GB 3060, but simultaneous H3 renders can still reduce throughput by competing for the same GPU compute resources. Benchmark first; parallelism comes later.

10. Profiles

The original README defined:

draft      : 704×384, 8 steps, ref_image_size=match
production : 1024×576, 8 steps, ref_image_size=match
hero       : 1024×576, 20 steps, ref_image_size=max

These profile definitions should now be treated as provisional until they are reconciled with the proven exported workflow.

The current known-good baseline is:

16:9
0.4 megapixels
20 steps
24 fps
5 seconds

Do not silently force profile values that materially change the known-good graph until the baseline render path has been verified.

All future profiles should continue to leave the actual working sampler, scheduler, model, LoRAs, VAEs, and decoder configuration in the exported ComfyUI workflow rather than guessing or rebuilding them in Python.

11. Planned image-to-movie path

A major near-term goal is an easy image-to-video command such as:

movie-factory render \
  --image ~/Pictures/scene.jpg \
  --prompt "Cinematic dusk, slow camera push-in, natural movement." \
  --duration 5

Do not bolt this onto the known-good baseline by dynamically rewiring the graph.

Instead, create and manually verify a second ComfyUI workflow with a real image input connected, then export it in API format, for example:

workflows/h3_i2v.api.json

Movie Factory can then:

upload or copy the source image into ComfyUI input handling
set the LoadImage filename
patch only safe documented inputs
submit the known-good image-to-video graph
collect the rendered video

Future image-related workflow variants may include:

h3_i2v.api.json
h3_ref2va.api.json
h3_fl2va_turbo.api.json

Keep each workflow separate and proven rather than constructing graphs dynamically.

12. OpenClaw

OpenClaw is optional.

The core architecture remains:

PydanticAI
    ↓
Prefect
    ↓
ComfyUI
    ↓
MiniMax H3

If OpenClaw is added later, it should sit above or beside the Movie Factory API/CLI as a convenient natural-language operator.

It should not replace Prefect or directly mutate arbitrary ComfyUI workflow JSON.

A safe future model is:

OpenClaw
    ↓
Movie Factory tool/API
    ↓
PydanticAI
    ↓
Prefect
    ↓
ComfyUI

13. What is deliberately not automated yet

The following remain outside the first verified baseline:

automatic model downloads
ComfyUI/custom-node upgrades
automatic checkpoint/LoRA switching
dynamic graph rewiring
image-to-video convenience path
REF2VA routing
Turbo workflow selection
Qwen-Image storyboard generation
SeedVR2 upscale pass
ACE-Step music generation
Whisper dialogue verification
visual/continuity QC
FFmpeg final edit/mux
multi-GPU or parallel H3 rendering

These are the next layer after the original README path works end-to-end:

plan
→ compile
→ dry-run
→ one real render

Troubleshooting

`does not appear to be a Python project`

A complete copy must contain:

pyproject.toml
src/movie_factory/cli.py

setup.sh checks for the project metadata before running pip.

If needed:

cd ~/movie-factory-blackwell
source .venv/bin/activate
python -m pip install -e .

`movie-factory: command not found`

Make sure the project virtual environment is active:

cd ~/movie-factory-blackwell
source .venv/bin/activate

Confirm:

echo "$VIRTUAL_ENV"
command -v movie-factory

Expected paths should be under:

/home/bruce/movie-factory-blackwell/.venv

If the CLI entry point is still missing:

python -m pip install -e .
hash -r

ComfyUI works in the browser but doctor fails

Confirm:

curl http://127.0.0.1:8188/system_stats

Then inspect:

COMFYUI_URL
COMFYUI_ROOT

in .env.

The current working values are:

COMFYUI_URL=http://127.0.0.1:8188
COMFYUI_ROOT=/home/bruce/comfy/ComfyUI

Find the actual running ComfyUI directory

Find the process:

pgrep -af 'ComfyUI|main.py'

Then inspect its current working directory:

readlink -f /proc/<PID>/cwd

For the current workstation this resolves to:

/home/bruce/comfy/ComfyUI

Verify API workflow node compatibility manually

Show unique workflow node classes:

jq -r '.[].class_type' \
  workflows/h3_fl2va.api.json \
  | sort -u

Compare them against live ComfyUI:

comm -23 \
  <(jq -r '.[].class_type' workflows/h3_fl2va.api.json | sort -u) \
  <(curl -s http://127.0.0.1:8188/object_info | jq -r 'keys[]' | sort -u)

If this command prints nothing, every workflow node type is available.

Plan cannot connect to Ollama

Check:

ollama list
curl http://127.0.0.1:11434/api/tags

If the chosen local model name differs, update:

DIRECTOR_MODEL