vastai-install-auth

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

Resources

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