kdev-cli 0.1.3__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.
- kdev_cli-0.1.3/.gitignore +11 -0
- kdev_cli-0.1.3/LICENSE +21 -0
- kdev_cli-0.1.3/PKG-INFO +598 -0
- kdev_cli-0.1.3/README.md +567 -0
- kdev_cli-0.1.3/pyproject.toml +73 -0
- kdev_cli-0.1.3/src/kdev/__init__.py +7 -0
- kdev_cli-0.1.3/src/kdev/__main__.py +3 -0
- kdev_cli-0.1.3/src/kdev/api.py +408 -0
- kdev_cli-0.1.3/src/kdev/auth.py +115 -0
- kdev_cli-0.1.3/src/kdev/bootstrap.py +510 -0
- kdev_cli-0.1.3/src/kdev/cli.py +162 -0
- kdev_cli-0.1.3/src/kdev/cloudflared.py +179 -0
- kdev_cli-0.1.3/src/kdev/commands/__init__.py +5 -0
- kdev_cli-0.1.3/src/kdev/commands/_common.py +51 -0
- kdev_cli-0.1.3/src/kdev/commands/account.py +148 -0
- kdev_cli-0.1.3/src/kdev/commands/box.py +694 -0
- kdev_cli-0.1.3/src/kdev/commands/doctor.py +127 -0
- kdev_cli-0.1.3/src/kdev/commands/home.py +92 -0
- kdev_cli-0.1.3/src/kdev/commands/settings.py +164 -0
- kdev_cli-0.1.3/src/kdev/commands/tunnel.py +78 -0
- kdev_cli-0.1.3/src/kdev/commands/workspace.py +210 -0
- kdev_cli-0.1.3/src/kdev/config.py +181 -0
- kdev_cli-0.1.3/src/kdev/errors.py +25 -0
- kdev_cli-0.1.3/src/kdev/kdev_box.py +538 -0
- kdev_cli-0.1.3/src/kdev/notebook.py +261 -0
- kdev_cli-0.1.3/src/kdev/persistence.py +314 -0
- kdev_cli-0.1.3/src/kdev/quota.py +102 -0
- kdev_cli-0.1.3/src/kdev/safety.py +72 -0
- kdev_cli-0.1.3/src/kdev/session.py +284 -0
- kdev_cli-0.1.3/src/kdev/sshcfg.py +72 -0
- kdev_cli-0.1.3/src/kdev/tunnel.py +259 -0
- kdev_cli-0.1.3/src/kdev/ui.py +666 -0
- kdev_cli-0.1.3/src/kdev/wizard.py +251 -0
- kdev_cli-0.1.3/tests/test_api.py +96 -0
- kdev_cli-0.1.3/tests/test_auth.py +64 -0
- kdev_cli-0.1.3/tests/test_bootstrap.py +314 -0
- kdev_cli-0.1.3/tests/test_cli.py +750 -0
- kdev_cli-0.1.3/tests/test_config.py +148 -0
- kdev_cli-0.1.3/tests/test_kdev_box.py +345 -0
- kdev_cli-0.1.3/tests/test_notebook.py +216 -0
- kdev_cli-0.1.3/tests/test_persistence.py +258 -0
- kdev_cli-0.1.3/tests/test_sshcfg.py +44 -0
- kdev_cli-0.1.3/tests/test_tunnel.py +270 -0
- kdev_cli-0.1.3/tests/test_ui.py +142 -0
kdev_cli-0.1.3/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 The kdev authors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
kdev_cli-0.1.3/PKG-INFO
ADDED
|
@@ -0,0 +1,598 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: kdev-cli
|
|
3
|
+
Version: 0.1.3
|
|
4
|
+
Summary: A Kaggle notebook as your remote dev box: SSH and VS Code in, files that persist across sessions, accounts and machines.
|
|
5
|
+
Project-URL: Homepage, https://github.com/tushar-mahalya/kdev
|
|
6
|
+
Project-URL: Repository, https://github.com/tushar-mahalya/kdev
|
|
7
|
+
Project-URL: Issues, https://github.com/tushar-mahalya/kdev/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/tushar-mahalya/kdev/blob/main/CHANGELOG.md
|
|
9
|
+
License: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: cloudflare-tunnel,gpu,kaggle,remote-development,ssh,vscode
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Intended Audience :: Science/Research
|
|
16
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
17
|
+
Classifier: Operating System :: MacOS
|
|
18
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
19
|
+
Classifier: Programming Language :: Python :: 3
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
23
|
+
Classifier: Topic :: Software Development
|
|
24
|
+
Requires-Python: >=3.11
|
|
25
|
+
Requires-Dist: httpx<1,>=0.27
|
|
26
|
+
Requires-Dist: kaggle<3,>=2.2
|
|
27
|
+
Requires-Dist: questionary<3,>=2.0
|
|
28
|
+
Requires-Dist: rich<16,>=13
|
|
29
|
+
Requires-Dist: typer<1,>=0.27
|
|
30
|
+
Description-Content-Type: text/markdown
|
|
31
|
+
|
|
32
|
+
<p align="center">
|
|
33
|
+
<img src="https://raw.githubusercontent.com/tushar-mahalya/kdev/main/docs/assets/kdev-logo.png" alt="kdev" width="520">
|
|
34
|
+
</p>
|
|
35
|
+
|
|
36
|
+
<p align="center">
|
|
37
|
+
<b>A Kaggle notebook as your remote dev box.</b><br>
|
|
38
|
+
Start it with one command, work in it from VS Code or a shell, and leave whenever you like.<br>
|
|
39
|
+
Your files are there next time — on any account in your Kaggle group, from any machine.
|
|
40
|
+
</p>
|
|
41
|
+
|
|
42
|
+
<p align="center">
|
|
43
|
+
<a href="https://github.com/tushar-mahalya/kdev/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/tushar-mahalya/kdev/actions/workflows/ci.yml/badge.svg"></a>
|
|
44
|
+
<a href="https://pypi.org/project/kdev-cli/"><img alt="PyPI" src="https://img.shields.io/pypi/v/kdev-cli?color=00b8d4"></a>
|
|
45
|
+
<img alt="Python 3.11 | 3.12 | 3.13" src="https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-3776AB?logo=python&logoColor=white">
|
|
46
|
+
<a href="https://github.com/tushar-mahalya/kdev/blob/main/LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-2ea44f"></a>
|
|
47
|
+
<a href="#contributing"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-00b8d4"></a>
|
|
48
|
+
</p>
|
|
49
|
+
|
|
50
|
+
<p align="center">
|
|
51
|
+
<a href="#install-and-set-up">Install</a> ·
|
|
52
|
+
<a href="#everyday-use">Everyday use</a> ·
|
|
53
|
+
<a href="#your-files">Your files</a> ·
|
|
54
|
+
<a href="#commands">Commands</a> ·
|
|
55
|
+
<a href="#troubleshooting">Troubleshooting</a> ·
|
|
56
|
+
<a href="#contributing">Contributing</a>
|
|
57
|
+
</p>
|
|
58
|
+
|
|
59
|
+
<br>
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
kdev setup # once per machine
|
|
63
|
+
kdev up # start the box (or connect to the one that is running)
|
|
64
|
+
ssh kaggle # or VS Code → Remote-SSH → kaggle
|
|
65
|
+
kdev down # optional: stop early and hand the quota back
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
- **One box, pooled quota.** Every account in your group runs the same shared
|
|
69
|
+
notebook on its own 30 GPU-hours a week. When one runs short, `kdev up` asks
|
|
70
|
+
which account takes over.
|
|
71
|
+
- **Files that persist.** Whatever is in `/kaggle/working` when a session ends
|
|
72
|
+
comes back at the next start, however it ended: `kdev down`, the Kaggle UI,
|
|
73
|
+
a timeout, a crash, your wifi dropping.
|
|
74
|
+
- **A real server.** A stable hostname over Cloudflare Tunnel, public-key SSH,
|
|
75
|
+
your notebook's full environment (CUDA, Python, Kaggle variables) in every
|
|
76
|
+
session, interactive or not.
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## Contents
|
|
81
|
+
|
|
82
|
+
- [How it works](#how-it-works)
|
|
83
|
+
- [Install and set up](#install-and-set-up)
|
|
84
|
+
- [Everyday use](#everyday-use)
|
|
85
|
+
- [Your files](#your-files)
|
|
86
|
+
- [Several accounts, several machines](#several-accounts-several-machines)
|
|
87
|
+
- [Commands](#commands)
|
|
88
|
+
- [Settings](#settings)
|
|
89
|
+
- [Troubleshooting](#troubleshooting)
|
|
90
|
+
- [Security and limits](#security-and-limits)
|
|
91
|
+
- [Contributing](#contributing)
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## How it works
|
|
96
|
+
|
|
97
|
+
Kaggle's API can save a notebook and run it, but it has no "give me a shell"
|
|
98
|
+
call. kdev writes a small cell at the top of your notebook. When Kaggle runs
|
|
99
|
+
that cell, it turns the container into an SSH server and connects it to your
|
|
100
|
+
Cloudflare tunnel. Your laptop then reaches it by name.
|
|
101
|
+
|
|
102
|
+
```mermaid
|
|
103
|
+
flowchart LR
|
|
104
|
+
subgraph laptop["Your machine"]
|
|
105
|
+
cli["kdev"]
|
|
106
|
+
code["VS Code / ssh"]
|
|
107
|
+
end
|
|
108
|
+
subgraph kaggle["Kaggle"]
|
|
109
|
+
api["Kaggle API"]
|
|
110
|
+
store[("Notebook versions<br/>= saved /kaggle/working")]
|
|
111
|
+
subgraph box["The box (a notebook session)"]
|
|
112
|
+
cell["kdev's cell:<br/>sshd · cloudflared · restore"]
|
|
113
|
+
work["/kaggle/working"]
|
|
114
|
+
end
|
|
115
|
+
end
|
|
116
|
+
edge(("Cloudflare<br/>edge"))
|
|
117
|
+
|
|
118
|
+
cli -- "save + run notebook,<br/>quota, logs" --> api
|
|
119
|
+
api --> box
|
|
120
|
+
cell -- "outbound tunnel" --> edge
|
|
121
|
+
code -- "ssh kaggle" --> edge
|
|
122
|
+
edge --> cell
|
|
123
|
+
work -. "saved when the<br/>session ends" .-> store
|
|
124
|
+
store -. "restored at<br/>the next start" .-> work
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Nothing listens on a public port: the box dials *out* to Cloudflare, and your
|
|
128
|
+
`ssh` reaches it through Cloudflare by hostname.
|
|
129
|
+
|
|
130
|
+
### What `kdev up` does
|
|
131
|
+
|
|
132
|
+
```mermaid
|
|
133
|
+
sequenceDiagram
|
|
134
|
+
autonumber
|
|
135
|
+
actor You
|
|
136
|
+
participant K as kdev
|
|
137
|
+
participant API as Kaggle API
|
|
138
|
+
participant B as The box
|
|
139
|
+
participant CF as Cloudflare
|
|
140
|
+
|
|
141
|
+
You->>K: kdev up
|
|
142
|
+
K->>API: session status (already running?)
|
|
143
|
+
alt a box is running
|
|
144
|
+
K-->>You: connect to it — no second session
|
|
145
|
+
else nothing running
|
|
146
|
+
K->>API: which saved version to build on (walk back from latest)
|
|
147
|
+
K->>API: SaveKernel: your notebook + kdev's cell, "Save & Run All"
|
|
148
|
+
API->>B: start the container
|
|
149
|
+
B->>B: record the plan in .kdev/state.json (before anything slow)
|
|
150
|
+
B->>B: sshd, environment, git clone
|
|
151
|
+
B->>CF: open the tunnel
|
|
152
|
+
B-->>K: KDEV_READY (via the session log)
|
|
153
|
+
K->>API: fresh file list + signed URLs for the saved version
|
|
154
|
+
K->>B: "restore this" (over ssh)
|
|
155
|
+
B->>API: download every file straight from Kaggle
|
|
156
|
+
B->>B: put back symlinks, empty dirs, exec bits
|
|
157
|
+
K->>B: ssh check
|
|
158
|
+
K-->>You: ready — open VS Code or a shell
|
|
159
|
+
end
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
The board you watch while this happens shows each step's own clock, so a slow
|
|
163
|
+
queue looks like a queue and not a hang:
|
|
164
|
+
|
|
165
|
+
```
|
|
166
|
+
alice · T4 ×2 · 9h 1m52s
|
|
167
|
+
✓ Submitting 1s
|
|
168
|
+
✓ Waiting for a machine 1m21s
|
|
169
|
+
✓ Installing SSH server 14s
|
|
170
|
+
✓ Exporting notebook environment 0s
|
|
171
|
+
✓ Syncing workspace 0s
|
|
172
|
+
✓ Starting Cloudflare tunnel 4s
|
|
173
|
+
⠹ Restoring your files 9s
|
|
174
|
+
812/1505 files
|
|
175
|
+
○ Ready
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
---
|
|
179
|
+
|
|
180
|
+
## Install and set up
|
|
181
|
+
|
|
182
|
+
Needs Python 3.11+, `ssh`, and a Kaggle account in a Kaggle group.
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
uv tool install kdev-cli # or: pipx install kdev-cli
|
|
186
|
+
kdev setup
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
The package is `kdev-cli` (PyPI does not allow `kdev`); the command it installs
|
|
190
|
+
is `kdev`. Upgrade with `uv tool upgrade kdev-cli`. For what is on `main` but not released
|
|
191
|
+
yet: `uv tool install git+https://github.com/tushar-mahalya/kdev`.
|
|
192
|
+
|
|
193
|
+
`kdev setup` does only what is missing, so it is safe to run again at any
|
|
194
|
+
time. It will:
|
|
195
|
+
|
|
196
|
+
1. find (or create) your SSH key;
|
|
197
|
+
2. fetch Cloudflare's `cloudflared` if you don't have it — a system install
|
|
198
|
+
(`brew install cloudflared`) always wins;
|
|
199
|
+
3. sign a Kaggle account in, through your browser (OAuth);
|
|
200
|
+
4. join your group's workspace notebook, or create one;
|
|
201
|
+
5. set up the tunnel — **skipped on a second machine**, which takes the tunnel
|
|
202
|
+
from the notebook itself.
|
|
203
|
+
|
|
204
|
+
### The tunnel
|
|
205
|
+
|
|
206
|
+
With a domain on Cloudflare (free plan, domain showing *Active*):
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
kdev tunnel setup # opens a browser once to authorise your Cloudflare account
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
It creates the tunnel and its DNS record, and stores the credentials. There's
|
|
213
|
+
nothing to configure in the Zero Trust dashboard. Re-running it is a no-op; it
|
|
214
|
+
never repoints a hostname that belongs to something else without asking.
|
|
215
|
+
|
|
216
|
+
| | Named tunnel (your domain) | Quick tunnel (no domain) |
|
|
217
|
+
|---|---|---|
|
|
218
|
+
| Setup | once, ~2 minutes | none |
|
|
219
|
+
| Hostname | the same forever | new every session |
|
|
220
|
+
| After a network drop | same name, `ssh` just reconnects | new name; `kdev up` finds it |
|
|
221
|
+
| Speed | identical | identical |
|
|
222
|
+
|
|
223
|
+
### The workspace
|
|
224
|
+
|
|
225
|
+
A Kaggle group can't own anything, so one account owns the notebook and shares
|
|
226
|
+
it with the group as **Can Edit**:
|
|
227
|
+
|
|
228
|
+
```bash
|
|
229
|
+
kdev workspace create --group <your-group-slug> # the owner, once
|
|
230
|
+
kdev workspace join # everyone else
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
---
|
|
234
|
+
|
|
235
|
+
## Everyday use
|
|
236
|
+
|
|
237
|
+
```bash
|
|
238
|
+
kdev # overview: the box, every account's quota, what to do next
|
|
239
|
+
kdev up # start the box, or connect to the one already running
|
|
240
|
+
kdev status # running? who started it? when does it end? files back?
|
|
241
|
+
kdev down # stop it now
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
Bare `kdev` in a terminal ends with a menu of the actions that make sense
|
|
245
|
+
right now: connect or stop when the box is up; start it, or switch account,
|
|
246
|
+
when it isn't.
|
|
247
|
+
|
|
248
|
+
The box you start is a setting — pick once, and `kdev up` stops asking:
|
|
249
|
+
|
|
250
|
+
```bash
|
|
251
|
+
kdev config set gpu t4
|
|
252
|
+
kdev config set hours 9
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
**Leaving needs no ceremony.** Close the laptop, lose the wifi, walk away.
|
|
256
|
+
The box runs to the end of its session and saves as it stops. `kdev down` is
|
|
257
|
+
for stopping *early*, to hand the quota back.
|
|
258
|
+
|
|
259
|
+
---
|
|
260
|
+
|
|
261
|
+
## Your files
|
|
262
|
+
|
|
263
|
+
`/kaggle/working` behaves like a disk that is always there.
|
|
264
|
+
|
|
265
|
+
**Kaggle saves it.** When a "Save & Run All" session ends, Kaggle keeps
|
|
266
|
+
`/kaggle/working` as that version's output — and it does so however the
|
|
267
|
+
session ends. A clean exit, a crash and a cancel were all measured to save
|
|
268
|
+
every file up to the moment the container stopped. Older versions stay
|
|
269
|
+
readable (`v1`, `v2`, …), and they belong to the **notebook**, not to an account.
|
|
270
|
+
|
|
271
|
+
**kdev puts it back.** Kaggle starts every batch session with an empty
|
|
272
|
+
`/kaggle/working`; its "Persistence" setting only covers the web editor. So
|
|
273
|
+
each `kdev up` works out which saved version you left off at, and the new box
|
|
274
|
+
downloads it before you connect.
|
|
275
|
+
|
|
276
|
+
```mermaid
|
|
277
|
+
stateDiagram-v2
|
|
278
|
+
direction LR
|
|
279
|
+
[*] --> Running: kdev up
|
|
280
|
+
Running --> Saved: the session ends, however it ends
|
|
281
|
+
Saved --> Running: kdev up, any account or machine
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
| how the last session ended | what the next `kdev up` gives you |
|
|
285
|
+
|---|---|
|
|
286
|
+
| `kdev down` | everything |
|
|
287
|
+
| `kdev down`, then `kdev up` straight away | everything: `up` waits for the save first (about 2 min per GB) |
|
|
288
|
+
| **Stop session** in the Kaggle UI | everything (a cancel still saves) |
|
|
289
|
+
| the session's time ran out | everything (the box stops itself 2 min early) |
|
|
290
|
+
| the tunnel process died | everything |
|
|
291
|
+
| the box crashed | everything, up to the crash |
|
|
292
|
+
| your laptop or network dropped | the box is still running: `kdev up` connects to it |
|
|
293
|
+
| Kaggle's machine itself failed | not testable; a git remote covers it |
|
|
294
|
+
|
|
295
|
+
### What kdev adds on top of Kaggle
|
|
296
|
+
|
|
297
|
+
Kaggle's saved output keeps every regular file — thousands of them, dotfiles,
|
|
298
|
+
`.git`, large binaries. It **drops symlinks and empty directories, and loses
|
|
299
|
+
executable bits**, which would break a Python virtualenv. The box records
|
|
300
|
+
those in `.kdev/meta.json` every 30 seconds, and the restore puts them back.
|
|
301
|
+
|
|
302
|
+
### Picking the version to restore
|
|
303
|
+
|
|
304
|
+
```mermaid
|
|
305
|
+
flowchart TD
|
|
306
|
+
start["latest saved version vN"] --> empty{"has files?"}
|
|
307
|
+
empty -- no --> back["try v(N-1)"] --> empty
|
|
308
|
+
empty -- yes --> state{"its .kdev/state.json says"}
|
|
309
|
+
state -- "restored: true<br/>(or kdev never touched it)" --> one["restore vN alone"]
|
|
310
|
+
state -- "restored: false, or files missing<br/>(cut short, or worked in<br/>before the restore)" --> stack["what vN never got from<br/>its base layers, then vN on top"]
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
A version with no files is a source-only save (group setup, a Quick Save), so
|
|
314
|
+
kdev walks past it. A session that was stopped before its restore finished —
|
|
315
|
+
or that you worked in before restoring — is not skipped: it gets stacked on
|
|
316
|
+
the versions it was meant to be built on, so nothing done in it is lost. The
|
|
317
|
+
layers underneath fill in only what that session's restore never delivered
|
|
318
|
+
(the box logs each file as it lands, in `.kdev/fetched`), so a file you deleted
|
|
319
|
+
there stays deleted.
|
|
320
|
+
|
|
321
|
+
A restore never overwrites a file written in the current session, so it is
|
|
322
|
+
safe to run again at any time:
|
|
323
|
+
|
|
324
|
+
```bash
|
|
325
|
+
kdev restore # finish or repeat the restore on the running box
|
|
326
|
+
kdev restore --from v12 # add files v12 has that the box doesn't (not a rollback)
|
|
327
|
+
kdev workspace files # what `kdev up` would restore (--version v12 for another)
|
|
328
|
+
kdev backup # optional: an exact copy of the box on this machine
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
### Your own cells in the notebook
|
|
332
|
+
|
|
333
|
+
kdev's cell sits on top, and **nothing below it runs**. When a session ends,
|
|
334
|
+
later cells are blanked for that run, so a training cell can't start after
|
|
335
|
+
`kdev down` and use quota. Your cells stay in the notebook, untouched.
|
|
336
|
+
|
|
337
|
+
### Files made in the Kaggle web editor
|
|
338
|
+
|
|
339
|
+
The editor's interactive session is the one place kdev can't reach: its files
|
|
340
|
+
only reach the API when a version is saved. Kaggle describes Quick Save as
|
|
341
|
+
saving the notebook "as displayed", which isn't a clear promise to save the
|
|
342
|
+
working directory, so check with `kdev workspace files`. Everything made
|
|
343
|
+
through kdev is covered.
|
|
344
|
+
|
|
345
|
+
---
|
|
346
|
+
|
|
347
|
+
## Several accounts, several machines
|
|
348
|
+
|
|
349
|
+
```mermaid
|
|
350
|
+
flowchart TB
|
|
351
|
+
subgraph group["Kaggle group (Can Edit on one notebook)"]
|
|
352
|
+
a["account A · 30h GPU/week"]
|
|
353
|
+
b["account B · 30h GPU/week"]
|
|
354
|
+
c["account C · 30h GPU/week"]
|
|
355
|
+
end
|
|
356
|
+
nb[("the shared notebook<br/>+ its saved versions")]
|
|
357
|
+
a & b & c -- "each runs it on<br/>its own quota" --> nb
|
|
358
|
+
l1["laptop 1"] & l2["laptop 2"] -- "kdev up / ssh" --> nb
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
- **Quota is per account.** A session is charged to the account that starts
|
|
362
|
+
it, not to the notebook's owner (measured).
|
|
363
|
+
- **Switching is a question, not a wall.** If the active account can't finish
|
|
364
|
+
the session you asked for, `kdev up` shows every account's remaining hours
|
|
365
|
+
and lets you pick. `kdev account use <name>` switches by hand.
|
|
366
|
+
- **The box is still running?** `kdev up` from any account or machine
|
|
367
|
+
connects to it instead of starting a second one.
|
|
368
|
+
- **A new laptop.** `kdev setup` signs you in and joins the workspace. The
|
|
369
|
+
tunnel and git settings come from the notebook, and the new laptop's SSH
|
|
370
|
+
key is saved in the workspace (`.kdev/authorized_keys`). So every machine
|
|
371
|
+
that has used it can reach every later box.
|
|
372
|
+
- **Stopping a box someone else started.** Kaggle only lets the account that
|
|
373
|
+
started a session cancel it. When the box doesn't answer, `kdev down` finds
|
|
374
|
+
out which account that was and cancels as it — or tells you which account
|
|
375
|
+
has to.
|
|
376
|
+
|
|
377
|
+
```bash
|
|
378
|
+
kdev account add alice # sign an account in (browser); re-run to refresh it
|
|
379
|
+
kdev account # every account and its GPU/TPU hours left
|
|
380
|
+
kdev account use alice # it runs the next box
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
---
|
|
384
|
+
|
|
385
|
+
## Commands
|
|
386
|
+
|
|
387
|
+
| command | what it does |
|
|
388
|
+
|---|---|
|
|
389
|
+
| `kdev` | overview of the box, accounts and workspace; in a terminal, the next actions |
|
|
390
|
+
| `kdev setup` | get this machine ready; only does what is missing |
|
|
391
|
+
| `kdev up` | start the box, or connect to the running one |
|
|
392
|
+
| `kdev down` | stop the box; files are saved however it stops |
|
|
393
|
+
| `kdev ssh [-- ARGS]` | shell on the box; ssh's exit code is kdev's |
|
|
394
|
+
| `kdev status [--json]` | running?, started by, ends at, reachable, restore state |
|
|
395
|
+
| `kdev logs [-n N] [--all]` | the session log |
|
|
396
|
+
| `kdev restore [--from vN \| --from-backup]` | put saved files back |
|
|
397
|
+
| `kdev backup` | copy the running box to this machine |
|
|
398
|
+
| `kdev account [--json]` | accounts and quota |
|
|
399
|
+
| `kdev account add \| use \| remove` | manage accounts |
|
|
400
|
+
| `kdev workspace` | the notebook: owner, sharing, members, saved versions |
|
|
401
|
+
| `kdev workspace files [--version vN] [--json]` | what a saved version holds |
|
|
402
|
+
| `kdev workspace join \| use \| create \| share` | choose, make, or re-share the notebook |
|
|
403
|
+
| `kdev config` / `set KEY VALUE` / `unset KEY` | settings |
|
|
404
|
+
| `kdev tunnel` / `tunnel setup` | the Cloudflare tunnel |
|
|
405
|
+
| `kdev doctor [--fix]` | check everything; exits 1 if something is broken |
|
|
406
|
+
|
|
407
|
+
Useful flags on `kdev up`: `--gpu none|t4|p100|tpu`, `--hours N`,
|
|
408
|
+
`--account NAME`, `--open code|shell|none`, `--no-restore`, `--replace`, `-y`.
|
|
409
|
+
|
|
410
|
+
Global: `-v` logs every Kaggle API call with its status and timing;
|
|
411
|
+
`--version`; `--install-completion` for shell completion.
|
|
412
|
+
|
|
413
|
+
**Exit codes:** `0` success · `1` failed (the message says why and what to
|
|
414
|
+
run) · `2` usage mistake · `130` cancelled.
|
|
415
|
+
|
|
416
|
+
**Scripting:** every prompt has a flag, and a prompt never appears without a
|
|
417
|
+
terminal. `status`, `account` and `workspace files` take `--json` (data on
|
|
418
|
+
stdout, errors on stderr). `NO_COLOR` is honoured.
|
|
419
|
+
|
|
420
|
+
---
|
|
421
|
+
|
|
422
|
+
## Settings
|
|
423
|
+
|
|
424
|
+
`kdev config` lists them; secrets are never shown.
|
|
425
|
+
|
|
426
|
+
| setting | meaning |
|
|
427
|
+
|---|---|
|
|
428
|
+
| `gpu` | accelerator for `kdev up`: `none`, `t4`, `p100`, `tpu` (and `l4`, `a100`, `h100` where your account has them) |
|
|
429
|
+
| `hours` | session length for `kdev up` (Kaggle's limit: 12h, 9h on TPU) |
|
|
430
|
+
| `git-remote` | a repo cloned at boot, pushed every 15 minutes and at teardown |
|
|
431
|
+
| `git-deploy-key` | path to that repo's deploy key |
|
|
432
|
+
| `ssh-key` | path to this machine's public key |
|
|
433
|
+
| `ssh-alias` | the name in `~/.ssh/config` (default `kaggle`) |
|
|
434
|
+
| `tunnel-hostname` | the box's hostname |
|
|
435
|
+
| `tunnel-token` | a Cloudflare-dashboard tunnel token, instead of `kdev tunnel setup` |
|
|
436
|
+
|
|
437
|
+
Stored in `~/.config/kdev/config.json` (mode 0600). Move it with
|
|
438
|
+
`KDEV_CONFIG_DIR`.
|
|
439
|
+
|
|
440
|
+
---
|
|
441
|
+
|
|
442
|
+
## Troubleshooting
|
|
443
|
+
|
|
444
|
+
```bash
|
|
445
|
+
kdev doctor # every dependency, account token, the workspace and the tunnel's DNS
|
|
446
|
+
kdev -v status # the same command, with each Kaggle API call logged
|
|
447
|
+
kdev logs # what the box itself is saying
|
|
448
|
+
```
|
|
449
|
+
|
|
450
|
+
| you see | what to do |
|
|
451
|
+
|---|---|
|
|
452
|
+
| `… is not signed in` | `kdev account add <name>` refreshes that account |
|
|
453
|
+
| `ssh does not answer` right after starting | give Cloudflare a minute; `kdev ssh` |
|
|
454
|
+
| `The session never reported a tunnel` | `kdev logs`; the message names the command to stop it |
|
|
455
|
+
| `Only X can cancel session …` | sign X in (`kdev account add`) or stop it in the Kaggle UI |
|
|
456
|
+
| `Not all your files are back yet` | `kdev restore` finishes it |
|
|
457
|
+
| `your last box is still saving your files` | nothing: `kdev up` waits, then starts |
|
|
458
|
+
| `… has a session kdev cannot reach` | someone is using the notebook in the Kaggle editor |
|
|
459
|
+
|
|
460
|
+
---
|
|
461
|
+
|
|
462
|
+
## Security and limits
|
|
463
|
+
|
|
464
|
+
- **Access** is public-key SSH only; password login is disabled. The box
|
|
465
|
+
accepts every key saved in the workspace's `.kdev/authorized_keys`: remove a
|
|
466
|
+
line there to revoke a machine.
|
|
467
|
+
- **Secrets in the notebook.** Kaggle has no API for notebook Secrets, so the
|
|
468
|
+
tunnel credentials (and a git deploy key, if you set one) sit in the private
|
|
469
|
+
notebook's source. Anyone with Can Edit can read them. Scope a deploy key to
|
|
470
|
+
one repository.
|
|
471
|
+
- **Host keys.** Every session is a new container with a new host key, so the
|
|
472
|
+
`kaggle` block in `~/.ssh/config` doesn't pin one; a pinned key would break
|
|
473
|
+
VS Code on every other machine. Only a box holding the workspace's tunnel
|
|
474
|
+
credentials can answer on that hostname, and anyone holding those can
|
|
475
|
+
already edit the notebook that builds the box.
|
|
476
|
+
- **One box at a time.** kdev is built for one person on one machine at a
|
|
477
|
+
time; switching machines is fine. Two machines running `kdev up` at the same
|
|
478
|
+
moment start two boxes behind one hostname, and only the one that stops last
|
|
479
|
+
carries forward. Start from one machine, then connect from the other.
|
|
480
|
+
- **Metadata in the last 30 s.** After a hard kill, symlinks, empty folders and
|
|
481
|
+
executable bits created in the final 30 seconds are gone. File contents never
|
|
482
|
+
are.
|
|
483
|
+
- **Nothing sensitive in crash reports.** kdev never prints tracebacks with
|
|
484
|
+
local variables; `-v` shows a traceback when you ask for one.
|
|
485
|
+
- **Kaggle's limits:** 12h per CPU/GPU session and 9h on TPU; weekly GPU/TPU
|
|
486
|
+
quota per account; 20 GB of `/kaggle/working` saved per version.
|
|
487
|
+
- **Kaggle's terms.** Kaggle allows one account per person, and restricts
|
|
488
|
+
tunnelling out of notebooks; accounts have been banned for both. kdev does
|
|
489
|
+
nothing to hide what it does. Know the rules you are working under.
|
|
490
|
+
|
|
491
|
+
---
|
|
492
|
+
|
|
493
|
+
## Contributing
|
|
494
|
+
|
|
495
|
+
Contributions are welcome — bug reports, fixes, docs and features alike. kdev
|
|
496
|
+
is small and opinionated, so for anything bigger than a fix, open an issue
|
|
497
|
+
first and say what you want to change and why. It saves you writing code that
|
|
498
|
+
goes a different way than the project.
|
|
499
|
+
|
|
500
|
+
### Ways to help
|
|
501
|
+
|
|
502
|
+
- **Report a bug.** Open an issue with what you ran, what you expected and
|
|
503
|
+
what happened. The output of the same command with `-v` (`kdev -v up …`)
|
|
504
|
+
helps most. It logs every Kaggle API call; check it for anything you would
|
|
505
|
+
rather not share before you paste it.
|
|
506
|
+
- **Fix something.** Pick an open issue and say in it that you are on it, so
|
|
507
|
+
two people don't fix the same thing.
|
|
508
|
+
- **Improve the docs.** If something here was unclear when you set up, it will
|
|
509
|
+
be unclear to the next person too.
|
|
510
|
+
- **Report a vulnerability** privately, as [SECURITY.md](https://github.com/tushar-mahalya/kdev/blob/main/SECURITY.md)
|
|
511
|
+
describes, never in a public issue.
|
|
512
|
+
|
|
513
|
+
### Set up
|
|
514
|
+
|
|
515
|
+
You need Python 3.11+ and [uv](https://docs.astral.sh/uv/).
|
|
516
|
+
|
|
517
|
+
```bash
|
|
518
|
+
git clone https://github.com/tushar-mahalya/kdev && cd kdev
|
|
519
|
+
uv sync
|
|
520
|
+
uv run pre-commit install # hooks on commit, tests on push
|
|
521
|
+
uv run pytest # 199 tests, no network needed
|
|
522
|
+
uv run kdev -v … # the working tree, with API logging
|
|
523
|
+
```
|
|
524
|
+
|
|
525
|
+
Every commit runs formatting, lint, a secrets scan (`detect-secrets`,
|
|
526
|
+
private-key detection), config validation and a lockfile check; every push
|
|
527
|
+
runs the tests. CI runs the same hooks, the tests on Python 3.11–3.13, a
|
|
528
|
+
build-and-install check, and `gitleaks` over the full history.
|
|
529
|
+
|
|
530
|
+
### Trying a change against real Kaggle
|
|
531
|
+
|
|
532
|
+
The test suite needs no Kaggle account, and most changes need nothing more.
|
|
533
|
+
When yours touches the box, the tunnel or the restore, try it for real:
|
|
534
|
+
|
|
535
|
+
- Use **your own** workspace (`kdev workspace create --group <slug>`), not a
|
|
536
|
+
shared one someone else works in.
|
|
537
|
+
- Start **CPU boxes**: `uv run kdev up --gpu none --hours 1`. They cost no GPU
|
|
538
|
+
quota. A GPU run spends the quota of whichever account starts it.
|
|
539
|
+
- `kdev down` when you are done, and `kdev workspace files` to see exactly
|
|
540
|
+
what was saved.
|
|
541
|
+
|
|
542
|
+
### How the code is laid out
|
|
543
|
+
|
|
544
|
+
```mermaid
|
|
545
|
+
flowchart LR
|
|
546
|
+
cli["cli.py<br/>entry point,<br/>one error boundary"]
|
|
547
|
+
cmds["commands/<br/>box · account · workspace<br/>config · tunnel · doctor · home"]
|
|
548
|
+
logic["session · persistence<br/>quota · notebook · bootstrap"]
|
|
549
|
+
edges["api · auth · config<br/>tunnel · cloudflared · sshcfg"]
|
|
550
|
+
ui["ui.py<br/>the design system"]
|
|
551
|
+
kbox["kdev_box.py<br/>runs on the box"]
|
|
552
|
+
|
|
553
|
+
cli --> cmds --> logic --> edges
|
|
554
|
+
cmds --> ui
|
|
555
|
+
logic -. "bootstrap ships it<br/>inside kdev's cell" .-> kbox
|
|
556
|
+
```
|
|
557
|
+
|
|
558
|
+
| layer | rule |
|
|
559
|
+
|---|---|
|
|
560
|
+
| `commands/` | parse arguments, call logic, render with `ui`; no API calls of their own beyond reads |
|
|
561
|
+
| `session`, `persistence`, `quota`, `notebook` | the behaviour; testable without a terminal |
|
|
562
|
+
| `kdev_box.py` | standard library only; it's shipped into the container and runs there |
|
|
563
|
+
| `ui.py` | every visual element, with its tokens and rules written down at the top |
|
|
564
|
+
| `errors.KdevError` | every failure a user can act on: a message and the command that fixes it |
|
|
565
|
+
|
|
566
|
+
Tests are split by module. `tests/test_cli.py` runs every command through
|
|
567
|
+
the real entry point against a fake Kaggle. `tests/test_kdev_box.py` runs the
|
|
568
|
+
on-box restore against a temporary directory.
|
|
569
|
+
|
|
570
|
+
### Pull requests
|
|
571
|
+
|
|
572
|
+
- **One change per pull request**, with a description of the problem it
|
|
573
|
+
solves and how you checked it.
|
|
574
|
+
- **A bug fix comes with a test** that fails without the fix. New behaviour
|
|
575
|
+
comes with the smallest test that would catch it breaking. Tests stay
|
|
576
|
+
offline: use the fake Kaggle in `tests/test_cli.py`.
|
|
577
|
+
- **Match the code around you.** `kdev_box.py` stays standard-library only.
|
|
578
|
+
Everything the user sees goes through `ui.py`. A failure the user can act on
|
|
579
|
+
is a `KdevError` with the command that fixes it.
|
|
580
|
+
- **Commit messages** follow [Conventional Commits](https://www.conventionalcommits.org/)
|
|
581
|
+
(`fix:`, `feat:`, `docs:`, `test:`, `ci:`, `refactor:`), with the *why* in
|
|
582
|
+
the body.
|
|
583
|
+
- **Record what users will notice** under `## [Unreleased]` in
|
|
584
|
+
[CHANGELOG.md](https://github.com/tushar-mahalya/kdev/blob/main/CHANGELOG.md), and update this README if a command or its
|
|
585
|
+
behaviour changes.
|
|
586
|
+
|
|
587
|
+
### Releasing
|
|
588
|
+
|
|
589
|
+
For maintainers: bump `version` in `pyproject.toml`, move the `Unreleased`
|
|
590
|
+
notes in `CHANGELOG.md` under the new version, then
|
|
591
|
+
`git tag vX.Y.Z && git push origin vX.Y.Z`. The release workflow checks that
|
|
592
|
+
the tag matches the version, runs the tests, and publishes a GitHub release
|
|
593
|
+
with the wheel and sdist attached.
|
|
594
|
+
|
|
595
|
+
### License
|
|
596
|
+
|
|
597
|
+
kdev is [MIT licensed](https://github.com/tushar-mahalya/kdev/blob/main/LICENSE). By contributing, you agree that your
|
|
598
|
+
contributions are licensed under the same terms.
|