badgr-cli 1.1.7 → 1.1.8

package/README.md

@@ -547,9 +547,25 @@ badgr serve meta-llama/Llama-3.1-8B-Instruct --target gpu-box-1
 
 A connected node is **private by default** — it is never marketplace-listed or shared; only you can target it, and only with `--target`. Marketplace listing, payout, and reputation scoring are not built yet (explicit follow-up phases).
 
+### Host-bound dependencies (venvs, patched source, model/cache dirs)
+
+Jobs run inside a Docker container, which starts with none of this machine's filesystem visible except what's explicitly mounted. If your launch command depends on paths that already exist on this host — a Python venv, a patched source checkout (e.g. a custom-built vLLM), a model directory, a pip/HuggingFace cache — those paths will **not** exist inside the container unless you mount them:
+
+```bash
+badgr node connect \
+  --mount /home/you/venvs/vllm:/opt/venv \
+  --mount /home/you/vllm-src:/opt/vllm-src \
+  --mount /sync/Models:/models:ro \
+  --mount /home/you/.cache:/root/.cache
+```
+
+Each `--mount` is `HOST:CONTAINER` or `HOST:CONTAINER:ro` (same shape as `docker run -v`), repeatable, and both sides must be absolute paths. Mounts are configured once per node (not per job) and applied to every job that node runs. If you connected without `--mount` and the worker is already running, stop it and restart with the printed `python3 .../node_worker.py ...` command plus your `--mount` flags — there is no separate command to add a mount to an already-running worker yet.
+
+An exact command that already works when you run it directly on this machine can still fail through `--target` if it references host paths you haven't mounted — that's a mounting gap, not a vendor/architecture/capacity one (see the BYO Preflight vendor/architecture checks above, which catch a different class of mismatch and pass independently of whether paths are mounted).
+
 | Command | What it does |
 |---------|-------------|
-| `badgr node connect [--name <name>]` | Register this machine and start its worker |
+| `badgr node connect [--name <name>] [--mount HOST:CONTAINER[:ro] ...]` | Register this machine and start its worker |
 | `badgr node list` | List your connected nodes |
 | `badgr node inspect <node-id>` | Show one node's full detail as JSON |
 | `badgr node disable <node-id>` | Stop a node from receiving new jobs |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "badgr-cli",
-  "version": "1.1.7",
+  "version": "1.1.8",
   "description": "Badgr — run or serve GPU workloads from one command",
   "type": "module",
   "bin": {

package/src/commands/node.js

@@ -71,13 +71,16 @@ function python3Available() {
   }
 }
 
-function startWorker(config, node) {
+function startWorker(config, node, mounts = []) {
   const logDir = path.join(os.homedir(), '.badgr', 'logs');
   fs.mkdirSync(logDir, { recursive: true });
   const logPath = path.join(logDir, `node-${node.node_id}.log`);
   const workerArgs = [
     WORKER_SCRIPT, '--node-id', node.node_id, '--api-key', config.apiKey, '--base-url', config.baseUrl,
   ];
+  for (const mount of mounts) {
+    workerArgs.push('--mount', mount);
+  }
   // Header line makes it obvious in the log file which `connect` invocation
   // spawned this worker run (helpful when a node is connected more than
   // once, or the worker is restarted) without needing to inspect argv.
@@ -114,15 +117,30 @@ function detectHardware() {
 }
 
 function parseFlags(args) {
-  const flags = {};
+  const flags = { mounts: [] };
   let i = 0;
   while (i < args.length) {
     if (args[i] === '--name') { flags.name = args[++i]; i++; continue; }
+    if (args[i] === '--mount') { flags.mounts.push(args[++i]); i++; continue; }
     i++;
   }
   return flags;
 }
 
+const MOUNT_RE = /^(\/[^:]+):(\/[^:]+)(:ro)?$/;
+
+function validateMounts(mounts, chalk) {
+  for (const spec of mounts) {
+    if (!MOUNT_RE.test(spec)) {
+      console.error(chalk.red(
+        `\n  ✗ Invalid --mount "${spec}": expected HOST:CONTAINER or HOST:CONTAINER:ro with absolute paths on both sides.\n`,
+      ));
+      return false;
+    }
+  }
+  return true;
+}
+
 function resolveNodeIdArg(config, args) {
   return args.find((a) => !a.startsWith('--'));
 }
@@ -134,6 +152,10 @@ export async function nodeCommand(config, args, chalk) {
 
   if (sub === 'connect') {
     const flags = parseFlags(rest);
+    if (!validateMounts(flags.mounts, chalk)) {
+      process.exitCode = 1;
+      return;
+    }
     const hardware = detectHardware();
     console.log(chalk.dim(
       `  Detected: vendor=${hardware.gpu_vendor || 'none'} gpu_count=${hardware.gpu_count} gpu_model=${hardware.gpu_model || 'none'} `
@@ -166,12 +188,16 @@ export async function nodeCommand(config, args, chalk) {
       ].filter(Boolean).join(', ');
       console.log(chalk.yellow(`  Not starting the worker automatically — missing: ${missing}.`));
       console.log(`  Once fixed, start it with:`);
-      console.log(chalk.cyan(`    python3 "${WORKER_SCRIPT}" --node-id ${node.node_id} --api-key <your-api-key>\n`));
+      const mountArgs = flags.mounts.map((m) => `--mount ${m}`).join(' ');
+      console.log(chalk.cyan(`    python3 "${WORKER_SCRIPT}" --node-id ${node.node_id} --api-key <your-api-key>${mountArgs ? ` ${mountArgs}` : ''}\n`));
       return;
     }
 
-    const { pid, logPath } = startWorker(config, node);
+    const { pid, logPath } = startWorker(config, node, flags.mounts);
     console.log(`  Worker started (pid ${pid}) — this node is now receiving jobs.`);
+    if (flags.mounts.length) {
+      console.log(chalk.dim(`    Host mounts: ${flags.mounts.join(', ')}`));
+    }
     console.log(chalk.dim(`    Logs: ${logPath}\n`));
     return;
   }
@@ -242,7 +268,8 @@ export async function nodeCommand(config, args, chalk) {
   }
 
   console.log(chalk.bold('\nbadgr node — manage your own connected GPUs\n'));
-  console.log('  badgr node connect [--name <name>]   Connect this machine\'s GPU (private)');
+  console.log('  badgr node connect [--name <name>] [--mount HOST:CONTAINER[:ro] ...]');
+  console.log('                                        Connect this machine\'s GPU (private)');
   console.log('  badgr node list                      List your connected nodes');
   console.log('  badgr node inspect <node-id>          Show one node\'s details');
   console.log('  badgr node disable <node-id>          Stop a node from receiving new jobs');

package/src/nodeWorker/node_worker.py

@@ -12,6 +12,18 @@ standard NVIDIA Container Toolkit flag) on NVIDIA, or the ROCm container
 device flags (`--device=/dev/kfd --device=/dev/dri --group-add video
 --group-add render --security-opt seccomp=unconfined`) on AMD — no
 Slurm/Kubernetes, per this PR's locked scope.
+
+The container starts with none of this machine's filesystem visible except
+what's explicitly bind-mounted. A workload whose launch command depends on
+host paths that already exist on this machine (a Python venv, a patched
+source checkout, a model directory, a HuggingFace/pip cache) will not find
+them inside the container unless this worker was started with `--mount
+HOST:CONTAINER[:ro]` (repeatable; same shape as `docker run -v`) for each
+one — see `--mount` in `main()`'s argparse setup and `badgr node connect
+--mount`. These are static, host-bound paths configured once per node, not
+part of a per-job plan: the backend has no visibility into what exists on
+a customer's own machine, so it never sends mount paths — only this
+worker, run by the machine's owner, can name them.
 A "job" workload runs to completion and reports its real exit code. An
 "endpoint" workload (badgr serve) runs detached and is reported "running"
 only after a real readiness check (GET health_path) and, when a model was
@@ -56,6 +68,37 @@ _RESULT_RE = re.compile(r"BADGR_RESULT=(PASS|FAIL)")
 # a long model load, so a tail -f doesn't look hung for minutes at a time.
 READINESS_LOG_EVERY_N_POLLS = 5
 
+# HOST:CONTAINER or HOST:CONTAINER:ro -- same shape docker itself takes for
+# `-v`. Requires absolute paths on both sides so a relative path (which
+# would resolve against whatever directory the worker daemon happens to be
+# started from, not the customer's intent) fails fast at startup instead of
+# silently mounting the wrong thing.
+_MOUNT_RE = re.compile(r"^(/[^:]+):(/[^:]+)(?::(ro))?$")
+
+
+def _parse_mount(spec: str) -> tuple[str, str, bool]:
+    """Validates and splits one `--mount` value. Raises ValueError with a
+    user-facing reason on anything malformed, since a bad mount spec should
+    stop the worker from starting rather than fail confusingly on the first
+    job."""
+    m = _MOUNT_RE.match(spec)
+    if not m:
+        raise ValueError(
+            f"invalid --mount {spec!r}: expected HOST:CONTAINER or HOST:CONTAINER:ro "
+            "with absolute paths on both sides"
+        )
+    host, container, ro = m.group(1), m.group(2), m.group(3)
+    return host, container, bool(ro)
+
+
+def _mount_docker_args(mounts: list[str] | None) -> list[str]:
+    """`-v` flags for every configured host mount. See module docstring."""
+    args: list[str] = []
+    for spec in mounts or []:
+        host, container, ro = _parse_mount(spec)
+        args += ["-v", f"{host}:{container}" + (":ro" if ro else "")]
+    return args
+
 
 def _detect_gpu_vendor() -> str | None:
     """One-time, read-only vendor probe (mirrors the CLI's own
@@ -175,7 +218,7 @@ def _parse_diagnostic_result(log_tail: str) -> str | None:
     return None
 
 
-def _run_job(base_url: str, api_key: str, node_id: str, job_id: str, plan: dict, gpu_vendor: str | None = None) -> None:
+def _run_job(base_url: str, api_key: str, node_id: str, job_id: str, plan: dict, gpu_vendor: str | None = None, mounts: list[str] | None = None) -> None:
     image = plan.get("image")
     command = plan.get("command") or []
     env = plan.get("env") or {}
@@ -187,7 +230,7 @@ def _run_job(base_url: str, api_key: str, node_id: str, job_id: str, plan: dict,
     max_runtime_seconds = plan.get("max_runtime_seconds") or DEFAULT_JOB_TIMEOUT_SECONDS
 
     container_name = f"badgr-job-{job_id}"
-    docker_cmd = ["docker", "run", *_gpu_docker_args(gpu_vendor), "--name", container_name]
+    docker_cmd = ["docker", "run", *_gpu_docker_args(gpu_vendor), *_mount_docker_args(mounts), "--name", container_name]
     docker_cmd += ["--rm"] if not is_endpoint else ["-d"]
     if privileged:
         # Bounded host diagnostics (NVLink/P2P/FabricManager/dmesg checks)
@@ -289,11 +332,22 @@ def main() -> None:
     parser.add_argument("--node-id", required=True, help="node_… id from `badgr node connect`")
     parser.add_argument("--api-key", required=True, help="badgr CLI API key (same one `badgr login` stored)")
     parser.add_argument("--base-url", default="https://aibadgr.com/v1")
+    parser.add_argument(
+        "--mount", action="append", default=[], metavar="HOST:CONTAINER[:ro]",
+        help="Bind-mount a host path into every job's container (repeatable). "
+             "Use for host-bound dependencies (venvs, patched source, model/cache "
+             "dirs) this workload's command expects to already exist on disk.",
+    )
     args = parser.parse_args()
 
+    for spec in args.mount:
+        _parse_mount(spec)  # fail fast at startup on a malformed --mount, not mid-job
+
     gpu_vendor = _detect_gpu_vendor()
     _log("INFO", f"worker starting for node_id={args.node_id} against {args.base_url}")
     _log("INFO", f"gpu_vendor={gpu_vendor or 'unknown'} (docker run device flags: {' '.join(_gpu_docker_args(gpu_vendor))})")
+    if args.mount:
+        _log("INFO", f"host mounts: {', '.join(args.mount)}")
     _log("INFO", f"heartbeat_interval={HEARTBEAT_INTERVAL_SECONDS}s poll_interval={POLL_INTERVAL_SECONDS}s")
     last_heartbeat = 0.0
     while True:
@@ -315,7 +369,7 @@ def main() -> None:
         if job.get("job_id"):
             _log("INFO", f"received job {job['job_id']} from poll")
             try:
-                _run_job(args.base_url, args.api_key, args.node_id, job["job_id"], job.get("plan") or {}, gpu_vendor)
+                _run_job(args.base_url, args.api_key, args.node_id, job["job_id"], job.get("plan") or {}, gpu_vendor, args.mount)
             except Exception:  # noqa: BLE001 — a bug in job handling must not silently kill the worker loop
                 _log("ERROR", f"unhandled exception while running job {job['job_id']}:\n{traceback.format_exc()}")
         else:

package/src/nodeWorker/test_node_worker.py

@@ -146,6 +146,61 @@ def test_gpu_docker_args_defaults_to_nvidia_flag_when_vendor_unknown():
     assert node_worker._gpu_docker_args(None) == ["--gpus", "all"]
 
 
+def test_mount_docker_args_builds_v_flags():
+    args = node_worker._mount_docker_args([
+        "/home/faisal/venvs/vllm:/opt/venv",
+        "/home/faisal/.cache:/root/.cache:ro",
+    ])
+    assert args == [
+        "-v", "/home/faisal/venvs/vllm:/opt/venv",
+        "-v", "/home/faisal/.cache:/root/.cache:ro",
+    ]
+
+
+def test_mount_docker_args_empty_when_no_mounts():
+    assert node_worker._mount_docker_args(None) == []
+    assert node_worker._mount_docker_args([]) == []
+
+
+def test_parse_mount_rejects_relative_path():
+    import pytest
+    with pytest.raises(ValueError):
+        node_worker._parse_mount("relative/path:/container/path")
+
+
+def test_parse_mount_rejects_malformed_spec():
+    import pytest
+    with pytest.raises(ValueError):
+        node_worker._parse_mount("/only/one/path")
+
+
+def test_run_job_includes_configured_mounts_in_docker_command(monkeypatch):
+    captured_cmds = []
+
+    class _FakeProc:
+        pid = 4242
+        returncode = 0
+        stdout = None
+
+        def poll(self):
+            return 0
+
+    monkeypatch.setattr(node_worker.subprocess, "Popen", lambda cmd, **kw: captured_cmds.append(cmd) or _FakeProc())
+    monkeypatch.setattr(node_worker, "_api", lambda *a, **kw: {})
+
+    node_worker._run_job(
+        "https://x/v1", "key", "node_1", "job_6",
+        {"image": "vllm/vllm-openai:latest", "command": ["python", "-m", "vllm.entrypoints.openai.api_server"]},
+        "nvidia",
+        ["/home/faisal/vllm-src:/opt/vllm-src", "/sync/Models:/models:ro"],
+    )
+
+    docker_cmd = captured_cmds[0]
+    assert "-v" in docker_cmd
+    assert "/home/faisal/vllm-src:/opt/vllm-src" in docker_cmd
+    assert "/sync/Models:/models:ro" in docker_cmd
+
+
 def test_job_exceeding_max_runtime_is_killed_and_reported(monkeypatch):
     """A hung diagnostic must not wedge the worker forever -- the loop kills
     the named container once max_runtime_seconds elapses and reports a