---

name: vastai-install-auth description: >- Install the supported Vast.ai CLI and establish a least-privilege authentication boundary without leaking or persisting the wrong key. Use when bootstrapping a workstation, CI runner, or automation account. Trigger with: "install Vast.ai", "configure VAST_API_KEY", "create a scoped Vast.ai key". allowed-tools: Read, Grep, Write, Edit version: 2.0.0 argument-hint: '[workstation-or-ci-and-required-operations]' model: inherit effort: high license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• vastai
• authentication
• cli
• least-privilege compatibility: 'Requires a Vast.ai account, an approved secret store, and Linux, macOS, WSL, or Python 3.9+.'

---

Vast.ai CLI Authentication Boundary

Overview

Install from the provider-supported channel, choose file-backed versus environment-backed authentication by runtime, and prove that the key can perform only the intended operations. The current CLI migrates legacy key files into the XDG configuration location.

Prerequisites

• Named workload owner and classified workstation, CI, container, or service runtime
• Permission inventory covering search, instance, user, billing, machine, and team operations
• Approved secret store plus a rotation and revocation owner

Instructions

Step 1: Select the install channel

Use the managed installer on Linux, macOS, or WSL when an isolated runtime is desired. Use the vastai PyPI package for Windows or Python SDK work; record the installed version.

Step 2: Place the credential

For an interactive workstation, let vastai set api-key write ~/.config/vastai/vast_api_key or the corresponding XDG configuration path. For CI or containers, inject VAST_API_KEY; the environment value takes precedence and avoids a key file.

Step 3: Create least privilege

Build a permission file containing only the categories and endpoint constraints the workload needs, then create a named scoped key. Do not use a full-access console key for shared automation.

Step 4: Verify positive and negative paths

Run vastai show user --raw, one required operation, and one operation expected to be denied. Preserve only status, key ID, and permission evidence.

Step 5: Plan rotation

Create and verify the replacement before deleting the old key. Revoke immediately if a key, command trace, or artifact may have exposed its value.

Authentication

Every API request requires a key. Treat VAST_API_KEY, the XDG key file, and the legacy ~/.vast_api_key location as secrets; never print key values or copy them into receipts.

Tool Discipline

Use Read and Grep to inspect manifests, configuration, provider output, and existing tests before proposing a mutation. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not create, update, destroy, or fund Vast.ai resources without explicit operator approval.

Output

• Install channel and exact CLI/SDK version
• Scoped permission manifest with positive and expected-denial results
• Redacted rotation, revocation, and rollback receipt

Return runtime, install channel, key ID, granted categories, verification outcomes, and credential owner.

Examples

A CI deployer receives misc, user_read, instance_read, and instance_write without billing or team access; its key is injected as a masked environment secret and deleted after replacement validation.

Error Handling

Failure	Response
vastai show user returns 401	Stop retries; verify key source, precedence, revocation state, and account context.
Required command returns 403	Add only the missing documented category or endpoint constraint, then rerun the negative test.
CLI reads an unexpected legacy key	Inspect XDG precedence and migrate or revoke the stale credential.
Credential may be exposed	Revoke it, scrub artifacts, rotate dependent jobs, and document the incident.

Resources

• First-party source notes
• CLI authentication
• CLI permissions
• Official Vast.ai CLI