modelbeast/HARDWARE.md

# MODELBEAST hardware guide — what runs on which Mac

Which Apple Silicon Mac can run which operator, by **unified memory (RAM)**. Numbers below are *measured on the M3 Ultra* unless marked *(est.)*; peak = peak unified memory during a run.

## How to read this

- **Unified memory is the gate.** CPU and GPU share one pool. A model's *peak* must fit in `RAM − ~3-5GB` (macOS + apps). For comfort without swapping, want peak **+ 8-12GB** headroom. Swapping = usable but slow.
- **Chip tier = speed, not fit.** An M1 Max 64GB *runs* the same models as an M3 Max 64GB, just slower. Rough per-generation speed: **Ultra > Max > Pro > base**, and **M5 > M4 > M3 > M2 > M1** per core. Our M1 Ultra runs the 3D stack at ~2× the M3 Ultra's time — fine for throughput, not for latency.
- **`net` operators run on *any* Mac** — an 8GB M1 mini is a perfectly good node for `fal_*` / `openrouter_image`, because the compute is in the cloud. Same for light `cpu` ops.
- **bf16 caveat (M1/M2):** M1 (and to a lesser extent M2) lack full hardware bf16. `trellis_mac` (torch-MPS, bf16) is **unverified on M1/M2 — treat as M3+**. `hunyuan3d_mlx` is fp16 MLX and runs fine on every Apple Silicon Mac with the RAM.
- **You can push the GPU memory ceiling** with `sudo sysctl iogpu.wired_limit_mb=<MB>` (e.g. raise a 128GB box's GPU cap toward ~120GB). Helps the largest models on Ultra/Max.

## Per-operator memory (sorted light → heavy)

| Operator | Lane | Weights | Peak RAM | Min Mac | Recommended | Notes |
|---|---|---|---|---|---|---|
| `fal_*`, `openrouter_image` | net | 0 | ~0 | **8 GB** | 8 GB | cloud compute; RAM irrelevant |
| `ffprobe` | cpu | 0 | <1 GB | 8 GB | 8 GB | trivial |
| `ffmpeg_frames` | cpu | 0 | <1 GB | 8 GB | 8 GB | frame extraction |
| `blender_convert` | cpu | 0 | 1–4 GB *(est.)* | 8 GB | 16 GB | needs Blender installed |
| `colmap_poses` | cpu | 0 | 2–8 GB *(scales w/ #images)* | 8 GB | 16 GB | needs COLMAP+GLOMAP |
| `bg_remove_local` (RMBG-2.0) | gpu | 0.8 GB | ~3 GB *(est.)* | **8 GB** | 16 GB | light; great first-step everywhere |
| `sf3d` | gpu | 3.7 GB | **~9 GB** | 16 GB | 24 GB | ~5s draft mesh |
| `seedvr2_upscale` | gpu | 6.8 GB | ~8–12 GB *(est.)* | 16 GB | 24 GB | image upscale |
| `hunyuan3d_mlx` INT4/INT8 *(self-convert)* | gpu | 1.6–3 GB | ~4–10 GB | **16 GB** | 16–24 GB | fits small Macs; see [Hunyuan guide](vendor/hunyuan3d-mlx/HARDWARE.md) |
| `flux_local` Klein 4B *(default)* | gpu | 15 GB | **18.0 GB** | 24 GB | 32 GB | 9s image, the volume workhorse |
| `flux_local` schnell-4bit | gpu | 8.9 GB | **19.1 GB** | 24 GB | 32 GB | fast FLUX.1 draft |
| `hunyuan3d_mlx` fp16 *(our default, 4096/120k)* | gpu | 13 GB | **20.2 GB** | 24 GB *(tight)* | 32 GB | Stage 1 alone ~10 GB; both stages ~20 GB |
| `trellis_mac` | gpu | 14 GB | ~15–18 GB | 24 GB | 32 GB | **M3+ (bf16)**; SOTA local mesh |
| `flux_local` FLUX.1 dev | gpu | 31 GB | **25.1 GB** | 32 GB | 48 GB | cinematic, ~2 min |
| `flux_local` Klein 9B | gpu | 32 GB | **28.4 GB** | 36 GB | 48 GB | best object accuracy in the lineup |
| `mflux_image_edit` (Qwen-Image-Edit) | gpu | 54 GB | ~30–40 GB *(est.)* | 48 GB | **64 GB+** | the heavyweight local editor |
| `brush_train` (3DGS) | gpu | 0 | scales w/ scene | 16 GB | 32 GB | Gaussian-splat training |

## What each Mac can do, by RAM

| RAM | Realistic role | Runs |
|---|---|---|
| **8 GB** (M1/M2/M3 base) | cloud + light node | all `net` ops, `ffmpeg`/`ffprobe`, `bg_remove_local`, a 3–4B Ollama LLM. *That's a genuinely useful fleet node.* |
| **16 GB** (base/Pro) | light local gen | above + `sf3d`, `seedvr2_upscale`, `colmap`, Hunyuan **INT4/INT8**, 7–8B Ollama. FLUX/fp16-Hunyuan/trellis won't fit. |
| **24 GB** (M2/M3 base, M4 Pro) | entry real-gen | above + `flux_local` **Klein 4B**, `hunyuan3d_mlx` fp16 *(tight)*, `trellis_mac` *(M3/M4 only)*. The practical floor for the full local 3D + image stack. |
| **32 GB** (Pro/Max) | comfortable all-round | the whole core stack with headroom: Klein 4B, hunyuan fp16 4096, trellis, FLUX dev. |
| **36–48 GB** (Max) | hero-tier images | + FLUX.1 **dev**, FLUX.2 **Klein 9B** (the accuracy king). |
| **64 GB** (Max/Ultra) | everything but the giant | + `mflux_image_edit` (Qwen 54 GB) comfortably; run two mid models resident. |
| **96–128 GB** (Ultra) | multi-model resident | several big models loaded at once; our **M1 Ultra 128 GB** tier — runs it all (mind the bf16 caveat for trellis). |
| **192–256 GB+** (Ultra) | the flex | every operator + a big local LLM (70B–235B) resident alongside — our **M3 Ultra 256 GB** primary. |

## Our fleet, mapped

| Node | RAM | Tier | What it serves |
|---|---|---|---|
| **M3 Ultra** | 256 GB | the flex | everything + primary/queue |
| **M1 Ultra** | 128 GB | multi-model | `hunyuan3d_mlx` (MLX-native), FLUX, sf3d, RMBG, cpu ops — *not* trellis (bf16 unverified) |
| **M4 Pro** | 24 GB | light helper | `bg_remove_local`, `ffmpeg_frames`/`ffprobe`, Ollama 7B — too small for the 18–28 GB gen models |

## Buying / sizing rules of thumb

- **Cheapest useful node:** any **8 GB** Apple Silicon → cloud + ffmpeg + background-removal + small LLM.
- **Cheapest *real* local-gen box:** **24 GB** (M4 Pro mini / M2-M3 24 GB) → Klein 4B images + local 3D.
- **Sweet spot for one do-everything machine:** **32–48 GB M-series Max** → the entire core stack, hero images, both local 3D models, comfortably.
- **Want Qwen image-edit or multiple big models resident:** **64 GB+**.
- **M1 owners:** prefer `hunyuan3d_mlx` over `trellis_mac` for local 3D (bf16). Everything MLX (FLUX via mflux, hunyuan) is first-class on M1.

*Fleet policy + queue routing: [CLUSTER.md](CLUSTER.md). Measured benchmarks: [BENCHMARKS.md](BENCHMARKS.md). Hunyuan-specific RAM tiers: [vendor/hunyuan3d-mlx/HARDWARE.md](vendor/hunyuan3d-mlx/HARDWARE.md).*