CH·02CLI reference

gpu deploy

Deploy a curated application template onto a GPU instance

Synopsis

Deploys a curated application template (e.g. comfyui, automatic1111, vllm, faster-whisper, axolotl-finetuning) onto a GPU instance. A template deploy *is* an instance — it reuses the same async operation FSM as gpu instances create. The cheapest eligible GPU is auto-selected unless you pass --type.

The CLI polls the operation until the app is ready (10-minute deadline by default), then prints the instance details plus the app's HTTPS URL — your app is reachable at https://.apps.gpu.ai behind HTTP basic-auth. The basic-auth username and password are printed on deploy and retrievable any time via gpu instances get, gpu instances open, or the dashboard instance page.

The password is redacted from bare API reads: third-party callers must pass ?include=credentials on GET /v1/instances/{id} to retrieve it (the CLI and dashboard do this for you). Instance lists and operation results never include it.

Use --wait-timeout=0 to skip polling and print just the operation_id for scripts that poll asynchronously.

Every template declares a minimum per-GPU VRAM (gpu templates show ). Passing a --type below that floor is rejected immediately with a 422 gpu_vram_too_small naming both numbers and the GPU types that do fit — such deploys used to be accepted and then died on boot. Auto-select is unaffected: it already only considers GPUs at or above the floor. See deployable-templates.md.

For templates that serve a Hugging Face model via --env MODEL=… (vLLM, SGLang), the API checks the model's published weights size against the GPU's VRAM at submit time: an oversized model on an explicit --type is rejected immediately with an actionable 422 model_too_large (rather than crash-looping until the provisioning timeout), and auto-select raises its VRAM floor so placement lands on a GPU the model fits. Gated/private/unknown repos are never blocked — the deploy proceeds and the CLI prints a Warning: line that the size could not be verified. See deployable-templates.md.

gpu deploy <template-id> [flags]

Examples

# Deploy ComfyUI (auto-selects the cheapest eligible GPU)
gpu deploy comfyui --tier on_demand --ssh-key-id <key-id>

# vLLM with a model + HF token (secret env is redacted from logs/metadata)
gpu deploy vllm --env MODEL=meta-llama/Llama-3.1-8B-Instruct --env HF_TOKEN=hf_xxx

# Axolotl fine-tuning workbench (Jupyter Lab) — HF token unlocks gated models
gpu deploy axolotl-finetuning --env HF_TOKEN=hf_xxx

# Faster Whisper speech-to-text (web UI + OpenAI-compatible audio API; zero config)
gpu deploy faster-whisper --tier on_demand --ssh-key-id <key-id>

# Stable Diffusion WebUI (A1111) — extra webui flags via A1111_ARGS
gpu deploy automatic1111 --env A1111_ARGS="--enable-insecure-extension-access"

# Pin a GPU type instead of auto-selecting
gpu deploy comfyui --type h100_sxm --ssh-key-id <key-id>

# Don't wait — just submit and print operation_id
gpu deploy comfyui --wait-timeout 0

Options

      --env stringToString        Env override KEY=VALUE (may repeat); only user-overridable keys are accepted
  -h, --help                      help for deploy
      --name string               Optional instance name
      --region string             Region (e.g., us-east); empty = any
      --ssh-key-id strings        SSH key ID to inject (may repeat)
      --tier string               Tier: on_demand (spot capacity is currently unavailable sitewide) (default "on_demand")
  -t, --type string               GPU type ID override (e.g., h100_sxm); empty = auto-select cheapest eligible
      --wait-timeout duration     How long to poll the operation; 0 = don't poll, just print operation_id (default 10m0s)

Options inherited from parent commands

      --api-base string   API base URL (override with GPUAI_API_BASE env) (default "https://api.gpu.ai/v1")
      --debug             Enable debug logging to stderr
  -o, --output string     Output format: table|json (default table on TTY, json otherwise)

Synopsis

Examples

Options

Options inherited from parent commands

SEE ALSO