OPBDH

Open the Pod Bay Door, Hal

Full documentation at opbdh

— “Of course I can do it, Dave.”

Launches a GPU pod, runs your model-backed script on it, syncs the results home, and deletes the pod.

First launch

pip install opbdh
opbdh

Running opbdh unconfigured starts a setup wizard: it picks a provider (RunPod or Prime Intellect), checks your API token (RUNPOD_API_TOKEN / PRIME_INTELLECT_API_KEY), and asks for defaults — model, code path, minimum VRAM, price caps — saved globally or per project.

Needs macOS or Linux, Python ≥ 3.11, and ssh/scp on your PATH. An existing ~/.ssh keypair is used if present, otherwise one is generated under ~/.config/opbdh/ssh/. Set HF_TOKEN for private/gated Hugging Face models.

Launch a pod

opbdh launch ./run.py --model Qwen/Qwen2.5-0.5B-Instruct --vram-gb 48 --max-spend 5

This verifies your code, picks the cheapest fitting GPU, launches the pod, runs your command, streams remote logs/ and results/ into runpod_results/<run_id>/, stops the run if estimated spend crosses the cap, and deletes the pod when it finishes — or fails. Add --dry-run to print the plan without contacting the provider; real launches ask for confirmation unless --yes.

From Python

The same thing, as a library:

import opbdh

result = opbdh.launch("./run.py", model="Qwen/Qwen2.5-0.5B-Instruct",
                      vram_gb=48, max_spend=5)
print(result.outputs_dir)

Keyword arguments are the config fields (plus model, max_spend, and min_ram_per_gpu as CLI-style aliases) and layer over opbdh.json and the global config exactly as flags do. opbdh.plan(...) builds the plan without renting anything, and on_event= streams progress. Unlike the CLI these functions never prompt: launch() spends without asking, and a failed run always cleans up its pod. Full reference in docs/API.md.

Features

• 🚀 One command, whole mission — verify, pick a GPU, launch, run, sync results, clean up
• 🐍 CLI or library — every command is a function call; see docs/API.md
• 💸 Cost-aware by default — hourly price caps, a hard max-spend guard, a confirmation gate
• 🎯 GPU selection from a budget — say how much VRAM and how many dollars
• 💾 Persistent model cache — network volumes sized from the model's real weight files, reused across runs (RunPod)
• 🧪 Nothing launches unverified — static checks and a --dry-run mode
• 🧙 Wizards or flags — first-run setup, opbdh config wizard, opbdh run wizard; or plain flags (each with a one-letter short form) and layered JSON config
• ☁️ Two providers — RunPod (default) or Prime Intellect's multi-cloud marketplace via --provider primeintellect
• 👁️ HAL watches your money — a pulsing red eye with elapsed time and estimated spend (TTY only; OPBDH_NO_HAL=1 to silence)

Options

Flags override a local opbdh.json/.opbdh.json, which overrides ~/.config/opbdh/config.json. String values support {cwd}-style placeholders and $VARs.

Config-only keys, one each: image (Docker tag, or Prime Intellect environment name), cloud_type (SECURE/COMMUNITY/ALL), container_disk_gb, pod_volume_gb, network_volume_name, network_volume_size_gb, pre_download_model (default on), results_dir, poll_seconds, failure_keepalive_seconds (debug window on failure, default 120 s), keep_pod_on_success, ssh_key/ssh_public_key.

Other commands, one each: opbdh plan (show the plan for a run), opbdh verify (static checks only), opbdh gpus (GPU candidates and prices), opbdh models search/size (find models, weight size + suggested volume), opbdh config show/write/wizard.

On the pod, your script runs with OPBDH_MODEL_ID, OPBDH_RESULTS_DIR, and the HF cache variables set; a sibling requirements.txt is pip-installed; write to logs/ and results/ and they come home. Network volumes are never deleted by OPBDH and bill by the GB-month — clean them up in the RunPod console.

Development

pip install -e ".[dev]"
ruff check .
pytest

See RELEASING.md for releases. MIT — unlike HAL, this software is incapable of refusing to open the pod bay door, becoming sentient, or reading lips.