trellis2-asset-skill

Trellis Asset Agent

An agent-facing wrapper for generating 3D assets through a local ComfyUI-Trellis2 runtime.

This repo does not reimplement TRELLIS. It gives agents a deterministic CLI and skill instructions for:

• taking an existing or generated image
• choosing a low-poly or high-quality Trellis workflow
• submitting the job to ComfyUI
• copying exported GLB files to a requested output directory
• writing a run manifest

Prerequisites

Before using this tool, you need:

1. Python 3.11+ with pip
2. git (for runtime mode)
3. NVIDIA GPU with CUDA (tested on RTX 5070 12GB)
4. HuggingFace access to the gated DINOv3 model:
   • Visit https://huggingface.co/facebook/dinov3-vitl16-pretrain-lvd1689m
   • Accept the license/terms on the model card
   • This is required for Trellis2 to function

The installer handles the rest: ComfyUI, ComfyUI-Trellis2, custom CUDA wheels, and model downloads.

Quick Start

Option A: Agent-First Install (recommended)

Copy this message into Codex, Claude Code, Gemini CLI, or another local coding agent:

Please install and configure Trellis Asset Agent for this machine.

Repo: https://github.com/YOUR_GITHUB_USERNAME/trellis-asset-agent

Prerequisites: I have a HuggingFace account and have accepted the terms at
https://huggingface.co/facebook/dinov3-vitl16-pretrain-lvd1689m

Tasks:
1. Clone the repo.
2. Run the installer: .\scripts\install.ps1 -Mode runtime -InstallSkill
3. If the installer asks about DINOv3 download, say yes.
4. Run verification: .\scripts\verify.ps1
5. Start the runtime: .\scripts\start-runtime.ps1
6. Test with the example image:
   python scripts\trellis_asset.py run --image example\fighter-jet.png --quality low --output-dir output\test --name fighter_jet --dry-run
7. Tell me the exact command to generate a high-quality GLB from any image.

If you already have ComfyUI-Trellis2 installed:

1. Clone the repo.
2. Run: .\scripts\install.ps1 -Mode existing -ComfyRoot C:\path\ComfyUI -InstallSkill
3. Run: .\scripts\verify.ps1

After the repo is published, replace YOUR_GITHUB_USERNAME with the actual GitHub owner.

Option B: Manual Install

# Clone
git clone https://github.com/YOUR_GITHUB_USERNAME/trellis-asset-agent.git
cd trellis-asset-agent

# Install (interactive - will ask which mode)
.\scripts\install.ps1

# Or explicit:
.\scripts\install.ps1 -Mode runtime
.\scripts\install.ps1 -Mode existing -ComfyRoot C:\path\ComfyUI

The runtime mode installer will:

1. Clone ComfyUI and ComfyUI-Trellis2 into .runtime/
2. Create a Python virtual environment
3. Install PyTorch (CUDA 12.8), ComfyUI, and Trellis2 dependencies
4. Detect your Python + Torch version and install matching custom CUDA wheels (cumesh, flex_gemm, nvdiffrast, etc.)
5. Prompt you to download the gated DINOv3 model (requires HuggingFace login and accepted terms)
6. Write local config to .trellis-asset-agent/config.json

Verify

.\scripts\verify.ps1

Install the Agent Skill

The skill tells future agents where your repo, ComfyUI, and workflows live:

.\scripts\install-skill.ps1 -Target codex -Force
.\scripts\install-skill.ps1 -Target agents -Force
.\scripts\install-skill.ps1 -Target custom -TargetRoot C:\path\skills -Force

Or do it in one step with the installer:

.\scripts\install.ps1 -Mode runtime -InstallSkill

Generate an Asset

ComfyUI must be running before submitting a job.

# Start ComfyUI (runtime mode)
.\scripts\start-runtime.ps1

# Or for existing install, start your ComfyUI normally

# Quick test with the bundled example
python scripts\trellis_asset.py run `
  --image example\fighter-jet.png `
  --quality low `
  --output-dir output\test `
  --name fighter_jet_test

# High-quality generation
python scripts\trellis_asset.py run `
  --image C:\path\source.png `
  --quality high `
  --output-dir C:\path\exports `
  --name tavern_01

Options

• --quality low|high|custom
• --workflow C:\path\workflow.json (for custom quality)
• --output-dir C:\path\exports (required)
• --name asset_name
• --comfy-url http://127.0.0.1:8188
• --transparent-policy black|preserve
• --remove-background / --no-remove-background
• --timeout-minutes 45
• --seed 12345
• --padding 64
• --max-size 1024
• --dry-run (validate inputs and print the ComfyUI prompt without queueing)

Image Guidance

For best results, use source images with:

• pitch-black background
• one centered object
• full object visible
• clean silhouette
• generous padding
• no floor plane, cast shadow, watermark, text, or extra props

Background removal is on by default. Transparent PNGs are composited onto black by default before submission; use --no-remove-background when you intentionally generated a clean black-background source image.

Example

Input image to generated 3D asset, using the bundled fighter jet example:

The example/fighter-jet.png source image is included for testing:

# Validate without running
python scripts\trellis_asset.py run `
  --image example\fighter-jet.png `
  --quality high `
  --output-dir output\example `
  --name fighter_jet `
  --dry-run

# Actually generate (requires running ComfyUI)
python scripts\trellis_asset.py run `
  --image example\fighter-jet.png `
  --quality low `
  --output-dir output\example `
  --name fighter_jet

Workflows

Bundled workflow templates:

• workflows/low_poly.json: quick draft and lower-poly outputs.
• workflows/high_quality.json: high-quality mesh plus high-quality texturing defaults.
• workflows/multi_view.json: reserved for future multiview/video-derived inputs.

Default model/runtime settings target a 12GB NVIDIA CUDA setup:

• visualbruno/TRELLIS.2-4B-FP8
• sdpa
• low_vram=true
• keep_models_loaded=false
• flex_gemm
• flash_attn sparse backend
• padding 64
• max input size 1024
• remove background enabled by default

Local Files

The following are intentionally not committed:

• .runtime/
• .trellis-asset-agent/
• model weights
• outputs
• logs
• virtual environments

License and Upstream Terms

This repo is a wrapper/tooling layer. It does not include ComfyUI, ComfyUI-Trellis2, TRELLIS model weights, DINOv3 model weights, or generated model outputs.

You are responsible for reviewing upstream licenses and model terms before commercial use. See docs/ACKNOWLEDGEMENTS.md.