gpumesh 0.6.4

Borrow your friends' GPUs: a terminal-based distributed compute mesh in pure Python

gpumesh

Borrow your friends' GPUs. A distributed compute mesh that lets you share GPU power across machines using Python.

---

Features

• Unified GPU pool — See all connected GPUs as one system
• One-line setup — gpumesh setup handles everything
• Auto-discovery — Workers find coordinators on the same network
• Smart scheduling — Fast GPUs get heavy tasks, slow ones get light tasks
• Fault tolerance — Dead workers are detected, tasks are re-queued
• Python API — Distribute functions from Jupyter notebooks

---

Installation

pip install gpumesh

Optional extras:

pip install gpumesh[gpu]       # GPU detection + CUDA benchmarks
pip install gpumesh[tunnel]    # ngrok for public URLs
pip install gpumesh[all]       # everything

Requires Python 3.9+.

---

Quick Start

1. Start a coordinator (one machine)

gpumesh serve --token mySecret

2. Join a worker (another machine)

gpumesh join http://192.168.1.10:8000 --token mySecret

3. Submit a job

# Set connection (saved automatically after first join)
export GPUMESH_URL=http://192.168.1.10:8000
export GPUMESH_TOKEN=mySecret

# Run a script across all workers
gpumesh submit examples/grid_search.py --payloads examples/payloads.json --wait

---

CLI Commands

Command	Description
gpumesh setup	Interactive setup wizard
gpumesh serve	Start coordinator
gpumesh join URL	Join as worker
gpumesh submit SCRIPT --payloads FILE	Submit a job
gpumesh status JOB_ID	Check job progress
gpumesh cancel JOB_ID	Cancel a job
gpumesh kill	Kill all tasks
gpumesh workers	List connected workers
gpumesh devices	Show all GPUs as one pool
gpumesh --version	Show version

---

Python API

from gpumesh import GPUMesh

# Connect to coordinator
mesh = GPUMesh("http://192.168.1.10:8000", token="mySecret")

# List workers
mesh.workers()

# Distribute a function across all workers
def train(lr, epochs):
    import os
    device = os.environ.get("GPUMESH_DEVICE", "cpu")
    # Your training code here
    return {"accuracy": 0.95, "lr": lr, "device": device}

results = mesh.distribute(
    function=train,
    params=[
        {"lr": 0.01, "epochs": 100},
        {"lr": 0.05, "epochs": 200},
    ],
)

See full API documentation for Jupyter/Colab examples, closures, and error handling.

---

Writing Task Scripts

Your script receives parameters on stdin and prints JSON on stdout:

import json, sys, os

payload = json.load(sys.stdin)
device = os.environ.get("GPUMESH_DEVICE", "cpu")

result = {"answer": 42, "device": device}
print(json.dumps(result))

---

Network Options

Method	Setup	Best for
LAN	None	Same Wi-Fi, fastest
Tailscale	Install Tailscale	Remote teams
ngrok	pip install gpumesh[tunnel]	Public access

---

Limitations

• Python only — Tasks must be Python scripts
• No GPU memory sharing — Each task gets its own process
• No model sharding — Each task runs on one machine
• Single coordinator — Single point of failure
• No persistent storage — Export results before shutdown

---

Troubleshooting

Problem	Fix
command not found	Use python -m gpumesh instead
401 bad token	Check coordinator and worker tokens match
coordinator unreachable	Check firewall and that coordinator is running
task timed out	Increase --timeout 600 or split into smaller tasks

---

Security

• Token authentication on all API requests
• Tokens hashed with SHA-256 before storage
• Rate limiting after 5 failed attempts
• Process isolation for all tasks

Important: Workers execute code from the coordinator. Only share your URL and token with people you trust.

---

Contributing

git clone https://github.com/Samurai007AK/gpumesh.git
cd gpumesh
pip install -e ".[dev]"
pytest

---

License

MIT License. See LICENSE for details.

---

Links

• GitHub: github.com/Samurai007AK/gpumesh
• PyPI: pypi.org/project/gpumesh
• Issues: github.com/Samurai007AK/gpumesh/issues