Deploy colab-gpu-platform
Headless GPU jobs on your Colab account - survive disconnects
colab-gpu-platform
Just deployed
/data
Colab GPU Platform — headless GPU jobs that survive disconnects
Submit GPU jobs to your own Colab account from any device — paste code or a notebook, pick an accelerator, close the tab. Jobs run server-side on Colab runtimes (official Colab API v1beta + standard Jupyter protocol), output streams into a run log you can reattach to anytime, and a checkpoint/resume layer handles Colab's runtime reclamation instead of pretending it does not exist.
One deploy prompt: GOOGLE_CREDENTIALS_JSON — a refresh-token credential for your
Google account. Everything else (password, webhook, concurrency) is optional and can be
added post-deploy.
What you get
- Dashboard (Jinja2): connect flow, job list, job detail with live log stream, artifact browser, Colab tier badge.
- Job API:
POST /api/jobs(code paste or.ipynbnotebook mode, accelerator NONE/T4/L4/A100/H100, shape STANDARD/HIGHMEM, timeout, cron schedule, per-job webhook), run history,WS /api/jobs/{id}/streamfor live output. - Runtime lifecycle: CreateRuntime (LRO) → token refresh at expiry−5 min →
Jupyter session execute → DeleteRuntime on completion (or reuse with
RUNTIME_REUSE=true; idle reused runtimes are reaped after 5 min). - Checkpoint/resume: jobs call
platform_checkpoint()to snapshotCHECKPOINT_PATHto the platform volume; on reclaim, the run is marked RECLAIMED, a webhook fires, and a new attempt auto-resumes with the checkpoint re-uploaded before your code re-runs. - Scheduler: per-job cron (
*/15 * * * *etc.), 30 s tick, skips ticks when a run is already active. - Artifacts: files written to
/content/artifactsare harvested to the volume at completion and downloadable from the UI. - Notifications:
NOTIFY_WEBHOOK_URL(Discord-compatible JSON) on COMPLETE/FAILED/RECLAIMED. - Security:
APP_ACCESS_PASSWORD(auto-generated per deploy) gates mutations; reads stay open via unguessable job ids.
Honest limits
- Free-tier Colab caps runtimes (~12 h) and actively deletes idle runtimes — that is Colab's design. This platform never sends synthetic keep-alive; checkpoint/resume is the reliability mechanism.
- Under load, Colab VMs can take minutes to boot and freshly assigned kernels often
sit in
startingfor 5–10+ minutes. The platform warm-waits over REST (up to 8 min), then probes execution; hung VMs are torn down and reprovisioned (up to 5 tries) — busy-day provisioning can take a while, honestly. - Colab quota can refuse runtime creation (quota/stockout) — errors surface verbatim. Pro/Pro+ raise limits and unlock A100/H100 (eligibility comes from the API itself).
- The Colab API is v1beta and allowlist-gated for some accounts; a 401/403 surfaces immediately at connect time. It also requires a quota project (any of your Google Cloud project IDs — the platform handles the header and API enablement).
- Files move through the Jupyter Contents API: 45 MB max per artifact/checkpoint file.
- Orchestration via the official API on your own account is sanctioned use; hosting live web services from runtimes is prohibited and this platform does not do it.
Deploy
- Click the deploy button. The deploy form asks for
GOOGLE_CREDENTIALS_JSON: get a refresh-token credential one of two ways:- Loopback copy-paste (zero setup): after deploy, open
/connecton your platform URL, copy the consent URL into the browser where you are signed in to Google, approve it — the browser then lands on a "This site can't be reached" page (expected; the redirect goes tohttp://localhost:8080and nothing is listening). Copy thecode=4/0A...value from the address bar, enter a quota project ID (any of your Google Cloud project IDs — the Colab API requires one; the platform auto-enablescolaboratory.googleapis.comon it), and submit — the platform exchanges the code server-side and stores the refresh token on the volume. - gcloud ADC: run
gcloud auth application-default login --scopes=openid,https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/colaboratorylocally, rungcloud services enable colaboratory.googleapis.com --project YOUR_PROJECT_ID, then paste the contents of~/.config/gcloud/application_default_credentials.json(plus a"quota_project_id": "YOUR_PROJECT_ID"key) into theGOOGLE_CREDENTIALS_JSONdeploy prompt.
- Loopback copy-paste (zero setup): after deploy, open
- Railway provisions one service + a
/datavolume (credential, SQLite jobs/runs, checkpoints, artifacts) and a public domain with a/healthhealthcheck. - Open the domain → the dashboard tells you exactly where you are: "Run your
first job" is a one-click button on first visit (hello-world on a real Colab
runtime end-to-end, typically under 2 minutes, including artifact harvest).
The password prompt on actions is
APP_ACCESS_PASSWORDfrom the Variables tab, entered once per browser. API users:POST /api/jobswith theX-Platform-Passwordheader (curl examples in the README).
Deploy and Host
About Hosting
One Railway service (Python 3.12 / FastAPI) with a persistent /data volume:
- colab-gpu-platform — the API + dashboard + worker. Healthcheck at
/health(restart ON_FAILURE, max 10 retries). SQLite (jobs, runs, artifacts, checkpoints) and the Google credential JSON live on the volume, so a redeploy keeps all state. - Public domain on the service; TCP is plain HTTPS (the platform talks to Colab server-side — nothing inbound except this dashboard/API).
Deploy-form variables:
GOOGLE_CREDENTIALS_JSON(required) — refresh-token credential JSON for your Google account (gcloud ADC file contents +quota_project_idkey, or paste the authorization code + quota project ID at/connectpost-deploy).APP_ACCESS_PASSWORD— auto-generated per deploy (${{secret(24)}}), shown in the Variables tab; gates all mutations.QUOTA_PROJECT_ID(optional) — your Google Cloud project ID used as the Colab API quota project (x-goog-user-project); settable per-deploy or at/connect.
Why Deploy
Colab gives you free/cheap GPUs but only through a browser tab that dies when you close it. This template turns that into a real job platform: server-side execution, a REST/WS API, cron schedules, checkpoints, and artifacts — with the runtime lifecycle handled the way Colab actually behaves (idle reclamation is expected and recovered, not fought with keep-alive hacks). Deploying the raw pieces yourself means gluing OAuth refresh, LRO polling, the Jupyter kernel WebSocket protocol, Contents-API chunking, and a reclaim state machine by hand — this template ships all of it working, on one service and one volume.
Common Use Cases
- Long training/eval sweeps that outlive a browser session (checkpoint every N steps).
- Nightly scheduled GPU jobs (
0 3 * * *) — backtests, data pipelines, fine-tunes. - Notebook mode: run an exported
.ipynbheadless on a schedule. - Team job endpoint: submit jobs from scripts/CI via
POST /api/jobs, watch viaWS /api/jobs/{id}/stream, get pinged on Discord when they finish or get reclaimed. - Artifact collection: models/metrics written to
/content/artifactsland on the platform volume, downloadable from the dashboard.
Dependencies for
Deployment Dependencies
- A Google account with Colab access (free tier works; Pro/Pro+ raise limits and
unlock A100/H100) and one-time consent via the
/connectpage or thegcloud auth application-default logincommand above. The credential refreshes server-side forever. - A Google Cloud project used as the Colab API quota project (any active
project of yours; the platform auto-enables
colaboratory.googleapis.comon it at connect time). Without it the Colab API returns 403 SERVICE_DISABLED for ADC user credentials. - No external database, no other services: SQLite on the volume.
- Colab API v1beta is Google's beta API; usage is subject to Colab's quotas and Terms of Service (batch orchestration on your own account — no hosted web services from runtimes, no keep-alive synthetics, both by design here).
Template Content
colab-gpu-platform
lNamelessl/colab-gpu-platformGOOGLE_CREDENTIALS_JSON

