Travis Herbranson 5cff79d211 docs: add CLAUDE.md + initial README

Repo had a 0-byte README and no CLAUDE.md.

README: requirements (NVIDIA GPU + CUDA 12.1 + ≥12GB VRAM), build/run
quickstart, project structure, callout that the root-level uv
scaffolding is not part of the build path.

CLAUDE.md captures the three upstream patches that are deliberately
applied (CUDA 12.1 pin, dedup'd conda create, onnxruntime fix for
upstream issue #175), the intentional `|| true` on bulk pip install
(nvdiffrast needs --no-build-isolation), build performance gotchas,
and the absence of an outputs bind mount.

Untracked .python-version / InstantMesh/ / uv.lock left out of this commit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-20 07:22:25 -04:00

2.0 KiB

Raw Blame History

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.