# instamesh-docker

Docker wrapper around [TencentARC/InstantMesh](https://github.com/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

```bash
# 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.