colabapi 0.1.0__py3-none-any.whl

colabapi/ui.py

@@ -0,0 +1,102 @@
+"""Tiny interactive terminal helpers (no extra dependencies).
+
+The arrow-key `select` menu is used wherever colabapi asks the user to pick a
+session (shell / stop / monitor). It uses raw terminal mode via termios, which is
+fine because the underlying `colab` CLI is Linux/macOS only. When stdin is not a
+TTY (e.g. run from a service) it degrades to returning the first option, so
+non-interactive callers still work.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Callable, Optional, Sequence, TypeVar
+
+T = TypeVar("T")
+
+_ESC = "\x1b"
+
+
+def _read_key() -> str:
+    """Read one logical keypress in raw mode and normalise it to a name."""
+    ch = sys.stdin.read(1)
+    if ch == _ESC:
+        nxt = sys.stdin.read(2)  # arrow keys arrive as ESC [ A/B/C/D
+        return {"[A": "up", "[B": "down"}.get(nxt, "esc")
+    if ch in ("\r", "\n"):
+        return "enter"
+    if ch == "\x03":  # Ctrl-C
+        raise KeyboardInterrupt
+    if ch in ("k", "K"):
+        return "up"
+    if ch in ("j", "J"):
+        return "down"
+    if ch in ("q", "Q"):
+        return "quit"
+    return ch
+
+
+def select(options: Sequence[T],
+           title: str = "Select",
+           to_label: Callable[[T], str] = str,
+           footer: str = "↑/↓ move · Enter select · q cancel") -> Optional[T]:
+    """Interactive single-choice menu. Returns the chosen item, or None if cancelled.
+
+    With zero options returns None; with exactly one option (or no TTY) returns it
+    immediately without prompting.
+    """
+    n = len(options)
+    if n == 0:
+        return None
+    if n == 1 or not sys.stdin.isatty() or not sys.stdout.isatty():
+        return options[0]
+
+    idx = 0
+    out = sys.stdout
+    lines = 0
+
+    def draw() -> None:
+        nonlocal lines
+        buf = [f"\x1b[1;36m{title}\x1b[0m"]
+        for i, opt in enumerate(options):
+            label = to_label(opt)
+            if i == idx:
+                buf.append(f"\x1b[1;32m❯ {label}\x1b[0m")
+            else:
+                buf.append(f"  {label}")
+        buf.append(f"\x1b[2m{footer}\x1b[0m")
+        out.write("\r\n".join(buf))
+        out.flush()
+        lines = len(buf)
+
+    import termios
+    import tty
+
+    fd = sys.stdin.fileno()
+    old = termios.tcgetattr(fd)
+    chosen: Optional[T] = None
+    try:
+        tty.setraw(fd)
+        draw()
+        while True:
+            key = _read_key()
+            if key == "up":
+                idx = (idx - 1) % n
+            elif key == "down":
+                idx = (idx + 1) % n
+            elif key == "enter":
+                chosen = options[idx]
+                break
+            elif key in ("quit", "esc"):
+                chosen = None
+                break
+            else:
+                continue
+            # Move cursor to the top of the block and repaint.
+            out.write(f"\r\x1b[{lines - 1}A\x1b[J")
+            draw()
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, old)
+        out.write("\r\n")
+        out.flush()
+    return chosen

colabapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: colabapi
+Version: 0.1.0
+Summary: Run and keep a Google Colab runtime alive, then reach its terminal from your own server or laptop. A CLI for headless, persistent Colab sessions.
+Author: lil-limbo
+License: MIT
+Project-URL: Homepage, https://github.com/lil-limbo/colabapi
+Project-URL: Repository, https://github.com/lil-limbo/colabapi
+Project-URL: Issues, https://github.com/lil-limbo/colabapi/issues
+Keywords: google colab,colab,colab terminal,colab ssh,colab cli,persistent colab,colab keep alive,headless colab,colab runtime,jupyter,gpu,remote terminal,vps
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: rich>=13.0
+Requires-Dist: google-colab-cli>=0.6.0
+Dynamic: license-file
+
+# colabapi: a terminal for a persistent Google Colab runtime
+
+**Run Google Colab from your own terminal, keep the runtime alive after you close the browser, and reach its shell from any VPS or laptop.** `colabapi` is a small, open source command line tool that turns a Google Colab GPU/TPU session into something you can drive headlessly. Perfect for demos, MVPs, and long running jobs that must survive after the Colab web tab is gone.
+
+> **In one line:** `colabapi` gives you a persistent Colab terminal on your own server, using Google's official, ban safe sign in and tunnel, and it never sees your Google password.
+
+<!-- Keywords: google colab terminal, colab cli, colab ssh, persistent colab, keep colab alive, headless colab, run colab from terminal, colab gpu terminal, colab from vps, colab session keep alive -->
+
+---
+
+## Why colabapi?
+
+Google Colab is fantastic free (and paid) GPU/TPU compute, but it only lives inside a browser tab. Close the tab or lose your connection and the session can go with it. That makes it awkward to:
+
+- **demo an MVP** that needs a GPU without renting a server,
+- **reach the runtime from a VPS** or a headless box,
+- **register it as a background service** that stays up, or
+- **watch CPU / GPU / RAM** from a normal terminal.
+
+`colabapi` solves this by wrapping **Google's official [`google-colab-cli`](https://github.com/googlecolab/google-colab-cli)** with a friendly single command, a systemd service, a runtime picker, a live resource monitor, and a session time display. You sign in through Google's own browser flow; `colabapi` connects over Google's sanctioned tunnel.
+
+## Features
+
+- 🔐 **Browser sign in, no password handling.** Authentication happens in Google's own login flow (including 2FA / device checks). `colabapi` never asks for, stores, or transmits your Google credentials.
+- 💻 **Real terminal into the runtime.** `colabapi shell` drops you into a live PTY on the Colab VM. `colabapi repl` gives you a Python REPL.
+- 🎛 **Runtime picker.** List CPU / T4 / L4 / G4 / A100 / H100 / TPU options; paid tier runtimes are clearly flagged as unavailable on a free account.
+- 📈 **Live CPU / GPU / RAM monitor.** `colabapi monitor` streams runtime stats to your terminal (psutil + `nvidia-smi`).
+- ⏱ **Session time display.** See uptime and an estimate of how long before Colab's max lifetime cap.
+- ♻️ **Keepalive that resists the idle timeout.** Google's official daemon does the primary keepalive; `colabapi` adds a supervisory health check.
+- 🧩 **Runs as a Linux service.** `colabapi service install` registers a systemd user service so your session survives logout.
+- 🔎 **Inspectable & MIT licensed.** Read every line. Nothing phones home.
+
+## How it works
+
+```
+you  >  colabapi (this tool)  >  colab (Google's official CLI)  >  Google's tunnel  >  your Colab runtime (GPU/TPU VM)
+
+colabapi adds: runtime picker, monitor, session timer, systemd service
+colabapi never handles your Google password
+```
+
+`colabapi` is an **orchestration and UX layer**. The heavy lifting (OAuth sign in, allocating the runtime, and the encrypted terminal tunnel) is delegated to Google's first party CLI, which is the safe, supported way to do this.
+
+## Install
+
+**One command installs the whole system.** Google's official Colab CLI is pulled in automatically as a dependency, so you never install it separately.
+
+### With pipx (recommended)
+
+```bash
+pipx install colabapi
+```
+
+### With pip
+
+```bash
+pip install --user colabapi
+```
+
+> **On Kali / Debian / Ubuntu** you may hit `error: externally-managed-environment` (PEP 668). This is the OS protecting its system Python, not a colabapi problem. Use `pipx` (above), a virtualenv, or override it:
+>
+> ```bash
+> pip install --user colabapi --break-system-packages
+> ```
+
+### One line install script
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/lil-limbo/colabapi/main/scripts/install.sh | bash
+```
+
+### From source
+
+```bash
+git clone https://github.com/lil-limbo/colabapi.git
+cd colabapi
+pip install -e .
+```
+
+> **On Kali / Debian / Ubuntu**, `pip install -e .` may fail with `externally-managed-environment` (PEP 668). Pick one:
+>
+> ```bash
+> # Option A: override the guard (quickest)
+> pip install -e . --break-system-packages
+>
+> # Option B: use an isolated virtualenv (cleanest)
+> python3 -m venv .venv && source .venv/bin/activate && pip install -e .
+> ```
+
+**Requirement:** Python 3.9+. That's it. Everything else installs with the package.
+
+Verify everything is wired up:
+
+```bash
+colabapi doctor
+```
+
+## Quickstart
+
+```bash
+# 1. Sign in (opens Google's own login in your browser, no password asked)
+colabapi login
+
+# 2. Pick a runtime, then name the session when asked
+colabapi run                # interactive picker + name prompt
+colabapi run --runtime t4   # or go straight to a T4 GPU
+
+# 3. Use it (omit the name to pick from an arrow-key list)
+colabapi shell      # terminal on the session, live monitor on top
+colabapi monitor    # live CPU / GPU / RAM
+colabapi sessions   # list your sessions
+colabapi status     # reachability + estimated time remaining
+colabapi stop       # stop a session (or: colabapi stop <name>)
+
+# 4. Keep it alive after you log out of your server
+colabapi service install
+systemctl --user start colabapi
+```
+
+Press **Ctrl+C** to leave the monitor; type **`exit`** or press **Ctrl+D** to leave the shell. The Colab runtime keeps running until you stop it or Colab's timers end it.
+
+## Command reference
+
+| Command | What it does |
+|---|---|
+| `colabapi login` | Sign in via Google's browser flow (no password handled). |
+| `colabapi runtimes` | List runtime types and which need a paid plan. |
+| `colabapi run [--runtime KEY]` | Allocate a runtime and name the session (delegates to `colab new -s NAME`). |
+| `colabapi sessions` | List the sessions colabapi manages. |
+| `colabapi shell [NAME]` | Terminal on a session with a live monitor on top; arrow-key picker if NAME omitted. |
+| `colabapi repl [NAME]` | Interactive Python REPL on a session (`colab repl`). |
+| `colabapi monitor [NAME]` | Live CPU / GPU / RAM monitor for a session. |
+| `colabapi status [NAME]` | Session reachability and estimated time left. |
+| `colabapi stop [NAME]` | Stop a session (`colab stop`); arrow-key picker if NAME omitted. |
+| `colabapi daemon [NAME]` | Supervisory keepalive (used by the service). |
+| `colabapi service install\|uninstall\|status` | Manage the systemd user service. |
+| `colabapi doctor` | Check your environment and the `colab` CLI interface. |
+| `colabapi raw -- <args>` | Passthrough to the official `colab` CLI. |
+
+## Running as a Linux service
+
+`colabapi` installs as a **systemd user service** (no root required):
+
+```bash
+colabapi service install        # writes ~/.config/systemd/user/colabapi.service and enables lingering
+systemctl --user start colabapi
+systemctl --user status colabapi
+```
+
+Lingering (`loginctl enable-linger`) lets the service keep running after you disconnect from the VPS, which is exactly what you want for an always on demo.
+
+## Privacy
+
+**We do not capture your login data. We do not collect anything.**
+
+- `colabapi` has **no code path that asks for, reads, stores, or transmits your Google password.** Sign in is delegated entirely to Google's official CLI and happens in your own browser under Google's real login flow.
+- `colabapi` operates **no servers**. There is nothing for your data to be sent to. The only network connections are between *your* machine, Google, and (via the official CLI) *your* Colab runtime.
+- The only things written to disk are **plain preferences and session bookkeeping** (which runtime you picked and when), under `~/.config/colabapi` and `~/.local/state/colabapi`.
+- The project is **MIT licensed and fully open source.** [Read the code](https://github.com/lil-limbo/colabapi/tree/main/colabapi). If you don't trust a claim here, verify it in the source. That's the point.
+
+## Safety & Colab's limits (please read)
+
+`colabapi` deliberately uses **Google's official CLI** instead of the older "SSH into Colab via ngrok/cloudflared" trick, because Colab's own FAQ lists *remote control such as SSH shells* as an activity that can get a runtime (or an account) terminated. Using the sanctioned path is far safer for your Google account.
+
+Two limits **nobody** can bypass, and `colabapi` doesn't pretend to:
+
+- **Idle timeout (~90 min):** avoided by the keepalive while a session is active.
+- **Absolute max lifetime (~12 h free, up to 24 h paid):** a hard cap. `colabapi` shows an *estimate* of time left, but Google enforces the ceiling.
+
+Be a good citizen: don't hold GPU runtimes idle just to reserve them. Aggressive keepalive can get an account flagged.
+
+## FAQ
+
+**Does colabapi see or store my Google password?**
+No. Sign in is handled by Google's official CLI in your browser. `colabapi` has no password code path at all.
+
+**How do I keep a Google Colab session alive after closing the browser?**
+Allocate a runtime with `colabapi run`, then install the service (`colabapi service install`). Google's keepalive holds off the idle timeout; the systemd service keeps `colabapi` supervising it after you log out.
+
+**Can I get a terminal / shell into Google Colab?**
+Yes. `colabapi shell` opens a live PTY on the runtime via Google's `colab console`. `colabapi repl` gives a Python REPL.
+
+**Can I use a free Colab account?**
+Yes. CPU and T4 GPU runtimes are available on the free tier. Paid runtimes (L4, A100, H100, TPU) are shown but flagged; Colab itself refuses them on free accounts.
+
+**How is this different from Google's official `colab` CLI?**
+`colabapi` *uses* the official CLI under the hood and adds a single `colabapi` command, a runtime picker with paid tier flags, a live resource monitor, a session timer, and a ready made systemd service. If you only need raw commands, use `colab` directly; if you want the persistent service demo workflow, use `colabapi`.
+
+**Does it work on a VPS / headless server?**
+Yes, that's the main use case. Sign in once in a browser, then run everything from the server, optionally as a systemd service.
+
+**Is this affiliated with Google?**
+No. `colabapi` is an independent, open source wrapper. "Google Colab" is a trademark of Google LLC.
+
+## Contributing
+
+Issues and pull requests welcome. If Google changes the official CLI's flags, the runtime→flag mapping lives in a single file (`colabapi/runtime.py`) and `colabapi doctor` will flag drift.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

colabapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+colabapi/__init__.py,sha256=xlliW1D0rdUbCaQml94K_VEVb4aMQV6PfWpHB8dbpz4,263
+colabapi/cli.py,sha256=MgpH_zs7aLjpVZjoxZLI9Ic_8z7cs1HuU9XPjygKFlg,17657
+colabapi/colabcli.py,sha256=AT51fxGzc8TTiu3xK8qp9R4jIjnF4r_pJy3_Zg3JS8E,9410
+colabapi/config.py,sha256=AXNKEXDk6VuWWEboRPNrNysaMnNGv-xBP7VBFtUrHwU,5011
+colabapi/keepalive.py,sha256=wE2m1x3Eruf8d0rpKqZg9Tr2dET7ZofLvcZlLQZV5GU,2483
+colabapi/monitor.py,sha256=Z-hhJohafL8F6p7vuhNkR1jiOMV-HHIV-V8oCE99cb8,4819
+colabapi/runtime.py,sha256=vSsfzIcKqPuu05T4ZY6TTVkikUzvBqfr2sgR_sHkN10,3004
+colabapi/service.py,sha256=_7-Z031HX-dmg2EZ-J9ZDklK22se0KJM6JkkdNU0UlA,2196
+colabapi/shellview.py,sha256=zH3-BGIjuwphl1GSxY40j8j-HZN45kyApGJ-tNFBFPQ,4428
+colabapi/timing.py,sha256=6TlQTfY6cId-UJL55wU_-Ht7_90RasKJlyYZ-uVsvr4,1714
+colabapi/ui.py,sha256=NDtVyf1oBH-eHK8sDf5mPdUnC9lPilkm_VJSmi9n084,3001
+colabapi-0.1.0.dist-info/licenses/LICENSE,sha256=yI25WSp2hzlwIoiklr-Re5bhLrp42lAKTHhCH4yPi_w,1066
+colabapi-0.1.0.dist-info/METADATA,sha256=JOipv-TNYqru66RrV-gfPfN64sYA3n5jXxV5mbr8pQI,11850
+colabapi-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+colabapi-0.1.0.dist-info/entry_points.txt,sha256=mirIudRE-VzrLVP7uL_Indt0qoL3z9X-iVTHi0I6qJk,47
+colabapi-0.1.0.dist-info/top_level.txt,sha256=oS9cg0HsjOh_gD_TBWEF7EYRoeqPRhM0On6ZKqONeA0,9
+colabapi-0.1.0.dist-info/RECORD,,

colabapi-0.1.0.dist-info/WHEEL

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

colabapi-0.1.0.dist-info/entry_points.txt

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

colabapi-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lil-limbo
+
+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.

colabapi-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+colabapi