deploygpu

Rent a GPU from the terminal.

npm install -g deploygpu

This installs the command as gpu (and as deploygpu and dgpu, which are the same thing). Requires Node 20.11+. No Node? npx deploygpu … works from any machine with npm, and a standalone binary is planned.

Typing just gpu shows what's running and what's in stock.

Quick start

gpu login                      # paste an API key
gpu                            # what's running, what's in stock
gpu ls h100                    # offers for one GPU
gpu up h100 --name trainer     # deploy the cheapest H100 and wait
gpu sh trainer                 # shell in
gpu down trainer               # stop billing

ls/up/sh/down are short for gpus/offers/run/ssh/stop; both forms work everywhere.

run picks the cheapest offer that is in stock and actually deployable, checks your balance and your ssh key before spending anything, shows you the hourly cost, waits for the box, and prints how to connect.

$ gpu run --gpu h100 --name trainer
offer  quantacloud · us-midwest-2 · 1× NVIDIA H100 PCIe 80GB
disk   100GB
cost   $2.59/hr · $62.16/day
       first hour ($2.59) is reserved now; unused time is refunded when you stop
       if it fails to provision, the next cheapest is tried automatically (up to 3)
Deploy this? [Y/n]
⠹ provisioning — reserving credits and asking the provider for the box (0:47)
✓ trainer is active · $2.59/hr
  ssh      ssh [email protected]

  connect  gpu ssh trainer
  stop     gpu stop trainer   ← billing runs until you do

Run a job and stop

The thing a CLI can do that a dashboard cannot:

gpu run --gpu h100 --rm -- python train.py

Deploys, waits for ssh, runs the command on the box with your terminal attached, then stops the deployment when it exits. The exit code is the command's. Ctrl-C stops the box too. --ssh does the same but leaves the box running when you log out.

When the cheapest offer fails

Providers oversell. When a create is refused (offer_cooling_down, offer_unavailable) or a deployment ends up failed, run moves to the next cheapest offer and tells you:

✗ hyperstack · CANADA-1 · 1× NVIDIA H100 PCIe 80GB — cooling down after a recent failure
→ trying quantacloud · us-midwest-2 · 1× NVIDIA H100 PCIe 80GB · $2.59/hr
✓ trainer is active · $2.59/hr
  after 2 attempts: ee7763a9 (cooling down) → 1e0cb91e ✓

Up to --attempts (default 3), and never more than 25% above the price you confirmed unless you set --max-price. A failed deployment is refunded in full — you are not billed for a box you never got.

Commands

| | | |---|---| | login / logout / whoami | credentials | | balance | credit balance | | gpus | GPU types, stock and cheapest price | | offers | individual offers, with filters | | providers | cloud providers and whether the API can deploy them | | run | deploy and wait; --ssh, --rm -- cmd | | ps | what's running, with live cost | | status <ref> | one deployment in detail | | stop <ref> | stop and end billing | | ssh <ref> [cmd] | shell in, or run one command | | cp <src> <dst> | copy files: ./data trainer:/workspace | | port-forward <ref> <port> | tunnel a remote port to localhost | | open <ref> | open the web endpoint (tunnel/Jupyter) in a browser | | keys | ssh keys on the account; add, generate, rm | | config | defaults for run: set disk 200, set gpu h100 | | completion <shell> | bash, zsh or fish completion | | doctor | check auth, connectivity, ssh and balance |

<ref> is a --name you chose, a full deployment id, or a unique id prefix as printed by ps.

Filters accept what people type: --region us, eu, finland, us-east; --provider quanta; --gpu h100 (any variant) or --gpu h100-pcie-80gb.

SSH keys

The account's default key is generated server-side at signup, so a machine that has never used the dashboard usually has no matching private key. run checks before deploying and, in a terminal, offers to fix it:

! No ssh key on this machine matches your account.
  Generate one now and register it? [Y/n]

Or do it explicitly: gpu keys add ~/.ssh/id_ed25519.pub, or gpu keys generate (creates ~/.ssh/deploygpu_ed25519 and remembers to use it). keys list shows which registered key this machine holds.

Scripting

Every command takes --json and writes the raw API shape to stdout. Human chatter goes to stderr, so pipes stay clean. -q prints only what a script needs.

ID=$(gpu run --gpu a100 -q -y)
gpu ps --json | jq -r '.[] | select(.status=="active") | .id'
gpu run --gpu h100 --json -y | jq .attempts

Exit codes:

| | | |---|---| | 0 | success | | 1 | error | | 2 | bad usage | | 3 | not authenticated | | 4 | not found | | 5 | insufficient balance | | 6 | rate limited | | 7 | the deployment failed | | 8 | no capacity (every tried offer was cooling down or unavailable) | | 130 | interrupted — the deployment exists; gpu stop <ref> |

Ctrl-C during run never loses the deployment id: if a create is in flight it finishes, prints the id, then exits.

Configuration

| Variable | | |---|---| | DEPLOYGPU_API_KEY | use this key instead of the stored one | | DEPLOYGPU_API_URL | override the API base URL | | DEPLOYGPU_PROFILE | select a credential profile | | DEPLOYGPU_CONFIG_DIR | where config is stored | | DEPLOYGPU_NO_CACHE | =1 to bypass the catalog cache | | DEPLOYGPU_NO_UPDATE_CHECK | =1 to never check npm for a newer version |

Credentials live in ~/.config/deploygpu/config.json, mode 0600. Use --profile to keep separate accounts side by side. Catalog responses are cached on disk (families and providers for 5 minutes, offers for 20 seconds), which is why the second gpus is instant.

The CLI checks npm for a newer version at most once a day, only in a terminal, and prints one line if there is one.

For CI, set DEPLOYGPU_API_KEY and skip login; a missing ssh key is a warning, not a failure.

Notes and current limits

These come from how the v1 API behaves today. They are tracked in ../CLI_PLAN.md §7.

• Container providers are hidden by default. The v1 API rejects Vast.ai deployments, but its offers dominate the marketplace listing — so offers and run skip them. --all shows them.
• Templates aren't supported. v1 deploys bare VMs only; ComfyUI, Jupyter and Ollama templates are dashboard-only. No --template flag yet.
• Failure reasons are coarse. failure_code is UNKNOWN for every failed deployment in production right now, so run reports the underlying failure_reason text instead of a specific remedy.
• No reliability signal. The API does not expose how often an offer fails, so "cheapest" can mean "cheapest that keeps failing". The fall-through above is the mitigation until it does.
• login --browser is not available. It needs a deploygpu-cli OAuth client with a loopback redirect registered on the authorization server.
• No server-side auto-stop. Nothing stops a forgotten box. --rm covers jobs; ps shows your hourly burn; stop --all is the blunt instrument.
• Polling, not streaming. run --wait polls every 2s for 30s, then 5s, then 10s, with jitter.

The API base URL is https://api.deploygpu.ai. platform.deploygpu.ai is the dashboard — it answers API paths with the SPA's HTML at HTTP 200, so the CLI detects that and tells you rather than failing to parse it.

Development

npm install
npm run typecheck
npm test
npm run build       # -> dist/index.js, a single bundled file
node dist/index.js --help

The API client is hand-written rather than generated: /api-docs renders every Map<String, Object> handler as an untyped object and documents only 200 responses, so codegen from it yields unknown everywhere.