alyxruntime 0.1.0__py3-none-any.whl

alyxruntime/__init__.py

@@ -0,0 +1,6 @@
+"""alyxruntime - use another computer's CPU/GPU as your Jupyter runtime."""
+from .client import AlyxError, AuthError, ExecResult, Runtime
+from .server import serve
+
+__version__ = "0.1.0"
+__all__ = ["Runtime", "ExecResult", "AlyxError", "AuthError", "serve", "__version__"]

alyxruntime/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

alyxruntime/cli.py

@@ -0,0 +1,255 @@
+import argparse
+import getpass
+import json
+import sys
+
+from . import __version__, hardware
+from .client import AlyxError, AuthError, Runtime
+from .config import clear_state, load_state, save_state
+
+
+def die(msg, code=1):
+    print("alyxruntime: " + msg, file=sys.stderr)
+    sys.exit(code)
+
+
+def _current() -> Runtime:
+    st = load_state()
+    if not st:
+        die("not connected. Run:  alyxruntime connect <url>")
+    return Runtime.from_state(st)
+
+
+def _persist(rt: Runtime):
+    save_state(rt.to_state())
+
+
+# ---------------------------------------------------------------- commands
+def cmd_connect(a):
+    rt = Runtime(a.url, token=a.token, insecure=a.insecure, kernel_name=a.kernel)
+    try:
+        wait = lambda: print("Waiting for the tunnel to come up ...", file=sys.stderr)
+        try:
+            rt.wait_until_reachable(on_wait=wait)
+        except AuthError:
+            if rt.token or not sys.stdin.isatty():
+                raise
+            rt.token = getpass.getpass("Access token: ")
+            rt.http.headers["Authorization"] = "token " + rt.token
+            rt.ping()
+        rt.ensure_kernel()
+        info = rt.info()
+    except AlyxError as e:
+        die(str(e))
+    _persist(rt)  # save first, so a closed stdout can't lose the session
+    print("Connected to %s\n%s\n  kernel: %s (%s)" % (rt.base, hardware.format_summary(info),
+                                                      rt.kernel_id[:8], rt.kernel_name))
+    print("\nNext:  alyxruntime run train.py   |   alyxruntime shell   |   alyxruntime info")
+    print("VS Code / JupyterLab: choose 'Existing Jupyter Server' and paste the same URL.")
+
+
+def _cells(path):
+    if path.endswith(".ipynb"):
+        nb = json.load(open(path))
+        for c in nb.get("cells", []):
+            if c.get("cell_type") == "code":
+                yield "".join(c["source"])
+    else:
+        yield open(path).read()
+
+
+def cmd_run(a):
+    rt = _current()
+    if a.code is not None:
+        sources = [a.code]
+    elif a.file == "-" or (a.file is None and not sys.stdin.isatty()):
+        sources = [sys.stdin.read()]
+    elif a.file:
+        sources = list(_cells(a.file))
+    else:
+        die("give a file, -c CODE, or pipe code on stdin")
+    try:
+        for src in sources:
+            res = rt.run(src, timeout=a.timeout)
+            for p in res.save_images():
+                print("[saved plot -> %s]" % p, file=sys.stderr)
+            if not res.ok:
+                _persist(rt)
+                sys.exit(1)
+    except KeyboardInterrupt:
+        die("interrupted (sent interrupt to remote kernel)", 130)
+    except AlyxError as e:
+        die(str(e))
+    _persist(rt)
+
+
+def cmd_shell(a):
+    import codeop
+    rt = _current()
+    print("Remote shell on %s  (Ctrl+D to leave)" % rt.base)
+    buf = []
+    while True:
+        try:
+            line = input("... " if buf else ">>> ")
+        except EOFError:
+            print()
+            break
+        except KeyboardInterrupt:
+            print("\nKeyboardInterrupt")
+            buf = []
+            continue
+        buf.append(line)
+        src = "\n".join(buf)
+        try:
+            if line.strip() and codeop.compile_command(src) is None:
+                continue  # statement incomplete, keep reading
+        except (SyntaxError, ValueError, OverflowError):
+            pass  # %magics, !shell etc: let the remote IPython deal with it
+        buf = []
+        if not src.strip():
+            continue
+        try:
+            for p in rt.run(src).save_images():
+                print("[saved plot -> %s]" % p)
+        except KeyboardInterrupt:
+            print("\nKeyboardInterrupt")
+        except AlyxError as e:
+            print("error: %s" % e, file=sys.stderr)
+    _persist(rt)
+
+
+def cmd_info(a):
+    rt = _current()
+    try:
+        print(hardware.format_summary(rt.info()))
+    except AlyxError as e:
+        die(str(e))
+
+
+def cmd_status(a):
+    st = load_state()
+    if not st:
+        print("Not connected.")
+        return
+    rt = Runtime.from_state(st)
+    try:
+        rt.ping()
+        print("Connected to %s\n  kernel: %s" % (rt.base, (rt.kernel_id or "none")[:8]))
+    except AlyxError as e:
+        print("Saved session for %s but it is not reachable: %s" % (rt.base, e))
+        sys.exit(1)
+
+
+def cmd_restart(a):
+    rt = _current()
+    try:
+        rt.restart()
+    except AlyxError as e:
+        die(str(e))
+    print("Kernel restarted (variables cleared).")
+
+
+def cmd_upload(a):
+    rt = _current()
+    try:
+        print("uploaded -> " + rt.upload(a.local, a.remote))
+    except (AlyxError, OSError) as e:
+        die(str(e))
+
+
+def cmd_download(a):
+    rt = _current()
+    try:
+        print("saved -> %s" % rt.download(a.remote, a.local))
+    except (AlyxError, OSError) as e:
+        die(str(e))
+
+
+def cmd_disconnect(a):
+    st = load_state()
+    if st and a.kill_kernel:
+        rt = Runtime.from_state(st)
+        rt.shutdown()
+    clear_state()
+    print("Disconnected.")
+
+
+def cmd_stream(a):
+    from .server import serve
+    try:
+        serve(allowed_ip=a.allowed_ip, host=a.host, port=a.port, token=a.token, root_dir=a.root_dir,
+              tls_cert=a.tls_cert, tls_key=a.tls_key, allow_any=a.allow_any, public_host=a.public_host,
+              tunnel=a.tunnel, tunnel_token=a.tunnel_token, public_url=a.public_url,
+              auto_install=a.install_cloudflared)
+    except ValueError as e:
+        die(str(e))
+
+
+# ------------------------------------------------------------------ parser
+def build_parser():
+    p = argparse.ArgumentParser(prog="alyxruntime",
+                                description="Use another computer's CPU/GPU as your Jupyter runtime.")
+    p.add_argument("--version", action="version", version="alyxruntime " + __version__)
+    sub = p.add_subparsers(dest="cmd", metavar="<command>")
+    sub.required = True
+
+    c = sub.add_parser("connect", help="connect to a runtime shared with `stream`")
+    c.add_argument("url", help="e.g. https://host:8765/?token=XXXX")
+    c.add_argument("--token", help="access token (or put it in the URL / $ALYX_TOKEN)")
+    c.add_argument("--insecure", action="store_true", help="skip TLS verification (self-signed certs)")
+    c.add_argument("--kernel", default="python3", help="kernelspec name (default python3)")
+    c.set_defaults(fn=cmd_connect)
+
+    s = sub.add_parser("stream", help="share THIS machine's CPU/GPU as a runtime")
+    s.add_argument("--allowed_ip", "--allowed-ip", nargs="+", action="extend", metavar="IP",
+                   help="client IP(s) or CIDR range(s) allowed to connect, e.g. 203.0.113.7 10.0.0.0/24; "
+                        "or the word 'all' to allow any IP (token is then the only protection)")
+    s.add_argument("--allow-any", action="store_true", help="accept any IP (token is the only protection)")
+    s.add_argument("--no-tunnel", dest="tunnel", action="store_false",
+                   help="don't use Cloudflare; listen directly on --host:--port (you handle NAT/TLS)")
+    s.add_argument("--tunnel-token", help="run a NAMED Cloudflare tunnel (stable hostname) with this token; "
+                   "needs --public-url and --port")
+    s.add_argument("--public-url", help="the https URL of your named tunnel, e.g. https://gpu.example.com")
+    s.add_argument("--install-cloudflared", action="store_true",
+                   help="download cloudflared automatically if it's missing (no prompt)")
+    s.add_argument("--port", type=int, help="local port (default: random with tunnel, 8765 with --no-tunnel)")
+    s.add_argument("--host", default="0.0.0.0", help="interface to bind with --no-tunnel (default all)")
+    s.add_argument("--token", help="use a fixed token instead of a random one")
+    s.add_argument("--root-dir", help="working directory exposed to the client (default: cwd)")
+    s.add_argument("--tls-cert", help="PEM certificate to serve HTTPS")
+    s.add_argument("--tls-key", help="PEM private key for --tls-cert")
+    s.add_argument("--public-host", help="hostname/IP to print in the connect URL (with --no-tunnel)")
+    s.set_defaults(fn=cmd_stream)
+
+    r = sub.add_parser("run", help="run a .py/.ipynb file or code on the remote runtime")
+    r.add_argument("file", nargs="?", help="script, notebook, or - for stdin")
+    r.add_argument("-c", "--code", help="code string to run")
+    r.add_argument("--timeout", type=float, help="seconds before interrupting")
+    r.set_defaults(fn=cmd_run)
+
+    for name, fn, h in (("shell", cmd_shell, "interactive Python prompt on the remote runtime"),
+                        ("info", cmd_info, "show remote CPU/RAM/GPU"),
+                        ("status", cmd_status, "show current connection"),
+                        ("restart", cmd_restart, "restart the remote kernel")):
+        sub.add_parser(name, help=h).set_defaults(fn=fn)
+
+    u = sub.add_parser("upload", help="copy a local file to the host")
+    u.add_argument("local"); u.add_argument("remote", nargs="?")
+    u.set_defaults(fn=cmd_upload)
+    d = sub.add_parser("download", help="copy a file from the host")
+    d.add_argument("remote"); d.add_argument("local", nargs="?")
+    d.set_defaults(fn=cmd_download)
+
+    x = sub.add_parser("disconnect", help="forget the saved connection")
+    x.add_argument("--kill-kernel", action="store_true", help="also shut down the remote kernel")
+    x.set_defaults(fn=cmd_disconnect)
+    return p
+
+
+def main(argv=None):
+    a = build_parser().parse_args(argv)
+    a.fn(a)
+
+
+if __name__ == "__main__":
+    main()

alyxruntime/client.py

@@ -0,0 +1,294 @@
+"""Client side: talk to a remote Jupyter runtime exposed by `alyxruntime stream`."""
+import base64
+import json
+import sys
+import time
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Callable, List, Optional
+from urllib.parse import parse_qs, urlsplit
+
+import requests
+import websocket
+
+from . import hardware
+
+
+class AlyxError(Exception):
+    pass
+
+
+class AuthError(AlyxError):
+    pass
+
+
+class UnreachableError(AlyxError):
+    """Host not reachable *yet* (fresh tunnel DNS / edge not registered). Worth retrying."""
+
+
+@dataclass
+class ExecResult:
+    status: str = "ok"
+    execution_count: Optional[int] = None
+    stdout: str = ""
+    stderr: str = ""
+    results: List[str] = field(default_factory=list)
+    images: List[bytes] = field(default_factory=list)
+    error: Optional[dict] = None
+
+    @property
+    def ok(self) -> bool:
+        return self.status == "ok"
+
+    def save_images(self, directory="alyx_outputs") -> List[Path]:
+        d = Path(directory)
+        paths = []
+        for i, data in enumerate(self.images):
+            d.mkdir(parents=True, exist_ok=True)
+            p = d / ("out_%d_%d.png" % (int(time.time()), i))
+            p.write_bytes(data)
+            paths.append(p)
+        return paths
+
+
+def split_url(url: str):
+    """'https://host:8765/?token=abc' -> ('https://host:8765', 'abc')"""
+    if "://" not in url:
+        url = "http://" + url
+    parts = urlsplit(url)
+    token = (parse_qs(parts.query).get("token") or [None])[0]
+    base = "%s://%s%s" % (parts.scheme, parts.netloc, parts.path.rstrip("/"))
+    # a trailing /lab or /tree from a copied browser URL is not part of the base
+    for suffix in ("/lab", "/tree", "/api"):
+        if base.endswith(suffix):
+            base = base[: -len(suffix)]
+    return base, token
+
+
+def _echo(stream, text):
+    out = sys.stderr if stream in ("stderr", "error") else sys.stdout
+    out.write(text)
+    out.flush()
+
+
+class Runtime:
+    """A connection to a remote runtime (a Jupyter server on another machine).
+
+    >>> rt = Runtime.connect("http://203.0.113.7:8765/?token=...")
+    >>> rt.run("import torch; print(torch.cuda.is_available())")
+    """
+
+    def __init__(self, url, token=None, insecure=False, kernel_name="python3",
+                 kernel_id=None, timeout=30):
+        import os
+        self.base, url_token = split_url(url)
+        self.token = token or url_token or os.environ.get("ALYX_TOKEN")
+        self.insecure = insecure
+        self.kernel_name = kernel_name
+        self.kernel_id = kernel_id
+        self.timeout = timeout
+        self.http = requests.Session()
+        self.http.verify = not insecure
+        if self.token:
+            self.http.headers["Authorization"] = "token " + self.token
+        if insecure:
+            import urllib3
+            urllib3.disable_warnings()
+
+    # ---- construction -------------------------------------------------
+    @classmethod
+    def connect(cls, url, token=None, insecure=False, kernel_name="python3"):
+        rt = cls(url, token=token, insecure=insecure, kernel_name=kernel_name)
+        rt.ping()
+        rt.ensure_kernel()
+        return rt
+
+    @classmethod
+    def from_state(cls, state: dict):
+        return cls(state["url"], token=state.get("token"), insecure=state.get("insecure", False),
+                   kernel_name=state.get("kernel_name", "python3"), kernel_id=state.get("kernel_id"))
+
+    def to_state(self) -> dict:
+        return {"url": self.base, "token": self.token, "insecure": self.insecure,
+                "kernel_name": self.kernel_name, "kernel_id": self.kernel_id}
+
+    # ---- REST ---------------------------------------------------------
+    def _api(self, method, path, **kw):
+        kw.setdefault("timeout", self.timeout)
+        kw.setdefault("allow_redirects", False)
+        try:
+            r = self.http.request(method, self.base + path, **kw)
+        except requests.exceptions.SSLError as e:
+            raise AlyxError("TLS verification failed (%s). For a self-signed host use --insecure." % e)
+        except requests.exceptions.ConnectionError as e:
+            low = str(e).lower()
+            if any(m in low for m in ("name or service not known", "nodename nor servname",
+                                      "getaddrinfo", "failed to resolve", "name resolution")):
+                raise UnreachableError("Cannot resolve %s (a brand-new tunnel can take a few seconds)." % self.base)
+            hint = (" The host closed the connection - your public IP is probably not in its --allowed_ip list."
+                    if "reset" in str(e).lower() or "aborted" in str(e).lower() else "")
+            raise AlyxError("Cannot reach %s.%s" % (self.base, hint))
+        except requests.exceptions.RequestException as e:
+            raise AlyxError("Cannot reach %s: %s" % (self.base, e))
+        if r.status_code in (301, 302, 401, 403):
+            if r.text.startswith("alyxruntime:"):  # the host's own explanation (names the IP to allow)
+                raise AuthError(r.text.strip()[len("alyxruntime:"):].strip())
+            raise AuthError("Access denied (HTTP %d). Check the token, and that your IP is in the host's --allowed_ip list."
+                            % r.status_code)
+        if r.status_code in (502, 503, 504, 530):
+            raise UnreachableError("Tunnel/host not ready (HTTP %d). Is `alyxruntime stream` still running?"
+                                   % r.status_code)
+        if r.status_code >= 400:
+            raise AlyxError("%s %s -> HTTP %d: %s" % (method, path, r.status_code, r.text[:200]))
+        return r
+
+    def ping(self):
+        return self._api("GET", "/api/status").json()
+
+    def wait_until_reachable(self, timeout: float = 45, on_wait=None):
+        """ping(), retrying while a fresh Cloudflare tunnel finishes coming up."""
+        end = time.time() + timeout
+        told = False
+        while True:
+            try:
+                return self.ping()
+            except UnreachableError:
+                if time.time() > end:
+                    raise
+                if on_wait and not told:
+                    on_wait()
+                    told = True
+                time.sleep(2)
+
+    def ensure_kernel(self) -> str:
+        if self.kernel_id:
+            try:
+                self._api("GET", "/api/kernels/" + self.kernel_id)
+                return self.kernel_id
+            except AuthError:
+                raise
+            except AlyxError:
+                self.kernel_id = None
+        self.kernel_id = self._api("POST", "/api/kernels", json={"name": self.kernel_name}).json()["id"]
+        return self.kernel_id
+
+    def restart(self):
+        self._api("POST", "/api/kernels/%s/restart" % self.ensure_kernel())
+
+    def interrupt(self):
+        if self.kernel_id:
+            self._api("POST", "/api/kernels/%s/interrupt" % self.kernel_id)
+
+    def shutdown(self):
+        if self.kernel_id:
+            try:
+                self._api("DELETE", "/api/kernels/" + self.kernel_id)
+            except AlyxError:
+                pass
+            self.kernel_id = None
+
+    # ---- code execution ----------------------------------------------
+    def _open_ws(self, kernel_id):
+        ws_base = ("wss" if self.base.startswith("https") else "ws") + self.base[self.base.index("://"):]
+        url = "%s/api/kernels/%s/channels" % (ws_base, kernel_id)
+        if self.token:
+            url += "?token=" + self.token
+        opts = {"cert_reqs": 0, "check_hostname": False} if self.insecure else {}
+        try:
+            return websocket.create_connection(
+                url, header=["Authorization: token %s" % self.token] if self.token else [],
+                sslopt=opts, timeout=self.timeout)
+        except websocket.WebSocketBadStatusException as e:
+            raise AuthError("WebSocket rejected: %s" % e)
+        except Exception as e:
+            raise AlyxError("WebSocket connection failed: %s" % e)
+
+    def run(self, code: str, echo: bool = True, timeout: Optional[float] = None,
+            on_output: Optional[Callable[[str, str], None]] = None) -> ExecResult:
+        """Execute `code` on the remote kernel (state persists between calls)."""
+        emit = on_output or (_echo if echo else (lambda s, t: None))
+        ws = self._open_ws(self.ensure_kernel())
+        ws.settimeout(1.0)
+        msg_id = uuid.uuid4().hex
+        ws.send(json.dumps({
+            "header": {"msg_id": msg_id, "username": "alyx", "session": uuid.uuid4().hex,
+                       "msg_type": "execute_request", "version": "5.3",
+                       "date": datetime.now(timezone.utc).isoformat()},
+            "parent_header": {}, "metadata": {}, "buffers": [], "channel": "shell",
+            "content": {"code": code, "silent": False, "store_history": True,
+                        "user_expressions": {}, "allow_stdin": False, "stop_on_error": True},
+        }))
+        res = ExecResult()
+        deadline = time.time() + timeout if timeout else None
+        idle = replied = False
+        try:
+            while not (idle and replied):
+                try:
+                    raw = ws.recv()
+                except websocket.WebSocketTimeoutException:
+                    if deadline and time.time() > deadline:
+                        self.interrupt()
+                        raise AlyxError("Execution timed out after %ss" % timeout)
+                    continue
+                except websocket.WebSocketConnectionClosedException:
+                    raise AlyxError("Connection to the runtime was lost.")
+                if not raw:
+                    raise AlyxError("Connection to the runtime was lost.")
+                msg = json.loads(raw)
+                if (msg.get("parent_header") or {}).get("msg_id") != msg_id:
+                    continue
+                kind = msg.get("msg_type") or msg["header"]["msg_type"]
+                c = msg["content"]
+                if kind == "stream":
+                    if c["name"] == "stderr":
+                        res.stderr += c["text"]
+                    else:
+                        res.stdout += c["text"]
+                    emit(c["name"], c["text"])
+                elif kind in ("execute_result", "display_data"):
+                    data = c.get("data", {})
+                    if "image/png" in data:
+                        res.images.append(base64.b64decode(data["image/png"]))
+                    if "text/plain" in data:
+                        res.results.append(data["text/plain"])
+                        emit("result", data["text/plain"] + "\n")
+                elif kind == "error":
+                    res.error = {"ename": c["ename"], "evalue": c["evalue"], "traceback": c["traceback"]}
+                    emit("error", "\n".join(c["traceback"]) + "\n")
+                elif kind == "status" and c.get("execution_state") == "idle":
+                    idle = True
+                elif kind == "execute_reply":
+                    replied = True
+                    res.status = c.get("status", "ok")
+                    res.execution_count = c.get("execution_count")
+        except KeyboardInterrupt:
+            self.interrupt()
+            raise
+        finally:
+            ws.close()
+        return res
+
+    def info(self) -> dict:
+        r = self.run(hardware.remote_snippet(), echo=False)
+        if not r.ok:
+            raise AlyxError("Could not read hardware info: %s" % (r.error or {}).get("evalue"))
+        return json.loads(r.stdout.strip().splitlines()[-1])
+
+    # ---- files --------------------------------------------------------
+    def upload(self, local, remote=None):
+        local = Path(local)
+        remote = (remote or local.name).lstrip("/")
+        body = {"type": "file", "format": "base64",
+                "content": base64.b64encode(local.read_bytes()).decode()}
+        self._api("PUT", "/api/contents/" + remote, json=body, timeout=600)
+        return remote
+
+    def download(self, remote, local=None):
+        remote = remote.lstrip("/")
+        r = self._api("GET", "/api/contents/" + remote,
+                      params={"content": 1, "format": "base64", "type": "file"}, timeout=600).json()
+        local = Path(local or Path(remote).name)
+        local.write_bytes(base64.b64decode(r["content"]))
+        return local

alyxruntime/config.py

@@ -0,0 +1,34 @@
+import json
+import os
+from pathlib import Path
+
+
+def home() -> Path:
+    p = Path(os.environ.get("ALYX_HOME", Path.home() / ".alyxruntime"))
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def _state_path() -> Path:
+    return home() / "session.json"
+
+
+def load_state():
+    try:
+        return json.loads(_state_path().read_text())
+    except (OSError, ValueError):
+        return None
+
+
+def save_state(state: dict) -> None:
+    # holds the access token, so make it owner-readable only
+    fd = os.open(_state_path(), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as f:
+        json.dump(state, f, indent=2)
+
+
+def clear_state() -> None:
+    try:
+        _state_path().unlink()
+    except OSError:
+        pass

alyxruntime/hardware.py

@@ -0,0 +1,58 @@
+# NOTE: this file is also sent as source to the remote kernel, so keep it
+# self-contained and compatible with old Pythons (no walrus, no f-string "=").
+import json
+import os
+import platform
+import shutil
+import subprocess
+
+
+def summary():
+    info = {
+        "hostname": platform.node(),
+        "os": platform.platform(),
+        "python": platform.python_version(),
+        "cpu_count": os.cpu_count(),
+        "ram_gb": None,
+        "gpus": [],
+    }
+    try:
+        with open("/proc/meminfo") as f:
+            for line in f:
+                if line.startswith("MemTotal"):
+                    info["ram_gb"] = round(int(line.split()[1]) / 1024 / 1024, 1)
+                    break
+    except OSError:
+        try:
+            import psutil
+
+            info["ram_gb"] = round(psutil.virtual_memory().total / 1024 ** 3, 1)
+        except Exception:
+            pass
+    exe = shutil.which("nvidia-smi")
+    if exe:
+        try:
+            out = subprocess.run(
+                [exe, "--query-gpu=name,memory.total,driver_version", "--format=csv,noheader"],
+                stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, universal_newlines=True, timeout=10,
+            ).stdout
+            for line in out.strip().splitlines():
+                name, mem, drv = [p.strip() for p in line.split(",")]
+                info["gpus"].append({"name": name, "memory": mem, "driver": drv})
+        except Exception:
+            pass
+    return info
+
+
+def format_summary(info):
+    gpus = info.get("gpus") or []
+    gpu_txt = ", ".join("%s (%s)" % (g["name"], g["memory"]) for g in gpus) or "none detected"
+    return "  host:   %s\n  cpu:    %s cores\n  ram:    %s GB\n  gpu:    %s\n  python: %s" % (
+        info.get("hostname"), info.get("cpu_count"), info.get("ram_gb"), gpu_txt, info.get("python"))
+
+
+def remote_snippet():
+    """Python source that prints summary() as JSON when run inside a kernel."""
+    with open(__file__, "r") as f:
+        src = f.read()
+    return src + "\nprint(json.dumps(summary()))\n"

alyxruntime/server.py

@@ -0,0 +1,344 @@
+"""Host side: share this machine's CPU/GPU as a Jupyter runtime.
+
+Architecture:  client --TCP--> [IP-allowlist proxy :8765] --> [Jupyter server 127.0.0.1:random]
+
+The Jupyter server only ever listens on loopback. The proxy is the only public
+socket: it drops any connection whose source IP is not allowed *before* a single
+byte reaches Jupyter, and Jupyter then still demands the access token.
+"""
+import asyncio
+import importlib.util
+import ipaddress
+import os
+import secrets
+import signal
+import socket
+import ssl
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Iterable, List, Optional
+
+import requests
+
+from . import hardware
+from .config import home
+from .tunnel import INSTALL_HELP, Tunnel, TunnelError, find_cloudflared, install_cloudflared
+
+
+ALL_WORDS = {"all", "any", "*"}
+
+
+def wants_all(values: Optional[Iterable[str]]) -> bool:
+    """True if --allowed_ip contains the keyword all / any / *  (= allow every IP)."""
+    for raw in values or []:
+        for item in str(raw).replace(",", " ").split():
+            if item.strip("{}'\"").lower() in ALL_WORDS:
+                return True
+    return False
+
+
+def parse_allowed(values: Optional[Iterable[str]]) -> list:
+    nets = []
+    for raw in values or []:
+        for item in str(raw).replace(",", " ").split():
+            item = item.strip("{}'\"")
+            if not item or item.lower() in ALL_WORDS:
+                continue
+            try:
+                nets.append(ipaddress.ip_network(item, strict=False))
+            except ValueError:
+                raise ValueError("%r is not a valid IP address or CIDR range "
+                                 "(examples: 203.0.113.7  or  10.0.0.0/24)" % item)
+    return nets
+
+
+def is_allowed(addr: str, nets: list, allow_any: bool = False, loopback_ok: bool = True) -> bool:
+    try:
+        ip = ipaddress.ip_address(addr.split("%")[0])
+    except ValueError:
+        return False
+    if ip.version == 6 and ip.ipv4_mapped:
+        ip = ip.ipv4_mapped
+    if allow_any:
+        return True
+    if loopback_ok and ip.is_loopback:  # the machine's own user (direct mode only)
+        return True
+    return any(ip in n for n in nets if n.version == ip.version)
+
+
+def inspect_head(head: bytes):
+    """Inspect one HTTP request head arriving through cloudflared.
+
+    Returns (client_ip_or_None, rewritten_head). The client IP comes from the
+    CF-Connecting-IP header, which Cloudflare's edge sets itself (clients can't forge it).
+    The head is rewritten to `Connection: close` (except WebSocket upgrades) so that every
+    TCP connection carries exactly ONE request - otherwise cloudflared could reuse a
+    connection for a different visitor after we've only vetted the first one.
+    """
+    lines = [l for l in head.split(b"\r\n") if l]
+    out, ips, upgrade = [lines[0]], [], False
+    kept = []
+    for ln in lines[1:]:
+        name, _, value = ln.partition(b":")
+        n = name.strip().lower()
+        if n == b"cf-connecting-ip":
+            ips.append(value.strip().decode("ascii", "ignore"))
+        elif n == b"upgrade" and b"websocket" in value.lower():
+            upgrade = True
+        kept.append((n, ln))
+    for n, ln in kept:
+        if n == b"connection" and not upgrade:
+            continue
+        out.append(ln)
+    if not upgrade:
+        out.append(b"Connection: close")
+    ip = ips[0] if len(ips) == 1 else None  # missing or ambiguous -> deny
+    return ip, b"\r\n".join(out) + b"\r\n\r\n"
+
+
+def _free_port() -> int:
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+def _guess_ip() -> str:
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
+            s.connect(("8.8.8.8", 80))
+            return s.getsockname()[0]
+    except OSError:
+        return socket.gethostname()
+
+
+class AllowlistProxy:
+    """Public-facing gate in front of Jupyter.
+
+    direct mode (trust_cf_header=False): raw TCP proxy, filters on the socket's peer IP.
+    tunnel mode (trust_cf_header=True):  listens on loopback for cloudflared and filters on
+                                         the CF-Connecting-IP header of every request.
+    """
+
+    def __init__(self, host, port, target_port, nets, allow_any=False, ssl_ctx=None,
+                 trust_cf_header=False):
+        self.host, self.port, self.target_port = host, port, target_port
+        self.nets, self.allow_any, self.ssl_ctx = nets, allow_any, ssl_ctx
+        self.cf = trust_cf_header
+        self.seen = set()
+
+    @staticmethod
+    def _log(msg):
+        print("[%s] %s" % (time.strftime("%H:%M:%S"), msg), flush=True)
+
+    async def _pipe(self, reader, writer):
+        try:
+            while True:
+                data = await reader.read(65536)
+                if not data:
+                    break
+                writer.write(data)
+                await writer.drain()
+        except (ConnectionError, ssl.SSLError, asyncio.CancelledError, OSError):
+            pass
+        finally:
+            try:
+                writer.close()
+            except Exception:
+                pass
+
+    async def _deny(self, writer, who, reason):
+        self._log("DENIED   %s (%s)" % (who or "unknown", reason))
+        if self.cf:
+            body = ("alyxruntime: access denied for IP %s. Ask the host to add it with "
+                    "--allowed_ip %s\n" % (who, who)).encode() if who else \
+                   b"alyxruntime: request did not come through the Cloudflare tunnel.\n"
+            try:
+                writer.write(b"HTTP/1.1 403 Forbidden\r\nContent-Type: text/plain\r\nConnection: close\r\n"
+                             b"Content-Length: %d\r\n\r\n" % len(body) + body)
+                await writer.drain()
+            except Exception:
+                pass
+        writer.close()
+
+    async def _handle(self, creader, cwriter):
+        head = None
+        if self.cf:
+            try:
+                raw = await asyncio.wait_for(creader.readuntil(b"\r\n\r\n"), 15)
+            except Exception:
+                cwriter.close()
+                return
+            who, head = inspect_head(raw)
+            if not who:
+                return await self._deny(cwriter, None, "no single CF-Connecting-IP header")
+            ok = is_allowed(who, self.nets, self.allow_any, loopback_ok=False)
+        else:
+            who = (cwriter.get_extra_info("peername") or ("?",))[0]
+            ok = is_allowed(who, self.nets, self.allow_any)
+        if not ok:
+            return await self._deny(cwriter, who, "not in --allowed_ip")
+        if who not in self.seen:
+            self.seen.add(who)
+            self._log("accepted %s" % who)
+        try:
+            ureader, uwriter = await asyncio.open_connection("127.0.0.1", self.target_port)
+            if head:
+                uwriter.write(head)
+                await uwriter.drain()
+        except OSError:
+            cwriter.close()
+            return
+        await asyncio.gather(self._pipe(creader, uwriter), self._pipe(ureader, cwriter))
+
+    async def start(self):
+        return await asyncio.start_server(self._handle, self.host, self.port, ssl=self.ssl_ctx)
+
+
+def _wait_ready(port, token, proc, timeout=90) -> bool:
+    s = requests.Session()
+    s.trust_env = False
+    end = time.time() + timeout
+    while time.time() < end:
+        if proc.poll() is not None:
+            return False
+        try:
+            if s.get("http://127.0.0.1:%d/api/status" % port,
+                     headers={"Authorization": "token " + token}, timeout=2).status_code == 200:
+                return True
+        except requests.RequestException:
+            pass
+        time.sleep(0.5)
+    return False
+
+
+def _ensure_cloudflared(auto_install: bool) -> str:
+    exe = find_cloudflared()
+    if exe:
+        return exe
+    want = auto_install
+    if not want and sys.stdin.isatty():
+        ans = input("cloudflared not found. Download the official binary from Cloudflare's GitHub "
+                    "releases into ~/.alyxruntime/bin? [Y/n] ")
+        want = ans.strip().lower() in ("", "y", "yes")
+    if not want:
+        raise SystemExit(INSTALL_HELP)
+    try:
+        return install_cloudflared()
+    except TunnelError as e:
+        raise SystemExit(str(e))
+
+
+def serve(allowed_ip: Optional[List[str]] = None, host: str = "0.0.0.0", port: Optional[int] = None,
+          token: Optional[str] = None, root_dir: Optional[str] = None,
+          tls_cert: Optional[str] = None, tls_key: Optional[str] = None,
+          allow_any: bool = False, public_host: Optional[str] = None,
+          tunnel: bool = True, tunnel_token: Optional[str] = None,
+          public_url: Optional[str] = None, auto_install: bool = False) -> None:
+    """Start sharing this machine. Blocks until Ctrl+C.
+
+    tunnel=True (default): expose it through a Cloudflare tunnel - no open ports, HTTPS included.
+    tunnel=False: listen directly on host:port (you handle NAT / TLS).
+    """
+    missing = [m for m in ("jupyter_server", "ipykernel") if importlib.util.find_spec(m) is None]
+    if missing:
+        raise SystemExit("Missing %s on this machine. Install with:  pip install 'alyxruntime[host]'"
+                         % ", ".join(missing))
+    nets = parse_allowed(allowed_ip)
+    allow_any = allow_any or wants_all(allowed_ip)  # `--allowed_ip all`
+    token = token or secrets.token_urlsafe(24)
+    root = str(Path(root_dir or os.getcwd()).resolve())
+
+    exe = None
+    if tunnel:
+        if tls_cert or tls_key:
+            raise SystemExit("--tls-cert/--tls-key are not needed with a tunnel (Cloudflare terminates "
+                             "HTTPS). Use --no-tunnel to serve TLS yourself.")
+        if not nets and not allow_any:
+            raise SystemExit("Through a tunnel, nobody counts as 'local', so say who may connect:\n"
+                             "  --allowed_ip <client public IP> [more IPs / CIDRs]\n"
+                             "or --allow-any to rely on the token alone.")
+        if tunnel_token and (not public_url or not port):
+            raise SystemExit("A named tunnel needs --public-url https://your.hostname and --port <N>, "
+                             "where N matches the service URL (http://localhost:N) set for it in the "
+                             "Cloudflare dashboard.")
+        exe = _ensure_cloudflared(auto_install)
+        host, port = "127.0.0.1", port or _free_port()  # only cloudflared may reach the gate
+    else:
+        port = port or 8765
+
+    ssl_ctx = None
+    if tls_cert:
+        ssl_ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+        ssl_ctx.load_cert_chain(tls_cert, tls_key)
+
+    internal = _free_port()
+    env = dict(os.environ, JUPYTER_TOKEN=token)  # env, not argv, so it's not visible in `ps`
+    logf = open(home() / "jupyter.log", "w")
+    cmd = [sys.executable, "-m", "jupyter_server", "--no-browser",
+           "--ServerApp.ip=127.0.0.1", "--ServerApp.port=%d" % internal, "--ServerApp.port_retries=0",
+           "--ServerApp.allow_remote_access=True", "--ServerApp.root_dir=" + root]
+    if hasattr(os, "geteuid") and os.geteuid() == 0:
+        cmd.append("--allow-root")  # common on Docker / cloud GPU boxes
+        print("! Running as root: connected clients get root-level code execution.", flush=True)
+    proc = subprocess.Popen(cmd, stdout=logf, stderr=subprocess.STDOUT, env=env, cwd=root)
+    tun = Tunnel(exe, port, tunnel_token, public_url) if tunnel else None
+
+    def _stop(*_):
+        raise KeyboardInterrupt
+
+    try:
+        signal.signal(signal.SIGTERM, _stop)
+    except (ValueError, AttributeError):
+        pass
+
+    async def _amain():
+        proxy = AllowlistProxy(host, port, internal, nets, allow_any, ssl_ctx, trust_cf_header=tunnel)
+        server = await proxy.start()
+        if tunnel:
+            print("Opening Cloudflare tunnel ...", flush=True)
+            base = await asyncio.get_running_loop().run_in_executor(None, tun.start)
+        else:
+            base = "%s://%s:%d" % ("https" if ssl_ctx else "http", public_host or _guess_ip(), port)
+        print("\nRuntime is up.  This machine:")
+        print(hardware.format_summary(hardware.summary()))
+        print("\nWorking dir : " + root)
+        if allow_any:
+            print("Allowed IPs : ANY  (token is the only protection!)")
+        elif tunnel:
+            print("Allowed IPs : %s  (as seen by Cloudflare)" % ", ".join(str(n) for n in nets))
+        elif nets:
+            print("Allowed IPs : %s  (+ loopback)" % ", ".join(str(n) for n in nets))
+        else:
+            print("Allowed IPs : loopback only  (pass --allowed_ip <your client IP> to let others in)")
+        if tunnel:
+            print("Transport   : Cloudflare tunnel (HTTPS, no open ports)")
+        elif not ssl_ctx and (nets or allow_any):
+            print("\n! Plain HTTP: the token and your code cross the network unencrypted.\n"
+                  "  Use --tls-cert/--tls-key, drop --no-tunnel, or tunnel it yourself.")
+        print("\nOn the client, run:\n\n    alyxruntime connect '%s/?token=%s'\n" % (base, token))
+        print("Ctrl+C to stop sharing.\n", flush=True)
+        async with server:
+            await server.serve_forever()
+
+    try:
+        print("Starting Jupyter runtime ...", flush=True)
+        if not _wait_ready(internal, token, proc):
+            tail = (home() / "jupyter.log").read_text()[-1500:]
+            raise SystemExit("Jupyter failed to start. Log (%s):\n%s" % (home() / "jupyter.log", tail))
+        asyncio.run(_amain())
+    except TunnelError as e:
+        print("\nTunnel error: %s" % e, file=sys.stderr)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        print("\nShutting down ...")
+        if tun:
+            tun.stop()
+        proc.terminate()
+        try:
+            proc.wait(10)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+        logf.close()

alyxruntime/tunnel.py

@@ -0,0 +1,152 @@
+"""Cloudflare tunnel (cloudflared) management: find / install / run."""
+import os
+import platform
+import re
+import shutil
+import subprocess
+import tarfile
+import tempfile
+import threading
+import time
+from pathlib import Path
+from typing import Optional
+
+import requests
+
+from .config import home
+
+QUICK_URL_RE = re.compile(r"https://[a-z0-9-]+\.trycloudflare\.com")
+REGISTERED_RE = re.compile(r"Registered tunnel connection", re.I)
+RELEASES = "https://github.com/cloudflare/cloudflared/releases/latest/download/"
+
+INSTALL_HELP = (
+    "cloudflared not found. Install it, or let alyxruntime fetch it:\n"
+    "  macOS:    brew install cloudflared\n"
+    "  Debian:   https://pkg.cloudflare.com/  (apt)\n"
+    "  Windows:  winget install Cloudflare.cloudflared\n"
+    "  or re-run with --install-cloudflared to download the official binary into ~/.alyxruntime/bin"
+)
+
+
+class TunnelError(Exception):
+    pass
+
+
+def _exe_name() -> str:
+    return "cloudflared.exe" if platform.system() == "Windows" else "cloudflared"
+
+
+def find_cloudflared() -> Optional[str]:
+    env = os.environ.get("ALYX_CLOUDFLARED")
+    if env and Path(env).exists():
+        return env
+    found = shutil.which("cloudflared")
+    if found:
+        return found
+    local = home() / "bin" / _exe_name()
+    return str(local) if local.exists() else None
+
+
+def _asset() -> str:
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+    arch = {"x86_64": "amd64", "amd64": "amd64", "aarch64": "arm64", "arm64": "arm64",
+            "armv7l": "arm", "armv6l": "arm", "i386": "386", "i686": "386"}.get(machine)
+    if not arch:
+        raise TunnelError("No official cloudflared build for CPU %r - install it manually." % machine)
+    if system == "linux":
+        return "cloudflared-linux-" + arch
+    if system == "darwin" and arch in ("amd64", "arm64"):
+        return "cloudflared-darwin-%s.tgz" % arch
+    if system == "windows" and arch in ("amd64", "386"):
+        return "cloudflared-windows-%s.exe" % arch
+    raise TunnelError("No official cloudflared build for %s/%s - install it manually." % (system, machine))
+
+
+def install_cloudflared() -> str:
+    """Download the official cloudflared release from GitHub into ~/.alyxruntime/bin."""
+    asset = _asset()
+    dest_dir = home() / "bin"
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest = dest_dir / _exe_name()
+    url = RELEASES + asset
+    print("Downloading %s ..." % url, flush=True)
+    try:
+        with requests.get(url, stream=True, timeout=60) as r:
+            r.raise_for_status()
+            with tempfile.NamedTemporaryFile(delete=False, dir=str(dest_dir)) as tmp:
+                for chunk in r.iter_content(1 << 20):
+                    tmp.write(chunk)
+                tmp_path = Path(tmp.name)
+    except requests.RequestException as e:
+        raise TunnelError("Download failed: %s\n%s" % (e, INSTALL_HELP))
+    if asset.endswith(".tgz"):
+        with tarfile.open(tmp_path) as tf:
+            member = next(m for m in tf.getmembers() if m.name.endswith("cloudflared"))
+            member.name = dest.name  # never trust archive paths
+            tf.extract(member, str(dest_dir))
+        tmp_path.unlink()
+    else:
+        os.replace(tmp_path, dest)
+    dest.chmod(0o755)
+    return str(dest)
+
+
+class Tunnel:
+    """Runs `cloudflared` and exposes a public https URL for a local port.
+
+    * quick tunnel (default): free, no account, random *.trycloudflare.com URL
+    * named tunnel (token + public_url): stable hostname on your Cloudflare account
+    """
+
+    def __init__(self, exe: str, local_port: int, token: Optional[str] = None,
+                 public_url: Optional[str] = None):
+        self.exe, self.port, self.token, self.public_url = exe, local_port, token, public_url
+        self.proc = None
+        self._url = None
+        self._url_evt = threading.Event()
+        self._reg_evt = threading.Event()
+        self.log_path = home() / "cloudflared.log"
+
+    def _reader(self):
+        with open(self.log_path, "w") as log:
+            for line in self.proc.stdout:
+                log.write(line)
+                log.flush()
+                if not self.token and not self._url:
+                    m = QUICK_URL_RE.search(line)
+                    if m:
+                        self._url = m.group(0)
+                        self._url_evt.set()
+                if REGISTERED_RE.search(line):
+                    self._reg_evt.set()
+                    if self.token:
+                        self._url_evt.set()
+
+    def start(self, timeout: float = 60) -> str:
+        env = dict(os.environ)
+        if self.token:
+            env["TUNNEL_TOKEN"] = self.token  # via env, not argv, so it's not visible in `ps`
+            cmd = [self.exe, "tunnel", "--no-autoupdate", "run"]
+        else:
+            cmd = [self.exe, "tunnel", "--no-autoupdate", "--url", "http://127.0.0.1:%d" % self.port]
+        self.proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+                                     universal_newlines=True, env=env)
+        threading.Thread(target=self._reader, daemon=True).start()
+        end = time.time() + timeout
+        while not self._url_evt.wait(0.5):
+            if self.proc.poll() is not None or time.time() > end:
+                tail = self.log_path.read_text()[-1200:] if self.log_path.exists() else ""
+                self.stop()
+                raise TunnelError("cloudflared did not come up (log: %s):\n%s" % (self.log_path, tail))
+        # URL is known; give the edge a moment to register so the client doesn't hit a 530
+        self._reg_evt.wait(20)
+        return (self.public_url if self.token else self._url).rstrip("/")
+
+    def stop(self):
+        if self.proc and self.proc.poll() is None:
+            self.proc.terminate()
+            try:
+                self.proc.wait(8)
+            except subprocess.TimeoutExpired:
+                self.proc.kill()

alyxruntime-0.1.0.dist-info/METADATA

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: alyxruntime
+Version: 0.1.0
+Summary: Use any remote machine's CPU/GPU as a Jupyter runtime over a Cloudflare tunnel, Colab-style, from the command line or Python.
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Requires-Dist: websocket-client>=1.4
+Provides-Extra: host
+Requires-Dist: jupyter_server>=2.0; extra == "host"
+Requires-Dist: ipykernel>=6.0; extra == "host"
+Provides-Extra: lab
+Requires-Dist: jupyter_server>=2.0; extra == "lab"
+Requires-Dist: ipykernel>=6.0; extra == "lab"
+Requires-Dist: jupyterlab>=4.0; extra == "lab"
+
+# alyxruntime
+
+Use any other computer's CPU/GPU as your Jupyter runtime - like Colab's "connect to local runtime",
+but for *any* machine you control, from the command line or from Python.
+
+```
+ your laptop        Cloudflare edge            GPU box (host) - no open ports, outbound only
+ ┌────────────┐ https ┌───────────────┐ tunnel ┌─────────────────────────────────────────┐
+ │ alyxruntime│ ────► │ *.trycloudflare│ ◄──────│ cloudflared ─► IP-allowlist gate        │
+ │  connect   │ +token│     .com       │        │                  └─► Jupyter (loopback) │
+ └────────────┘       └───────────────┘        │                        └─► kernel (GPU) │
+                                                └─────────────────────────────────────────┘
+```
+
+The host talks *out* to Cloudflare through `cloudflared`, so there is **no port forwarding, no public IP,
+and HTTPS is included** - it works from behind home routers, NAT and most firewalls.
+
+## Install
+
+```bash
+pip install "alyxruntime[host]"   # on the machine that SHARES its GPU/CPU
+pip install alyxruntime           # on the machine that CONNECTS (lighter)
+```
+
+## Usage
+
+On the **host** (the machine with the GPU):
+
+```bash
+alyxruntime stream --allowed_ip 203.0.113.7                # your client's public IP
+alyxruntime stream --allowed_ip 203.0.113.7 10.0.0.0/24    # several IPs / CIDR ranges
+alyxruntime stream --allowed_ip all                        # any IP - the token is the only gate
+```
+
+It starts a Cloudflare quick tunnel (if `cloudflared` is missing it offers to download the official
+binary, or pass `--install-cloudflared`) and prints a ready-to-paste command with a random access token:
+
+```bash
+alyxruntime connect 'https://random-words.trycloudflare.com/?token=...'
+```
+
+Not sure what your public IP is? Run `alyxruntime connect` from the client anyway: the host replies
+`access denied for IP x.x.x.x. Ask the host to add it with --allowed_ip x.x.x.x`.
+
+On the **client**:
+
+```bash
+alyxruntime connect https://my-host:8765/?token=XXXX   # verifies, shows remote CPU/RAM/GPU, saves session
+alyxruntime run train.py            # run a script   (also .ipynb, `-c "code"`, or stdin with `-`)
+alyxruntime shell                   # interactive prompt; variables persist between commands
+alyxruntime info                    # remote CPU / RAM / GPU
+alyxruntime upload data.csv         # copy files to the host's working dir
+alyxruntime download model.pt
+alyxruntime restart                 # fresh kernel
+alyxruntime disconnect --kill-kernel
+```
+
+Plots (`plt.show()`) are saved locally to `./alyx_outputs/`.
+VS Code / JupyterLab also work: *Select Kernel -> Existing Jupyter Server* -> paste the same URL.
+
+### From Python
+
+```python
+from alyxruntime import Runtime
+
+rt = Runtime.connect("https://my-host:8765/?token=XXXX")
+rt.run("import torch; print(torch.cuda.is_available())")
+res = rt.run("2 + 2", echo=False);  print(res.results)     # ['4']
+rt.upload("data.csv"); rt.download("out.pt")
+```
+
+Host side from Python: `from alyxruntime import serve; serve(allowed_ip=["203.0.113.7"])`.
+
+### Stable URL (named tunnel)
+
+Quick tunnels get a new random URL every run. For a fixed hostname, create a tunnel in the Cloudflare
+dashboard (Zero Trust -> Networks -> Tunnels), point a public hostname at `http://localhost:9000`, then:
+
+```bash
+alyxruntime stream --tunnel-token <TOKEN> --public-url https://gpu.example.com --port 9000 \
+                   --allowed_ip 203.0.113.7
+```
+
+## `stream` options
+
+| flag | meaning |
+|---|---|
+| `--allowed_ip IP [IP...]` | public IPs / CIDR ranges (v4 or v6) allowed to connect, as seen by Cloudflare, or the word `all` (same as `--allow-any`). **Required** in tunnel mode. |
+| `--allow-any` | accept any IP (the token is then your only protection) |
+| `--no-tunnel` | skip Cloudflare; listen directly on `--host:--port` (you handle NAT; loopback is always allowed in this mode) |
+| `--install-cloudflared` | download `cloudflared` automatically if it's missing |
+| `--tunnel-token` / `--public-url` / `--port` | use a named tunnel with a stable hostname (see above) |
+| `--token` | fixed access token instead of a random one |
+| `--root-dir` | directory the client can see (default: current dir) |
+| `--tls-cert` / `--tls-key` | HTTPS for `--no-tunnel` mode (not needed with a tunnel) |
+| `--public-host` | hostname/IP to print in the connect URL with `--no-tunnel` |
+
+## Security - please read
+
+A runtime is **remote code execution by design**: whoever connects runs arbitrary code as the host user.
+
+* **Two independent gates:** the IP allowlist *and* a random token.
+* **How the allowlist works with a tunnel:** `cloudflared` reaches the host from `127.0.0.1`, so the
+  socket address is useless for filtering. The gate instead reads the `CF-Connecting-IP` header, which
+  Cloudflare's edge sets itself, and checks **every request** against `--allowed_ip`. Requests with no
+  such header (anything not coming through the tunnel) are refused, loopback gets no special pass, and
+  each request is forced to `Connection: close` so one vetted connection can't be reused by someone else.
+* The quick-tunnel URL is public: anyone who learns it can *reach* the gate (and be refused). Treat the
+  token like a password, and don't paste the connect line in public places.
+* Traffic passes through Cloudflare's network (TLS to Cloudflare, then Cloudflare -> your host over the
+  tunnel); Cloudflare can technically see it. If that's unacceptable, use `--no-tunnel` with your own VPN.
+* IP allowlisting trusts that Cloudflare reports the true client IP. It won't protect against someone
+  sharing your NAT/VPN exit IP, and mobile/CGNAT or rotating-IP connections will need a CIDR range.
+* Local users on the host can reach the gate on its loopback port and are trusted like the host user.
+* Don't run `stream` as root unless you mean it. The client's saved token lives in `~/.alyxruntime/session.json` (0600).
+* Cloudflare's free quick tunnels are meant for development: no uptime guarantee, and you should read
+  Cloudflare's terms before using them for anything heavy or long-lived (use a named tunnel for that).

alyxruntime-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+alyxruntime/__init__.py,sha256=STqcviNQJ3D5jNF1CHStHU5Tk8_XBNQcArINUkAExz4,273
+alyxruntime/__main__.py,sha256=MSmt_5Xg84uHqzTN38JwgseJK8rsJn_11A8WD99VtEo,61
+alyxruntime/cli.py,sha256=x8FXenSVU99BzjJADfQJhlh_f3NSAMoYtoDAEyzZq_o,9453
+alyxruntime/client.py,sha256=KS_b6QhxG9mn92XC-xkdH8IghWWXIH3w8zGyWqhn7Yc,12317
+alyxruntime/config.py,sha256=1W4cFtWzfRIkn8YuGtT8XCFcy9tRgJNCvj6fxG2t4Iw,747
+alyxruntime/hardware.py,sha256=jN3GI2CgKC0pQ9sTAz6GjmStPCa5nT6gUVe2UY38Lac,2020
+alyxruntime/server.py,sha256=EEcr7r8y80J4ScJuW5kR11gfF8K06F8ztkTqgqik794,13834
+alyxruntime/tunnel.py,sha256=a0NV0PDD58vONyRg7IkwmbD9P8IjwfbvkGfGT8ZLqpY,5916
+alyxruntime-0.1.0.dist-info/METADATA,sha256=VTxiWj-uW9PtAeqFEbR_moHJLVkMzydCYZij7j0TGZc,7212
+alyxruntime-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+alyxruntime-0.1.0.dist-info/entry_points.txt,sha256=kyerWOzN5te9fUZhnL1Fg52cAX5Ow5Sx7_okaQhBp-Q,53
+alyxruntime-0.1.0.dist-info/top_level.txt,sha256=ppH5DWnTRtjyzvpVoPCnGKsdhKPHBqe8HjpWFSB_n-U,12
+alyxruntime-0.1.0.dist-info/RECORD,,

alyxruntime-0.1.0.dist-info/WHEEL

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

alyxruntime-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+alyxruntime = alyxruntime.cli:main

alyxruntime-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+alyxruntime