Important: The Wrapper Is Not the Upstream Project
Microsoft maintains TRELLIS.2. ComfyUI integrations are community projects with their own code, release cadence, installation steps, wheels, and security posture. They are not automatically reviewed or supported by Microsoft, ComfyUI, or trellis-2.com.
Do not paste old TRELLIS commands into a TRELLIS.2 environment. The model names, packages, setup flags, and output pipeline differ.
What the Official Repository Currently States
The official TRELLIS.2 README documents:
- A 4B image-to-3D model using O-Voxel
- Published 512³, 1024³, and 1536³ modes with PBR materials
- Code verification on NVIDIA A100 and H100 GPUs
- Conda as the recommended environment manager
- Python 3.8 or later
- CUDA tooling for packages compiled during setup
- A default environment based on PyTorch 2.6.0 and CUDA 12.4
flash-attnby default, with anxformersalternative for unsupported GPUs
These requirements can change. Read the current upstream README and setup.sh --help at the commit you plan to install.
Microsoft's H100 timing table is a model benchmark on stated hardware, not evidence that a particular consumer GPU, operating system, or community node will fit memory or achieve the same speed.
Decide Whether Local Setup Is Appropriate
Local operation can improve code/data control and remove a per-job hosted credit, but it adds:
- GPU and storage capacity planning
- Dependency and CUDA compatibility work
- Model-download provenance checks
- Security review of custom nodes and binary wheels
- Monitoring, upgrades, backups, and incident response
- Electricity and operator time
If you only need to evaluate one image, a hosted 512 job is usually a smaller operational test. If you need sustained volume or internal integration, benchmark self-hosting with the real workload.
Safe Installation Order
1. Validate the official pipeline first
Clone the official repository recursively and use the setup command from its current README. As of this review, Microsoft documents a new Conda environment with the basic runtime and the packages needed for attention, rendering, mesh processing, O-Voxel, and sparse convolution.
Do not rely on a copied one-line command indefinitely. Pin the Git commit and record:
- Operating system and driver
- CUDA toolkit and
CUDA_HOME - Python, PyTorch, and attention backend
- TRELLIS.2 commit
- Model repository and revision
- Successful resolution and peak memory
Run the official example before adding ComfyUI. This separates an upstream compatibility problem from a wrapper problem.
2. Review the ComfyUI wrapper
For any community wrapper, inspect:
- Repository owner, recent commits, issues, and release tags
- Installation scripts and every downloaded binary wheel
- Exact TRELLIS.2 commit or model revision it expects
- Supported ComfyUI frontend/backend versions
- Whether nodes execute shell commands or open network listeners
- Where images, models, and outputs are stored
- License compatibility
Examples of community work can be found through the ComfyUI registry or repositories such as visualbruno/ComfyUI-Trellis2. A link is not an endorsement; review the current project before installing.
Use a dedicated environment and never expose production API keys, payment secrets, or unrelated model credentials to a custom-node process.
3. Verify model weights
Follow the model link from Microsoft's repository, pin a revision, and record file hashes when deploying to more than one machine. Avoid re-uploaded archives whose source cannot be traced to the official project or model publisher.
4. Build the smallest workflow
A minimal conceptual graph is:
load image
→ preprocess image/mask
→ load official TRELLIS.2 components
→ image-to-shape at one resolution
→ shape-to-textured mesh
→ export GLB
→ inspect resultNode names and parameters depend on the wrapper version. Import a workflow only from a source you trust, then inspect every node before running it.
First Validation Run
- Use a small, non-sensitive image with one clear object.
- Start at the lowest supported resolution.
- Record runtime, peak GPU memory, host memory, and output path.
- Inspect the GLB from every side and verify material channels.
- Restart the process and repeat to expose initialization or cache assumptions.
- Test a controlled failure and confirm temporary files and GPU memory are released.
Do not call the setup production-ready after one successful sample.
Troubleshooting by Layer
CUDA or compiled-extension failure
Check driver/toolkit compatibility, CUDA_HOME, compiler output, and the exact package that failed. Use the official setup help instead of mixing wheels from another CUDA/Python combination.
Attention backend failure
The official README notes flash-attn as the default and xformers as an alternative for unsupported GPUs. Follow the current upstream instructions; do not install both randomly or claim a speed multiplier without measuring the exact environment.
Out-of-memory failure
Confirm the resolution and whether multiple model components remain loaded. Close unrelated GPU processes and capture peak allocation. A wrapper's “low VRAM” option is wrapper-specific and does not guarantee success.
Missing or incompatible nodes
Pin compatible ComfyUI and wrapper commits. Review the wrapper's issue tracker and migration notes. Updating ComfyUI, custom nodes, PyTorch, and CUDA simultaneously makes the cause harder to isolate.
Output differs from the hosted site
Compare model revision, resolution, preprocessing, random seed, texture settings, remesh/decimation, and export path. A community workflow and a hosted provider may not expose identical defaults.
Production Checklist
- Official pipeline passes on the pinned environment.
- Wrapper code and binary sources have been reviewed.
- Model revision and hashes are recorded.
- Sensitive inputs and outputs have a retention/deletion policy.
- The service is isolated from unrelated secrets and networks.
- Timeouts, concurrency, disk limits, and GPU recovery are tested.
- Failed jobs do not leave unlimited temporary files or locked GPU memory.
- Output acceptance and human-review criteria are documented.
- License and input rights have been reviewed.
- Upgrade and rollback steps are rehearsed.
When to Use the Hosted Workflow
Use the hosted generator when you want to validate the image-to-GLB result without taking responsibility for the GPU stack. Use local TRELLIS.2 when operational control or sustained usage justifies the setup and maintenance burden.