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

Self-hosted deployment of [TencentARC/InstantMesh](
https://github.com/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