cotop 0.1.0__tar.gz → 0.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {cotop-0.1.0 → cotop-0.3.0}/.github/workflows/publish.yml +2 -2
- cotop-0.3.0/PKG-INFO +138 -0
- cotop-0.3.0/README.md +115 -0
- cotop-0.3.0/SECURITY.md +23 -0
- {cotop-0.1.0 → cotop-0.3.0}/docs/data-sources.md +32 -9
- cotop-0.3.0/docs/images/dashboard.png +0 -0
- cotop-0.3.0/docs/images/demo.gif +0 -0
- cotop-0.3.0/docs/images/stop.png +0 -0
- {cotop-0.1.0 → cotop-0.3.0}/pyproject.toml +2 -3
- cotop-0.3.0/scripts/demo.tape +36 -0
- cotop-0.3.0/scripts/screenshots.py +39 -0
- {cotop-0.1.0 → cotop-0.3.0}/src/cotop/app.py +94 -23
- {cotop-0.1.0 → cotop-0.3.0}/src/cotop/colab.py +27 -40
- cotop-0.3.0/src/cotop/colab_cli_calls.py +70 -0
- cotop-0.3.0/src/cotop/demo.py +221 -0
- {cotop-0.1.0 → cotop-0.3.0}/src/cotop/model.py +43 -11
- cotop-0.3.0/tests/test_app.py +410 -0
- cotop-0.3.0/tests/test_colab.py +79 -0
- cotop-0.3.0/tests/test_handoff.py +100 -0
- {cotop-0.1.0 → cotop-0.3.0}/tests/test_model.py +28 -0
- {cotop-0.1.0 → cotop-0.3.0}/uv.lock +2 -4
- cotop-0.1.0/PKG-INFO +0 -100
- cotop-0.1.0/README.md +0 -76
- cotop-0.1.0/docs/images/dashboard.png +0 -0
- cotop-0.1.0/docs/images/stop.png +0 -0
- cotop-0.1.0/scripts/screenshots.py +0 -205
- cotop-0.1.0/tests/test_app.py +0 -231
- cotop-0.1.0/tests/test_colab.py +0 -13
- {cotop-0.1.0 → cotop-0.3.0}/.gitignore +0 -0
- {cotop-0.1.0 → cotop-0.3.0}/LICENSE +0 -0
- {cotop-0.1.0 → cotop-0.3.0}/src/cotop/__init__.py +0 -0
- {cotop-0.1.0 → cotop-0.3.0}/src/cotop/widgets.py +0 -0
- {cotop-0.1.0 → cotop-0.3.0}/tests/__init__.py +0 -0
- {cotop-0.1.0 → cotop-0.3.0}/tests/fixtures/resources_g4.txt +0 -0
- {cotop-0.1.0 → cotop-0.3.0}/tests/test_widgets.py +0 -0
|
@@ -13,8 +13,8 @@ jobs:
|
|
|
13
13
|
id-token: write # the OIDC token PyPI checks
|
|
14
14
|
contents: read
|
|
15
15
|
steps:
|
|
16
|
-
- uses: actions/checkout@v4
|
|
17
|
-
- uses: astral-sh/setup-uv@v6
|
|
16
|
+
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
|
|
17
|
+
- uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
|
|
18
18
|
- name: Tag matches the package version
|
|
19
19
|
run: test "v$(uv version --short)" = "${GITHUB_REF_NAME}"
|
|
20
20
|
- run: uv build
|
cotop-0.3.0/PKG-INFO
ADDED
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: cotop
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: A top-like terminal dashboard for Google Colab runtimes and compute units
|
|
5
|
+
Project-URL: Homepage, https://github.com/benngarcia/cotop
|
|
6
|
+
Project-URL: Issues, https://github.com/benngarcia/cotop/issues
|
|
7
|
+
License-Expression: Apache-2.0
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Keywords: colab,dashboard,google-colab,gpu,textual,tui
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Intended Audience :: Science/Research
|
|
14
|
+
Classifier: Operating System :: MacOS
|
|
15
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Topic :: System :: Monitoring
|
|
18
|
+
Requires-Python: >=3.12
|
|
19
|
+
Requires-Dist: google-colab-cli~=0.8.0
|
|
20
|
+
Requires-Dist: requests
|
|
21
|
+
Requires-Dist: textual<9,>=6
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
|
|
24
|
+
# cotop
|
|
25
|
+
|
|
26
|
+
`top` for Google Colab: compute units, runtimes and what they cost, live in your terminal.
|
|
27
|
+
|
|
28
|
+

|
|
29
|
+
|
|
30
|
+
- **Your account:** compute units left, the hourly rate, when you run out, and the rate over the last day. Compute units left turn red when they run out within a day.
|
|
31
|
+
- **Runtimes:** every VM on your account, most expensive first, including ones opened in a browser, with a live GPU sparkline, rate, spend, uptime and state. A runtime idle while it bills, out of RAM or disk, or unreachable says so in its row.
|
|
32
|
+
- **The selected runtime:** a braille graph of GPU utilization, read every two seconds, with VRAM, RAM and disk meters, what it has cost and its recent activity. On a runtime without a GPU, the graph shows RAM.
|
|
33
|
+
- **History:** press `h` for past sessions, how long each ran and roughly what it cost.
|
|
34
|
+
- **Actions:** stop a runtime, restart its kernel, or open a shell on it.
|
|
35
|
+
|
|
36
|
+
cotop works on top of the official [Colab CLI](https://pypi.org/project/google-colab-cli/). It uses the CLI's sign-in, session names and history, so runtimes you start with `colab new` show up by name.
|
|
37
|
+
|
|
38
|
+
## Install
|
|
39
|
+
|
|
40
|
+
```sh
|
|
41
|
+
uv tool install cotop
|
|
42
|
+
cotop
|
|
43
|
+
cotop --demo # a made-up account with twelve runtimes; no sign-in
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
cotop needs Python 3.12 or later. It is tested on macOS and should work on Linux. If you have not signed in to the Colab CLI yet, cotop runs the same Google sign-in on first launch. On macOS, Keychain may ask once whether cotop's Python can read the Colab CLI's token.
|
|
47
|
+
|
|
48
|
+
## Keys
|
|
49
|
+
|
|
50
|
+
| Key | Action |
|
|
51
|
+
|---|---|
|
|
52
|
+
| `↑` `↓` or `k` `j` | Select a runtime |
|
|
53
|
+
| `h` | Past sessions and the hardware your account can use |
|
|
54
|
+
| `r` | Refresh now (cotop also refreshes every 15 seconds) |
|
|
55
|
+
| `s` | Stop the selected runtime |
|
|
56
|
+
| `R` | Restart its kernel |
|
|
57
|
+
| `x` | Open a shell on it with `colab ssh` |
|
|
58
|
+
| `?` | Show every key |
|
|
59
|
+
| `q` | Quit |
|
|
60
|
+
|
|
61
|
+

|
|
62
|
+
|
|
63
|
+
Stop and restart ask first, and Cancel has focus. `colab ssh` looks for `~/.ssh/id_ed25519.pub` or `~/.ssh/id_ecdsa.pub`. For another key, start cotop with `cotop -i ~/.ssh/KEY.pub`. Restart and ssh work only on runtimes started with the Colab CLI. Stop works on any runtime.
|
|
64
|
+
|
|
65
|
+
## Which numbers are estimates
|
|
66
|
+
|
|
67
|
+
Colab reports one hourly rate for the whole account, not one per runtime. cotop shows a per-runtime rate as follows:
|
|
68
|
+
|
|
69
|
+
- With one runtime, the rate is exact.
|
|
70
|
+
- With several runtimes on the same hardware, cotop splits the total evenly.
|
|
71
|
+
- Otherwise cotop uses a rate it learned earlier, when only that hardware was running. These rates are stored in `~/.cache/cotop/rates.json`.
|
|
72
|
+
- With no learned rate, the column shows `?`.
|
|
73
|
+
|
|
74
|
+
Estimates start with `≈`, and upper bounds start with `≤`. Colab boots VMs before it assigns them, so uptime and spend count from the assignment time in the CLI's history. A runtime opened in a browser has no assignment time, so cotop counts from VM boot and shows an upper bound.
|
|
75
|
+
|
|
76
|
+
[docs/data-sources.md](docs/data-sources.md) lists each request cotop makes and what it reads.
|
|
77
|
+
|
|
78
|
+
## What cotop can touch
|
|
79
|
+
|
|
80
|
+
cotop signs in with the Colab CLI's own credentials, so it can do anything `colab` can, with the access you granted when you signed in. It adds no credentials of its own.
|
|
81
|
+
|
|
82
|
+
### Guarantees
|
|
83
|
+
|
|
84
|
+
Each line is true of this release and names the test on `main` that checks it:
|
|
85
|
+
|
|
86
|
+
- Before it stops, restarts or opens a shell on a named runtime, cotop checks that the name still points at the runtime you selected (`test_every_named_action_checks_the_name_still_means_this_runtime`).
|
|
87
|
+
- No module in `src/cotop` other than `colab_cli_calls.py` has an import statement for `google-colab-cli`, or writes `_session` (the attribute that holds the signed-in session) as an attribute or a string literal (`test_only_the_handoff_module_imports_colab_cli_or_touches_the_session`).
|
|
88
|
+
- A runtime's proxy token never follows a redirect (`test_the_proxy_token_never_follows_a_redirect`).
|
|
89
|
+
- From the CLI's history, cotop never shows code, outputs or prompt replies (`test_history_never_surfaces_code_outputs_or_stdin`).
|
|
90
|
+
|
|
91
|
+
### What cotop does in this release
|
|
92
|
+
|
|
93
|
+
- It sends GET requests through the CLI's signed-in session: to `colab.research.google.com` for the balance and the runtime list, and to Google's userinfo endpoint for your email address.
|
|
94
|
+
- It sends GET requests to each runtime's proxy, at the URL Colab returns for it, with that runtime's proxy token.
|
|
95
|
+
- It reads the CLI's history files in `~/.config/colab-cli/history/` and the CLI's session list.
|
|
96
|
+
- It writes learned rates and balance samples to `~/.cache/cotop/`.
|
|
97
|
+
- For a runtime the CLI started, it runs `colab stop -s NAME` or `colab restart-kernel -s NAME` when you press `s` or `R` and confirm, and `colab ssh -s NAME [-i KEY]` in your terminal when you press `x`.
|
|
98
|
+
- `cotop --demo` returns from `main()` before `sign_in` and runs on the made-up account in `src/cotop/demo.py`, with its cache in a temporary directory (`run_demo`).
|
|
99
|
+
|
|
100
|
+
[docs/data-sources.md](docs/data-sources.md) gives each request and how often cotop sends it.
|
|
101
|
+
|
|
102
|
+
### Calls into the Colab CLI
|
|
103
|
+
|
|
104
|
+
`src/cotop/colab_cli_calls.py` hands these calls to `google-colab-cli`:
|
|
105
|
+
|
|
106
|
+
- `sign_in` calls the CLI's `get_credentials()` at start. It returns a `Google`, which keeps the session private and offers two calls:
|
|
107
|
+
- `Google.get` sends a GET through the session. When the session's access token expires, the session refreshes it with a POST.
|
|
108
|
+
- `Google.unassign` calls the CLI client's `unassign`, to stop a runtime the CLI didn't start.
|
|
109
|
+
- `named_sessions` calls the CLI's `StateStore(path).list()`, once `~/.config/colab-cli/sessions.json` exists.
|
|
110
|
+
- `colab_argv` builds the `colab` command lines described above.
|
|
111
|
+
|
|
112
|
+
What these calls read, write and send inside the CLI is the CLI's behavior.
|
|
113
|
+
|
|
114
|
+
### What the CLI does (0.8.0; not a complete list)
|
|
115
|
+
|
|
116
|
+
These examples are taken from [google-colab-cli 0.8.0](https://pypi.org/project/google-colab-cli/0.8.0/):
|
|
117
|
+
|
|
118
|
+
- `get_credentials()` reads and writes the OS keyring. It moves an old plaintext `~/.config/colab-cli/token.json` into the keyring, and reads `~/.colab-cli-oauth-config.json` if that file exists.
|
|
119
|
+
- The three `colab` commands cotop runs log to `~/.config/colab-cli/colab.log` with secrets redacted, update files under `~/.config/colab-cli/`, and check `pypi.org` for an update at most once a day.
|
|
120
|
+
- `colab ssh` reads your SSH public key.
|
|
121
|
+
|
|
122
|
+
## Not affiliated with Google
|
|
123
|
+
|
|
124
|
+
cotop is an independent project. It relies on internal parts of `google-colab-cli` and on Colab endpoints that are not public APIs. Either can change without notice. cotop pins the Colab CLI's minor version for that reason.
|
|
125
|
+
|
|
126
|
+
## Development
|
|
127
|
+
|
|
128
|
+
```sh
|
|
129
|
+
uv sync
|
|
130
|
+
uv run pytest
|
|
131
|
+
uv run python scripts/screenshots.py OUT_DIR # README screenshots, rendered from the demo account
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
To release, set `version` in `pyproject.toml`, then push a matching tag such as `v0.1.0`. The [publish workflow](.github/workflows/publish.yml) builds the package and uploads it to PyPI with trusted publishing.
|
|
135
|
+
|
|
136
|
+
## License
|
|
137
|
+
|
|
138
|
+
[Apache 2.0](LICENSE)
|
cotop-0.3.0/README.md
ADDED
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# cotop
|
|
2
|
+
|
|
3
|
+
`top` for Google Colab: compute units, runtimes and what they cost, live in your terminal.
|
|
4
|
+
|
|
5
|
+

|
|
6
|
+
|
|
7
|
+
- **Your account:** compute units left, the hourly rate, when you run out, and the rate over the last day. Compute units left turn red when they run out within a day.
|
|
8
|
+
- **Runtimes:** every VM on your account, most expensive first, including ones opened in a browser, with a live GPU sparkline, rate, spend, uptime and state. A runtime idle while it bills, out of RAM or disk, or unreachable says so in its row.
|
|
9
|
+
- **The selected runtime:** a braille graph of GPU utilization, read every two seconds, with VRAM, RAM and disk meters, what it has cost and its recent activity. On a runtime without a GPU, the graph shows RAM.
|
|
10
|
+
- **History:** press `h` for past sessions, how long each ran and roughly what it cost.
|
|
11
|
+
- **Actions:** stop a runtime, restart its kernel, or open a shell on it.
|
|
12
|
+
|
|
13
|
+
cotop works on top of the official [Colab CLI](https://pypi.org/project/google-colab-cli/). It uses the CLI's sign-in, session names and history, so runtimes you start with `colab new` show up by name.
|
|
14
|
+
|
|
15
|
+
## Install
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
uv tool install cotop
|
|
19
|
+
cotop
|
|
20
|
+
cotop --demo # a made-up account with twelve runtimes; no sign-in
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
cotop needs Python 3.12 or later. It is tested on macOS and should work on Linux. If you have not signed in to the Colab CLI yet, cotop runs the same Google sign-in on first launch. On macOS, Keychain may ask once whether cotop's Python can read the Colab CLI's token.
|
|
24
|
+
|
|
25
|
+
## Keys
|
|
26
|
+
|
|
27
|
+
| Key | Action |
|
|
28
|
+
|---|---|
|
|
29
|
+
| `↑` `↓` or `k` `j` | Select a runtime |
|
|
30
|
+
| `h` | Past sessions and the hardware your account can use |
|
|
31
|
+
| `r` | Refresh now (cotop also refreshes every 15 seconds) |
|
|
32
|
+
| `s` | Stop the selected runtime |
|
|
33
|
+
| `R` | Restart its kernel |
|
|
34
|
+
| `x` | Open a shell on it with `colab ssh` |
|
|
35
|
+
| `?` | Show every key |
|
|
36
|
+
| `q` | Quit |
|
|
37
|
+
|
|
38
|
+

|
|
39
|
+
|
|
40
|
+
Stop and restart ask first, and Cancel has focus. `colab ssh` looks for `~/.ssh/id_ed25519.pub` or `~/.ssh/id_ecdsa.pub`. For another key, start cotop with `cotop -i ~/.ssh/KEY.pub`. Restart and ssh work only on runtimes started with the Colab CLI. Stop works on any runtime.
|
|
41
|
+
|
|
42
|
+
## Which numbers are estimates
|
|
43
|
+
|
|
44
|
+
Colab reports one hourly rate for the whole account, not one per runtime. cotop shows a per-runtime rate as follows:
|
|
45
|
+
|
|
46
|
+
- With one runtime, the rate is exact.
|
|
47
|
+
- With several runtimes on the same hardware, cotop splits the total evenly.
|
|
48
|
+
- Otherwise cotop uses a rate it learned earlier, when only that hardware was running. These rates are stored in `~/.cache/cotop/rates.json`.
|
|
49
|
+
- With no learned rate, the column shows `?`.
|
|
50
|
+
|
|
51
|
+
Estimates start with `≈`, and upper bounds start with `≤`. Colab boots VMs before it assigns them, so uptime and spend count from the assignment time in the CLI's history. A runtime opened in a browser has no assignment time, so cotop counts from VM boot and shows an upper bound.
|
|
52
|
+
|
|
53
|
+
[docs/data-sources.md](docs/data-sources.md) lists each request cotop makes and what it reads.
|
|
54
|
+
|
|
55
|
+
## What cotop can touch
|
|
56
|
+
|
|
57
|
+
cotop signs in with the Colab CLI's own credentials, so it can do anything `colab` can, with the access you granted when you signed in. It adds no credentials of its own.
|
|
58
|
+
|
|
59
|
+
### Guarantees
|
|
60
|
+
|
|
61
|
+
Each line is true of this release and names the test on `main` that checks it:
|
|
62
|
+
|
|
63
|
+
- Before it stops, restarts or opens a shell on a named runtime, cotop checks that the name still points at the runtime you selected (`test_every_named_action_checks_the_name_still_means_this_runtime`).
|
|
64
|
+
- No module in `src/cotop` other than `colab_cli_calls.py` has an import statement for `google-colab-cli`, or writes `_session` (the attribute that holds the signed-in session) as an attribute or a string literal (`test_only_the_handoff_module_imports_colab_cli_or_touches_the_session`).
|
|
65
|
+
- A runtime's proxy token never follows a redirect (`test_the_proxy_token_never_follows_a_redirect`).
|
|
66
|
+
- From the CLI's history, cotop never shows code, outputs or prompt replies (`test_history_never_surfaces_code_outputs_or_stdin`).
|
|
67
|
+
|
|
68
|
+
### What cotop does in this release
|
|
69
|
+
|
|
70
|
+
- It sends GET requests through the CLI's signed-in session: to `colab.research.google.com` for the balance and the runtime list, and to Google's userinfo endpoint for your email address.
|
|
71
|
+
- It sends GET requests to each runtime's proxy, at the URL Colab returns for it, with that runtime's proxy token.
|
|
72
|
+
- It reads the CLI's history files in `~/.config/colab-cli/history/` and the CLI's session list.
|
|
73
|
+
- It writes learned rates and balance samples to `~/.cache/cotop/`.
|
|
74
|
+
- For a runtime the CLI started, it runs `colab stop -s NAME` or `colab restart-kernel -s NAME` when you press `s` or `R` and confirm, and `colab ssh -s NAME [-i KEY]` in your terminal when you press `x`.
|
|
75
|
+
- `cotop --demo` returns from `main()` before `sign_in` and runs on the made-up account in `src/cotop/demo.py`, with its cache in a temporary directory (`run_demo`).
|
|
76
|
+
|
|
77
|
+
[docs/data-sources.md](docs/data-sources.md) gives each request and how often cotop sends it.
|
|
78
|
+
|
|
79
|
+
### Calls into the Colab CLI
|
|
80
|
+
|
|
81
|
+
`src/cotop/colab_cli_calls.py` hands these calls to `google-colab-cli`:
|
|
82
|
+
|
|
83
|
+
- `sign_in` calls the CLI's `get_credentials()` at start. It returns a `Google`, which keeps the session private and offers two calls:
|
|
84
|
+
- `Google.get` sends a GET through the session. When the session's access token expires, the session refreshes it with a POST.
|
|
85
|
+
- `Google.unassign` calls the CLI client's `unassign`, to stop a runtime the CLI didn't start.
|
|
86
|
+
- `named_sessions` calls the CLI's `StateStore(path).list()`, once `~/.config/colab-cli/sessions.json` exists.
|
|
87
|
+
- `colab_argv` builds the `colab` command lines described above.
|
|
88
|
+
|
|
89
|
+
What these calls read, write and send inside the CLI is the CLI's behavior.
|
|
90
|
+
|
|
91
|
+
### What the CLI does (0.8.0; not a complete list)
|
|
92
|
+
|
|
93
|
+
These examples are taken from [google-colab-cli 0.8.0](https://pypi.org/project/google-colab-cli/0.8.0/):
|
|
94
|
+
|
|
95
|
+
- `get_credentials()` reads and writes the OS keyring. It moves an old plaintext `~/.config/colab-cli/token.json` into the keyring, and reads `~/.colab-cli-oauth-config.json` if that file exists.
|
|
96
|
+
- The three `colab` commands cotop runs log to `~/.config/colab-cli/colab.log` with secrets redacted, update files under `~/.config/colab-cli/`, and check `pypi.org` for an update at most once a day.
|
|
97
|
+
- `colab ssh` reads your SSH public key.
|
|
98
|
+
|
|
99
|
+
## Not affiliated with Google
|
|
100
|
+
|
|
101
|
+
cotop is an independent project. It relies on internal parts of `google-colab-cli` and on Colab endpoints that are not public APIs. Either can change without notice. cotop pins the Colab CLI's minor version for that reason.
|
|
102
|
+
|
|
103
|
+
## Development
|
|
104
|
+
|
|
105
|
+
```sh
|
|
106
|
+
uv sync
|
|
107
|
+
uv run pytest
|
|
108
|
+
uv run python scripts/screenshots.py OUT_DIR # README screenshots, rendered from the demo account
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
To release, set `version` in `pyproject.toml`, then push a matching tag such as `v0.1.0`. The [publish workflow](.github/workflows/publish.yml) builds the package and uploads it to PyPI with trusted publishing.
|
|
112
|
+
|
|
113
|
+
## License
|
|
114
|
+
|
|
115
|
+
[Apache 2.0](LICENSE)
|
cotop-0.3.0/SECURITY.md
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Security
|
|
2
|
+
|
|
3
|
+
cotop runs with your Colab CLI sign-in, so a bug in it could expose that token
|
|
4
|
+
or act on a runtime you didn't choose. The README's
|
|
5
|
+
[guarantees](README.md#guarantees) say what cotop's code holds to, each with the
|
|
6
|
+
test on `main` that checks it.
|
|
7
|
+
|
|
8
|
+
## Scope
|
|
9
|
+
|
|
10
|
+
In scope is cotop's own code. Examples:
|
|
11
|
+
- a token reaching the screen, the cache, or a host other than the one Colab returned;
|
|
12
|
+
- an action on a runtime other than the one you chose.
|
|
13
|
+
|
|
14
|
+
Behavior inside `google-colab-cli` or the `colab` command belongs to that
|
|
15
|
+
project.
|
|
16
|
+
|
|
17
|
+
## Reporting a vulnerability
|
|
18
|
+
|
|
19
|
+
Don't put details in a public issue. Report it privately through
|
|
20
|
+
[GitHub's form](https://github.com/benngarcia/cotop/security/advisories/new),
|
|
21
|
+
which goes to the maintainer instead of the public.
|
|
22
|
+
|
|
23
|
+
Fixes go into the latest release on PyPI.
|
|
@@ -1,18 +1,26 @@
|
|
|
1
1
|
# Where cotop's numbers come from
|
|
2
2
|
|
|
3
|
-
cotop polls the account, the runtime list and each runtime's kernels
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
cotop polls the account, the runtime list and each runtime's kernels at a
|
|
4
|
+
15-second interval, on `r` and after each action, and each runtime's resources
|
|
5
|
+
at a 2-second interval for the graphs. In this release those requests are GETs. The Colab
|
|
6
|
+
CLI's signed-in session refreshes its access token with a POST when it expires.
|
|
7
|
+
Stop sends a POST: the colab CLI's own `colab stop`, or for a runtime the CLI
|
|
8
|
+
didn't start, the CLI client's `unassign` call. The README's
|
|
9
|
+
[What cotop can touch](../README.md#what-cotop-can-touch) lists the guarantees
|
|
10
|
+
and the calls cotop makes into the CLI.
|
|
11
|
+
|
|
12
|
+
`cotop --demo` runs on `src/cotop/demo.py`, a made-up account, and sends no
|
|
13
|
+
requests at all.
|
|
6
14
|
|
|
7
15
|
| Panel | Source | Notes |
|
|
8
16
|
|---|---|---|
|
|
9
17
|
| Account email | `openidconnect.googleapis.com/v1/userinfo` | Signed in with the Colab CLI's OAuth token from the OS keyring |
|
|
10
18
|
| Balance, rate, eligible hardware | `colab.research.google.com/tun/m/ccu-info` | The same call as `colab usage`. The CLI drops `eligibleGpus` and `eligibleTpus`; cotop reads the raw body |
|
|
11
19
|
| Runtimes | `/tun/m/assignments` | Every VM the account holds, including ones opened in a browser. These show as *untracked* |
|
|
12
|
-
| Runtime names, running command | `~/.config/colab-cli/sessions.json` | Read under the CLI's file lock and joined on `endpoint`.
|
|
20
|
+
| Runtime names, running command | `~/.config/colab-cli/sessions.json` | Read under the CLI's file lock and joined on `endpoint`. `colab sessions` and `colab status` prune and rewrite this file, and `colab stop`, which cotop runs on `s`, updates it |
|
|
13
21
|
| Kernel state, idle time, clients | Runtime proxy `/api/kernels`, `/api/status` | Requests carry `?no_track_activity=1` |
|
|
14
22
|
| GPU, VRAM, RAM, disk | Runtime proxy `/api/colab/resources`, every 2 s | The same endpoint the Colab VS Code extension uses. The body has an XSSI prefix. Values change every second; a read takes about 0.4 s. A read that fails or takes over 3 s is a gap in the graph, never a zero |
|
|
15
|
-
| Assignment time, recent events, past sessions | `~/.config/colab-cli/history/*.jsonl` |
|
|
23
|
+
| Assignment time, recent events, past sessions | `~/.config/colab-cli/history/*.jsonl` | Code, outputs and prompt replies are not shown; see the README's guarantees |
|
|
16
24
|
|
|
17
25
|
## Estimates
|
|
18
26
|
|
|
@@ -37,19 +45,34 @@ the fall in balance between the first and last settled step in the past hour,
|
|
|
37
45
|
logged in `~/.cache/cotop/usage.jsonl`. You can compare it with the rate
|
|
38
46
|
Colab reports.
|
|
39
47
|
|
|
48
|
+
## Watching did not keep an idle runtime alive
|
|
49
|
+
|
|
50
|
+
Tested on 2026-11-17 with two idle CPU runtimes started with `colab new`, neither
|
|
51
|
+
with a kernel. One was read the way cotop reads a runtime: the same endpoints
|
|
52
|
+
and flag, its resources about every 2 seconds and its kernels about every 16 to
|
|
53
|
+
20 seconds. The other was never touched. Colab reclaimed both in the same
|
|
54
|
+
one-minute check, 3 hours 1 minute after they started.
|
|
55
|
+
|
|
56
|
+
The read requests carry `no_track_activity=1`, and Jupyter honors it: the
|
|
57
|
+
runtime's `last_activity` did not move after flagged reads, and did move after
|
|
58
|
+
the same reads without the flag. Colab does not document what it counts as
|
|
59
|
+
idle activity.
|
|
60
|
+
|
|
40
61
|
## Not verified
|
|
41
62
|
|
|
42
|
-
- Whether reading a runtime's Jupyter API delays Colab's idle shutdown. Requests
|
|
43
|
-
send `no_track_activity=1`, including the reads every 2 seconds. Colab's own
|
|
44
|
-
idle signal is not documented.
|
|
45
63
|
- That billing starts at assignment rather than at VM boot.
|
|
64
|
+
- Whether Colab reclaimed these runtimes for being idle or at a fixed time
|
|
65
|
+
limit near 3 hours. The test had no runtime that stayed active, so it cannot
|
|
66
|
+
tell the two apart.
|
|
67
|
+
- Runtimes with an idle kernel, and GPU or TPU runtimes. The test covered CPU
|
|
68
|
+
runtimes without a kernel only.
|
|
46
69
|
|
|
47
70
|
## Actions
|
|
48
71
|
|
|
49
72
|
| Key | Runs | Notes |
|
|
50
73
|
|---|---|---|
|
|
51
74
|
| `s` | `colab stop -s NAME` | For an untracked runtime, the CLI's `Client.unassign(endpoint)`, because no name exists |
|
|
52
|
-
| `
|
|
75
|
+
| `R` | `colab restart-kernel -s NAME` | Only for runtimes the CLI started |
|
|
53
76
|
| `x` | `colab ssh -s NAME [-i KEY]` | The dashboard suspends while the shell runs. A failed connection waits for Enter so its error stays readable |
|
|
54
77
|
|
|
55
78
|
The CLI resolves names, not endpoints. Before a named action, cotop reads
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "cotop"
|
|
3
|
-
version = "0.
|
|
3
|
+
version = "0.3.0"
|
|
4
4
|
description = "A top-like terminal dashboard for Google Colab runtimes and compute units"
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
license = "Apache-2.0"
|
|
@@ -20,9 +20,8 @@ classifiers = [
|
|
|
20
20
|
dependencies = [
|
|
21
21
|
# cotop reads the CLI's internals (auth, session file, client), so it pins the minor version.
|
|
22
22
|
"google-colab-cli~=0.8.0",
|
|
23
|
-
"packaging",
|
|
24
23
|
"requests",
|
|
25
|
-
"textual>=6",
|
|
24
|
+
"textual>=6,<9", # 6.0 and 8.2 tested; 9 may change the DataTable and screen APIs cotop uses
|
|
26
25
|
]
|
|
27
26
|
|
|
28
27
|
[project.urls]
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Records docs/images/demo.gif from `cotop --demo`; nothing here touches a Colab account.
|
|
2
|
+
# Run from the repo root: vhs scripts/demo.tape (it syncs the environment itself,
|
|
3
|
+
# and fails without writing the GIF if cotop doesn't start).
|
|
4
|
+
Output docs/images/demo.gif
|
|
5
|
+
Set Shell "bash"
|
|
6
|
+
Set FontSize 15
|
|
7
|
+
Set Width 1360
|
|
8
|
+
Set Height 820
|
|
9
|
+
Set Padding 12
|
|
10
|
+
Set Framerate 12
|
|
11
|
+
Set TypingSpeed 0
|
|
12
|
+
|
|
13
|
+
Hide
|
|
14
|
+
Type "export PS1='$ ' && uv sync -q && clear && echo synced" Enter
|
|
15
|
+
Wait+Screen@180s /^synced/
|
|
16
|
+
Type "uv run --no-sync cotop --demo" Enter
|
|
17
|
+
Wait+Screen@30s /compute units left/
|
|
18
|
+
Sleep 1s
|
|
19
|
+
Show
|
|
20
|
+
Sleep 3s
|
|
21
|
+
Type "j" Sleep 1.2s
|
|
22
|
+
Type "j" Sleep 1.2s
|
|
23
|
+
Type "j" Sleep 1.2s
|
|
24
|
+
Type "j" Sleep 2.5s
|
|
25
|
+
Type "j" Sleep 1.2s
|
|
26
|
+
Type "j" Sleep 1.2s
|
|
27
|
+
Type "j" Sleep 2.5s
|
|
28
|
+
Type "?" Sleep 3s
|
|
29
|
+
Type "?" Sleep 1s
|
|
30
|
+
Type "h" Sleep 4s
|
|
31
|
+
Escape Sleep 1s
|
|
32
|
+
Type "k" Sleep 1s
|
|
33
|
+
Type "s" Sleep 3s
|
|
34
|
+
Type "n" Sleep 2s
|
|
35
|
+
Hide
|
|
36
|
+
Type "q"
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
"""Render the README screenshots from the demo account; no Colab account is touched. The GIF comes from
|
|
2
|
+
scripts/demo.tape: `vhs scripts/demo.tape`.
|
|
3
|
+
|
|
4
|
+
uv run python scripts/screenshots.py OUT_DIR
|
|
5
|
+
|
|
6
|
+
writes OUT_DIR/dashboard.svg (138x40), small.svg (80x24), large.svg (180x52) and
|
|
7
|
+
stop.svg. To get the PNGs in docs/images:
|
|
8
|
+
|
|
9
|
+
chrome --headless --force-device-scale-factor=2 --window-size=1380,880 \\
|
|
10
|
+
--screenshot=docs/images/dashboard.png OUT_DIR/dashboard.svg
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
import asyncio
|
|
14
|
+
import sys
|
|
15
|
+
import tempfile
|
|
16
|
+
from pathlib import Path
|
|
17
|
+
|
|
18
|
+
from cotop.app import demo_dashboard
|
|
19
|
+
|
|
20
|
+
SIZES = {"dashboard": (138, 40), "small": (80, 24), "large": (180, 52)}
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
async def shoot(out: Path) -> None:
|
|
24
|
+
for name, size in SIZES.items():
|
|
25
|
+
with tempfile.TemporaryDirectory() as cache:
|
|
26
|
+
app = demo_dashboard(Path(cache))
|
|
27
|
+
async with app.run_test(size=size) as pilot:
|
|
28
|
+
for _ in range(3):
|
|
29
|
+
await app.workers.wait_for_complete()
|
|
30
|
+
await pilot.pause()
|
|
31
|
+
app.save_screenshot(f"{name}.svg", path=str(out))
|
|
32
|
+
if name == "dashboard":
|
|
33
|
+
await pilot.press("down", "down", "down", "down", "down", "s")
|
|
34
|
+
await pilot.pause()
|
|
35
|
+
app.save_screenshot("stop.svg", path=str(out))
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
if __name__ == "__main__":
|
|
39
|
+
asyncio.run(shoot(Path(sys.argv[1])))
|