modly README

The project's README from github.com/lightningpixel/modly. As one markdown file: README.md.

Modly logo

Modly

Local, open source, AI-powered image-to-3D mesh generation. Turn any photo into a 3D model using open source AI models running entirely on your GPU. Modly is a desktop application for Windows, Linux, and Apple Silicon macOS.

Created by Lightning Pixel

Modly screenshot

Download

Head to the Releases page to download the latest installer for Windows, Linux, or Apple Silicon macOS.

Alternatively, you can clone the repository and run the app directly without installing:

# Windows
launch.bat

# Linux / macOS
./launch.sh

Getting started

1. Install JS dependencies

npm install

2. Set up Python backend

cd api
python -m venv .venv
.venv\Scripts\activate     # Windows
source .venv/bin/activate  # Linux / macOS
pip install -r requirements.txt

3. Run in development

npm run dev

4. Test

npm test
./node_modules/.bin/tsc --noEmit -p tsconfig.node.json
npm run build

Platform notes

Extension system

Modly supports external model and process extensions. Each extension is a GitHub repository containing a manifest.json plus the runtime entry files required by its type.

Official extensions

Extension Model URL
modly-hunyuan3d-mini-extension Hunyuan3D 2 Mini https://github.com/lightningpixel/modly-hunyuan3d-mini-extension
modly-hunyuan3d-mini-turbo-extension Hunyuan3D 2 Mini Turbo https://github.com/lightningpixel/modly-hunyuan3d-mini-turbo-extension
modly-hunyuan3d-mini-fast-extension Hunyuan3D 2 Mini Fast https://github.com/lightningpixel/modly-hunyuan3d-mini-fast-extension
modly-triposg-extension TripoSG https://github.com/lightningpixel/modly-triposg-extension
modly-trellis2-gguf-extension Trellis2 GGUF https://github.com/lightningpixel/modly-trellis2-gguf-extension

How to install an extension

1. Go to the Models page and click Install from GitHub.

Install from GitHub

2. Enter the HTTPS URL of the extension repository and confirm.

Enter extension URL

3. If the extension exposes model nodes, download the model or one of its variants. Process extensions are ready once installation and setup complete.

Install models

Workflows

Start with a basic workflow first. For example, on the "Workflows" tab, try: Image -> Generate Mesh -> Add to Scene. Make sure there is a connection between each of the steps. Go to the "Generate" tab, make sure the workflow is selected, then click on "Generate 3D Model". Click on "Settings/Logs/Errors" to see any issues.

Modly CLI

Agents and scripts can call a running Modly desktop app without using the UI via the stdlib-only CLI. The CLI is a thin helper over Modly's canonical automation concepts and keeps final machine-readable JSON on stdout:

python tools/modly-cli/agent.py health
python tools/modly-cli/agent.py model list
python tools/modly-cli/agent.py workflow-run status <run_id>
python tools/modly-cli/agent.py generate --image ./input.png --output ./export.glb

Canonical commands are health, model, workflow-run, capability, and process-run. The friendly generate command starts POST /workflow-runs/from-image, polls the returned run, exports the final mesh when requested, and includes recovery metadata such as workflow-run status ... and workflow-run cancel ... in the JSON response.

Compatibility and helper surfaces are intentionally separated: legacy wraps old /generate/* job endpoints, dev serve-api / dev ensure-server start only the FastAPI backend and do not prove Electron/Desktop bridge readiness, and experimental comfy-image / experimental generate-from-workflow are external ComfyUI orchestration helpers rather than the canonical Modly agent contract. Hidden helper aliases such as status, export, and batch remain parseable for scripts, but they are not presented as canonical root commands.

experimental generate-from-workflow --workflow <name> --output <path> treats --output as the final artifact location. When the ComfyUI workflow produces a downloadable 3D asset, the CLI downloads it directly; image-only workflows remain a compatibility path through Modly image-to-3D generation.

See tools/modly-cli/SKILL.md for the agent workflow and output contract.

Community

Join the Discord server to stay up to date with the latest news, report bugs, and share feedback.

Sponsors

Thanks to our early sponsors for believing in Modly and helping make local AI 3D generation more accessible.

DrHepa
DrHepa    benjapenjamin
benjapenjamin    iammojogo-sudo
iammojogo-sudo

License

MIT License — see LICENSE for details.

If you fork this project and build your own app from it, you must credit the original project and its creator:

Based on Modly by Lightning Pixel

This is a requirement of the MIT license attribution clause. Please keep this credit visible in your app's UI or documentation.

modly (lightningpixel/modly)

Searching Database…

8.2K ·GitHub
Modly
What is this?Modly is a desktop app that turns a photo (or a text prompt) into a 3D mesh using open source AI models, running entirely on your own GPU with no cloud calls.
Is this a standalone app or a library I'd embed in my own project?It is a standalone Electron desktop application built with React and Three.js, not a library; it also ships a separate stdlib-only CLI for scripting it.
How do I get it running?Download the installer for your platform from the Releases page, or clone the repository, install the JS dependencies, set up the Python backend, and run it in development mode.
Do I need a specific GPU or any extra runtime to use it?Yes, generation runs entirely on your local GPU, and the app bundles a Python backend alongside its Node/Electron frontend, so you need both Node and Python set up if building from source.
Does it work on any Mac, or only newer ones?macOS support is limited to Apple Silicon only; Intel Macs are not supported, while Windows and Linux are fully supported.
Which operating systems does it run on?Windows, Linux, and Apple Silicon macOS, each with native installers from the Releases page.
Does any of my data leave my machine?No, generation is designed to run entirely on your own GPU with local open source models, so images and prompts stay on your machine.
What is the Modly CLI for?It lets agents and scripts drive a running Modly desktop instance headlessly, hitting the same workflow-run endpoints as the UI and getting machine-readable JSON back, without touching the Electron window.
How does the extension system work?Extensions are GitHub repos containing a manifest.json plus runtime files; you install one from the Models page by pasting its HTTPS URL, then download the model it exposes. Official extensions include Hunyuan3D 2 Mini/Turbo/Fast, TripoSG, and Trellis2 GGUF.
How do workflows work inside the app?Workflows are node graphs you wire on the Workflows tab, e.g. Image -> Generate Mesh -> Add to Scene; invalid graphs are blocked with inline warnings instead of breaking the current mesh.
Can I clean up a generated mesh afterward?Yes, imported meshes can be smoothed and decimated directly inside the app, with the optimized result written back into your workspace.
What are similar projects?ooosplat, TRELLIS, image-to-3dlab, dioramas, image-blaster, ml-sharp, genex-desktop, artcraft
Which topics is it in?gaussian-splatting, image-to-3d, 3d-generation, local-ai, ai-tools, plugin-system, 3d, apple-silicon, electron, gpu, react, desktop-app
Creator
lightningpixel
Size
25.2 MB
Stars
8.2K
Updated
CommitOct 04Releasev0.4.3Oct 04
Age
7mo
Commits · 90 Days