# Claude notes — instamesh-docker

Agent context for this repo. Read before non-trivial changes.

## What this is

Docker wrapper around upstream [TencentARC/InstantMesh](https://github.com/TencentARC/InstantMesh)
for single-image → 3D mesh generation. **Not** a fork of InstantMesh
itself — this repo owns the docker build + compose plus a small set of
patches that fix known upstream build breakage.

## Repo shape

```
instamesh-docker/
  InstantMesh/          # UNTRACKED — upstream clone. Operators run
                        # `git clone https://github.com/TencentARC/InstantMesh.git`
                        # once before `docker compose build`. Not a submodule.
  docker/
    Dockerfile          # patched (see "Patches applied" below)
    compose.yml         # GPU compose, named volume for model cache, port 43839
    requirements.txt    # InstantMesh's pip deps, kept here so the Dockerfile
                        # can ADD them without changing the upstream tree
  main.py, pyproject.toml, uv.lock, .python-version
                        # leftover uv scaffolding from initial repo init;
                        # NOT part of the build path. Don't extend these.
  README.md
  CLAUDE.md
```

`InstantMesh/` is intentionally untracked. Don't add it as a submodule
or vendor it into source control — keep the upstream boundary clean.

## Patches applied (vs. upstream)

The Dockerfile is forked from InstantMesh's docker config with three
deliberate changes — call out any churn around these:

1. **CUDA aligned to 12.1.** Base image is
   `nvidia/cuda:12.1.0-runtime-ubuntu22.04`; conda installs `cuda` from
   `nvidia/label/cuda-12.1.0`; pip installs `torch==2.1.0 + cu121` and
   `xformers==0.0.22.post7`. All four must stay in sync. Don't bump CUDA
   without re-pinning all of them.
2. **Duplicate `conda create` removed.** Upstream's Dockerfile created
   the conda env twice; the second one nuked the first's pinned
   packages. Don't reintroduce.
3. **`onnxruntime` added.** Missing from upstream's `requirements.txt`
   (InstantMesh issue #175). Installed as a separate `pip install` step
   after the bulk requirements install so it's not silently dropped by
   the `|| true` below.

## Intentional `|| true` on the bulk pip install

```dockerfile
RUN pip install --no-cache-dir -r requirements.txt || true
```

This is **on purpose**. The requirements include `nvdiffrast` via a git
URL that needs `--no-build-isolation`, which pip's bulk install won't
do. We let that line fail, then install `nvdiffrast` correctly:

```dockerfile
RUN pip install git+https://github.com/NVlabs/nvdiffrast.git --no-build-isolation
```

Don't "fix" the bulk install by removing `|| true` — the build will
hard-fail on nvdiffrast.

## Hardware contract

- **NVIDIA GPU required**, exposed through Docker via the nvidia
  runtime. InstantMesh wants **≥ 12 GB VRAM** comfortably; smaller cards
  may OOM during inference.
- **CUDA 12.1** — see patch #1 above.

## Build is slow + brittle

Expect a 15+ minute first build. Conda + nvdiffrast compilation +
PyTorch wheels add up. Triggers that re-run the slow layers:
- Editing `docker/requirements.txt` invalidates the conda install layer.
- Editing the Dockerfile's `apt-get install` line redoes the whole
  thing from a fresh base image.

Lean on Docker's layer cache; don't restructure for "cleanliness"
without measuring the rebuild cost.

## Compose

```yaml
ports:
  - "43839:43839"      # Gradio app, host-published
volumes:
  - instantmesh-models:/workspace/models   # weights cache (named volume)
```

No host-network mode, no bind mounts for code (the upstream tree is
COPYed at build time). If you need to iterate on InstantMesh source,
edit `InstantMesh/` locally and rebuild — there's no dev-mode wiring.

## Where outputs go

InstantMesh's Gradio app writes generated meshes inside the container
(under `/workspace/instantmesh/`). There's **no bind mount** for
outputs in `compose.yml` — operator downloads results from the Gradio
UI. If you find yourself wanting to bind-mount an outputs dir, mirror
`hunyuan3d-sunnie/docker/outputs/`.

## Don't-touch zones

- The CUDA 12.1 pins (base image / conda label / PyTorch wheel index /
  xformers wheel) — load-bearing as a set.
- The `|| true` on bulk requirements install — required for nvdiffrast.
- The `onnxruntime` separate install line — load-bearing per upstream #175.
- The untracked `InstantMesh/` directory — let operators reclone.

## Bigger picture

Personal/one-off project, GPU-only. Runs on the dev tower; not part of
the homelab production stack. Sibling project `hunyuan3d-sunnie/` uses
a different model (Hunyuan3D-2) for the same general shape of problem
on a 10 GB card — pick that one if VRAM is tight.