kdev-cli 0.1.3__tar.gz → 0.2.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.
- kdev_cli-0.2.0/.gitignore +14 -0
- kdev_cli-0.2.0/PKG-INFO +195 -0
- kdev_cli-0.2.0/README.md +162 -0
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/pyproject.toml +16 -3
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/api.py +125 -24
- kdev_cli-0.2.0/src/kdev/auth.py +254 -0
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/bootstrap.py +47 -0
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/cli.py +85 -22
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/cloudflared.py +7 -6
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/commands/_common.py +9 -6
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/commands/account.py +21 -5
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/commands/box.py +505 -91
- kdev_cli-0.2.0/src/kdev/commands/doctor.py +189 -0
- kdev_cli-0.2.0/src/kdev/commands/home.py +399 -0
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/commands/settings.py +35 -5
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/commands/tunnel.py +17 -12
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/commands/workspace.py +41 -10
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/config.py +13 -0
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/errors.py +12 -0
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/kdev_box.py +14 -0
- kdev_cli-0.2.0/src/kdev/menu.py +372 -0
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/notebook.py +55 -22
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/persistence.py +218 -16
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/quota.py +34 -2
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/safety.py +18 -1
- kdev_cli-0.2.0/src/kdev/session.py +536 -0
- kdev_cli-0.2.0/src/kdev/sshcfg.py +118 -0
- kdev_cli-0.2.0/src/kdev/ui.py +1493 -0
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/wizard.py +10 -4
- kdev_cli-0.2.0/tests/conftest.py +86 -0
- kdev_cli-0.2.0/tests/test_account.py +56 -0
- kdev_cli-0.2.0/tests/test_api.py +275 -0
- kdev_cli-0.2.0/tests/test_api_errors.py +55 -0
- kdev_cli-0.2.0/tests/test_auth.py +307 -0
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/tests/test_bootstrap.py +112 -3
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/tests/test_cli.py +702 -28
- kdev_cli-0.2.0/tests/test_concurrent_start.py +401 -0
- kdev_cli-0.2.0/tests/test_hermetic.py +28 -0
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/tests/test_kdev_box.py +25 -0
- kdev_cli-0.2.0/tests/test_menu.py +93 -0
- kdev_cli-0.2.0/tests/test_notebook.py +382 -0
- kdev_cli-0.2.0/tests/test_persistence.py +562 -0
- kdev_cli-0.2.0/tests/test_sshcfg.py +214 -0
- kdev_cli-0.2.0/tests/test_ui.py +527 -0
- kdev_cli-0.2.0/website/README.md +40 -0
- kdev_cli-0.1.3/.gitignore +0 -11
- kdev_cli-0.1.3/PKG-INFO +0 -598
- kdev_cli-0.1.3/README.md +0 -567
- kdev_cli-0.1.3/src/kdev/auth.py +0 -115
- kdev_cli-0.1.3/src/kdev/commands/doctor.py +0 -127
- kdev_cli-0.1.3/src/kdev/commands/home.py +0 -92
- kdev_cli-0.1.3/src/kdev/session.py +0 -284
- kdev_cli-0.1.3/src/kdev/sshcfg.py +0 -72
- kdev_cli-0.1.3/src/kdev/ui.py +0 -666
- kdev_cli-0.1.3/tests/test_api.py +0 -96
- kdev_cli-0.1.3/tests/test_auth.py +0 -64
- kdev_cli-0.1.3/tests/test_notebook.py +0 -216
- kdev_cli-0.1.3/tests/test_persistence.py +0 -258
- kdev_cli-0.1.3/tests/test_sshcfg.py +0 -44
- kdev_cli-0.1.3/tests/test_ui.py +0 -142
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/LICENSE +0 -0
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/__init__.py +0 -0
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/__main__.py +0 -0
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/commands/__init__.py +0 -0
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/tunnel.py +0 -0
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/tests/test_config.py +0 -0
- {kdev_cli-0.1.3 → kdev_cli-0.2.0}/tests/test_tunnel.py +0 -0
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
.venv/
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*.egg-info/
|
|
5
|
+
dist/
|
|
6
|
+
build/
|
|
7
|
+
.pytest_cache/
|
|
8
|
+
.ruff_cache/
|
|
9
|
+
.coverage
|
|
10
|
+
htmlcov/
|
|
11
|
+
.DS_Store
|
|
12
|
+
|
|
13
|
+
# Design kit fetched for the website build-out (Leonxlnx/taste-skill, MIT); local only.
|
|
14
|
+
.agents/skills/design-taste-frontend/
|
kdev_cli-0.2.0/PKG-INFO
ADDED
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: kdev-cli
|
|
3
|
+
Version: 0.2.0
|
|
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://kdev-cli.pages.dev
|
|
6
|
+
Project-URL: Documentation, https://kdev-cli.pages.dev/docs/
|
|
7
|
+
Project-URL: Repository, https://github.com/tushar-mahalya/kdev
|
|
8
|
+
Project-URL: Issues, https://github.com/tushar-mahalya/kdev/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/tushar-mahalya/kdev/blob/main/CHANGELOG.md
|
|
10
|
+
License: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: cloudflare-tunnel,gpu,kaggle,remote-development,ssh,vscode
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Environment :: Console
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Intended Audience :: Science/Research
|
|
17
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
18
|
+
Classifier: Operating System :: MacOS
|
|
19
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
20
|
+
Classifier: Programming Language :: Python :: 3
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
24
|
+
Classifier: Topic :: Software Development
|
|
25
|
+
Requires-Python: >=3.11
|
|
26
|
+
Requires-Dist: httpx<1,>=0.27
|
|
27
|
+
Requires-Dist: kaggle<3,>=2.2
|
|
28
|
+
Requires-Dist: prompt-toolkit<4,>=3.0.36
|
|
29
|
+
Requires-Dist: questionary<3,>=2.0
|
|
30
|
+
Requires-Dist: rich<16,>=13
|
|
31
|
+
Requires-Dist: typer<1,>=0.27
|
|
32
|
+
Description-Content-Type: text/markdown
|
|
33
|
+
|
|
34
|
+
<p align="center">
|
|
35
|
+
<img src="https://raw.githubusercontent.com/tushar-mahalya/kdev/main/docs/assets/kdev-logo.png" alt="kdev" width="520">
|
|
36
|
+
</p>
|
|
37
|
+
|
|
38
|
+
<p align="center">
|
|
39
|
+
<b>A Kaggle notebook as your remote dev box.</b><br>
|
|
40
|
+
Start it with one command, work in it from VS Code or a shell, and leave whenever you like.<br>
|
|
41
|
+
Your files are there next time — on any account in your Kaggle group, from any machine.
|
|
42
|
+
</p>
|
|
43
|
+
|
|
44
|
+
<p align="center">
|
|
45
|
+
<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>
|
|
46
|
+
<a href="https://pypi.org/project/kdev-cli/"><img alt="PyPI" src="https://img.shields.io/pypi/v/kdev-cli?logo=pypi&logoColor=white&color=00b8d4"></a>
|
|
47
|
+
<a href="https://pypi.org/project/kdev-cli/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/kdev-cli?logo=python&logoColor=white&color=3776AB"></a>
|
|
48
|
+
<a href="https://github.com/tushar-mahalya/kdev/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/tushar-mahalya/kdev?label=release&logo=github&color=2ea44f"></a>
|
|
49
|
+
<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>
|
|
50
|
+
<a href="https://scorecard.dev/viewer/?uri=github.com/tushar-mahalya/kdev"><img alt="OpenSSF Scorecard" src="https://api.scorecard.dev/projects/github.com/tushar-mahalya/kdev/badge"></a>
|
|
51
|
+
<a href="https://kdev-cli.pages.dev"><img alt="Website" src="https://img.shields.io/badge/website-kdev--cli.pages.dev-00b8d4"></a>
|
|
52
|
+
<a href="https://github.com/tushar-mahalya/kdev/blob/main/CONTRIBUTING.md"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-00b8d4"></a>
|
|
53
|
+
</p>
|
|
54
|
+
|
|
55
|
+
<p align="center">
|
|
56
|
+
<a href="https://kdev-cli.pages.dev"><b>Website</b></a> ·
|
|
57
|
+
<a href="https://kdev-cli.pages.dev/docs/">Docs</a> ·
|
|
58
|
+
<a href="https://kdev-cli.pages.dev/docs/how-it-works/">How it works</a> ·
|
|
59
|
+
<a href="https://kdev-cli.pages.dev/docs/commands/">Commands</a> ·
|
|
60
|
+
<a href="https://github.com/tushar-mahalya/kdev/blob/main/CHANGELOG.md">Changelog</a>
|
|
61
|
+
</p>
|
|
62
|
+
|
|
63
|
+
## Why kdev
|
|
64
|
+
|
|
65
|
+
Kaggle gives every account free GPU hours, but only inside a notebook. kdev
|
|
66
|
+
turns that notebook into a machine you can `ssh` into or open in VS Code.
|
|
67
|
+
|
|
68
|
+
- **One box, pooled quota.** Every account in your Kaggle group runs the same
|
|
69
|
+
shared notebook on its own weekly GPU hours. When one runs short, `kdev up`
|
|
70
|
+
asks 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`, a timeout, a
|
|
73
|
+
crash, your wifi dropping.
|
|
74
|
+
- **A real server.** A stable hostname over Cloudflare Tunnel, public-key SSH,
|
|
75
|
+
and your notebook's full environment (CUDA, Python, Kaggle variables).
|
|
76
|
+
No port is opened on the box.
|
|
77
|
+
|
|
78
|
+
## Install
|
|
79
|
+
|
|
80
|
+
Needs Python 3.11+, `ssh`, and a Kaggle account in a Kaggle group.
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
uv tool install kdev-cli # or: pipx install kdev-cli
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
The package is `kdev-cli`; the command it installs is `kdev`. Upgrade with
|
|
87
|
+
`uv tool upgrade kdev-cli`.
|
|
88
|
+
|
|
89
|
+
## Quick start
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
kdev setup # once per machine: SSH key, cloudflared, Kaggle sign-in, workspace, tunnel
|
|
93
|
+
kdev up # start the box, or connect to the one already running
|
|
94
|
+
ssh kaggle # or VS Code → Remote-SSH → kaggle
|
|
95
|
+
kdev down # optional: stop early and hand the quota back
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
`kdev setup` only does what is missing, so it is safe to run again. Two parts
|
|
99
|
+
of it you may want to run on their own:
|
|
100
|
+
|
|
101
|
+
- **The tunnel.** With a domain on Cloudflare, `kdev tunnel setup` creates a
|
|
102
|
+
named tunnel with a hostname that never changes. Without one, `kdev setup`
|
|
103
|
+
offers a free quick tunnel, on a new hostname each session.
|
|
104
|
+
- **The workspace.** One account owns the notebook and shares it with the
|
|
105
|
+
group: `kdev workspace create --group <your-group-slug>`, once. Everyone else
|
|
106
|
+
runs `kdev workspace join`.
|
|
107
|
+
|
|
108
|
+
Leaving needs no ceremony: close the laptop and walk away. The box runs to the
|
|
109
|
+
end of its session and saves as it stops.
|
|
110
|
+
|
|
111
|
+
## Everyday commands
|
|
112
|
+
|
|
113
|
+
| command | what it does |
|
|
114
|
+
|---|---|
|
|
115
|
+
| `kdev` | the home screen: the box and every account's quota, live; one key per action |
|
|
116
|
+
| `kdev up` | start the box, or connect to the running one |
|
|
117
|
+
| `kdev down` | stop the box; files are saved however it stops |
|
|
118
|
+
| `kdev ssh` | open a shell on the box |
|
|
119
|
+
| `kdev status` | running? who started it? when does it end? files back? |
|
|
120
|
+
| `kdev forward PORT` | reach a service on the box through localhost (`9000:8888` remaps) |
|
|
121
|
+
| `kdev logs` | stream the session's log |
|
|
122
|
+
| `kdev history` | past saved sessions, who ran them and how they ended |
|
|
123
|
+
| `kdev restore` | finish or repeat the restore of your saved files |
|
|
124
|
+
| `kdev backup` | copy the running box's files to this machine |
|
|
125
|
+
| `kdev account` | accounts and their GPU/TPU hours left (`add`, `use`, `remove`) |
|
|
126
|
+
| `kdev workspace` | the shared notebook (`files`, `join`, `use`, `create`, `share`) |
|
|
127
|
+
| `kdev doctor` | check everything kdev depends on |
|
|
128
|
+
|
|
129
|
+
Run bare `kdev` and press a key: `1` starts the box, `s` shows its status, `q`
|
|
130
|
+
quits. The highlighted item always shows the command it runs, so everything
|
|
131
|
+
the menu does you can also type or script.
|
|
132
|
+
|
|
133
|
+
Useful flags on `kdev up`: `--gpu none|t4|p100|tpu`, `--hours N`,
|
|
134
|
+
`--account NAME`, `--open code|shell|none`, `--no-restore`, `--replace`, `-y`.
|
|
135
|
+
Add `-v` to any command to log each Kaggle API call. `status`, `history`,
|
|
136
|
+
`account` and `workspace files` take `--json` for scripts.
|
|
137
|
+
See the [full command reference](https://kdev-cli.pages.dev/docs/commands/).
|
|
138
|
+
|
|
139
|
+
## Settings
|
|
140
|
+
|
|
141
|
+
Pick once with `kdev config set`, and `kdev up` stops asking:
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
kdev config set gpu t4 # none, t4, p100, tpu (and l4, a100, h100 where available)
|
|
145
|
+
kdev config set hours 9 # Kaggle's limit: 12h, 9h on TPU
|
|
146
|
+
kdev config # list every setting; secrets are never shown
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
Other settings cover a git remote that the box clones at boot and pushes every
|
|
150
|
+
15 minutes, your SSH key and alias, and the tunnel. They are stored in
|
|
151
|
+
`~/.config/kdev/config.json` (mode 0600). All of them:
|
|
152
|
+
[Settings](https://kdev-cli.pages.dev/docs/settings/).
|
|
153
|
+
|
|
154
|
+
## Troubleshooting
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
kdev doctor # every dependency, account token, the workspace and the tunnel's DNS
|
|
158
|
+
kdev -v status # the same command, with each Kaggle API call logged
|
|
159
|
+
kdev logs # what the box itself is saying
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Most messages name the command that fixes them. Common ones are listed in
|
|
163
|
+
[Troubleshooting](https://kdev-cli.pages.dev/docs/troubleshooting/).
|
|
164
|
+
|
|
165
|
+
## Documentation
|
|
166
|
+
|
|
167
|
+
- [Install and set up](https://kdev-cli.pages.dev/docs/): the tunnel and the workspace in detail
|
|
168
|
+
- [How it works](https://kdev-cli.pages.dev/docs/how-it-works/): the architecture, what `kdev up` does, how files persist, with diagrams
|
|
169
|
+
- [Your files](https://kdev-cli.pages.dev/docs/files/) and [Several accounts, several machines](https://kdev-cli.pages.dev/docs/accounts/)
|
|
170
|
+
- [Security and limits](https://kdev-cli.pages.dev/docs/security/)
|
|
171
|
+
- [Architecture for contributors](https://github.com/tushar-mahalya/kdev/blob/main/docs/ARCHITECTURE.md), including how the code is laid out
|
|
172
|
+
|
|
173
|
+
## Contributing
|
|
174
|
+
|
|
175
|
+
Bug reports, fixes, docs and features are welcome. For anything bigger than a
|
|
176
|
+
fix, open an issue first. Questions go to
|
|
177
|
+
[Discussions](https://github.com/tushar-mahalya/kdev/discussions). How to set
|
|
178
|
+
up, test without spending GPU quota, and send a pull request:
|
|
179
|
+
[CONTRIBUTING.md](https://github.com/tushar-mahalya/kdev/blob/main/CONTRIBUTING.md).
|
|
180
|
+
|
|
181
|
+
## Security
|
|
182
|
+
|
|
183
|
+
Access is public-key SSH only. Kaggle has no API for notebook Secrets, so the
|
|
184
|
+
tunnel credentials sit in the private notebook's source, readable by anyone
|
|
185
|
+
with Can Edit. Kaggle allows one account per person and restricts tunnelling
|
|
186
|
+
out of notebooks; know the rules you are working under. Details are in
|
|
187
|
+
[Security and limits](https://kdev-cli.pages.dev/docs/security/). Report a
|
|
188
|
+
vulnerability privately, as
|
|
189
|
+
[SECURITY.md](https://github.com/tushar-mahalya/kdev/blob/main/SECURITY.md)
|
|
190
|
+
describes.
|
|
191
|
+
|
|
192
|
+
## License
|
|
193
|
+
|
|
194
|
+
[MIT](https://github.com/tushar-mahalya/kdev/blob/main/LICENSE). kdev is an
|
|
195
|
+
independent project, not affiliated with Kaggle, Google or Cloudflare.
|
kdev_cli-0.2.0/README.md
ADDED
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://raw.githubusercontent.com/tushar-mahalya/kdev/main/docs/assets/kdev-logo.png" alt="kdev" width="520">
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<p align="center">
|
|
6
|
+
<b>A Kaggle notebook as your remote dev box.</b><br>
|
|
7
|
+
Start it with one command, work in it from VS Code or a shell, and leave whenever you like.<br>
|
|
8
|
+
Your files are there next time — on any account in your Kaggle group, from any machine.
|
|
9
|
+
</p>
|
|
10
|
+
|
|
11
|
+
<p align="center">
|
|
12
|
+
<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>
|
|
13
|
+
<a href="https://pypi.org/project/kdev-cli/"><img alt="PyPI" src="https://img.shields.io/pypi/v/kdev-cli?logo=pypi&logoColor=white&color=00b8d4"></a>
|
|
14
|
+
<a href="https://pypi.org/project/kdev-cli/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/kdev-cli?logo=python&logoColor=white&color=3776AB"></a>
|
|
15
|
+
<a href="https://github.com/tushar-mahalya/kdev/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/tushar-mahalya/kdev?label=release&logo=github&color=2ea44f"></a>
|
|
16
|
+
<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>
|
|
17
|
+
<a href="https://scorecard.dev/viewer/?uri=github.com/tushar-mahalya/kdev"><img alt="OpenSSF Scorecard" src="https://api.scorecard.dev/projects/github.com/tushar-mahalya/kdev/badge"></a>
|
|
18
|
+
<a href="https://kdev-cli.pages.dev"><img alt="Website" src="https://img.shields.io/badge/website-kdev--cli.pages.dev-00b8d4"></a>
|
|
19
|
+
<a href="https://github.com/tushar-mahalya/kdev/blob/main/CONTRIBUTING.md"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-00b8d4"></a>
|
|
20
|
+
</p>
|
|
21
|
+
|
|
22
|
+
<p align="center">
|
|
23
|
+
<a href="https://kdev-cli.pages.dev"><b>Website</b></a> ·
|
|
24
|
+
<a href="https://kdev-cli.pages.dev/docs/">Docs</a> ·
|
|
25
|
+
<a href="https://kdev-cli.pages.dev/docs/how-it-works/">How it works</a> ·
|
|
26
|
+
<a href="https://kdev-cli.pages.dev/docs/commands/">Commands</a> ·
|
|
27
|
+
<a href="https://github.com/tushar-mahalya/kdev/blob/main/CHANGELOG.md">Changelog</a>
|
|
28
|
+
</p>
|
|
29
|
+
|
|
30
|
+
## Why kdev
|
|
31
|
+
|
|
32
|
+
Kaggle gives every account free GPU hours, but only inside a notebook. kdev
|
|
33
|
+
turns that notebook into a machine you can `ssh` into or open in VS Code.
|
|
34
|
+
|
|
35
|
+
- **One box, pooled quota.** Every account in your Kaggle group runs the same
|
|
36
|
+
shared notebook on its own weekly GPU hours. When one runs short, `kdev up`
|
|
37
|
+
asks which account takes over.
|
|
38
|
+
- **Files that persist.** Whatever is in `/kaggle/working` when a session ends
|
|
39
|
+
comes back at the next start, however it ended: `kdev down`, a timeout, a
|
|
40
|
+
crash, your wifi dropping.
|
|
41
|
+
- **A real server.** A stable hostname over Cloudflare Tunnel, public-key SSH,
|
|
42
|
+
and your notebook's full environment (CUDA, Python, Kaggle variables).
|
|
43
|
+
No port is opened on the box.
|
|
44
|
+
|
|
45
|
+
## Install
|
|
46
|
+
|
|
47
|
+
Needs Python 3.11+, `ssh`, and a Kaggle account in a Kaggle group.
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
uv tool install kdev-cli # or: pipx install kdev-cli
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
The package is `kdev-cli`; the command it installs is `kdev`. Upgrade with
|
|
54
|
+
`uv tool upgrade kdev-cli`.
|
|
55
|
+
|
|
56
|
+
## Quick start
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
kdev setup # once per machine: SSH key, cloudflared, Kaggle sign-in, workspace, tunnel
|
|
60
|
+
kdev up # start the box, or connect to the one already running
|
|
61
|
+
ssh kaggle # or VS Code → Remote-SSH → kaggle
|
|
62
|
+
kdev down # optional: stop early and hand the quota back
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
`kdev setup` only does what is missing, so it is safe to run again. Two parts
|
|
66
|
+
of it you may want to run on their own:
|
|
67
|
+
|
|
68
|
+
- **The tunnel.** With a domain on Cloudflare, `kdev tunnel setup` creates a
|
|
69
|
+
named tunnel with a hostname that never changes. Without one, `kdev setup`
|
|
70
|
+
offers a free quick tunnel, on a new hostname each session.
|
|
71
|
+
- **The workspace.** One account owns the notebook and shares it with the
|
|
72
|
+
group: `kdev workspace create --group <your-group-slug>`, once. Everyone else
|
|
73
|
+
runs `kdev workspace join`.
|
|
74
|
+
|
|
75
|
+
Leaving needs no ceremony: close the laptop and walk away. The box runs to the
|
|
76
|
+
end of its session and saves as it stops.
|
|
77
|
+
|
|
78
|
+
## Everyday commands
|
|
79
|
+
|
|
80
|
+
| command | what it does |
|
|
81
|
+
|---|---|
|
|
82
|
+
| `kdev` | the home screen: the box and every account's quota, live; one key per action |
|
|
83
|
+
| `kdev up` | start the box, or connect to the running one |
|
|
84
|
+
| `kdev down` | stop the box; files are saved however it stops |
|
|
85
|
+
| `kdev ssh` | open a shell on the box |
|
|
86
|
+
| `kdev status` | running? who started it? when does it end? files back? |
|
|
87
|
+
| `kdev forward PORT` | reach a service on the box through localhost (`9000:8888` remaps) |
|
|
88
|
+
| `kdev logs` | stream the session's log |
|
|
89
|
+
| `kdev history` | past saved sessions, who ran them and how they ended |
|
|
90
|
+
| `kdev restore` | finish or repeat the restore of your saved files |
|
|
91
|
+
| `kdev backup` | copy the running box's files to this machine |
|
|
92
|
+
| `kdev account` | accounts and their GPU/TPU hours left (`add`, `use`, `remove`) |
|
|
93
|
+
| `kdev workspace` | the shared notebook (`files`, `join`, `use`, `create`, `share`) |
|
|
94
|
+
| `kdev doctor` | check everything kdev depends on |
|
|
95
|
+
|
|
96
|
+
Run bare `kdev` and press a key: `1` starts the box, `s` shows its status, `q`
|
|
97
|
+
quits. The highlighted item always shows the command it runs, so everything
|
|
98
|
+
the menu does you can also type or script.
|
|
99
|
+
|
|
100
|
+
Useful flags on `kdev up`: `--gpu none|t4|p100|tpu`, `--hours N`,
|
|
101
|
+
`--account NAME`, `--open code|shell|none`, `--no-restore`, `--replace`, `-y`.
|
|
102
|
+
Add `-v` to any command to log each Kaggle API call. `status`, `history`,
|
|
103
|
+
`account` and `workspace files` take `--json` for scripts.
|
|
104
|
+
See the [full command reference](https://kdev-cli.pages.dev/docs/commands/).
|
|
105
|
+
|
|
106
|
+
## Settings
|
|
107
|
+
|
|
108
|
+
Pick once with `kdev config set`, and `kdev up` stops asking:
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
kdev config set gpu t4 # none, t4, p100, tpu (and l4, a100, h100 where available)
|
|
112
|
+
kdev config set hours 9 # Kaggle's limit: 12h, 9h on TPU
|
|
113
|
+
kdev config # list every setting; secrets are never shown
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Other settings cover a git remote that the box clones at boot and pushes every
|
|
117
|
+
15 minutes, your SSH key and alias, and the tunnel. They are stored in
|
|
118
|
+
`~/.config/kdev/config.json` (mode 0600). All of them:
|
|
119
|
+
[Settings](https://kdev-cli.pages.dev/docs/settings/).
|
|
120
|
+
|
|
121
|
+
## Troubleshooting
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
kdev doctor # every dependency, account token, the workspace and the tunnel's DNS
|
|
125
|
+
kdev -v status # the same command, with each Kaggle API call logged
|
|
126
|
+
kdev logs # what the box itself is saying
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Most messages name the command that fixes them. Common ones are listed in
|
|
130
|
+
[Troubleshooting](https://kdev-cli.pages.dev/docs/troubleshooting/).
|
|
131
|
+
|
|
132
|
+
## Documentation
|
|
133
|
+
|
|
134
|
+
- [Install and set up](https://kdev-cli.pages.dev/docs/): the tunnel and the workspace in detail
|
|
135
|
+
- [How it works](https://kdev-cli.pages.dev/docs/how-it-works/): the architecture, what `kdev up` does, how files persist, with diagrams
|
|
136
|
+
- [Your files](https://kdev-cli.pages.dev/docs/files/) and [Several accounts, several machines](https://kdev-cli.pages.dev/docs/accounts/)
|
|
137
|
+
- [Security and limits](https://kdev-cli.pages.dev/docs/security/)
|
|
138
|
+
- [Architecture for contributors](https://github.com/tushar-mahalya/kdev/blob/main/docs/ARCHITECTURE.md), including how the code is laid out
|
|
139
|
+
|
|
140
|
+
## Contributing
|
|
141
|
+
|
|
142
|
+
Bug reports, fixes, docs and features are welcome. For anything bigger than a
|
|
143
|
+
fix, open an issue first. Questions go to
|
|
144
|
+
[Discussions](https://github.com/tushar-mahalya/kdev/discussions). How to set
|
|
145
|
+
up, test without spending GPU quota, and send a pull request:
|
|
146
|
+
[CONTRIBUTING.md](https://github.com/tushar-mahalya/kdev/blob/main/CONTRIBUTING.md).
|
|
147
|
+
|
|
148
|
+
## Security
|
|
149
|
+
|
|
150
|
+
Access is public-key SSH only. Kaggle has no API for notebook Secrets, so the
|
|
151
|
+
tunnel credentials sit in the private notebook's source, readable by anyone
|
|
152
|
+
with Can Edit. Kaggle allows one account per person and restricts tunnelling
|
|
153
|
+
out of notebooks; know the rules you are working under. Details are in
|
|
154
|
+
[Security and limits](https://kdev-cli.pages.dev/docs/security/). Report a
|
|
155
|
+
vulnerability privately, as
|
|
156
|
+
[SECURITY.md](https://github.com/tushar-mahalya/kdev/blob/main/SECURITY.md)
|
|
157
|
+
describes.
|
|
158
|
+
|
|
159
|
+
## License
|
|
160
|
+
|
|
161
|
+
[MIT](https://github.com/tushar-mahalya/kdev/blob/main/LICENSE). kdev is an
|
|
162
|
+
independent project, not affiliated with Kaggle, Google or Cloudflare.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "kdev-cli"
|
|
3
|
-
version = "0.
|
|
3
|
+
version = "0.2.0"
|
|
4
4
|
description = "A Kaggle notebook as your remote dev box: SSH and VS Code in, files that persist across sessions, accounts and machines."
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
requires-python = ">=3.11"
|
|
@@ -28,11 +28,15 @@ dependencies = [
|
|
|
28
28
|
"kaggle>=2.2,<3",
|
|
29
29
|
"typer>=0.27,<1",
|
|
30
30
|
"questionary>=2.0,<3",
|
|
31
|
+
# The home menu is a small prompt_toolkit app of its own (questionary is
|
|
32
|
+
# built on it too).
|
|
33
|
+
"prompt-toolkit>=3.0.36,<4",
|
|
31
34
|
"rich>=13,<16",
|
|
32
35
|
]
|
|
33
36
|
|
|
34
37
|
[project.urls]
|
|
35
|
-
Homepage = "https://
|
|
38
|
+
Homepage = "https://kdev-cli.pages.dev"
|
|
39
|
+
Documentation = "https://kdev-cli.pages.dev/docs/"
|
|
36
40
|
Repository = "https://github.com/tushar-mahalya/kdev"
|
|
37
41
|
Issues = "https://github.com/tushar-mahalya/kdev/issues"
|
|
38
42
|
Changelog = "https://github.com/tushar-mahalya/kdev/blob/main/CHANGELOG.md"
|
|
@@ -55,7 +59,7 @@ include = ["src/kdev", "tests", "README.md", "LICENSE", "pyproject.toml"]
|
|
|
55
59
|
[dependency-groups]
|
|
56
60
|
# ruff is pinned to the version .pre-commit-config.yaml runs, so a clean
|
|
57
61
|
# `uv run ruff` locally means a clean hook and a clean CI.
|
|
58
|
-
dev = ["pytest>=8", "ruff==0.16.
|
|
62
|
+
dev = ["pytest>=8", "pytest-cov>=7.1", "ruff==0.16.10", "pre-commit>=4", "basedpyright>=1.40"]
|
|
59
63
|
|
|
60
64
|
[tool.pytest.ini_options]
|
|
61
65
|
testpaths = ["tests"]
|
|
@@ -71,3 +75,12 @@ docstring-code-format = true
|
|
|
71
75
|
[tool.ruff.lint]
|
|
72
76
|
select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
|
|
73
77
|
ignore = ["E501", "RUF001", "RUF002", "RUF003"] # the design glyphs are deliberate
|
|
78
|
+
|
|
79
|
+
# Basic mode for now: catches wrong types, misspelled attributes and
|
|
80
|
+
# str | None passed where str is needed, without demanding full strictness.
|
|
81
|
+
# kdev_box.py runs inside the Kaggle notebook with only the standard
|
|
82
|
+
# library, so it must never gain imports from this package at runtime.
|
|
83
|
+
[tool.pyright]
|
|
84
|
+
include = ["src", "tests"]
|
|
85
|
+
pythonVersion = "3.11"
|
|
86
|
+
typeCheckingMode = "basic"
|