Hordelib
A wrapper around ComfyUI to allow use by the AI Horde.
Last verified:
What is Hordelib?
Hordelib (now called horde-engine) is an open-source Python library that serves as a wrapper around ComfyUI, enabling the AI Horde distributed computing network to run inference pipelines designed visually in the ComfyUI GUI. The primary purpose is to allow developers to design stable diffusion image generation pipelines in ComfyUI's node-based interface and then call those pipelines programmatically through Python code.
Key features include support for basic image inference with customizable parameters like sampler names, CFG scale, denoising strength, seeds, resolution, and models; built-in model management with download and validation capabilities; support for ControlNet preprocessing, face restoration nodes, and QR code generation; custom ComfyUI nodes for horde-specific processing; and the ability to design pipelines using the ComfyUI web app and save them as JSON files for programmatic execution. The library uses loguru for logging and automatically manages dependencies including ComfyUI itself.
Hordelib is designed for AI Horde workers, developers building AI image generation applications, researchers working with stable diffusion models, and anyone who wants to leverage ComfyUI's powerful node-based workflow system through programmatic API access. It is particularly useful for those contributing to the AI Horde distributed computing network or building custom AI image generation services that need to integrate with ComfyUI workflows.
Hordelib pricing
Pricing model: Freemium
Completely free and open source under AGPL-3.0 license. Available on PyPI as hordelib with no paid tiers. All features including ComfyUI integration, model management, ControlNet support, and custom nodes are included at no cost. The library is maintained by the AI Horde community as a free distributed computing project.
Hordelib pros
- Open source with AGPL-3.0 license
- Enables programmatic access to ComfyUI pipelines
- Designed visually in ComfyUI GUI then called via code
- Default inference backend for AI Horde since v1.0.0
- Automatic dependency installation including ComfyUI
- Support for ControlNet preprocessing
- Built-in face restoration node support
- Custom nodes for horde-specific processing
- Model management with download and validation
- Support for multiple samplers including k_dpmpp_2m
- Configurable CFG scale, steps, and denoising strength
- QR code generation capabilities via ComfyQR
- Pipeline design saved as JSON for reuse
- Comprehensive test suite with tox
- Active development with 96 releases
- 60+ stars on GitHub with community support
- Discord community for developer support
Hordelib cons
- Requires Nvidia CUDA Toolkit installation on Linux
- Needs minimum 16GB RAM with swap space
- May require /tmp size increase on Linux for installation
- erases command line arguments when initialise() called
- Model directory must use specific AI Horde directory structure
- Steep learning curve for ComfyUI pipeline design
- No graphical interface - Python code required
- Bundled dependencies increase installation size
- Primarily designed for AI Horde workers not general users
Frequently asked questions about Hordelib
What is hordelib/horde-engine?
Hordelib (now called horde-engine) is a wrapper around ComfyUI primarily designed to enable the AI Horde to run inference pipelines that are designed visually in the ComfyUI GUI. It allows developers to create stable diffusion image generation workflows in ComfyUI's node-based interface and then call those pipelines programmatically through Python code.
How do I install hordelib?
Install from PyPI using a requirements file that includes '--extra-index-url https://download.pytorch.org/whl/cu121' followed by 'hordelib' and your other dependencies. On Linux, you must first install the Nvidia CUDA Toolkit from developer.nvidia.com/cuda-downloads. If you have only 16GB RAM, you may need to increase /tmp size and add swap space.
What is the minimum hardware requirement?
You need at least 16GB of RAM and an Nvidia GPU with CUDA support. If you only have 16GB RAM, you absolutely need swap space and may need to remount /tmp with larger size (sudo mount -o remount,size=16G /tmp) before installing the CUDA Toolkit or installation may fail.
How do I generate an image with hordelib?
First call hordelib.initialise(), then import HordeLib from hordelib.horde. Create a generate = HordeLib() instance, download and validate a model using SharedModelManager, then call generate.basic_inference_single_image(data) with a dictionary containing sampler_name, cfg_scale, denoising_strength, seed, height, width, prompt, model, and other parameters. Save the returned pil_image.
Can I design custom pipelines?
Yes. Use the standard ComfyUI web app to design your pipeline, name nodes using the 'title' attribute (these become parameter names), save the pipeline as JSON in hordelib/pipeline_designs/ with naming convention 'pipeline_<name>.json', then convert it to backend format and save in hordelib/pipelines/. You can then call it using run_image_pipeline() method.
What models does hordelib support?
Hordelib supports stable diffusion models in the compvis directory including Deliberate and other checkpoints. Models must be in the original AI Horde directory structure with clip, codeformer, compvis, controlnet, embeds, esrgan, gfpgan, and safety_checker directories. Use SharedModelManager.manager.compvis.download_model() and validate_model() to manage models.
How do I run tests?
Simply execute 'tox' or 'tox -q' for less verbose output. This installs all dependencies and runs the test suite. Successful tests produce images in the images/ folder. To run a specific test file, use 'tox -- -k <filename>' like 'tox -- -k test_initialisation'. Use 'tox list' to see all predefined test suites.
What is the difference between hordelib and horde-engine?
They are the same project. The project was formerly known as hordelib but has been renamed to horde-engine. The project namespace will be changed in the near future to reflect this change. Horde-engine has been the default inference backend library of the AI Horde since hordelib v1.0.0.
How do I disable automatic logging setup?
Hordelib uses loguru for logging and sets it up automatically during initialise(). If you don't want hordelib to control logging configuration, call hordelib.initialise(setup_logging=False) instead of the default initialise() call.
Where can I get help or support?
The developers of horde-engine can be found in the AI Horde Discord server at https://discord.gg/3DxrhksKzn. The project is open source on GitHub at github.com/Haidra-Org/hordelib with 60+ stars and 12 contributors. You can also check the tests/run_*.py files for standalone examples.