alyxruntime 0.1.0__tar.gz

alyxruntime-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,117 @@
+# 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/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-0.1.0/alyxruntime/__main__.py

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

alyxruntime-0.1.0/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()