samurai007ak/gpumesh repository overview

┌──────────────┐         ┌──────────────┐
│  Coordinator │◄───────►│   Worker 1   │
│  (your Mac)  │         │ RTX 4090     │
│  Port 8732   │         │ Score: 120   │
└──────┬───────┘         └──────────────┘
       │
       │                 ┌──────────────┐
       ├────────────────►│   Worker 2   │
       │                 │ RTX 3080     │
       │                 │ Score: 85    │
       │                 └──────────────┘
       │
       │                 ┌──────────────┐
       └────────────────►│   Worker 3   │
                         │ Laptop CPU   │
                         │ Score: 0.5   │
                         └──────────────┘

export GPUMESH_TOKEN=$(python -c "import secrets; print(secrets.token_urlsafe(32))")

docker run -d \
  --name gpumesh-coordinator \
  -p 127.0.0.1:8732:8732 \
  -e GPUMESH_TOKEN \
  samurai007ak/gpumesh:3.0.0 \
  serve --host 0.0.0.0 --port 8732

docker run -d \
  --name gpumesh-worker \
  -e GPUMESH_TOKEN \
  samurai007ak/gpumesh:3.0.0 \
  join http://coordinator-ip:8732

from gpumesh import GPUMesh, accelerate

mesh = GPUMesh("http://coordinator:8732", token=TOKEN)

@accelerate(mesh)
def train(lr, epochs):
    return {"accuracy": 0.95}

# Single call → best available worker (or local if none)
result = train(lr=0.01, epochs=100)

# Map call → spread across ALL connected workers
results = train.map([
    {"lr": 0.01, "epochs": 100},
    {"lr": 0.05, "epochs": 200},
])

docker pull samurai007ak/gpumesh:3.0.0
# or
docker pull samurai007ak/gpumesh:latest

docker run --rm samurai007ak/gpumesh:3.0.0 --version
# gpumesh 3.0.0 (3.11.9, linux)

docker run --rm samurai007ak/gpumesh:3.0.0 doctor --json
# {"version": "3.0.0", "python": "3.11.9", "status": "ok"}

services:
  coordinator:
    image: samurai007ak/gpumesh:3.0.0
    ports:
      - "${GPUMESH_BIND:-127.0.0.1}:${GPUMESH_PORT:-8732}:8732"
      - "${GPUMESH_BIND:-127.0.0.1}:48900:48900/udp"
    environment:
      - GPUMESH_TOKEN=${GPUMESH_TOKEN:?set GPUMESH_TOKEN}
      - GPUMESH_HOST=0.0.0.0
    command: serve --host 0.0.0.0 --port 8732
    volumes:
      - gpumesh_data:/data
    healthcheck:
      test: ["CMD", "nc", "-z", "localhost", "8732"]
      interval: 10s
      timeout: 3s
      retries: 3
      start_period: 10s
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL

  worker:
    image: samurai007ak/gpumesh:3.0.0
    depends_on:
      coordinator:
        condition: service_healthy
    environment:
      - GPUMESH_TOKEN=${GPUMESH_TOKEN:?set GPUMESH_TOKEN}
    command: join http://coordinator:8732
    deploy:
      replicas: ${WORKER_REPLICAS:-2}
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL

volumes:
  gpumesh_data:

# Generate a token
export GPUMESH_TOKEN=$(python -c "import secrets; print(secrets.token_urlsafe(32))")

# Start coordinator + 2 workers
docker compose up -d

# Scale to 4 workers
WORKER_REPLICAS=4 docker compose up -d

# Reachable from other machines on your LAN
GPUMESH_BIND=0.0.0.0 docker compose up -d

# View logs
docker compose logs -f

# Stop
docker compose down

@accelerate(mesh)
def preprocess(chunk_id, data_path):
    return {"chunk": chunk_id, "rows": len(df)}

# Single call → best local device
result = preprocess(chunk_id=0, data_path="data.parquet")

# Map call → spread across ALL mesh devices
results = preprocess.map([
    {"chunk_id": 0, "data_path": "part0.parquet"},
    {"chunk_id": 1, "data_path": "part1.parquet"},
])

@accelerate(mesh, gpu="A100")
def train(model):
    return model.cuda().forward(x)

@accelerate(mesh, cores=8, memory="16GB", timeout=300)
def heavy_computation(data):
    return processed

  Score       Typical GPU        Use Case
  ─────       ───────────        ────────
  ~100+       RTX 4090, A100     Heavy training, large models
  ~50-100     RTX 3080, 3090     Medium training, inference
  ~10-50      RTX 3060, T4       Light tasks, preprocessing
  under 1     CPU only           Very light tasks

                    COORDINATOR
   ┌─────────────────────────────────────────────────┐
   │                                                 │
   │  ┌──────────┐  ┌──────────┐  ┌──────────────┐  │
   │  │ Job Queue │  │ Task DB  │  │ Worker       │  │
   │  │ (memory)  │  │ (SQLite) │  │ Registry     │  │
   │  └────┬─────┘  └──────────┘  └──────┬───────┘  │
   │       │                              │          │
   │       └──────────┬───────────────────┘          │
   │                  │                              │
   │         HTTP API :8732                          │
   └──────────────────┼──────────────────────────────┘
                      │
         ┌────────────┼────────────┐
         │            │            │
   ┌─────▼────┐ ┌────▼────┐ ┌────▼────┐
   │ Worker 1 │ │Worker 2 │ │Worker 3 │
   │ RTX 4090 │ │RTX 3080 │ │   T4    │
   │Score: 120│ │Score: 85│ │Score: 12│
   └──────────┘ └─────────┘ └─────────┘