{"id":20681697,"url":"https://github.com/haidra-org/horde-worker-regen","last_synced_at":"2025-04-22T12:12:51.644Z","repository":{"id":197571751,"uuid":"663488105","full_name":"Haidra-Org/horde-worker-reGen","owner":"Haidra-Org","description":"The default client software to create images for the AI-Horde","archived":false,"fork":false,"pushed_at":"2025-03-10T14:39:41.000Z","size":1244,"stargazers_count":119,"open_issues_count":58,"forks_count":47,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-22T12:12:41.684Z","etag":null,"topics":["ai","ai-horde","distributed-computing","generative-ai","volunteer-computing"],"latest_commit_sha":null,"homepage":"https://aihorde.net/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Haidra-Org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-07T12:07:37.000Z","updated_at":"2025-04-17T20:18:54.000Z","dependencies_parsed_at":"2023-10-20T16:26:02.810Z","dependency_job_id":"aa963f43-048a-4d81-a0a6-98fee66917a1","html_url":"https://github.com/Haidra-Org/horde-worker-reGen","commit_stats":null,"previous_names":["tazlin/horde-worker-regen","haidra-org/horde-worker-regen"],"tags_count":47,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Haidra-Org%2Fhorde-worker-reGen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Haidra-Org%2Fhorde-worker-reGen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Haidra-Org%2Fhorde-worker-reGen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Haidra-Org%2Fhorde-worker-reGen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Haidra-Org","download_url":"https://codeload.github.com/Haidra-Org/horde-worker-reGen/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250237832,"owners_count":21397401,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-horde","distributed-computing","generative-ai","volunteer-computing"],"created_at":"2024-11-16T22:11:38.874Z","updated_at":"2025-04-22T12:12:51.637Z","avatar_url":"https://github.com/Haidra-Org.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Horde Worker reGen\n\nWelcome to the [AI Horde](https://github.com/Haidra-Org/AI-Horde), a free and open decentralized platform for collaborative AI! The AI Horde enables people from around the world to contribute their GPU power to generate images, text, and more. By running a worker on your local machine, you can earn [kudos](https://github.com/Haidra-Org/haidra-assets/blob/main/docs/kudos.md) which give you priority when making your own requests to the horde.\n\nA worker is a piece of software that handles jobs from the AI Horde, such as generating an image from a text prompt. When your worker successfully completes a job, you are rewarded with kudos. The more kudos you have, the faster your own requests will be processed.\n\nYou can read about [kudos](https://github.com/Haidra-Org/haidra-assets/blob/main/docs/kudos.md), the reward granted to you for running a worker, including some reasons for running a worker on our [detailed kudos explanation](https://github.com/Haidra-Org/haidra-assets/blob/main/docs/kudos.md).\n\n## Contents\n\n- [AI Horde Worker reGen](#ai-horde-worker-regen)\n  - [Contents](#contents)\n  - [Before You Begin](#before-you-begin)\n  - [Installation](#installation)\n    - [Windows](#windows)\n      - [Option 1: Using Git (Recommended)](#option-1-using-git-recommended)\n      - [Option 2: Without Git](#option-2-without-git)\n    - [Linux](#linux)\n    - [AMD GPUs](#amd-gpus)\n    - [DirectML](#directml)\n  - [Configuration](#configuration)\n    - [Basic Settings](#basic-settings)\n    - [Suggested Settings](#suggested-settings)\n    - [Important Notes](#important-notes)\n  - [Running the Worker](#running-the-worker)\n    - [Starting](#starting)\n    - [Stopping](#stopping)\n    - [Monitoring](#monitoring)\n    - [Multiple GPUs](#multiple-gpus)\n  - [Updating](#updating)\n    - [Updating the Worker](#updating-the-worker)\n    - [Updating the Runtime](#updating-the-runtime)\n  - [Custom Models](#custom-models)\n  - [Docker](#docker)\n  - [Support \\\u0026 Troubleshooting](#support--troubleshooting)\n  - [Model Usage \\\u0026 Licenses](#model-usage--licenses)\n\n## Before You Begin\n\nBefore installing the worker:\n\n1. Register an account on the [AI Horde website](https://aihorde.net/register).\n2. Securely store the API key you receive. **Treat this key like a password**.\n\n\n## Installation\n\n### Windows\n\n#### Option 1: Using Git (Recommended)\n\n1. Install [git for Windows](https://gitforwindows.org/) if you haven't already.\n2. Open PowerShell or Command Prompt.\n3. Navigate to the folder where you want to install the worker:\n\n   ```cmd\n   cd C:\\path\\to\\install\\folder\n   ```\n\n4. Clone the repository:\n\n   ```cmd\n   git clone https://github.com/Haidra-Org/horde-worker-reGen.git\n   cd horde-worker-reGen\n   ```\n\n#### Option 2: Without Git\n\n1. Download the [zipped worker files](https://github.com/Haidra-Org/horde-worker-reGen/archive/refs/heads/main.zip).\n2. Extract to a folder of your choice.\n\n### Linux\n\nOpen a terminal and run:\n\n```bash\ngit clone https://github.com/Haidra-Org/horde-worker-reGen.git\ncd horde-worker-reGen\n```\n\n### AMD GPUs\n\nAMD support is experimental, and **Linux-only** for now:\n\n- Use `horde-bridge-rocm.sh` and `update-runtime-rocm.sh` in place of the standard versions.\n- [WSL support](README_advanced.md#advanced-users-amd-rocm-inside-windows-wsl) is highly experimental.\n- Join the [AMD discussion on Discord](https://discord.com/channels/781145214752129095/1076124012305993768) if you're interested in trying.\n\n### DirectML\n\n**Experimental** Support for DirectML has been added. See [Running on DirectML](README_advanced.md#advanced-users-running-on-directml) for more information and further instructions. You can now follow this guide using  `update-runtime-directml.cmd` and `horde-bridge-directml.cmd` where appropriate. Please note that DirectML is several times slower than *ANY* other methods of running the worker.\n\n## Configuration\n\n### Basic Settings\n\n1. Copy `bridgeData_template.yaml` to `bridgeData.yaml`.\n2. Edit `bridgeData.yaml` following the instructions inside.\n3. Set a unique `dreamer_name`\n  - If the name is already taken, you'll get a \"Wrong Credentials\" error. The name must be unique across the entire horde network.\n\n### Suggested Settings\n\nTailor settings to your GPU, following these pointers:\n\n- **24GB+ VRAM** (e.g. 3090, 4090):\n\n  ```yaml\n  - queue_size: 1 # \u003c32GB RAM: 0, 32GB: 1, \u003e32GB: 2\n  - safety_on_gpu: true\n  - high_memory_mode: true\n  - high_performance_mode: true\n  - unload_models_from_vram_often: false\n  - max_threads: 1 # 2 is often viable for xx90 cards\n  - post_process_job_overlap: true\n  - queue_size: 2 # Set to 1 if max_threads: 2\n  - max_power: 64 # Reduce if max_threads: 2\n  - max_batch: 8 # Increase if max_threads: 1, decrease if max_threads: 2\n  - allow_sdxl_controlnet: true\n  ```\n\n- **12-16GB VRAM** (e.g. 3080 Ti, 4070 Ti, 4080):\n\n  ```yaml\n  - queue_size: 1 # \u003c32GB RAM: 0, 32GB: 1, \u003e32GB: 2\n  - safety_on_gpu: true # Consider false if using Cascade/Flux\n  - moderate_performance_mode: true\n  - unload_models_from_vram_often: false\n  - max_threads: 1\n  - max_power: 50\n  - max_batch: 4 # Or higher\n  ```\n\n- **8-10GB VRAM** (e.g. 2080, 3060, 4060, 4060 Ti):\n\n  ```yaml\n  - queue_size: 1 # \u003c32GB RAM: 0, 32GB: 1, \u003e32GB: 2\n  - safety_on_gpu: false\n  - max_threads: 1\n  - max_power: 32 # No higher\n  - max_batch: 4 # No higher\n  - allow_post_processing: false # If using SDXL/Flux, else can be true\n  - allow_sdxl_controlnet: false\n  ```\n\n  - Also minimize other VRAM-consuming apps while the worker runs.\n\n- **Lower-end GPUs / Under-performing Workers**:\n  - `extra_slow_worker: true` gives more time per job, but users must opt-in. Only use if \u003c0.3 MPS/S or \u003c3000 kudos/hr consistently with correct config.\n  - `limit_max_steps: true` caps total steps per job based on model.\n  - `preload_timeout: 120` allows longer model load times. Avoid misusing to prevent kudos loss or maintenance mode.\n\n- **Systems with less than 32GB of System RAM**:\n  - Be sure to only run SD15 models and queue_size: 0.\n    - Set `load_large_models: false`\n    - To your `models_to_skip` add `ALL SDXL`, `ALL SD21`, and the 'unpruned' models (see config) to prevent running out of memory\n\n### Important Notes\n\n- Use an SSD, especially for multiple models. HDDs should offer one model only, loading within 60s.\n- Configure 8GB (preferably 16GB+) of swap space, even on Linux.\n- Keep `threads` ≤2 unless using a 48GB+ VRAM data center GPU.\n- Worker RAM usage scales with `queue_size`. Use 1 for \u003c32GB RAM, and optimize further for \u003c16GB.\n- SDXL needs ~9GB free RAM consistently (32GB+ total recommended).\n- Flux and Stable Cascade need ~20GB free RAM consistently (48GB+ total recommended).\n- Disable sleep/power-saving modes while the worker runs.\n\n## Running the Worker\n\n### Starting\n\n\u003e **Note**: The worker is resource-intensive. Avoid gaming or other heavy tasks while it runs. Turn it off or limit to small models at reduced settings if needed.\n\n1. Install the worker as described in the [Installation](#installation) section.\n2. Run `horde-bridge.cmd` (Windows) or `horde-bridge.sh` (Linux).\n   - **AMD**: Use `horde-bridge-rocm` versions.\n\n### Stopping\n\n- Press `Ctrl+C` in the worker's terminal.\n- It will finish current jobs before exiting.\n\n### Monitoring\n\nWatch the terminal for progress, completed jobs, kudos earned, stats, and errors.\n\nDetailed logs are in the `logs` directory:\n\n- `bridge*.log`: All info\n  - `bridge.log` is the main window\n  - `bridge_n.log` is process-specific (`n` is the process number)\n- `trace*.log`: Errors and warnings only\n  - `trace.log` is the main window\n  - `trace_n.log` is process-specific\n\n### Multiple GPUs\n\n\u003e **Future versions won't need multiple worker instances**\n\nFor now, start a separate worker per GPU.\n\nOn Linux, specify the GPU for each instance:\n\n```bash\nCUDA_VISIBLE_DEVICES=0 ./horde-bridge.sh -n \"Instance 1\"\nCUDA_VISIBLE_DEVICES=1 ./horde-bridge.sh -n \"Instance 2\"\n```\n\n**Warning**: High RAM (32-64GB+) is needed for multiple workers. `queue_size` and `max_threads` greatly impact RAM per worker.\n\n## Updating\n\nThe worker is constantly improving. Follow development and get update notifications in our [Discord](https://discord.gg/3DxrhksKzn).\n\nScript names below assume Windows (`.cmd`) and NVIDIA. For Linux use `.sh`, for AMD use `-rocm` versions.\n\n### Updating the Worker\n\n1. Stop the worker with `Ctrl+C`.\n2. Update the files:\n   - If you used `git clone`:\n     - Open a terminal in the worker folder\n     - Run `git pull`\n   - If you used the zip download:\n     - Delete the old `horde_worker_regen` folder\n     - Download the [latest zip](https://github.com/db0/horde-worker-reGen/archive/refs/heads/main.zip)\n     - Extract to the original location, overwriting existing files\n3. Continue with [Updating the Runtime](#updating-the-runtime) below.\n\n### Updating the Runtime\n\n\u003e **Warning**: Some antivirus software (e.g. Avast) may interfere with the update. If you get `CRYPT_E_NO_REVOCATION_CHECK` errors, disable antivirus, retry, then re-enable.\n\n4. Run `update-runtime` for your OS to update dependencies.\n   - Not all updates require this, but run it if unsure\n   - **Advanced users**: see [README_advanced.md](README_advanced.md) for manual options\n5. [Start the worker](#starting) again\n\n## Custom Models\n\nServing custom models not in our reference requires the `customizer` role. Request it on Discord.\n\nWith the role:\n\n1. Download your model files locally.\n2. Reference them in `bridgeData.yaml`:\n\n   ```yaml\n   custom_models:\n     - name: My Custom Model\n       baseline: stable_diffusion_xl\n       filepath: /path/to/model/file.safetensors\n   ```\n\n   Currently supported baselines:\n    ```\n        stable_diffusion_1\n        stable_diffusion_2_768\n        stable_diffusion_2_512\n        stable_diffusion_xl\n        stable_cascade\n        flux_1\n    ```\n    \u003e **Warning**: Flux.schnell series models are the only Flux models allowed; Flux.dev is *not* currently permitted. Do not attempt to offer Flux.dev, models derived from it, or models which contain data from it.\n    See [`STABLE_DIFFUSION_BASELINE_CATEGORY` in horde_model_reference](https://github.com/Haidra-Org/horde-model-reference/blob/main/horde_model_reference/meta_consts.py#L86) for an up to date list.\n\n\n3. Add the model `name` to your `models_to_load` list.\n\n\u003e Note: Do not use sexually explicit or excessively vulgar names for models.\n\nIf set up correctly, `custom_models.json` will appear in the worker directory on startup.\n\nNotes:\n\n- Custom model names can't match our existing model names\n- The horde will treat them as SD 1.5 for kudos rewards and safety checks\n\n## Docker\n\nDocker images are at \u003chttps://hub.docker.com/r/tazlin/horde-worker-regen/tags\u003e.\n\nDetailed guide: [Dockerfiles/README.md](Dockerfiles/README.md)\n\nManual worker setup: [README_advanced.md](README_advanced.md)\n\n## Support \u0026 Troubleshooting\n\nCheck the [#local-workers Discord channel](https://discord.com/channels/781145214752129095/1076124012305993768) for the latest info and community support.\n\nCommon issues and fixes:\n\n- **Download failures**: Check disk space and internet connection.\n- **Job timeouts**:\n  - Remove large models (Flux, Cascade, SDXL)\n  - Lower `max_power`\n  - Disable `allow_post_processing`, `allow_controlnet`, `allow_sdxl_controlnet`, and/or `allow_lora`\n- **Out of memory**: Decrease `max_threads`, `max_batch`, or `queue_size` to reduce VRAM/RAM use. Close other intensive programs.\n- **I have less kudos than I expect**: As a new user, 50% of your job reward kudos and 100% of uptime kudos are held in escrow until you become trusted after ~1 week of worker uptime. You'll then receive the escrowed kudos and earn full rewards immediately going forward.\n- **My worker is in [maintenance mode](https://github.com/Haidra-Org/haidra-assets/blob/main/docs/definitions.md#maintenance)**: You can log into [artbot here](https://tinybots.net/artbot/settings) and use the [manage workers](https://tinybots.net/artbot/settings?panel=workers) page **with the worker on** and click \"unpause\" to take your worker out of maintenance mode.\n  - **Note**: Workers are put into maintenance mode automatically by the server when the worker is failing to perform fast enough or if it is reporting that it failed too many jobs. You should investigate the [logs](logs/README.md) (search for \"ERROR\") to see what led to the issue. You can also [open an issue](https://github.com/Haidra-Org/horde-worker-reGen/issues) or ask in the [#local-workers channel](https://discord.com/channels/781145214752129095/1076124012305993768) in our [Discord](https://discord.gg/3DxrhksKzn).\n\n[Open an issue](https://github.com/Haidra-Org/horde-worker-reGen/issues) to report bugs or request features. We appreciate your help!\n\n## Model Usage \u0026 Licenses\n\nMany bundled models use the [CreativeML OpenRAIL License](https://huggingface.co/spaces/CompVis/stable-diffusion-license). Please review it before use.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaidra-org%2Fhorde-worker-regen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhaidra-org%2Fhorde-worker-regen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaidra-org%2Fhorde-worker-regen/lists"}