gpumesh 0.1.0__tar.gz

gpumesh-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: gpumesh
+Version: 0.1.0
+Summary: Borrow your friends' GPUs: a terminal-based distributed compute mesh in pure Python
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: gpu
+Requires-Dist: torch; extra == "gpu"
+Provides-Extra: tunnel
+Requires-Dist: pyngrok; extra == "tunnel"
+Provides-Extra: sysinfo
+Requires-Dist: psutil; extra == "sysinfo"
+
+# gpumesh
+
+**Borrow your friends' GPUs.** A terminal-based distributed compute mesh written in
+pure Python (stdlib only — `torch`, `psutil`, `pyngrok` are optional extras).
+
+You have ML work to run but a weak laptop. Your friend has a strong GPU sitting
+idle. `gpumesh` turns any group of machines into a small compute cluster: one
+machine coordinates, any number of machines join with a single command, and work
+is split between them **proportionally to how fast each machine is**.
+
+```
+ your laptop (coordinator)              friend's laptop (worker)
+┌───────────────────────┐    HTTP/JSON  ┌────────────────────────┐
+│  job queue            │◄─────────────►│  hardware probe        │
+│  capability scheduler │   (optional   │  matmul benchmark      │
+│  SQLite (WAL)         │    ngrok      │  sandboxed subprocess  │
+│  heartbeats + reaper  │    tunnel)    │  executor              │
+└──────────▲────────────┘               └────────────────────────┘
+           │ submit / status
+       client CLI
+```
+
+## Quick start
+
+```bash
+pip install -e .
+```
+
+**Machine 1 — start the coordinator:**
+
+```bash
+gpumesh serve --port 8000
+# prints a token and a ready-made join command, e.g.
+#   gpumesh join http://192.168.1.5:8000 --token Kv3xP9qL2mNa
+```
+
+Add `--public` (with `pip install pyngrok`) to get a public URL friends can
+reach over the internet.
+
+**Machine 2..N — join as a worker (one command, as promised):**
+
+```bash
+gpumesh join http://192.168.1.5:8000 --token Kv3xP9qL2mNa
+```
+
+The worker probes its hardware (CUDA GPU → Apple Silicon → CPU), benchmarks
+itself with a matmul, and starts pulling tasks. Your own laptop can join too —
+then both machines compute in parallel.
+
+**Submit work:**
+
+```bash
+gpumesh submit examples/grid_search.py --payloads examples/payloads.json \
+    --url http://192.168.1.5:8000 --token Kv3xP9qL2mNa --wait
+```
+
+A job is a Python script plus a JSON list of payloads (shards). Each payload
+becomes one task; an optional `"cost"` field marks how heavy it is. Heavy
+tasks go to fast machines, light tasks to slow ones.
+
+**Watch the mesh:**
+
+```bash
+gpumesh workers --url ... --token ...
+gpumesh status JOB_ID --url ... --token ...
+```
+
+## Writing your own task script
+
+The contract is two lines of glue:
+
+```python
+import json, sys
+payload = json.load(sys.stdin)        # your shard's parameters
+# ... do the work (os.environ["GPUMESH_DEVICE"] tells you cuda/mps/cpu) ...
+print(json.dumps({"answer": 42}))     # result = last stdout line, as JSON
+```
+
+Anything data-parallel fits: hyperparameter search, batch inference,
+cross-validation folds, rendering chunks, brute-force search shards.
+
+## How the scheduler splits work
+
+1. Every worker benchmarks itself at join time → a GFLOP/s **score**.
+2. Pending tasks are sorted by `cost`.
+3. When a worker asks for work, its score percentile among live workers picks
+   the matching percentile of task costs — the strongest machine gets the
+   heaviest remaining task, the weakest gets the lightest.
+4. Tasks are leased, not given away: if a worker dies (heartbeats stop) or the
+   lease expires, the reaper re-queues the task for someone else (max 3
+   attempts, then marked failed).
+
+## Design notes (the interview section)
+
+- **Networking** — hand-rolled JSON-over-HTTP protocol on `http.server`
+  (no framework), worker heartbeats, poll-based task leasing that survives
+  flaky tunnels, shared-token auth, ngrok tunneling for NAT traversal.
+- **DBMS** — SQLite in WAL mode; schema with foreign keys and indexes; atomic
+  lease acquisition via a conditional `UPDATE ... WHERE status='pending'` so
+  two workers can never grab the same task; transactions around multi-row
+  writes.
+- **Operating systems** — every task runs in a fresh subprocess in its own
+  session (process group); timeouts kill the whole process tree with
+  `SIGKILL`; POSIX `RLIMIT_CPU` caps runaway loops; coordinator uses threads
+  with a lock around the shared DB connection.
+- **Distributed systems** — capability-based scheduling, lease/heartbeat
+  failure detection, idempotent re-queue with bounded retries, work-stealing
+  style pull model (workers pull; the coordinator never needs to reach them
+  through NAT).
+- **Task-parallel, not tensor-parallel** — splitting a single model's tensors
+  across machines over the internet dies on latency (that's what NCCL +
+  InfiniBand are for). Sharding independent work units is the model serverless
+  GPU platforms (e.g. RunPod) actually use.
+
+## Security warning
+
+Workers execute code submitted to the coordinator. That is the point of the
+tool, and it is also remote code execution by design. Only share your
+coordinator URL + token with people you trust, treat the token as a password,
+and don't leave a public tunnel running unattended. The subprocess sandbox
+limits accidents, not attackers.
+
+## Layout
+
+```
+gpumesh/
+  cli.py         command line entry point (serve / join / submit / status / workers)
+  server.py      coordinator: threaded HTTP JSON API + lease reaper
+  db.py          SQLite layer: workers, jobs, tasks, atomic leasing
+  worker.py      agent loop: register, heartbeat, lease, execute, report
+  sandbox.py     subprocess isolation: timeouts, process-group kill, rlimits
+  capability.py  hardware probe + matmul benchmark -> capability score
+  client.py      job submission and status polling
+  tunnel.py      optional ngrok public URL
+examples/
+  grid_search.py hyperparameter-search demo task (pure Python)
+  payloads.json  six shards with varying cost
+```

gpumesh-0.1.0/README.md

@@ -0,0 +1,138 @@
+# gpumesh
+
+**Borrow your friends' GPUs.** A terminal-based distributed compute mesh written in
+pure Python (stdlib only — `torch`, `psutil`, `pyngrok` are optional extras).
+
+You have ML work to run but a weak laptop. Your friend has a strong GPU sitting
+idle. `gpumesh` turns any group of machines into a small compute cluster: one
+machine coordinates, any number of machines join with a single command, and work
+is split between them **proportionally to how fast each machine is**.
+
+```
+ your laptop (coordinator)              friend's laptop (worker)
+┌───────────────────────┐    HTTP/JSON  ┌────────────────────────┐
+│  job queue            │◄─────────────►│  hardware probe        │
+│  capability scheduler │   (optional   │  matmul benchmark      │
+│  SQLite (WAL)         │    ngrok      │  sandboxed subprocess  │
+│  heartbeats + reaper  │    tunnel)    │  executor              │
+└──────────▲────────────┘               └────────────────────────┘
+           │ submit / status
+       client CLI
+```
+
+## Quick start
+
+```bash
+pip install -e .
+```
+
+**Machine 1 — start the coordinator:**
+
+```bash
+gpumesh serve --port 8000
+# prints a token and a ready-made join command, e.g.
+#   gpumesh join http://192.168.1.5:8000 --token Kv3xP9qL2mNa
+```
+
+Add `--public` (with `pip install pyngrok`) to get a public URL friends can
+reach over the internet.
+
+**Machine 2..N — join as a worker (one command, as promised):**
+
+```bash
+gpumesh join http://192.168.1.5:8000 --token Kv3xP9qL2mNa
+```
+
+The worker probes its hardware (CUDA GPU → Apple Silicon → CPU), benchmarks
+itself with a matmul, and starts pulling tasks. Your own laptop can join too —
+then both machines compute in parallel.
+
+**Submit work:**
+
+```bash
+gpumesh submit examples/grid_search.py --payloads examples/payloads.json \
+    --url http://192.168.1.5:8000 --token Kv3xP9qL2mNa --wait
+```
+
+A job is a Python script plus a JSON list of payloads (shards). Each payload
+becomes one task; an optional `"cost"` field marks how heavy it is. Heavy
+tasks go to fast machines, light tasks to slow ones.
+
+**Watch the mesh:**
+
+```bash
+gpumesh workers --url ... --token ...
+gpumesh status JOB_ID --url ... --token ...
+```
+
+## Writing your own task script
+
+The contract is two lines of glue:
+
+```python
+import json, sys
+payload = json.load(sys.stdin)        # your shard's parameters
+# ... do the work (os.environ["GPUMESH_DEVICE"] tells you cuda/mps/cpu) ...
+print(json.dumps({"answer": 42}))     # result = last stdout line, as JSON
+```
+
+Anything data-parallel fits: hyperparameter search, batch inference,
+cross-validation folds, rendering chunks, brute-force search shards.
+
+## How the scheduler splits work
+
+1. Every worker benchmarks itself at join time → a GFLOP/s **score**.
+2. Pending tasks are sorted by `cost`.
+3. When a worker asks for work, its score percentile among live workers picks
+   the matching percentile of task costs — the strongest machine gets the
+   heaviest remaining task, the weakest gets the lightest.
+4. Tasks are leased, not given away: if a worker dies (heartbeats stop) or the
+   lease expires, the reaper re-queues the task for someone else (max 3
+   attempts, then marked failed).
+
+## Design notes (the interview section)
+
+- **Networking** — hand-rolled JSON-over-HTTP protocol on `http.server`
+  (no framework), worker heartbeats, poll-based task leasing that survives
+  flaky tunnels, shared-token auth, ngrok tunneling for NAT traversal.
+- **DBMS** — SQLite in WAL mode; schema with foreign keys and indexes; atomic
+  lease acquisition via a conditional `UPDATE ... WHERE status='pending'` so
+  two workers can never grab the same task; transactions around multi-row
+  writes.
+- **Operating systems** — every task runs in a fresh subprocess in its own
+  session (process group); timeouts kill the whole process tree with
+  `SIGKILL`; POSIX `RLIMIT_CPU` caps runaway loops; coordinator uses threads
+  with a lock around the shared DB connection.
+- **Distributed systems** — capability-based scheduling, lease/heartbeat
+  failure detection, idempotent re-queue with bounded retries, work-stealing
+  style pull model (workers pull; the coordinator never needs to reach them
+  through NAT).
+- **Task-parallel, not tensor-parallel** — splitting a single model's tensors
+  across machines over the internet dies on latency (that's what NCCL +
+  InfiniBand are for). Sharding independent work units is the model serverless
+  GPU platforms (e.g. RunPod) actually use.
+
+## Security warning
+
+Workers execute code submitted to the coordinator. That is the point of the
+tool, and it is also remote code execution by design. Only share your
+coordinator URL + token with people you trust, treat the token as a password,
+and don't leave a public tunnel running unattended. The subprocess sandbox
+limits accidents, not attackers.
+
+## Layout
+
+```
+gpumesh/
+  cli.py         command line entry point (serve / join / submit / status / workers)
+  server.py      coordinator: threaded HTTP JSON API + lease reaper
+  db.py          SQLite layer: workers, jobs, tasks, atomic leasing
+  worker.py      agent loop: register, heartbeat, lease, execute, report
+  sandbox.py     subprocess isolation: timeouts, process-group kill, rlimits
+  capability.py  hardware probe + matmul benchmark -> capability score
+  client.py      job submission and status polling
+  tunnel.py      optional ngrok public URL
+examples/
+  grid_search.py hyperparameter-search demo task (pure Python)
+  payloads.json  six shards with varying cost
+```

gpumesh-0.1.0/gpumesh/__init__.py

@@ -0,0 +1,3 @@
+"""gpumesh - distributed compute sharing over a mesh of volunteer machines."""
+
+__version__ = "0.1.0"

gpumesh-0.1.0/gpumesh/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running gpumesh as a module: python -m gpumesh"""
+
+from .cli import main
+
+main()

gpumesh-0.1.0/gpumesh/capability.py

@@ -0,0 +1,148 @@
+"""Hardware probing and benchmarking.
+
+Detects the best compute device available and produces a single numeric
+capability score used by the scheduler. torch and psutil are optional:
+without them the probe falls back to CPU info and a pure-Python benchmark.
+
+GPU detection uses nvidia-smi (no PyTorch required for detection).
+PyTorch with CUDA is auto-installed when a GPU is detected.
+"""
+
+import os
+import platform
+import shutil
+import socket
+import subprocess
+import sys
+import time
+
+
+def _detect_nvidia_gpu() -> dict:
+    """Detect NVIDIA GPU using nvidia-smi (no PyTorch required)."""
+    if shutil.which("nvidia-smi") is None:
+        return None
+    try:
+        result = subprocess.run(
+            ["nvidia-smi", "--query-gpu=name,memory.total", "--format=csv,noheader,nounits"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            parts = result.stdout.strip().split(",")
+            name = parts[0].strip()
+            memory = parts[1].strip() if len(parts) > 1 else "unknown"
+            return {"name": name, "memory_mb": memory}
+    except (subprocess.SubprocessError, FileNotFoundError):
+        pass
+    return None
+
+
+def _install_pytorch_cuda():
+    """Install PyTorch with CUDA support if NVIDIA GPU detected."""
+    print("[mesh] NVIDIA GPU detected, installing PyTorch with CUDA support...")
+    try:
+        subprocess.run(
+            [sys.executable, "-m", "pip", "install", "torch", "torchvision", "torchaudio",
+             "--index-url", "https://download.pytorch.org/whl/cu118"],
+            check=True,
+            timeout=300,
+        )
+        print("[mesh] PyTorch with CUDA installed successfully!")
+        return True
+    except (subprocess.CalledProcessError, subprocess.TimeoutExpired) as e:
+        print(f"[mesh] Failed to install PyTorch: {e}")
+        print("[mesh] Continuing with CPU-only mode.")
+        return False
+
+
+def probe_device() -> dict:
+    info = {
+        "hostname": socket.gethostname(),
+        "platform": platform.platform(),
+        "cpu_count": os.cpu_count() or 1,
+        "device": "cpu",
+        "device_name": platform.processor() or "cpu",
+    }
+    
+    # First check for NVIDIA GPU using nvidia-smi (fast, no PyTorch needed)
+    nvidia_gpu = _detect_nvidia_gpu()
+    if nvidia_gpu:
+        info["nvidia_gpu"] = nvidia_gpu["name"]
+        info["nvidia_memory"] = nvidia_gpu["memory_mb"]
+    
+    # Try to use PyTorch for GPU detection and benchmarking
+    try:
+        import torch
+        if torch.cuda.is_available():
+            info["device"] = "cuda"
+            info["device_name"] = torch.cuda.get_device_name(0)
+        elif getattr(torch.backends, "mps", None) and torch.backends.mps.is_available():
+            info["device"] = "mps"
+            info["device_name"] = "Apple Silicon GPU"
+    except ImportError:
+        # PyTorch not installed - try to auto-install if NVIDIA GPU detected
+        if nvidia_gpu:
+            if _install_pytorch_cuda():
+                try:
+                    import torch
+                    if torch.cuda.is_available():
+                        info["device"] = "cuda"
+                        info["device_name"] = torch.cuda.get_device_name(0)
+                except Exception:
+                    pass
+    
+    try:
+        import psutil
+        info["ram_gb"] = round(psutil.virtual_memory().total / 1e9, 1)
+    except ImportError:
+        pass
+    
+    return info
+
+
+def _bench_torch(device: str) -> float:
+    """Time a matmul on the given torch device; return ops/sec score."""
+    import torch
+
+    n = 1024
+    a = torch.rand(n, n, device=device)
+    b = torch.rand(n, n, device=device)
+    # warmup
+    (a @ b).sum().item()
+    start = time.perf_counter()
+    iters = 10
+    for _ in range(iters):
+        c = a @ b
+    c.sum().item()  # force sync on cuda/mps
+    elapsed = time.perf_counter() - start
+    flops = 2 * n**3 * iters
+    return flops / elapsed / 1e9  # GFLOP/s
+
+
+def _bench_python() -> float:
+    """Pure-Python matmul fallback. Slow by design; scores are comparable
+    across machines because everyone runs the same loop."""
+    n = 48
+    a = [[(i * j) % 7 / 7.0 for j in range(n)] for i in range(n)]
+    b = [[(i + j) % 5 / 5.0 for j in range(n)] for i in range(n)]
+    start = time.perf_counter()
+    iters = 5
+    for _ in range(iters):
+        [[sum(a[i][k] * b[k][j] for k in range(n)) for j in range(n)] for i in range(n)]
+    elapsed = time.perf_counter() - start
+    flops = 2 * n**3 * iters
+    return flops / elapsed / 1e9
+
+
+def benchmark(device: str) -> float:
+    try:
+        return round(_bench_torch(device), 3)
+    except ImportError:
+        return round(_bench_python(), 3)
+
+
+def full_probe() -> dict:
+    info = probe_device()
+    info["score"] = benchmark(info["device"])
+    return info

gpumesh-0.1.0/gpumesh/cli.py

@@ -0,0 +1,225 @@
+"""gpumesh command line interface.
+
+  gpumesh serve      [--port 8000] [--token SECRET] [--public]
+  gpumesh join       URL [--token SECRET]
+  gpumesh quickjoin  URL --token TOKEN    # One-click setup & join
+  gpumesh submit     SCRIPT --payloads FILE [--wait] --url URL [--token SECRET]
+  gpumesh status     JOB_ID --url URL [--token SECRET]
+  gpumesh cancel     JOB_ID --url URL [--token SECRET]
+  gpumesh workers    --url URL [--token SECRET]
+"""
+
+import argparse
+import os
+import secrets
+import socket
+import subprocess
+import sys
+
+from . import client, server, tunnel, worker
+
+
+def _lan_ip() -> str:
+    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        s.connect(("8.8.8.8", 80))
+        return s.getsockname()[0]
+    except OSError:
+        return "127.0.0.1"
+    finally:
+        s.close()
+
+
+def cmd_serve(args):
+    token = args.token or secrets.token_urlsafe(12)
+    httpd = server.serve("0.0.0.0", args.port, args.db, token)
+    ip = _lan_ip()
+    print(f"[mesh] coordinator listening on 0.0.0.0:{args.port}")
+    print(f"[mesh] token: {token}")
+    print(f"[mesh] LAN join command:")
+    print(f"       gpumesh join http://{ip}:{args.port} --token {token}")
+    if args.public:
+        tunnel.open_tunnel(args.port)
+    print("[mesh] Ctrl+C to stop")
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        print("\n[mesh] shutting down")
+        httpd.gpumesh_stop.set()
+        httpd.shutdown()
+
+
+def cmd_join(args):
+    worker.run_worker(args.url, args.token, task_timeout=args.timeout)
+
+
+def cmd_submit(args):
+    job_id = client.submit_job(args.url, args.token, args.script,
+                               args.payloads, name=args.name)
+    print(f"[client] submitted job {job_id}")
+    if args.wait:
+        job = client.wait_for_job(args.url, args.token, job_id)
+        client.print_job(job)
+    else:
+        print(f"[client] check progress: gpumesh status {job_id}"
+              f" --url {args.url} --token {args.token}")
+
+
+def cmd_status(args):
+    job = client.get_status(args.url, args.token, args.job_id)
+    client.print_job(job)
+
+
+def cmd_cancel(args):
+    result = client.cancel_job(args.url, args.token, args.job_id)
+    if result is None:
+        print(f"[client] job {args.job_id} not found")
+    else:
+        print(f"[client] cancelled job {args.job_id}")
+        print(f"  pending tasks cancelled: {result['pending']}")
+        print(f"  running tasks cancelled: {result['running']}")
+        print(f"  already finished: {result['already_finished']}")
+
+
+def cmd_workers(args):
+    from .worker import MeshClient
+
+    resp = MeshClient(args.url, args.token).call("GET", "/api/workers")
+    for w in resp["workers"]:
+        state = "alive" if w["alive"] else "dead"
+        print(f"  {w['id']}  {w['hostname']:<20} {w['device']:<5} "
+              f"score={w['score']:<10} [{state}]")
+    if not resp["workers"]:
+        print("  (no workers yet)")
+
+
+def cmd_quickjoin(args):
+    """One-click setup: install dependencies, detect GPU, and join mesh."""
+    url = args.url
+    token = args.token
+    
+    print("[mesh] Quick Join - Setting up your machine as a worker...")
+    print()
+    
+    # Step 1: Check Python version
+    print("[1/4] Checking Python version...")
+    if sys.version_info < (3, 9):
+        print("[mesh] ERROR: Python 3.9 or higher is required.")
+        print("[mesh] Please install Python 3.9+ from https://www.python.org/downloads/")
+        return
+    print(f"[mesh] Python {sys.version_info.major}.{sys.version_info.minor} ✓")
+    
+    # Step 2: Install gpumesh if not already installed
+    print("[2/4] Checking gpumesh installation...")
+    try:
+        import gpumesh
+        print("[mesh] gpumesh already installed ✓")
+    except ImportError:
+        print("[mesh] Installing gpumesh...")
+        try:
+            subprocess.run(
+                [sys.executable, "-m", "pip", "install", "-e", "."],
+                check=True,
+                timeout=120,
+            )
+            print("[mesh] gpumesh installed ✓")
+        except (subprocess.CalledProcessError, subprocess.TimeoutExpired) as e:
+            print(f"[mesh] ERROR: Failed to install gpumesh: {e}")
+            print("[mesh] Please install manually: pip install gpumesh")
+            return
+    
+    # Step 3: Detect hardware and install GPU support if needed
+    print("[3/4] Detecting hardware...")
+    from . import capability
+    
+    # Check for NVIDIA GPU using nvidia-smi
+    nvidia_gpu = capability._detect_nvidia_gpu()
+    if nvidia_gpu:
+        print(f"[mesh] NVIDIA GPU detected: {nvidia_gpu['name']}")
+        
+        # Check if PyTorch with CUDA is available
+        try:
+            import torch
+            if torch.cuda.is_available():
+                print(f"[mesh] PyTorch with CUDA ready ✓")
+            else:
+                print("[mesh] PyTorch installed but CUDA not available")
+                capability._install_pytorch_cuda()
+        except ImportError:
+            print("[mesh] PyTorch not found, installing with CUDA support...")
+            capability._install_pytorch_cuda()
+    else:
+        print("[mesh] No NVIDIA GPU detected, using CPU")
+    
+    # Step 4: Join the mesh
+    print("[4/4] Joining the mesh...")
+    print(f"[mesh] Connecting to {url}...")
+    print()
+    
+    # Now run the normal join command
+    worker.run_worker(url, token)
+
+
+def _add_conn_args(p):
+    p.add_argument("--url", default=os.environ.get("GPUMESH_URL", ""),
+                   help="coordinator URL (or set GPUMESH_URL)")
+    p.add_argument("--token", default=os.environ.get("GPUMESH_TOKEN", ""),
+                   help="shared auth token (or set GPUMESH_TOKEN)")
+
+
+def main():
+    ap = argparse.ArgumentParser(prog="gpumesh",
+                                 description="borrow your friends' GPUs")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("serve", help="start a coordinator on this machine")
+    p.add_argument("--port", type=int, default=8000)
+    p.add_argument("--db", default="gpumesh.db")
+    p.add_argument("--token", default="", help="auth token (random if omitted)")
+    p.add_argument("--public", action="store_true",
+                   help="expose a public URL via ngrok")
+    p.set_defaults(func=cmd_serve)
+
+    p = sub.add_parser("join", help="offer this machine's compute to a mesh")
+    p.add_argument("url", help="coordinator URL")
+    p.add_argument("--token", default=os.environ.get("GPUMESH_TOKEN", ""))
+    p.add_argument("--timeout", type=float, default=240.0,
+                   help="per-task wall clock limit in seconds")
+    p.set_defaults(func=cmd_join)
+
+    p = sub.add_parser("submit", help="submit a job to the mesh")
+    p.add_argument("script", help="python script to run for every payload")
+    p.add_argument("--payloads", required=True,
+                   help="JSON file: list of payload objects (each may set 'cost')")
+    p.add_argument("--name", default="")
+    p.add_argument("--wait", action="store_true", help="block until finished")
+    _add_conn_args(p)
+    p.set_defaults(func=cmd_submit)
+
+    p = sub.add_parser("status", help="show job progress and results")
+    p.add_argument("job_id")
+    _add_conn_args(p)
+    p.set_defaults(func=cmd_status)
+
+    p = sub.add_parser("cancel", help="cancel a running job")
+    p.add_argument("job_id")
+    _add_conn_args(p)
+    p.set_defaults(func=cmd_cancel)
+
+    p = sub.add_parser("quickjoin", help="one-click setup: install, detect GPU, and join mesh")
+    p.add_argument("url", help="coordinator URL")
+    p.add_argument("--token", required=True, help="shared auth token")
+    p.set_defaults(func=cmd_quickjoin)
+
+    p = sub.add_parser("workers", help="list workers in the mesh")
+    _add_conn_args(p)
+    p.set_defaults(func=cmd_workers)
+
+    args = ap.parse_args()
+    if hasattr(args, "url") and not args.url and args.cmd != "serve":
+        ap.error("--url required (or set GPUMESH_URL)")
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()