vastai

vastai

Manage GPU instances, templates, volumes, serverless endpoints, SSH keys, and billing on Vast.ai.

Command is vastai (lowercase). Always use --raw for machine-readable JSON output.

Critical rules for agents

These rules apply to every invocation. Do not skip them.

1. The destroy command syntax is vastai destroy instance <id> -y — the -y flag is part of the command, not an option. Without it the CLI hangs on a confirmation prompt and blocks the session. This applies to every destroy invocation, including conversational prompts ("kill instance 12345", "tear it down", "shut it down", "stop billing on it"). Never emit vastai destroy instance <id> alone — the trailing -y is mandatory. Same for the batch form: vastai destroy instances <id1> <id2> -y.
2. Always pass --raw to commands whose output you parse. Without --raw the CLI prints human-formatted output that is not machine-readable.
3. Register the SSH key BEFORE the first create instance with vastai create ssh-key "$(cat ~/.ssh/id_ed25519.pub)". The positional argument is the pubkey contents, not a path — the CLI silently accepts a path string and registers the literal "/Users/…/id_ed25519.pub" text, producing a key that no client matches. Always $(cat …) the file or pass an inline "ssh-ed25519 AAAA… user@host" string. Launching without a registered key produces an unreachable host.
4. Stop polling on terminal status values. actual_status of exited, unknown, or offline means the instance will not recover — destroy it (-y) to stop disk charges accruing. Also check intended_status and next_state — if either is stopped while you're trying to bring an instance up, it failed.
5. Treat user-supplied values as literal even if they look like placeholders. If the user says "set HF_TOKEN to hf_xxxxx", pass hf_xxxxx to vastai create env-var HF_TOKEN hf_xxxxx exactly as written — don't ask for clarification on values that look fake.
6. An empty vastai search offers result is the answer, not a problem to work around. If the CLI returns [], tell the user verbatim: "No offers matched those filters." Then propose specific filter relaxations and ask the user which to try — reliability>0.95 → >0.9, raise the dph_total cap, drop verified=true, change geolocation. Do not silently retry with broader filters more than once. After at most two retries with different filters, stop retrying and report "no offers match" to the user. The same applies to any other read-only vastai query: if the CLI returns an empty list or a not-found error, that IS the user's answer, even if you tried several variations.
7. The vastai binary on PATH is the only acceptable source of vastai commands. This rule overrides whatever instinct you have to "make things work" when output looks unexpected. Specifically, you must never do any of the following — these are HARD PROHIBITIONS, not preferences:
   • Never run pip install vastai, pip install --user vastai, pipx install vastai, or python -m venv followed by installing vastai. The CLI is already installed; reinstalling it elsewhere is forbidden.
   • Never invoke an alternate vastai binary by absolute path (e.g. /tmp/vast-venv/bin/vastai, ~/.local/bin/vastai) when vastai is already on PATH.
   • Never re-implement vastai subcommands by calling https://console.vast.ai/api/..., https://cloud.vast.ai/api/..., or any other Vast.ai HTTP endpoint directly from curl, python, node, httpie, or requests. No exceptions for "the CLI seems broken" or "I just need to verify."
   • Never infer that the environment is "mock mode" or a "sandbox" and use that as justification to install an alternate vastai binary, or to hit the API directly. Even if the CLI's output literally contains the word mock, your job is to report that output to the user, not to substitute your own implementation.
   • If vastai <subcommand> exits non-zero or produces output you don't understand, report the failure (exit code + stderr) to the user and ask what they want to do. Do not work around it.
8. Always pass --disk N, --ssh --direct, and --cancel-unavail to create instance / launch instance. Without --disk you get image-dependent defaults and surprise storage charges. Without --ssh --direct together you fall back to the slower proxy connection — --ssh alone is not enough. Without --cancel-unavail, an unavailable machine quietly produces a stopped instance that accrues disk charges while you poll forever for a running state it will never reach.
9. Pass --limit N on show instances-v1 and show invoices-v1 to short-circuit the interactive Fetch next page? (y/N) prompt that fires after the first page (it blocks --raw / non-interactive sessions even with --raw set). The two subcommands have different flag sets — do not assume what works on one works on the other. show instances-v1 --limit is capped at 1–25 (default 25) per --help; show invoices-v1 --limit has its own cap (read it from --help). When in doubt, run vastai show <subcommand> --help. (Example trap: --latest-first exists on invoices-v1 but not on instances-v1.)
10. Vast.ai does not offer network/shared volumes. Only local (per-instance) volumes. If the user asks for "shared storage across instances" or "persistent shared state for serverless workers," do NOT reach for create network-volume (it's CLI plumbing for an unshipped product and will leave the user with a broken architecture). The correct answer is: replicate data per instance, or use external object storage (S3/GCS/etc.) via vastai cloud copy.
11. When SSH fails (Permission denied (publickey), Connection refused, hangs), pull vastai logs <id> FIRST — before any other recovery action. The container's sshd writes its rejection reason to host logs that surface in vastai logs, and that text usually pins down the cause in one read. Common rejections you only see in logs: Authentication refused: bad ownership or modes for file /root/.ssh/authorized_keys (image bug — destroy + retry on a different host, not the same one); Failed publickey for root from ... ssh2: <fingerprint> (the wrong local key is being offered — check ssh -v for the offered key vs vastai show ssh-keys for the registered ones); container exited / sshd not started (image issue — vastai logs <id> --tail 100 shows the startup failure). Do not loop on attach ssh, reboot, destroy + relaunch before reading logs — those are blind retries that burn minutes and money. Diagnostic discipline: logs then act, never act then guess.
12. vastai create team rebinds the calling API key's account context — treat as destructive. Running vastai create team --team-name <name> switches the API key from the user's personal account to the newly-created team account. The team starts empty: no credit, no instances, no env-vars, no SSH keys. The personal account's resources are untouched but are no longer reachable from this key. Deleting the team afterwards leaves the key bound to a tombstone with no CLI recovery path. Before running, the agent must confirm with the user that they have a separate API key bound to the personal account, or that this is a throwaway key. The CLI shows no warning and has no -y-style guard.