pbs-projects/Tech/Projects/instantmesh-docker.md

project	type	status	path	tags	created	updated
instantmesh-docker	project-plan	active	Tech/Projects	homelab docker ai-ml gpu	2026-04-27	2026-04-27

InstantMesh Docker Deployment

Self-hosted deployment of TencentARC/InstantMesh on the Manjaro tower (RTX 3080) for single-image to 3D mesh generation. Gradio UI exposed on port 43839.

Goals

• Run InstantMesh locally via Docker Compose on the Manjaro tower
• Persist downloaded model weights outside the container (re-pulls are slow)
• Build from official repo source, patch the known onnxruntime issue from upstream

Stack

• Host: Manjaro tower (i7 / 128GB / RTX 3080, 10GB VRAM)
• Runtime: Docker + NVIDIA Container Toolkit
• Base image: Built from TencentARC/InstantMesh/docker/Dockerfile
• UI: Gradio on :43839
• Model variant: instant-mesh-large (default, fits in 10GB VRAM)

Known issue

Upstream Dockerfile has a missing dep — container fails at runtime with ModuleNotFoundError: No module named 'onnxruntime' (issue #175). Fix is to add onnxruntime to the pip install step in the Dockerfile before building, or install it post-build.

Setup steps

• Verify NVIDIA Container Toolkit is functional: docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi
• Clone repo: git clone https://github.com/TencentARC/InstantMesh.git ~/projects/instantmesh
• Patch Dockerfile to add onnxruntime to pip install
• Build image: docker compose build
• Create model dir: mkdir -p ~/instantmesh-models
• First run: docker compose up — model weights download on first launch (~10GB)
• Verify Gradio UI at http://localhost:43839
• Test inference with sample image

docker-compose.yml

yaml services: instantmesh: build: context: ./InstantMesh dockerfile: docker/Dockerfile image: instantmesh:local container_name: instantmesh ports: - "43839:43839" volumes: - ~/instantmesh-models:/workspace/instantmesh/models deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] restart: unless-stopped

Open questions

• Reverse proxy through Traefik on *.lab.herbylab.dev, or keep local-only?
• Worth wiring into OpenClaw later as a callable 3D-gen tool?

References

• Repo: https://github.com/TencentARC/InstantMesh
• Docker dir: https://github.com/TencentARC/InstantMesh/tree/main/docker
• onnxruntime issue: https://github.com/TencentARC/InstantMesh/issues/175
• Community fix PR: https://github.com/TencentARC/InstantMesh/pull/181

...sent from Jenny & Travis