Skip to content

KeepGPU

Keep a polite GPU presence while the scheduler, lab mate, or cluster watchdog waits.

KeepGPU is a tiny-but-focused toolkit that allocates memory and runs low-cost platform-specific keep-alive work when utilization backoff permits. When utilization telemetry is unavailable, the default loop backs off and sleeps instead of forcing compute; --busy-threshold -1 is the explicit unconditional keepalive mode, especially on Mac M/MPS.

Why it matters

  • Hold your session – Prevent preemptive job eviction on shared clusters that recycle idle GPUs after a short grace period.
  • Avoid surprise card sharing – Keep teammates, notebooks, or background jobs from silently grabbing the GPU while you are still working.
  • Stay lightweight – Instead of pinning a full training job, KeepGPU runs periodic lightweight elementwise ops and sleeps between bursts to keep thermals/noise low.

What’s inside

  • Rich CLI based on Typer + Rich for blocking and non-blocking session workflows.
  • GlobalGPUController that spins up a keep-alive worker per selected GPU.
  • CudaGPUController, RocmGPUController, and MacMGPUController context managers for fine-grained orchestration inside scripts.
  • Service dashboard, REST endpoints, JSON-RPC methods, and MCP server for browser controls, scripts, and agent integrations.
  • Helpers for parsing human VRAM sizes (1GiB, 850MB, etc.) and platform detection.
  • Power-aware keep-alive loop: periodic elementwise ops to signal “busy” without flooding matmuls or spiking thermals.

Where to go next

  • Getting Started – Install, verify keep-gpu works, and run your first protection loop.
  • CLI Playbook – Task-focused recipes for keepalive sessions on clusters, workstations, or Jupyter.
  • Python API Recipes – Drop-in snippets for wrapping preprocessing stages or orchestration scripts.
  • Dashboard, MCP, and Service API – Run keep-gpu serve, use the browser dashboard, or integrate through JSON-RPC/REST/MCP endpoints.
  • :material-diagram-project: How KeepGPU Works – Learn how controllers allocate VRAM and throttle themselves.
  • Reference – Full option list plus mkdocstrings API reference.

Prefer a fast skim?

The left sidebar mirrors the lifecycle: overview → usage → concepts → references. Jump straight to what you need; sections stand on their own.