{"id":31817813,"url":"https://github.com/zenwor/zwdx","last_synced_at":"2026-07-15T21:34:46.403Z","repository":{"id":317982421,"uuid":"1062034480","full_name":"zenwor/zwdx","owner":"zenwor","description":"distributed. accelerated. done.","archived":false,"fork":false,"pushed_at":"2025-10-19T18:10:48.000Z","size":23222,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-19T23:50:19.256Z","etag":null,"topics":["cuda","distributed-computing","dl","docker","pytorch","react"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zenwor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-22T18:04:05.000Z","updated_at":"2025-10-19T18:10:51.000Z","dependencies_parsed_at":"2025-10-19T17:15:59.429Z","dependency_job_id":"01993577-a5de-463b-b323-dae5147076f5","html_url":"https://github.com/zenwor/zwdx","commit_stats":null,"previous_names":["zenwor/zwdx"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zenwor/zwdx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zenwor%2Fzwdx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zenwor%2Fzwdx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zenwor%2Fzwdx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zenwor%2Fzwdx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zenwor","download_url":"https://codeload.github.com/zenwor/zwdx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zenwor%2Fzwdx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35522129,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-15T02:00:06.706Z","response_time":131,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["cuda","distributed-computing","dl","docker","pytorch","react"],"created_at":"2025-10-11T10:26:27.445Z","updated_at":"2026-07-15T21:34:46.397Z","avatar_url":"https://github.com/zenwor.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo.png\" alt=\"zwdx\" title=\"zwdx\" width=\"200\"/\u003e\u003cbr\u003e\n  distributed. accelerated. done.\n\u003c/p\u003e\n\n⚠️ This is a personal project. It is not done, as it still only works locally. Will make it work truly remotely hopefully soon. Shouldn't be too problematic.\n\n[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/)\n[![PyTorch](https://img.shields.io/badge/PyTorch-ee4c2c?logo=pytorch\u0026logoColor=white)](#)\n[![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?logo=docker\u0026logoColor=white)](https://www.docker.com/)\n[![React](https://img.shields.io/badge/React-%2320232a.svg?logo=react\u0026logoColor=%2361DAFB)](#)\n[![MongoDB](https://img.shields.io/badge/MongoDB-%234ea94b.svg?logo=mongodb\u0026logoColor=white)](#)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## About\n\n**zwdx** is a distributed deep learning platform that enables GPU sharing and collaborative training across multiple machines. Instead of being limited to your local hardware, zwdx allows you to:\n\n- **Distribute training** across multiple GPUs from different contributors\n- **Share your idle GPUs** with others who need compute power\n- **Submit training jobs** without managing infrastructure\n- **Scale seamlessly** from single GPU to multi-node distributed training\n\nUnlike traditional distributed training solutions, zwdx separates compute providers (GPU clients) from compute consumers (job submitters), creating a flexible environment for GPU resources.\n\n## Table of Contents\n\n- [Features](#features)\n- [Architecture](#architecture)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Setup](#setup)\n  - [Server](#server)\n  - [GPU Client](#gpu-client)\n- [Quick Start](#quick-start)\n- [Configuration](#configuration)\n- [Monitoring](#monitoring)\n- [Security Considerations](#security-considerations)\n- [Limitations](#limitations)\n- [Legal Notice](#legal-notice)\n- [License](#license)\n\n## Features\n\n- ✅ **Distributed Training**: Built-in support for DDP / FSDP\n- ✅ **GPU Pooling**: Aggregate GPU resources from multiple machines\n- ✅ **Room-based Access**: Secure, token-based room system for private GPU sharing\n- ✅ **Framework Support**: PyTorch native (additional frameworks coming soon)\n- ✅ **Simple API**: Submit jobs with just a few lines of code\n- ✅ **Real-time Monitoring**: Track training progress and metrics\n- ✅ **Job Management**: Query past jobs\n- ✅ **Docker-based**: Consistent environment across all GPU clients\n\n## Architecture\n\n```\n┌─────────────────┐\n│    zwdx User    │\n│   (Your Code)   │\n└────────┬────────┘\n         │\n         │ Submit Job\n         ▼\n┌─────────────────────────────┐\n│    Server                   │\n│   ┌─────────────────────┐   │\n│   │  Job Pool           │   │\n│   ├─────────────────────┤   │\n│   │  Room Pool          │   │\n│   ├─────────────────────│   │\n│   │  Database           │   │\n│   └─────────────────────┘   │\n└──────────┬──────────────────┘\n           │\n           │ Distribute \n           │\n    ┌──────┴──────┬──────────┐\n    ▼             ▼          ▼\n┌─────────┐  ┌─────────┐  ┌─────────┐\n│ GPU     │  │ GPU     │  │ GPU     │\n│ Client  │  │ Client  │  │ Client  │\n│ (Rank 0)│  │ (Rank 1)│  │ (Rank 2)│\n└─────────┘  └─────────┘  └─────────┘\n```\n\n**How it works:**\n1. **Server** manages job pool, GPU client pool, room pool and communication\n2. **GPU Clients** join rooms using auth tokens and wait for work\n3. **Job Submitters** send training jobs to specific rooms\n4. Results are collected and returned to the job submitter\n\n## Prerequisites\n\n### Software Requirements\n- **Python**: 3.12.4\n- **Docker**: 28.4.0\n- **CUDA**: 12.8\n- **Operating System**: Linux, Windows (WSL2)\n\n## Installation\n\n1. **Clone the repository:**\n```bash\ngit clone https://github.com/zenwor/zwdx.git\ncd zwdx\n```\n\n2. **Install Python dependencies:**\n```bash\nuv pip install --system -r requirements.txt\n```\n\n## Setup\n\nLoad environment variables before proceeding:\n```bash\ncd zwdx/zwdx\nsource ./setup.sh\n```\n\n### Server\n\nThe server manages GPU clients, job queues, database, and UI communication. **No GPUs required on the server machine.**\n\n**Start the server:**\n```bash\n./run_all.sh  # inside zwdx/zwdx/\n```\n\n**What runs:**\n- Flask server (port 4461)\n- Database service (MongoDB, port 5561)\n- Web UI (React.js, port 3000)\n\n### GPU Client\n\nGPU clients provide computing power to the server.\n\n**1. Pull NVIDIA base image and build container:**\n```bash\ndocker pull pytorch/pytorch:2.8.0-cuda12.8-cudnn9-devel\ndocker build -t zwdx_gpu .\n```\n\n**2. Launch GPU client:**\n```bash\ncd zwdx/gpu_client/\n./run_gpu_client.sh -rt {ROOM_TOKEN}\n```\n\n**Arguments:**\n- `-rt, --room_token`: Room authentication token (required)\n\n**Example with specific GPUs:**\n```bash\n./run_gpu_client.sh -rt my_room_token\n```\n\n## Quick Start\nThe ZWDX interface is designed to be intuitive and Pythonic:\n\n```python\nfrom zwdx import ZWDX\n\nzwdx = ZWDX(server_url=\"http://localhost:8000\")\n\nresult = zwdx.submit_job(\n    model=YourModel(),                    # PyTorch model instance\n    data_loader_func=create_data_loader,  # Function that returns DataLoader\n    train_func=train,                     # Training function\n    eval_func=eval,                       # Evaluation function\n    optimizer=torch.optim.AdamW(...),     # Optimizer instance\n    parallelism=\"DDP\",                    # Parallelism strategy\n    memory_required=12_000_000_000,       # Minimum GPU memory in bytes\n    room_token=\"your_room_token\",         # Room authentication token\n    epochs=10,                            # Number of training epochs\n)\n\n# Access results\nprint(result[\"job_id\"])\nprint(result[\"results\"][\"final_loss\"])\n\n# Retrieve trained model\ntrained_model = zwdx.get_trained_model(result[\"job_id\"], YourModel())\n```\n\nFor a complete MNIST example, see [`test/mnist.py`](./test/mnist.py).\n\n## Configuration\n\n### Environment Variables\n\nEdit the `.env` file or set these environment variables:\n\n```bash\n# Server\n## Flask\nFLASK_HOST=\"0.0.0.0\"\nFLASK_PORT=4461\nMASTER_ADDR=\"29500\"\nLT_SUBDOMAIN=\"zwdx\"\nLT_PORT=4461\n## MongoDB\nMONGODB_PORT=5561\nMONGODB_DBPATH=\"./data/\"\n\n# Client\nSERVER_URL=\"http://172.17.0.1:4461\"\n```\n## Monitoring\n\n### Server Logs\n```bash\ntail -f /var/log/zwdx/server.log\n```\n\n### GPU Client Logs\n```bash\ndocker logs -f zwdx_gpu_client_container\n```\n\n### Job Metrics\nAccess real-time metrics via the web UI at `http://localhost:3000` or programmatically:\n\n```python\nmetrics = zwdx.get_job_metrics(job_id)\nprint(metrics[\"gpu_utilization\"])\nprint(metrics[\"throughput\"])  # samples/second\n```\n\n### Monitoring Dashboard\nThe web UI provides:\n- Job queue and current jobs\n- Training metrics and loss curves\n- Historical job performance\n\n## Security Considerations\n\n### Room Tokens\n- Room tokens provide isolation between different groups\n- Tokens should be treated as sensitive credentials\n- Generate strong, random tokens for production use\n- Rotate tokens periodically\n\n### Data Privacy\n- Training data is sent to GPU client machines\n- **Do not use zwdx for sensitive/confidential data unless you trust all GPU providers**\n- Model weights are transmitted between clients and server\n- Consider using encrypted communication channels for production\n\n## Limitations\n- **Framework Support**: PyTorch only (TensorFlow/JAX planned)\n- **Parallelism**: DDP / FSDP only (more coming soon)\n- **Data Transfer**: Large datasets must be pre-distributed to clients\n\n## Legal Notice\n\n\u003e ⚠️ **NVIDIA Software Usage**\n\u003e \n\u003e This project uses NVIDIA software. The base container is proprietary and must be pulled by each user separately:\n\u003e ```bash\n\u003e docker pull pytorch/pytorch:2.8.0-cuda12.8-cudnn9-devel\n\u003e ```\n\u003e \n\u003e **Do NOT redistribute the NVIDIA container.** \n\u003e \n\u003e See [NVIDIA Deep Learning Container License](https://developer.download.nvidia.com/licenses/NVIDIA_Deep_Learning_Container_License.pdf) for complete terms.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\nCopyright (c) 2025 zenwor\n\n---\n\n**Built with ❤️ by zenwor**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzenwor%2Fzwdx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzenwor%2Fzwdx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzenwor%2Fzwdx/lists"}