instamesh-docker

Docker wrapper around TencentARC/InstantMesh for single-image → 3D mesh generation. Patches upstream's docker setup to fix a couple of known build issues (missing onnxruntime, duplicate conda env create) and pins CUDA to 12.1 to match the InstantMesh PyTorch / xformers wheels.

Requirements

• NVIDIA GPU with CUDA 12.1 support and ≥ 12 GB VRAM (InstantMesh is not VRAM-friendly).
• Docker + the NVIDIA Container Toolkit (nvidia runtime exposed to compose).
• Disk: several GB for the conda env + model weights.
• Network egress on first build to pull miniconda, PyTorch wheels, and the nvdiffrast / InstantMesh dependencies (long build — 15+ minutes is normal).

Quick start

# Clone the upstream model repo into this directory (the Dockerfile
# COPYs it via the build context; not a git submodule). Operator-managed;
# not committed.
git clone https://github.com/TencentARC/InstantMesh.git

# Build and run
cd docker
docker compose build
docker compose up

# Gradio UI at http://localhost:43839

Project structure

instamesh-docker/
  InstantMesh/         # cloned upstream — operator-managed, not committed
  docker/
    Dockerfile         # patched build (CUDA 12.1, onnxruntime fix)
    compose.yml        # GPU compose, named volume for model cache
    requirements.txt   # Python deps installed inside the conda env
  README.md
  CLAUDE.md

Notes

• First run downloads model weights into the instantmesh-models named volume (mounted at /workspace/models). Several GB.
• The build uses miniconda inside the container with a python=3.10 env named instantmesh — not the host's Python. The repo-root pyproject.toml / uv.lock / .python-version are leftover uv scaffolding and are not part of the build path.
• See CLAUDE.md for the agent-facing gotchas: the patched bits, the intentional || true on the bulk requirements install, and the CUDA pin reasoning.