---
created: 2026-04-27
path: Sources/Homelab
project: hunyuan3d-sunnie-pipeline
status: active
tags:
- homelab
- docker
- ai-ml
- gpu
- blender
- pbs
- sunnie
type: project-plan
updated: 2026-04-27
---

# Hunyuan3D-2 + Sunnie Animation Pipeline

Self-hosted deployment of [Tencent Hunyuan3D-2](
https://github.com/Tencent-Hunyuan/Hunyuan3D-2) on the Manjaro tower (RTX
3080), feeding into a Blender pipeline to produce a dancing 3D version of
Sunnie for PBS content.

## Why Hunyuan3D-2 over InstantMesh

For stylized characters, open-source models (Hunyuan, Trellis) preserve
cartoon aesthetics better than commercial tools (Tripo, Meshy) that
over-detail. Hunyuan3D-2 also outputs PBR textures (not just vertex
colors), which matters once Sunnie hits Blender for re-lighting.
InstantMesh stays in flight as a comparison data point.

## Stack

- **Host:** Manjaro tower (i7 / 128GB / RTX 3080, 10GB VRAM)
- **Runtime:** Docker + NVIDIA Container Toolkit
- **Model variant:** `Hunyuan3D-2mini` with `hunyuan3d-dit-v2-mini-turbo`
subfolder (10GB VRAM-friendly)
- **Required flags:** `--low_vram_mode --enable_flashvdm`
- **UI:** Gradio on `:8080`
- **Downstream:** Blender 4.x, Mixamo for auto-rig + dance animations

## VRAM reality check

The full `Hunyuan3D-2` model wants more than 10GB. The `mini-turbo` variant
+ low-VRAM flags is the target config for the 3080. If quality is
unacceptable, fallbacks: rent an A100/4090 hour on RunPod for final-quality
renders, or move workload to a future GPU upgrade.

## Known issues

- No official Tencent Docker image — community Dockerfiles only (referenced
in repo issues #125, #122)
- First-run model download is large (multiple GB across HuggingFace repos)
— persist to host volume
- Hunyuan3D-2.1 exists with better PBR but Docker support is rougher;
deferring until 2.0 baseline works

## Phase 1 — Deploy Hunyuan3D-2

- [ ] Verify NVIDIA Container Toolkit: `docker run --rm --gpus all
nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi`
- [ ] Clone repo: `git clone
https://github.com/Tencent-Hunyuan/Hunyuan3D-2.git ~/projects/hunyuan3d-2`
- [ ] Write Dockerfile (community-style, base
`nvidia/cuda:12.4.0-devel-ubuntu22.04`)
- [ ] Build image: `docker compose build`
- [ ] Create model cache dir: `mkdir -p ~/hunyuan3d-models`
- [ ] First run: `docker compose up` — weights download to mounted volume
- [ ] Verify Gradio UI at `http://localhost:8080`
- [ ] Smoke test with sample image, save `.glb` output

## Phase 2 — Sunnie mesh generation

- [ ] Prepare Sunnie reference image (front-facing, transparent or white
background, clean lines)
- [ ] Generate mesh via Gradio UI
- [ ] Export as `.glb` or `.obj` with PBR textures
- [ ] Iterate prompt/source image until mesh is acceptable

## Phase 3 — Blender cleanup

- [ ] Import mesh into Blender 4.x
- [ ] Inspect topology — likely needs decimate or retopo for clean rig
deformation
- [ ] Verify UV maps and PBR material assignment
- [ ] Pose into T-pose if not already (Mixamo requirement)
- [ ] Export as `.fbx` for Mixamo upload

## Phase 4 — Rig + animate via Mixamo

- [ ] Upload `.fbx` to Mixamo, place rigging markers
- [ ] Verify auto-rig deformation
- [ ] Pick dance animation from Mixamo library
- [ ] Download rigged `.fbx` with skin + animation
- [ ] Re-import to Blender, verify playback

## Phase 5 — Final render

- [ ] Set up Blender scene (lighting, camera, background)
- [ ] Render dance sequence (Cycles or Eevee depending on quality target)
- [ ] Export video for PBS use

## docker-compose.yml (starting point)

yaml
services:
  hunyuan3d:
    build:
      context: ./Hunyuan3D-2
      dockerfile: Dockerfile
    image: hunyuan3d-2:local
    container_name: hunyuan3d
    ports:
      - "8080:8080"
    volumes:
      - ~/hunyuan3d-models:/root/.cache/hy3dgen
      - ./outputs:/workspace/outputs
    command: >
      python3 gradio_app.py
      --model_path tencent/Hunyuan3D-2mini
      --subfolder hunyuan3d-dit-v2-mini-turbo
      --texgen_model_path tencent/Hunyuan3D-2
      --low_vram_mode
      --enable_flashvdm
      --host 0.0.0.0
      --port 8080
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    restart: unless-stopped


## Open questions

- [ ] If `mini-turbo` quality is insufficient for Sunnie, escalate to
Hunyuan3D-2.1 (more VRAM-hungry, rougher Docker) or RunPod cloud GPU?
- [ ] Reverse-proxy through Traefik on `*.lab.herbylab.dev`, or keep
local-only?
- [ ] Worth integrating with InstantMesh deploy for side-by-side mesh
comparison?
- [ ] Long-term: candidate tool for OpenClaw to call as a 3D-gen capability?

## References

- Hunyuan3D-2 repo: https://github.com/Tencent-Hunyuan/Hunyuan3D-2
- Hunyuan3D-2.1 (newer, PBR-focused):
https://github.com/Tencent-Hunyuan/Hunyuan3D-2.1
- Docker discussion:
https://github.com/Tencent-Hunyuan/Hunyuan3D-2/issues/125
- Mixamo: https://www.mixamo.com
- Companion project: `instantmesh-docker`


...sent from Jenny & Travis