gcloud-gpu-agent

gcloud-gpu-agent

🤖 An AI agent skill that spins up and drives Google Cloud GPUs for you.

Ask your agent to "launch an L4 and run my training" — it creates the VM, pushes your repo, kicks off the job in a detached session, streams the logs, pulls your results, and reminds you to shut it down. Works with Claude Code and Codex CLI. Powered by one dependency-free Bash script wrapping gcloud, so it also works as a plain CLI.

Claude Code:

/plugin marketplace add AlexBodner/gcloud-gpu-agent
/plugin install gcloud-gpu-agent@alexbodner-gcloud-gpu-agent

Codex CLI:

# 1. Install the CLI (needed so the agent can call gpu-vm commands)
curl -fsSL https://raw.githubusercontent.com/AlexBodner/gcloud-gpu-agent/main/install.sh | bash

# 2. Add the skill to your project (or ~/.codex/skills/ for global use)
mkdir -p .codex/skills/gcloud-gpu-agent
curl -fsSL https://raw.githubusercontent.com/AlexBodner/gcloud-gpu-agent/main/.codex/skills/gcloud-gpu-agent/SKILL.md \
  -o .codex/skills/gcloud-gpu-agent/SKILL.md

Now just talk to your agent:

"Spin up an A100, push this repo, and start train.py in tmux." "Tail the training log." · "Pull the checkpoints and stop the VM."

The agent runs the right commands under the hood and reads the output back for you.

Use it as a plain CLI too

The same tool works without an agent:

curl -fsSL https://raw.githubusercontent.com/AlexBodner/gcloud-gpu-agent/main/install.sh | bash

GPU=nvidia-l4 gpu-vm create                         # 🚀 a 24GB GPU box, ~90 seconds
gpu-vm push ~/my-project                            # 📦 upload (private repos OK)
gpu-vm run "cd my-project && python train.py" train # 🏃 detached job in tmux
gpu-vm logs train.log                               # 📜 stream the logs
gpu-vm pull my-project/outputs ./outputs            # ⬇️  bring results home
gpu-vm stop                                         # ⏸  stop billing (disk kept)

The installer drops gpu-vm into ~/.local/bin — make sure that's on your PATH.

Why

Renting a cloud GPU for an afternoon shouldn't require learning an infrastructure framework. The console is clicky, raw gcloud is verbose, and notebooks die when your laptop sleeps. gpu-vm gives an agent (or you) the five verbs that actually matter — create, push, run, pull, stop — with sane GPU defaults and the gotchas (stockouts, first-boot driver install, private-repo upload, tmux jobs) already handled.

• 🤖 Built for agents. Every command runs locally and returns the VM's output — no interactive shell — so Claude can run jobs and read results directly.
• 🧩 One file, zero deps. Pure Bash + gcloud. Read it in two minutes.
• 🔒 Private repos just work. push ships git archive HEAD over scp; no GitHub credentials ever land on the VM.
• 🧵 Long jobs survive disconnects. run launches inside tmux; wait blocks until it's done without the classic pgrep self-match footgun.
• 💸 Cost-aware by default. Reminds you to stop/delete; SPOT=1 for cheap preemptible instances.

Manual / standalone install

curl -fsSL https://raw.githubusercontent.com/AlexBodner/gcloud-gpu-agent/main/gpu-vm.sh \
  -o ~/.local/bin/gpu-vm && chmod +x ~/.local/bin/gpu-vm

Prerequisites (one time)

brew install --cask google-cloud-sdk     # or: https://cloud.google.com/sdk/docs/install
gcloud auth login
gcloud config set project YOUR_PROJECT_ID

You also need GPU quota. New projects often start at 0 — request it under IAM & Admin → Quotas (search e.g. NVIDIA_L4_GPUS). Approval can take minutes to a day.

# Check your current GPU quota:
gcloud compute regions describe us-central1 \
  --format="value(quotas)" | tr ';' '\n' | grep -i gpus

Quickstart

# 1. Create a VM (defaults: nvidia-l4, us-central1-a, 200GB disk)
GPU=nvidia-l4 ZONE=us-central1-a NAME=ml gpu-vm create

# 2. Confirm the GPU is up (first boot installs the driver, ~1-2 min)
NAME=ml gpu-vm status

# 3. Upload your code (a git repo → committed files only; works with private repos)
NAME=ml gpu-vm push ~/path/to/project

# 4. Install deps (one-shot command; output comes back to your terminal)
NAME=ml gpu-vm ssh "cd project && pip install -r requirements.txt"

# 5. Launch a long training job in tmux (survives SSH disconnects)
NAME=ml gpu-vm run "cd project && python train.py" train

# 6. Watch it
NAME=ml gpu-vm logs train.log        # tail -f, Ctrl-C to stop watching
NAME=ml gpu-vm status                # tmux sessions + nvidia-smi
NAME=ml gpu-vm wait train            # block until the job finishes

# 7. Get your results and shut down
NAME=ml gpu-vm pull project/outputs ./outputs
NAME=ml gpu-vm stop                  # keeps the disk; or `delete` to free everything