icefold-runner 0.1.0__py3-none-any.whl

icefold_runner/__init__.py

@@ -0,0 +1,26 @@
+"""icefold-runner — a self-hosted execution runner for IceFold nodes.
+
+Like a GitHub self-hosted CI runner: you start it on your own machine, it
+reverse-connects to an IceFold server, receives node-execution jobs, and runs
+them locally — pulling input media over HTTP and pushing products back.
+
+The runner is a *generic execution framework*: it ships no node implementations
+of its own. The server renders each node into a self-contained ``.py`` bundle;
+the runner fetches the bundle on demand, pre-flights its declared dependencies,
+and runs it. So upgrading or adding nodes on the server never requires updating
+the runner.
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__", "WorkerClient", "NodeRunner"]
+
+
+def __getattr__(name):  # lazy so importing the package is cheap
+    if name == "WorkerClient":
+        from icefold_runner.client import WorkerClient
+        return WorkerClient
+    if name == "NodeRunner":
+        from icefold_runner.runner import NodeRunner
+        return NodeRunner
+    raise AttributeError(name)

icefold_runner/__main__.py

@@ -0,0 +1,75 @@
+"""CLI entrypoint:  icefold-runner --token <token>
+
+Run IceFold nodes on this machine. The runner reverse-connects to IceFold and
+serves the account the token belongs to — the token (generated in the IceFold
+app, Nodes ▸ Connect a runner) encodes + signs your user id, so there's no
+server URL or user id to pass.
+
+Bootstrap order matters: we point ``ICEFOLD_PROJECT_ROOT`` at the runner's
+``--work-dir`` *before* importing ``icefold``, so the SDK's ``DATA_DIR``
+(hence where ffmpeg writes products) resolves under this runner's own dir.
+``icefold`` itself is an installed dependency (``pip install icefold-sdk``).
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import socket
+
+# Built-in server. Self-hosters / dev can override via the ICEFOLD_RUNNER_SERVER
+# env var (intentionally not a CLI flag — the normal user never sets it).
+DEFAULT_SERVER = "wss://api.icefold.com"
+
+
+def _parse_args(argv):
+    p = argparse.ArgumentParser(
+        prog="icefold-runner",
+        description="Run IceFold nodes on this machine. "
+                    "Get a token from the IceFold app (Nodes ▸ Connect a runner).",
+    )
+    p.add_argument("--token", default=os.environ.get("ICEFOLD_RUNNER_TOKEN", ""),
+                   help="Runner token from the IceFold app. env: ICEFOLD_RUNNER_TOKEN")
+    p.add_argument("--runner-id", default=os.environ.get("ICEFOLD_RUNNER_ID", "") or socket.gethostname(),
+                   help="Stable id for this runner (default: hostname). env: ICEFOLD_RUNNER_ID")
+    p.add_argument("--work-dir",
+                   default=os.environ.get("ICEFOLD_RUNNER_DIR", "") or os.path.abspath("./icefold-runner-data"),
+                   help="Scratch dir for staged inputs + ffmpeg products. env: ICEFOLD_RUNNER_DIR")
+    args = p.parse_args(argv)
+
+    if not args.token:
+        p.error("missing required argument: --token "
+                "(generate one in the IceFold app: Nodes ▸ Connect a runner)")
+    return args
+
+
+def main(argv=None) -> int:
+    args = _parse_args(argv)
+
+    # Built-in server; ICEFOLD_RUNNER_SERVER overrides for self-host / dev.
+    server = os.environ.get("ICEFOLD_RUNNER_SERVER", "").strip() or DEFAULT_SERVER
+
+    work_dir = os.path.abspath(args.work_dir)
+    os.makedirs(os.path.join(work_dir, "data", "download"), exist_ok=True)
+    os.makedirs(os.path.join(work_dir, "data", "upload"), exist_ok=True)
+
+    # Must precede any icefold import so DATA_DIR resolves under work_dir.
+    os.environ["ICEFOLD_PROJECT_ROOT"] = work_dir
+
+    from icefold_runner.client import WorkerClient
+
+    client = WorkerClient(
+        server=server,
+        token=args.token,
+        worker_id=args.runner_id,
+    )
+    try:
+        asyncio.run(client.run_forever())
+    except KeyboardInterrupt:
+        print("\nicefold-runner stopped")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

icefold_runner/client.py

@@ -0,0 +1,306 @@
+"""Reverse WebSocket client for icefold-runner.
+
+Dials out to ``<server>/v1/ws/worker``, authenticates with the shared token
+(also the XOR keystream), then serves leaf ``node_exec`` jobs concurrently.
+Reconnects with jittered exponential backoff; an auth rejection is fatal.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import random
+from typing import Dict, Optional
+from urllib.parse import urlencode, urlsplit, urlunsplit
+
+import websockets
+
+import uuid
+
+from icefold.crypto import xor_bytes
+from icefold.exceptions import MissingDependencyError
+from icefold.wire import (
+    SRV_CANCEL,
+    SRV_NODE_CALLBACK_RESULT,
+    SRV_NODE_EXEC,
+    SRV_PING,
+    WKR_HELLO,
+    WKR_NODE_DONE,
+    WKR_PONG,
+    WKR_PING,
+    make_missing_dep,
+    make_node_callback,
+)
+from icefold_runner import __version__ as VERSION
+from icefold_runner.runner import NodeRunner
+from icefold import log_error, log_info, log_warning
+
+_BACKOFF_MIN = 1.0
+_BACKOFF_MAX = 30.0
+_KEEPALIVE_S = 20.0
+_MAX_FRAME = 8 * 1024 * 1024
+
+
+class AuthError(Exception):
+    """Server rejected our credentials — fatal, retrying won't help."""
+
+
+def _log(level: str, msg: str, **kw) -> None:
+    {"warn": log_warning, "error": log_error}.get(level, log_info)("worker", msg, **kw)
+
+
+class WorkerClient:
+    def __init__(
+        self,
+        *,
+        server: str,
+        token: str,
+        worker_id: str,
+        http_base: Optional[str] = None,
+    ) -> None:
+        self.server = server
+        self.token = token
+        self.worker_id = worker_id
+        self.xor_key = token.encode("utf-8") if token else b""
+        self.http_base = (http_base or self._derive_http_base(server)).rstrip("/")
+        self.runner = NodeRunner(self.http_base, token, _log)
+        self._tasks: Dict[str, asyncio.Task] = {}
+        # Bundle-host callback bookkeeping: bundle code reaches back into the
+        # server via ``ctx.progress(...)`` / ``ctx.llm.text(...)``; those land
+        # here as outbound ``node_callback`` frames keyed by ``req_id`` and
+        # we await the server's matching ``node_callback_result`` to resolve
+        # the bundle's future.
+        self._pending_callbacks: Dict[str, "asyncio.Future[dict]"] = {}
+
+    # ── URL helpers ──
+
+    @staticmethod
+    def _derive_http_base(server: str) -> str:
+        parts = urlsplit(server)
+        scheme = {"ws": "http", "wss": "https"}.get(parts.scheme, parts.scheme or "http")
+        return urlunsplit((scheme, parts.netloc, "", "", ""))
+
+    def _ws_url(self) -> str:
+        parts = urlsplit(self.server)
+        scheme = {"http": "ws", "https": "wss"}.get(parts.scheme, parts.scheme or "ws")
+        path = parts.path.rstrip("/")
+        if not path.endswith("/v1/ws/worker"):
+            path = path + "/v1/ws/worker"
+        # No user_id: the token encodes + signs it; the server derives the
+        # identity from the token so this runner can't claim another account.
+        query = urlencode({
+            "token": self.token,
+            "worker_id": self.worker_id,
+        })
+        return urlunsplit((scheme, parts.netloc, path, query, ""))
+
+    # ── main loop ──
+
+    async def run_forever(self) -> None:
+        _log("info", f"icefold-runner {VERSION} starting",
+             server=self.server, worker_id=self.worker_id)
+        backoff = _BACKOFF_MIN
+        while True:
+            try:
+                await self._run_once()
+                backoff = _BACKOFF_MIN
+                _log("info", "connection closed; will reconnect")
+            except AuthError as e:
+                _log("error", f"authentication failed; exiting: {e}")
+                return
+            except Exception as e:  # noqa: BLE001
+                _log("error", f"connection failed: {e}", next_retry=round(backoff, 1))
+            sleep = backoff + random.uniform(0, backoff / 4)
+            await asyncio.sleep(sleep)
+            backoff = min(backoff * 2, _BACKOFF_MAX)
+
+    async def _run_once(self) -> None:
+        url = self._ws_url()
+        _log("info", "dialing", url=self._redact(url))
+        try:
+            ws = await websockets.connect(
+                url, max_size=_MAX_FRAME, open_timeout=15,
+                ping_interval=_KEEPALIVE_S, ping_timeout=_KEEPALIVE_S,
+            )
+        except Exception as e:  # noqa: BLE001
+            if self._is_auth_rejection(e):
+                raise AuthError(str(e))
+            raise
+        async with ws:
+            await self._send(ws, {
+                "type": WKR_HELLO,
+                "worker_id": self.worker_id,
+                "version": VERSION,
+                "capabilities": ["builtin"],
+            })
+            _log("info", "connected", worker_id=self.worker_id)
+            keepalive = asyncio.create_task(self._keepalive(ws))
+            try:
+                async for raw in ws:
+                    msg = self._decode(raw)
+                    if msg is not None:
+                        await self._handle(ws, msg)
+            finally:
+                keepalive.cancel()
+                for t in list(self._tasks.values()):
+                    t.cancel()
+                self._tasks.clear()
+
+    async def _keepalive(self, ws) -> None:
+        try:
+            while True:
+                await asyncio.sleep(_KEEPALIVE_S)
+                await self._send(ws, {"type": WKR_PING})
+        except asyncio.CancelledError:
+            pass
+        except Exception:  # noqa: BLE001
+            pass
+
+    # ── frame codec ──
+
+    def _decode(self, raw) -> Optional[dict]:
+        try:
+            if isinstance(raw, (bytes, bytearray)):
+                data = xor_bytes(bytes(raw), self.xor_key) if self.xor_key else bytes(raw)
+                return json.loads(data.decode("utf-8"))
+            return json.loads(raw)
+        except Exception as e:  # noqa: BLE001
+            _log("warn", f"bad frame from server: {e}")
+            return None
+
+    async def _send(self, ws, msg: dict) -> None:
+        payload = json.dumps(msg).encode("utf-8")
+        if self.xor_key:
+            await ws.send(xor_bytes(payload, self.xor_key))
+        else:
+            await ws.send(payload.decode("utf-8"))
+
+    # ── dispatch ──
+
+    async def _handle(self, ws, msg: dict) -> None:
+        mtype = msg.get("type", "")
+        if mtype == SRV_NODE_EXEC:
+            call_id = msg.get("call_id", "")
+            if not call_id:
+                return
+            self._tasks[call_id] = asyncio.create_task(self._run_node(ws, msg))
+        elif mtype == SRV_CANCEL:
+            task = self._tasks.get(msg.get("call_id", ""))
+            if task is not None:
+                task.cancel()
+        elif mtype == SRV_NODE_CALLBACK_RESULT:
+            # Server is replying to a callback the bundle issued via
+            # ctx.progress(...) / ctx.llm.text(...). Look up the awaiter
+            # by req_id and feed it the result; the bundle's coroutine
+            # resumes inside the node's task.
+            req_id = msg.get("req_id", "")
+            fut = self._pending_callbacks.pop(req_id, None)
+            if fut is not None and not fut.done():
+                fut.set_result(msg)
+        elif mtype == SRV_PING:
+            await self._send(ws, {"type": WKR_PONG})
+
+    async def _run_node(self, ws, msg: dict) -> None:
+        call_id = msg["call_id"]
+        node_type = msg.get("node_type", "")
+        try:
+            _log("info", f"running node {node_type}", call_id=call_id)
+            send_callback = self._make_send_callback(ws, call_id)
+            output = await self.runner.run(msg, send_callback=send_callback)
+            await self._send(ws, {
+                "type": WKR_NODE_DONE, "call_id": call_id,
+                "output": output, "err": "", "killed": False,
+            })
+            _log("info", f"node done {node_type}", call_id=call_id)
+        except MissingDependencyError as dep:
+            # Bundle pre-flight detected a missing native/python dep. Send the
+            # typed reply (not node_done) so the server can surface a
+            # user-actionable "install X via …" notification.
+            _log(
+                "warn",
+                f"node {node_type} skipped: missing deps "
+                f"binaries={list(dep.missing_binaries)} python={list(dep.missing_python)}",
+                call_id=call_id,
+            )
+            await self._safe_send(ws, make_missing_dep(
+                call_id=call_id,
+                missing_binaries=dep.missing_binaries,
+                missing_python=dep.missing_python,
+                install_hint=dep.install_hint,
+            ))
+        except asyncio.TimeoutError:
+            await self._safe_send(ws, {
+                "type": WKR_NODE_DONE, "call_id": call_id,
+                "output": None, "err": "remote node timed out", "killed": True,
+            })
+        except asyncio.CancelledError:
+            # Server asked us to cancel (or we're tearing down). The server's
+            # awaiting future is already cancelled, so no node_done is needed.
+            raise
+        except Exception as e:  # noqa: BLE001
+            _log("error", f"node failed {node_type}: {e}", call_id=call_id)
+            await self._safe_send(ws, {
+                "type": WKR_NODE_DONE, "call_id": call_id,
+                "output": None, "err": str(e), "killed": False,
+            })
+        finally:
+            self._tasks.pop(call_id, None)
+            # Fail any still-pending callbacks (e.g. the bundle was cancelled
+            # mid-LLM-call) so the bundle's awaiter doesn't hang on shutdown.
+            for req_id, fut in list(self._pending_callbacks.items()):
+                if not fut.done():
+                    fut.set_result({
+                        "type": SRV_NODE_CALLBACK_RESULT,
+                        "call_id": call_id, "req_id": req_id,
+                        "ok": False, "result": None,
+                        "error": "node ended before callback resolved",
+                    })
+                self._pending_callbacks.pop(req_id, None)
+
+    def _make_send_callback(self, ws, call_id: str):
+        """Return the bundle-host callback sender bound to one node_exec.
+
+        Bundles only ever see this closure (never the raw WS). It allocates
+        a ``req_id``, queues a ``node_callback`` frame, and awaits the
+        server's matching ``node_callback_result``. Result frames where
+        ``ok=False`` are translated into ``RuntimeError`` so the bundle can
+        catch them like any synchronous failure.
+        """
+        loop = asyncio.get_event_loop()
+
+        async def _send(kind: str, payload: dict):
+            req_id = uuid.uuid4().hex
+            fut: "asyncio.Future[dict]" = loop.create_future()
+            self._pending_callbacks[req_id] = fut
+            try:
+                await self._send(ws, make_node_callback(
+                    call_id=call_id, req_id=req_id, kind=kind, payload=payload,
+                ))
+            except Exception:
+                self._pending_callbacks.pop(req_id, None)
+                raise
+            reply = await fut
+            if not reply.get("ok"):
+                raise RuntimeError(reply.get("error") or f"callback {kind!r} failed")
+            return reply.get("result")
+
+        return _send
+
+    async def _safe_send(self, ws, msg: dict) -> None:
+        try:
+            await self._send(ws, msg)
+        except Exception:  # noqa: BLE001
+            pass
+
+    # ── error classification ──
+
+    @staticmethod
+    def _is_auth_rejection(e: Exception) -> bool:
+        resp = getattr(e, "response", None)
+        status = getattr(resp, "status_code", None) or getattr(e, "status_code", None)
+        return status in (401, 403)
+
+    @staticmethod
+    def _redact(url: str) -> str:
+        parts = urlsplit(url)
+        return urlunsplit((parts.scheme, parts.netloc, parts.path, "token=<redacted>", ""))

icefold_runner/runner.py

@@ -0,0 +1,282 @@
+"""Run one leaf node-exec job on this machine.
+
+Each ``node_exec`` frame is a single, already-sliced variant (the server did
+all variant planning) and carries a **bundle hash** — the server has already
+rendered the node into a self-contained ``.py``. The runner ships no node
+implementations of its own and never compiles user source.
+
+Per call:
+
+  1. fetch (cache-aware) ``/v1/bundles/<hash>`` into ``runner_work_dir/bundles/``
+  2. exec the bundle in a fresh module namespace — it self-declares
+     ``__icefold_python_deps__`` / ``__icefold_binary_deps__`` plus the
+     ``async def __icefold_run__(inputs, ctx_dict) -> Any`` entry point
+  3. pre-flight the declared deps (``shutil.which`` + ``import_module``);
+     surface ``MissingDependencyError`` so the client wraps a structured
+     ``missing_dep`` reply instead of ``node_done``
+  4. download ``/upload/`` & ``/download/`` input refs to a staging dir and
+     rewrite them to local paths
+  5. await ``__icefold_run__(local_inputs, ctx_dict)``
+  6. upload product files back to the server and rewrite the output to the
+     server-canonical paths it hands back
+
+Output that isn't a file (text, numbers, None) passes through untouched.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import importlib.util
+import os
+import shutil
+import sys
+from types import ModuleType
+from typing import Any, Dict, List, Tuple
+
+import httpx
+
+# Bundled node SDK (importable via the CLI's _sdk sys.path entry). DATA_DIR
+# reflects this runner's --work-dir because the CLI sets ICEFOLD_PROJECT_ROOT
+# before these imports, so executors write products under our download dir.
+from icefold.config import DATA_DIR
+from icefold.exceptions import MissingDependencyError
+from icefold.wire import OUTPUT_UPLOAD_PATH, binary_install_hint
+
+_STAGED_DIR = os.path.join(DATA_DIR, "staged")
+_BUNDLES_DIR = os.path.join(DATA_DIR, "bundles")
+
+
+def _is_server_ref(value: Any) -> bool:
+    return isinstance(value, str) and (
+        value.startswith("/upload/") or value.startswith("/download/")
+    )
+
+
+def _ext_from_ref(ref: str) -> str:
+    ext = os.path.splitext(ref.split("?", 1)[0])[1].lower()
+    if not ext or len(ext) > 12 or not ext[1:].isalnum():
+        return ""
+    return ext
+
+
+class NodeRunner:
+    """Stateless per-worker runner; one instance shared across jobs."""
+
+    def __init__(self, http_base: str, token: str, log) -> None:
+        self._http_base = http_base.rstrip("/")
+        self._token = token
+        self._log = log
+        # Cache of bundle modules keyed by bundle hash. A bundle is a
+        # self-contained .py; once exec'd we keep the module around for the
+        # lifetime of this runner process.
+        self._bundles: Dict[str, ModuleType] = {}
+        os.makedirs(_STAGED_DIR, exist_ok=True)
+        os.makedirs(_BUNDLES_DIR, exist_ok=True)
+
+    async def run(self, msg: dict, *, send_callback=None) -> Any:
+        """Execute one ``node_exec`` frame against a server-rendered bundle.
+
+        ``send_callback(kind, payload) -> awaitable`` (optional) is the
+        host-injected seam the bundle uses to reach back into the server for
+        capabilities the runner can't fulfil locally — ``progress`` (session
+        notifications) and ``llm.*`` (the server owns the provider keys and
+        accounting). The runner client wires this so the same callable
+        correlates replies via ``req_id``. ``None`` means no host is wired
+        (e.g. self-check), and the bundle's callback methods raise instead of
+        silently no-op'ing.
+        """
+        bundle_hash = msg.get("bundle_hash") or ""
+        if not bundle_hash:
+            node_type = msg.get("node_type") or msg.get("node_id", "")
+            raise RuntimeError(
+                f"node_exec for {node_type!r} arrived without bundle_hash; "
+                "the server must render a bundle via codegen before dispatch"
+            )
+        timeout = max(1.0, msg.get("timeout_ms", 1800_000) / 1000.0)
+
+        async with httpx.AsyncClient(timeout=httpx.Timeout(600.0)) as http:
+            local_inputs = await self._download_inputs(http, msg.get("inputs") or {})
+            output = await asyncio.wait_for(
+                self._run_bundle(http, bundle_hash, msg, local_inputs, send_callback),
+                timeout=timeout,
+            )
+            return await self._upload_outputs(http, output, msg.get("session_id", ""))
+
+    # ── bundle path ──
+
+    async def _run_bundle(
+        self,
+        http: httpx.AsyncClient,
+        bundle_hash: str,
+        msg: dict,
+        local_inputs: Any,
+        send_callback,
+    ) -> Any:
+        """Fetch + pre-flight + exec a server-rendered self-contained bundle."""
+        mod = self._bundles.get(bundle_hash)
+        if mod is None:
+            bundle_path = await self._fetch_bundle(http, bundle_hash, msg.get("bundle_url") or "")
+            mod = self._import_bundle(bundle_hash, bundle_path)
+            self._bundles[bundle_hash] = mod
+
+        # Pre-flight declared deps (binary first, then python). Raise a typed
+        # exception so the client wraps a ``missing_dep`` reply instead of
+        # ``node_done``.
+        self._preflight_deps(
+            tuple(getattr(mod, "__icefold_binary_deps__", ()) or ()),
+            tuple(getattr(mod, "__icefold_python_deps__", ()) or ()),
+        )
+
+        ctx_dict = {
+            "node_id": msg.get("node_id", msg.get("node_type", "")),
+            "node_config": msg.get("node_config") or {},
+            "user_id": msg.get("user_id", ""),
+            "session_id": msg.get("session_id") or None,
+            "space_name": msg.get("space_name") or None,
+            "variant": msg.get("variant") or {},
+            "raw_inputs": local_inputs if isinstance(local_inputs, dict) else {},
+            "provider": msg.get("provider") or {},
+            "model": msg.get("model", ""),
+        }
+        # Bundle-host callback seam: bundles call this via the embedded
+        # NodeContext's ``progress`` / ``llm.text`` methods. The runner
+        # client wires ``send_callback(kind, payload)`` so it correlates
+        # the reply via ``req_id`` and resolves the bundle's awaiter.
+        if send_callback is not None:
+            ctx_dict["_send_callback"] = send_callback
+
+        entry = getattr(mod, "__icefold_run__", None)
+        if entry is None:
+            raise RuntimeError(
+                f"bundle {bundle_hash[:8]} is missing __icefold_run__ entry point"
+            )
+        return await entry(local_inputs if isinstance(local_inputs, dict) else {}, ctx_dict)
+
+    async def _fetch_bundle(
+        self, http: httpx.AsyncClient, bundle_hash: str, bundle_url: str,
+    ) -> str:
+        """Cache-aware bundle fetch. Returns the on-disk path."""
+        path = os.path.join(_BUNDLES_DIR, f"{bundle_hash}.py")
+        if os.path.isfile(path):
+            return path
+        url = bundle_url or f"{self._http_base}/v1/bundles/{bundle_hash}"
+        self._log("info", f"pulling bundle {bundle_hash[:8]}")
+        headers = {"X-Worker-Token": self._token} if self._token else {}
+        async with http.stream("GET", url, headers=headers) as resp:
+            resp.raise_for_status()
+            tmp = path + ".part"
+            with open(tmp, "wb") as fh:
+                async for chunk in resp.aiter_bytes(64 * 1024):
+                    fh.write(chunk)
+            os.replace(tmp, path)
+        # Sanity: re-hash + compare so a corrupted download can't silently exec.
+        with open(path, "rb") as fh:
+            got = hashlib.sha256(fh.read()).hexdigest()
+        if got != bundle_hash:
+            os.unlink(path)
+            raise RuntimeError(
+                f"bundle hash mismatch: expected {bundle_hash[:8]}, got {got[:8]}"
+            )
+        return path
+
+    @staticmethod
+    def _import_bundle(bundle_hash: str, path: str) -> ModuleType:
+        """exec the bundle in a fresh module namespace. No sys.modules pollution."""
+        mod_name = f"_icefold_bundle_{bundle_hash[:16]}"
+        spec = importlib.util.spec_from_file_location(mod_name, path)
+        if spec is None or spec.loader is None:
+            raise RuntimeError(f"failed to create import spec for bundle {bundle_hash[:8]}")
+        mod = importlib.util.module_from_spec(spec)
+        sys.modules[mod_name] = mod
+        try:
+            spec.loader.exec_module(mod)
+        except Exception:
+            sys.modules.pop(mod_name, None)
+            raise
+        return mod
+
+    def _preflight_deps(
+        self, binary_deps: Tuple[str, ...], python_deps: Tuple[str, ...],
+    ) -> None:
+        """Surface a structured ``MissingDependencyError`` when any dep is absent."""
+        missing_bin: List[str] = [b for b in binary_deps if b and shutil.which(b) is None]
+        missing_py: List[str] = []
+        for pkg in python_deps:
+            if not pkg:
+                continue
+            try:
+                __import__(pkg.split(".")[0])
+            except ImportError:
+                missing_py.append(pkg)
+        if not (missing_bin or missing_py):
+            return
+        # Build a platform-aware install hint covering both categories.
+        plat = sys.platform if sys.platform in ("linux", "darwin", "win32") else "linux"
+        lines: List[str] = []
+        for b in missing_bin:
+            lines.append(f"  · {b} (binary) → {binary_install_hint(b, plat)}")
+        for p in missing_py:
+            lines.append(f"  · {p} (python) → pip install {p}")
+        hint = "Install the following on this runner host:\n" + "\n".join(lines)
+        raise MissingDependencyError(
+            missing_binaries=tuple(missing_bin),
+            missing_python=tuple(missing_py),
+            install_hint=hint,
+        )
+
+    # ── input staging (download) ──
+
+    async def _download_inputs(self, http: httpx.AsyncClient, inputs: Any) -> Any:
+        if isinstance(inputs, str):
+            if _is_server_ref(inputs):
+                return await self._download_one(http, inputs)
+            return inputs
+        if isinstance(inputs, dict):
+            return {k: await self._download_inputs(http, v) for k, v in inputs.items()}
+        if isinstance(inputs, (list, tuple)):
+            return [await self._download_inputs(http, v) for v in inputs]
+        return inputs
+
+    async def _download_one(self, http: httpx.AsyncClient, ref: str) -> str:
+        url = self._http_base + ref
+        dest = os.path.join(_STAGED_DIR, f"{os.urandom(8).hex()}{_ext_from_ref(ref)}")
+        self._log("info", f"pulling input {ref}")
+        async with http.stream("GET", url) as resp:
+            resp.raise_for_status()
+            with open(dest, "wb") as fh:
+                async for chunk in resp.aiter_bytes(1024 * 1024):
+                    fh.write(chunk)
+        return dest
+
+    # ── output staging (upload) ──
+
+    async def _upload_outputs(self, http: httpx.AsyncClient, output: Any, session_id: str) -> Any:
+        if isinstance(output, str):
+            if output and os.path.isfile(output) and os.path.abspath(output).startswith(
+                os.path.abspath(DATA_DIR)
+            ):
+                return await self._upload_one(http, output, session_id)
+            return output
+        if isinstance(output, dict):
+            return {k: await self._upload_outputs(http, v, session_id) for k, v in output.items()}
+        if isinstance(output, (list, tuple)):
+            return [await self._upload_outputs(http, v, session_id) for v in output]
+        return output
+
+    async def _upload_one(self, http: httpx.AsyncClient, path: str, session_id: str) -> str:
+        url = self._http_base + OUTPUT_UPLOAD_PATH
+        self._log("info", f"pushing product {os.path.basename(path)}")
+        headers = {"X-Worker-Token": self._token} if self._token else {}
+        with open(path, "rb") as fh:
+            resp = await http.post(
+                url,
+                headers=headers,
+                data={"session_id": session_id or ""},
+                files={"file": (os.path.basename(path), fh, "application/octet-stream")},
+            )
+        resp.raise_for_status()
+        server_path = resp.json().get("path")
+        if not server_path:
+            raise RuntimeError("server did not return a stored path for output")
+        return server_path

icefold_runner-0.1.0.dist-info/METADATA

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: icefold-runner
+Version: 0.1.0
+Summary: Self-hosted execution runner for IceFold nodes (reverse-connects to an IceFold server, like a self-hosted CI runner).
+Author: IceFold
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/IceFold/icefold-runner
+Project-URL: Repository, https://github.com/IceFold/icefold-runner
+Keywords: icefold,runner,self-hosted,node-execution
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: icefold-sdk>=0.1.0
+Requires-Dist: websockets>=12
+Requires-Dist: httpx>=0.27
+Dynamic: license-file
+
+# icefold-runner
+
+A self-hosted execution runner for [IceFold](https://icefold.com) nodes — like
+a GitHub self-hosted CI runner. You start it on your own machine; it
+**reverse-connects** to an IceFold server (so it works behind NAT with no
+inbound ports, no public IP, no tunnel), receives node-execution jobs, runs them
+locally, and streams results back.
+
+It is the place where **your uploaded node code runs** — on your hardware, with
+full `subprocess` / `ffmpeg` / GPU / any-dependency access — instead of inside
+the server's restricted sandbox.
+
+## How it works
+
+```
+   your machine (private, behind NAT)              IceFold server (public)
+ ┌──────────────────────────────────┐  reverse WSS  ┌───────────────────────────┐
+ │ icefold-runner                    │ ───────────► │ /v1/ws/worker?token         │
+ │  • dials out, token auth          │  node_exec ◄─│ routes node runs (per user) │
+ │  • reconnect + keepalive          │  node_done ─►│                             │
+ │  • bundle runner:                 │              │                             │
+ │    GET /v1/bundles/<hash>         │   HTTP pull  │ /upload  /download          │
+ │    import bundle + preflight deps │ ◄──────────► │ /v1/workers/output          │
+ │    await __icefold_run__          │              │                             │
+ └──────────────────────────────────┘   HTTP push  └───────────────────────────┘
+```
+
+- **Control plane** rides the reverse WebSocket (`node_exec` / `cancel` →
+  `node_status` / `node_done` / `missing_dep`), JSON frames XOR-obfuscated with
+  the token (TLS still does the real protection). Each `node_exec` frame only
+  carries a `bundle_hash` and a single already-sliced variant — no source.
+- **Bulk media + bundles** ride plain HTTP: the runner GETs inputs from the
+  server's `/upload` & `/download` and node bundles from `/v1/bundles/<hash>`
+  (sha256-addressed, cached locally as `runner_work_dir/bundles/<hash>.py`,
+  re-hashed on every download), runs the bundle, POSTs products back to
+  `/v1/workers/output` (which returns server-canonical paths).
+- **The runner ships no node implementations and never compiles user source.**
+  The IceFold server renders every node (your custom ones *and* the platform's
+  built-in ones) into a self-contained `.py` bundle, with `python_deps` /
+  `binary_deps` declared in the bundle header. The runner imports the bundle,
+  pre-flights the deps (sending back a structured `missing_dep` reply with
+  platform-aware install hints if anything is absent), and awaits
+  `__icefold_run__(inputs, ctx_dict)`. So when the server adds or upgrades
+  nodes, **you never have to upgrade the runner.**
+- Variant planning / dimension & provider resolution all stay on the server;
+  each job is a single already-sliced leaf call.
+
+## Install
+
+Requires **Python ≥ 3.11**, **ffmpeg/ffprobe** on `PATH` (for media nodes), and
+whatever third-party packages your custom nodes import.
+
+```bash
+pip install icefold-runner          # pulls in icefold-sdk
+```
+
+From source:
+
+```bash
+git clone <this-repo> icefold-runner
+cd icefold-runner
+python -m venv .venv && . .venv/bin/activate
+pip install -e .
+```
+
+## Run
+
+Generate a token in the IceFold app (**Nodes ▸ Connect a runner**), then:
+
+```bash
+icefold-runner --token <your-token>
+```
+
+That's it — the token (GitHub-CI style) encodes + signs your IceFold user id, so
+there's no server URL or user id to pass. The server is built in.
+
+Every flag also reads an env var (see [`.env.example`](.env.example)):
+
+| flag | env | meaning |
+|---|---|---|
+| `--token` | `ICEFOLD_RUNNER_TOKEN` | runner token from the IceFold app |
+| `--runner-id` | `ICEFOLD_RUNNER_ID` | stable id (default: hostname) |
+| `--work-dir` | `ICEFOLD_RUNNER_DIR` | scratch for staged inputs + products |
+
+The runner honors standard proxy env vars (`HTTPS_PROXY`, …) for reaching the
+server. It reconnects automatically with backoff; an auth rejection is fatal.
+
+> Self-hosting / dev: point the runner at a different server with the
+> `ICEFOLD_RUNNER_SERVER` env var (e.g. `ws://127.0.0.1:7000`).
+
+### Run as a service (systemd)
+
+```ini
+# /etc/systemd/system/icefold-runner.service
+[Unit]
+Description=IceFold runner
+After=network-online.target
+
+[Service]
+EnvironmentFile=/etc/icefold-runner.env
+ExecStart=/opt/icefold-runner/.venv/bin/icefold-runner
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+## Layout
+
+```
+icefold_runner/      the runner agent (connection, file staging, bundle exec)
+  client.py            reverse-WS client: dial / auth / reconnect / keepalive
+  runner.py            fetch /v1/bundles/<hash>, preflight deps, await __icefold_run__
+  __main__.py          CLI entrypoint (icefold-runner)
+```
+
+The runner imports the bundle on demand; the bundle is **self-contained** and
+already inlines whatever it needs (the author's function body, the
+`Inputs` / `Output` dataclasses, and a minimal `NodeContext` shim). The only
+runtime dependency on `icefold-sdk` is the wire protocol + a small helper kit
+(`get_file_id` / `run_blocking` / `write_text`), used by the runner agent
+itself, not by node code.
+
+## Security model
+
+- Node code runs **unsandboxed** here — it's your machine, your risk. That's the
+  point: code the server sandbox forbids (subprocess/ffmpeg/native deps) runs on
+  the runner instead. The runner downloads each bundle from the server and
+  executes it; it verifies the bundle's sha256 matches the requested hash, but
+  the bundle itself is whatever the server you authenticated to sends. Only
+  point a runner at a server you trust.
+- The runner only talks to the one server you point it at, authenticated by the
+  shared token; it pulls input files and pushes products over HTTP to that host.
+
+## Self-check
+
+A no-network sanity check that `icefold` is importable and the bundle execution
+path (fetch + import + run `__icefold_run__`) works against a locally-rendered
+bundle:
+
+```bash
+python selfcheck.py
+```

icefold_runner-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+icefold_runner/__init__.py,sha256=E5P4VMUKq7Kva5iRBnTsvZkM_nCsWUfCUB8dmmicyys,1035
+icefold_runner/__main__.py,sha256=BEjQKyeniGOTaai0r5QuiKDV6CVPwCVu7_zkxVd10Jw,2881
+icefold_runner/client.py,sha256=mEnjkzMRlVVcuO8KG0_3TjhNAFhu4paToGt_wcIMlE0,11842
+icefold_runner/runner.py,sha256=BWVc7M7RnyO2eqmA0M6Su_0eWUc-9RTiBSBR0zU0Xoc,12280
+icefold_runner-0.1.0.dist-info/licenses/LICENSE,sha256=GkZpO-PWJeVUDysnFXlj-lDZPx0qQWrtOe1Cuzk4phA,1064
+icefold_runner-0.1.0.dist-info/METADATA,sha256=alMtzr2kXRm2dfGLh-Y00M-hlCUXMAYf8HekpcJRjpI,7171
+icefold_runner-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+icefold_runner-0.1.0.dist-info/entry_points.txt,sha256=U63xdZSCxgXJhs8JT-F1FHHr_aH_Ov97yUrbJB5lEs4,64
+icefold_runner-0.1.0.dist-info/top_level.txt,sha256=o5xHC1eeRUfy6gGuAUA-tTXazxLy0zpDR9C8IKgaf68,15
+icefold_runner-0.1.0.dist-info/RECORD,,

icefold_runner-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

icefold_runner-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+icefold-runner = icefold_runner.__main__:main

icefold_runner-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IceFold
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

icefold_runner-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+icefold_runner