Vastkit

Vastkit

Use the Vastkit runtime bundled with this plugin as the execution layer. Apply the workflow and guardrails below; do not install a separate Vastkit package or recreate Vast.ai API requests in ad hoc scripts.

Resolve the CLI

Resolve <skill-dir> to the directory containing this SKILL.md. In Claude Code, ${CLAUDE_SKILL_DIR} is that directory. In other agents, use the skill path shown by the host.

VK="<skill-dir>/scripts/vastkit-cli"
"$VK" --version

The launcher resolves the Python package from the installed plugin. If the version check reports that the runtime is missing, stop and ask the user to update or reinstall the plugin through their agent. Do not use pip as a fallback.

Require Python 3.9+, internet access, ssh, and tar. Prefer rsync when available; Vastkit falls back to tar transfers when the remote image lacks it.

Protect Credentials

• Use VAST_API_KEY or ~/.vast_api_key. Never put an API key in a command, pass --api-key, print it, commit it, or ask the user to paste it into chat.
• Let Vastkit auto-detect an SSH key, or use VASTKIT_SSH_KEY. Never print or transfer private keys.
• Do not upload .env files or credential directories. Vastkit excludes common environment files by default; add explicit exclusions for any project-specific secret paths.
• Pass remote secrets only by referencing an already-exported local variable, for example --env HF_TOKEN="$HF_TOKEN". Never place a literal token in the command or response.

If authentication is not configured, stop and ask the user to configure it locally using the Vast.ai API key page. Continue only after they confirm.

Apply Spending Guardrails

Run read-only discovery commands without approval: whoami, search, ls, status, jobs, and logs.

Before rent or start, obtain explicit user approval for the cost-bearing action. A prior request counts only when it clearly authorizes renting or resuming. State:

• GPU and minimum VRAM
• maximum hourly price
• disk allocation and image
• expected duration and download volume
• estimated session cost and any known excluded costs
• instance label
• whether to destroy automatically after verified output retrieval

Always include --max-price on agent-selected rentals. Treat est_session_cost as an estimate, not a guaranteed bill. Use --yes only after approval, and only for the approved limits.

Before stop, destroy, push --delete, or replacing remote data, confirm that the exact instance or data is authorized unless the user's request already said to perform that action. Never use destroy --all unless the user explicitly requested every matching instance be destroyed.

Stopping releases the GPU but storage remains billed. Destroying is irreversible and is the action that ends instance billing.

Run the Workflow

1. Establish Requirements

Inspect the workload before choosing hardware. Determine the minimum VRAM, GPU count, CUDA compatibility, disk space, image, approximate runtime, model or dataset download size, local project path, remote command, outputs to retrieve, and cleanup policy. Infer technical values from the project when reliable; ask about missing financial limits or destructive cleanup intent.

2. Preflight the Account

"$VK" whoami --json
"$VK" ls --json

Check for an existing suitable instance before creating another. Do not reuse, stop, or destroy an existing instance without user authorization. For all automation, use explicit instance IDs even when Vastkit could infer the only instance.

3. Search and Explain the Choice

Use realistic session assumptions so bandwidth-heavy hosts rank honestly:

"$VK" search \
  --gpu "L40S" --gpu "RTX 6000Ada" \
  --vram 45 --disk 80 --max-price 1.00 \
  --hours 2 --download-gb 40 --max-bw 10 \
  --reliability 0.95 --json

Read the structured results. Prefer the lowest effective session cost that meets the workload, not merely the lowest hourly price. Present the chosen offer's GPU, VRAM, location, reliability, hourly price, bandwidth price, and estimated session cost before requesting approval.

Avoid rent --offer for agent-selected machines because it bypasses the search filters. Use it only when the user selected a current offer and approved its current price.

4. Rent Within the Approved Limits

Repeat the approved search constraints in rent, choose a distinctive safe label, and request JSON output:

"$VK" rent \
  --gpu "L40S" --gpu "RTX 6000Ada" \
  --vram 45 --disk 80 --max-price 1.00 \
  --hours 2 --download-gb 40 --max-bw 10 \
  --reliability 0.95 --label agent-training \
  --attempts 3 --boot-timeout 600 --yes --json

Record the returned instance ID immediately and use it in every later command. Tell the user when billing starts, including the ID and hourly rate.

5. Transfer and Execute

Push only required inputs. The default excludes cover .git, virtual environments, caches, and .env files. Additional --exclude flags extend those defaults.

"$VK" push "$ID" ./project /workspace/project \
  --exclude outputs --exclude checkpoints

"$VK" exec "$ID" --cwd /workspace/project -- \
  'python -m pip install -r requirements.txt && python prepare.py'

"$VK" exec "$ID" --detach --job training --cwd /workspace/project -- \
  python train.py --output /workspace/project/outputs

Use job names containing only letters, digits, dots, underscores, and hyphens. Use a detached job for long work so it survives connection loss. Quote a compound remote shell command as one argument after --.

Monitor without starting duplicate work:

"$VK" jobs "$ID" --json
"$VK" logs "$ID" --job training -f

logs -f returns the detached job's exit code. Treat a nonzero code as a workload failure and inspect the log before retrying.

6. Retrieve and Verify Outputs

Pull results before any destructive cleanup:

"$VK" pull "$ID" /workspace/project/outputs/ ./outputs/

Verify locally that expected files exist, are non-empty, and are usable. Do not destroy the instance merely because a transfer command returned zero when the expected artifacts are missing.

7. End Billing

When cleanup was approved and output verification succeeded:

"$VK" destroy "$ID" --yes
"$VK" ls --json

Verify that the exact ID is gone. Report the approximate accrued cost shown by Vastkit. If the user wants to keep the instance, report its ID, hourly rate, status, and the exact destroy command prominently.

Recover Safely

• If any command fails after a rental may have been created, run ls --json immediately and locate the distinctive label. Do this after interruptions during rent as well.
• Vastkit destroys boot attempts that time out, but verify account state after an interrupted process or a failed destroy request.
• If approved automatic cleanup applies, make a best-effort exact-ID destroy after a failed workload. Preserve outputs first when possible.
• If cleanup is not authorized or destruction fails, do not hide the state. Report the live instance ID, price, and dashboard/CLI cleanup action.
• Never finish a normal run while an active billed instance is unaccounted for.