caudex

Run your Jupyter notebooks on Kaggle's free GPUs, from your terminal.

Write a notebook on your laptop, send it to Kaggle, watch it run, get your files back. No browser tabs, no dropdown menus, no refreshing a page to see if it finished.

It uses your own Kaggle account and your own free weekly quota. Your notebooks, credentials and outputs go straight to Kaggle from your machine — never through anyone else's servers — and every file stays on your machine.

Install

pip install caudex

You need Python 3.11 or newer and a free Kaggle account.

Works on Windows, Linux, and macOS on Apple Silicon (M1 and later). Intel Macs are not supported — pip will say it cannot find a matching distribution rather than installing something that does not run.

Step 1 — connect your Kaggle account

You do this once.

caudex auth --setup

It will ask for your Kaggle username and an API key. To get the key:

1. Go to kaggle.com, click your profile picture → Settings
2. Scroll to API → click Create New Token
3. A file called kaggle.json downloads — open it in any text editor
4. Copy the two values into the prompt

Check it worked:

caudex whoami

Step 2 — make a notebook project

caudex init train.ipynb

This creates a folder with a starter notebook inside it, and tells you where it is. Open that notebook in Jupyter, VS Code, or whatever you normally use, and write your code.

One thing to know: anything you want to keep must be saved to /kaggle/working/.

model.save("/kaggle/working/model.keras")
df.to_csv("/kaggle/working/scores.csv", index=False)

That folder is the only thing that comes back to you. Everything else on the Kaggle machine disappears when the run ends.

Step 3 — run it

caudex execute --gpu

That one command does the whole job: uploads your notebook, starts it on Kaggle, streams the output to your screen as it happens, waits for it to finish, and downloads your files.

Leave off --gpu and it runs on a CPU instead — which doesn't use any of your GPU hours, so it's the cheap way to check your code works before spending quota on it.

When it finishes you'll see where your files went, and a summary of how long each cell took.

The easier way: open the shell

Typing caudex on its own opens an interactive session:

 ██████╗ █████╗ ██╗   ██╗██████╗ ███████╗██╗  ██╗
██╔════╝██╔══██╗██║   ██║██╔══██╗██╔════╝╚██╗██╔╝
██║     ███████║██║   ██║██║  ██║█████╗   ╚███╔╝
██║     ██╔══██║██║   ██║██║  ██║██╔══╝   ██╔██╗
╚██████╗██║  ██║╚██████╔╝██████╔╝███████╗██╔╝ ██╗
 ╚═════╝╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚══════╝╚═╝  ╚═╝

  0.7.0
  your-username  ·  GPU 12h left
  no project — try:  init train.ipynb
  /  commands    ^C  cancel    ^D  exit

Inside it you can drop the caudex prefix and the folder name — it remembers which project you're working on:

> use ./my-experiment
> execute --gpu
> logs

Press / to see every command in a menu; arrow keys to pick one, Enter to accept it, Enter again to run. Ctrl-C cancels whatever is running without closing the session. Ctrl-D or exit leaves.

It remembers your history between sessions, and Tab completes commands, options and file paths.

Watching a long run

caudex ui

A live dashboard: your notebooks on the left, the current run's status and log tail on the right, your remaining quota along the bottom. j/k to move, Enter to follow a notebook's log, q to leave.

If you'd rather just tail the log:

caudex logs --follow

Things you'll want sooner or later

Add --help to anything for the full list of options.

Where your files go

Run caudex paths show and it will tell you exactly. By default:

• Your notebook projects live wherever you made them
• Results come back to a folder per notebook, under your user directory
• Your Kaggle token sits in ~/.kaggle/kaggle.json — the same file the official kaggle command uses, so the two work side by side

You can change where results land:

caudex paths set output_dir ~/kaggle-results

If something goes wrong

"Kaggle auth failed" — your token has expired or been revoked. Make a new one at kaggle.com → Settings → API → Create New Token, then run caudex auth --setup again.

The run stops and says it timed out — that means caudex gave up watching, not that your notebook died. It is probably still running on Kaggle and still using your quota. Check it with caudex status, or use caudex execute --on-timeout cancel next time if you'd rather it stopped the run too.

Your notebook produced no files — anything you want back has to be written to /kaggle/working/. Files written anywhere else are thrown away when the run ends.

You ran out of GPU hours — Kaggle gives you a fixed number per week and resets them on a fixed day; caudex quota shows both. CPU runs don't touch that budget, so you can keep working while you wait.

Exit codes, for scripts

0 worked · 1 failed · 2 you typed something wrong · 124 gave up waiting

124 is deliberately not 1: a run that outlives your patience is not a run that broke.

Licence

Business Source License 1.1, from 0.6.0 onward. Free to use for real work; not to resell as a hosted service, and not to strip the licence check out of. It converts automatically to Apache-2.0 on 2030-08-20.

Versions 0.2.0–0.5.2 were released under Apache-2.0 and remain so permanently.

The full text ships in every release as LICENSE. For alternative licensing, contact mdsohanurislamshuvo@gmail.com.

What talks to the network

Your Kaggle credentials are never sent to us and no file passes through our servers.

What needs a licence

From 0.7.0, the commands that send work to Kaggle need one. Getting it is free:

caudex auth --licence

Free without one — enough to see whether caudex is for you:

Needs a licence — push, execute, pull, logs, status, watch, run, ui, dataset, init, convert, runtime.

The check reads a file on your machine and is silent when it passes. It asks our server at most once a day, and if we are unreachable caudex keeps working for another two weeks rather than blaming your key for our outage.