diff --git a/agents.mdx b/agents.mdx new file mode 100644 index 0000000..bab62a7 --- /dev/null +++ b/agents.mdx @@ -0,0 +1,144 @@ +--- +title: "For AI Agents" +sidebarTitle: "AI Agent Guide" +description: "Bootstrap information for AI agents working with the Vast.ai platform — API key setup, SSH timing, VRAM units, onstart limits, and response format quirks." +--- + +This page documents the key facts that AI agents need to work with Vast.ai without burning +compute or hitting silent failures. It covers authentication, SSH key timing, VRAM units, +onstart limits, and response format quirks that are not obvious from the API surface alone. + +## Execute — Don't Plan + +When asked to perform Vast.ai tasks, use the CLI with `--raw` for machine-readable JSON output. +Fall back to the REST API only for operations the CLI doesn't expose. Do not deliver runbooks +or step-by-step guides unless the user explicitly asks for one. + +## Install CLI (if needed) + +```bash +pip install vastai +``` + +Platform caveats: +- **macOS**: use `pip3 install vastai` (or `python3 -m pip install vastai`) — `pip` may point to Python 2 or be missing +- **Linux (no venv)**: if `vastai` is not found after install, add `~/.local/bin` to your PATH, or run `python3 -m vastai` +- **Windows**: use `pip install vastai` in a standard terminal, or `py -m pip install vastai` if `pip` is not on PATH +- **Permission errors**: prefer `pip install --user vastai` over `sudo pip install` + +## Authentication + + +Before asking the user for an API key, check the standard location first: +```bash +cat ~/.vast_api_key +``` + + +API key locations (checked in order by the CLI): + +1. `$VAST_API_KEY` environment variable — highest priority +2. `~/.config/vastai/vast_api_key` — primary file (XDG-compliant) +3. `~/.vast_api_key` — legacy location (auto-migrated on first run) + +Set the key: +```bash +vastai set api-key YOUR_KEY +# or +export VAST_API_KEY=YOUR_KEY +``` + +## SSH Key Workflow (Critical) + + +**Register your SSH key before creating an instance.** Account-level SSH keys are applied +at container creation time. + +If you forgot: +- **Docker instance:** `POST /api/v0/instances/{id}/ssh/` with `{"ssh_key": "..."}` — no destroy needed +- **VM instance:** destroy and recreate (keys cannot be added after VM creation) + + +Register via CLI: +```bash +vastai create ssh-key ~/.ssh/id_ed25519.pub +``` + +Register via REST: +```bash +curl -s -H "Authorization: Bearer $VAST_API_KEY" \ + -H "Content-Type: application/json" \ + -X POST \ + -d '{"ssh_key": "ssh-ed25519 AAAA... user@host"}' \ + "https://console.vast.ai/api/v0/ssh/" +``` + +Your key persists on your account — register once per key, not once per instance. + +## GPU Search — VRAM Units + + +`gpu_ram` means different things in the CLI vs REST API: + + +| Interface | Field | Unit | Example (48 GB) | +|-----------|-------|------|-----------------| +| CLI (`vastai search offers`) | `gpu_ram` | **GB** | `gpu_ram>=48` | +| REST API (`POST /api/v0/bundles/`) | `gpu_ram` | **MB** | `{"gte": 49152}` | + +The CLI converts gigabytes to megabytes automatically before sending to the API. + +## Onstart Script Limit + +The `onstart` field is limited to **4048 characters**. For longer scripts, gzip and base64 encode: + +```bash +onstart_b64=$(gzip -c setup.sh | base64 -w0) +onstart_cmd="echo $onstart_b64 | base64 -d | gunzip | bash" +``` + +Pass `onstart_cmd` as the `onstart` value when creating the instance. + +## Instance Response Format + +`GET /api/v0/instances/` (list all) returns an **object keyed by instance ID**, not an array: + +```json +{ + "instances": { + "12345678": {"actual_status": "running", "ssh_host": "...", "ssh_port": 12345}, + "87654321": {"actual_status": "loading", ...} + } +} +``` + +`GET /api/v0/instances/{id}/` (single instance) returns `{"instances": }` where +`instances` is a single object, not a dict of dicts. + +## User ID Pattern + +`PUT /users/me/` returns "Invalid user ID format" — it is not supported. Correct flow: + +1. `GET /api/v0/users/current/` → extract the numeric `"id"` field +2. `PUT /api/v0/users/{id}/` with your payload + +## Recommended Docker Images + +| Use case | Image | +|----------|-------| +| PyTorch (general) | `pytorch/pytorch:2.4.0-cuda12.4-cudnn9-runtime` | +| Fine-tuning (Axolotl) | `winglian/axolotl:main-latest` | +| Image generation (ComfyUI) | `vastai/comfyui:latest` | + + +`diffusers` on the PyTorch 2.4 base image requires version pins: +`pip install diffusers==0.26.3 huggingface_hub==0.22.2` + + +## Billing / Spending + +```bash +vastai show invoices +``` + +REST: `GET /api/v0/users/me/charges/` with `Authorization: Bearer $VAST_API_KEY` diff --git a/api-reference/authentication.mdx b/api-reference/authentication.mdx new file mode 100644 index 0000000..08a3d66 --- /dev/null +++ b/api-reference/authentication.mdx @@ -0,0 +1,97 @@ +--- +title: "Authentication" +sidebarTitle: "Authentication" +--- + +Every request to the Vast.ai API must include an API key. This page covers how to create keys, how to include them in requests, and key lifecycle details. + +## Create an API Key + +Generate a key from the [Keys page](https://cloud.vast.ai/cli/keys/) in the web console: + +1. Click **+New**. +2. Give the key a name (optional but recommended — e.g. "CI pipeline" or "notebook"). +3. Copy the key immediately — you'll only see it once. + + +You can also create keys programmatically via the API ([Create API Key](/api-reference/accounts/create-api-key)), CLI ([`vastai create api-key`](/cli/reference/create-api-key)), or SDK ([`vast.create_api_key()`](/sdk/python/reference/create-api-key)). + + +## Use an API Key + +Include your key as a Bearer token in the `Authorization` header: + + +```bash cURL +curl -s -H "Authorization: Bearer $VAST_API_KEY" \ + "https://console.vast.ai/api/v0/users/current/" +``` + +```python Python +import os +import requests + +headers = {"Authorization": f"Bearer {os.environ['VAST_API_KEY']}"} +resp = requests.get("https://console.vast.ai/api/v0/users/current/", headers=headers) +print(resp.json()) +``` + + +A common pattern is to store your key in an environment variable: + +```bash +export VAST_API_KEY="your-api-key-here" +``` + +This keeps the key out of your code and makes it easy to rotate. + + +If you get a `401 Unauthorized` or `403 Forbidden` response, double-check your API key. The most common causes are a typo, an expired key, or a scoped key that lacks the required permission for the endpoint you're calling. + + +## Verify Your Key + +A quick way to confirm your key works is to fetch your account info: + +```bash +curl -s -H "Authorization: Bearer $VAST_API_KEY" \ + "https://console.vast.ai/api/v0/users/current/" +``` + +A successful response includes your user ID, email, balance, and SSH key: + +```json +{ + "id": 123456, + "email": "you@example.com", + "credit": 25.00, + "ssh_key": "ssh-rsa AAAAB3..." +} +``` + +## Scoped Keys and Permissions + +By default, the web console creates a **full-access** key. For CI/CD pipelines, shared tooling, or team environments, you should create **scoped keys** that restrict access to only the permissions you need. + +For example, a key that can only read and manage instances (but cannot access billing): + +```json +{ + "api": { + "misc": {}, + "user_read": {}, + "instance_read": {}, + "instance_write": {} + } +} +``` + +See the [Permissions](/api-reference/permissions) page for the full list of permission categories, endpoint mappings, constraint syntax, and advanced examples. + +## Key Expiration + +API keys do not expire by default. You can revoke a key at any time from the [Keys page](https://cloud.vast.ai/cli/keys/) or by calling the [Delete API Key](/api-reference/accounts/delete-api-key) endpoint. + + +Treat your API key like a password. Do not commit keys to version control or share them in plaintext. If a key is compromised, revoke it immediately and create a new one. + diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx index 26c7e84..0dcad5b 100644 --- a/api-reference/introduction.mdx +++ b/api-reference/introduction.mdx @@ -1,9 +1,186 @@ --- -title: "API Introduction" +title: "API Hello World" +sidebarTitle: "API Hello World" --- -**The raw REST API is intended for advanced users only.** These endpoints offer maximum flexibility but require you to manage all aspects of integration yourself. Most users will have a significantly better experience using the [CLI](/cli/get-started) or the [Python SDK](/sdk/python/quickstart), which handle these details for you. **If you are not sure whether you need direct API access, you almost certainly don't** — start with the CLI or SDK instead. + The raw REST API is intended for advanced users only. These endpoints offer maximum flexibility but require you to manage all aspects of integration yourself. Most users will have a significantly better experience using the [CLI](/cli/hello-world) or the [Python SDK](/sdk/python/quickstart), which handle these details for you. If you are not sure whether you need direct API access, you almost certainly don't — start with the CLI or SDK instead. -Welcome to Vast.ai's API documentation. Our API allows you to programmatically manage GPU instances, handle machine operations, and automate your AI/ML workflow. Whether you're running individual GPU instances or managing a fleet of machines, our API provides comprehensive control over all Vast.ai platform features. \ No newline at end of file +The Vast.ai REST API gives you programmatic control over GPU instances — useful for automation, CI/CD pipelines, or building your own tooling on top of Vast. + +This guide walks through the complete instance lifecycle: authenticate, search for a GPU, rent it, wait for it to boot, connect to it, and clean up. By the end you'll understand the core API calls needed to manage instances without touching the web console. + +## Prerequisites + +- A Vast.ai account with credit (~$0.01–0.05, depending on test instance run time) +- `curl` installed + +## 1. Get Your API Key + +Generate an API key from the [Keys page](https://cloud.vast.ai/cli/keys/) by clicking **+New**. Copy the key — you'll need it for your API calls, and you'll only see it once. + +Export it as an environment variable: + +```bash +export VAST_API_KEY="your-api-key-here" +``` + +## 2. Verify Authentication + +Confirm your key works by listing your current instances. If you have none, this returns an empty list. + +```bash +curl -s -H "Authorization: Bearer $VAST_API_KEY" \ + "https://console.vast.ai/api/v0/instances/" +``` + +```json +{ + "instances_found": 0, + "instances": [] +} +``` + + +If you get a `401` or `403`, double-check your API key. If you already have instances, you'll see them listed here. + + +## 3. Search for GPUs + +Find available machines using the bundles endpoint. This query returns the top 5 on-demand RTX 4090s sorted by deep learning performance benchmarked per dollar: + +```bash +curl -s -H "Authorization: Bearer $VAST_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "verified": {"eq": true}, + "rentable": {"eq": true}, + "gpu_name": {"eq": "RTX 4090"}, + "num_gpus": {"eq": 1}, + "direct_port_count": {"gte": 1}, + "order": [["dlperf_per_dphtotal", "desc"]], + "type": "on-demand", + "limit": 5 + }' \ + "https://console.vast.ai/api/v0/bundles/" +``` + +Each parameter in the query above controls a different filter: + +| Parameter | Value | Meaning | +|-----------|-------|---------| +| `verified` | `{"eq": true}` | Only machines verified by Vast.ai (identity-checked hosts) | +| `rentable` | `{"eq": true}` | Only machines currently available to rent | +| `gpu_name` | `{"eq": "RTX 4090"}` | Filter to a specific GPU model | +| `num_gpus` | `{"eq": 1}` | Exactly 1 GPU per instance | +| `direct_port_count` | `{"gte": 1}` | At least 1 directly accessible port (needed for SSH) | +| `order` | `[["dlperf_per_dphtotal", "desc"]]` | Sort by deep learning performance per dollar, best value first | +| `type` | `"on-demand"` | On-demand pricing (vs. interruptible spot/bid) | +| `limit` | `5` | Return at most 5 results | + +The response contains an `offers` array. Note the `id` of the offer you want — you'll use it in the next step. If no offers are returned, try relaxing your filters (e.g. a different GPU model or removing `direct_port_count`). + + +See the [Search Offers](/api-reference/search/search-offers) reference for the full list of filter parameters and operators. + + +## 4. Create an Instance + +Rent the machine by sending a PUT request with your Docker image and disk size. Replace `OFFER_ID` with the `id` from step 3. `disk` is in GB and specifies the size of the disk on your new instance. + +```bash +curl -s -H "Authorization: Bearer $VAST_API_KEY" \ + -H "Content-Type: application/json" \ + -X PUT \ + -d '{ + "image": "pytorch/pytorch:2.4.0-cuda12.4-cudnn9-runtime", + "disk": 20, + "onstart": "echo hello && nvidia-smi" + }' \ + "https://console.vast.ai/api/v0/asks/OFFER_ID/" +``` + +```json +{ + "success": true, + "new_contract": 12345678, + "instance_api_key": "d15a..." +} +``` + +Save the `new_contract` value — this is your instance ID. The `instance_api_key` is a restricted key injected into the container as `CONTAINER_API_KEY` — it can only start, stop, or destroy that specific instance. + +## 5. Wait Until Ready + +The instance needs time to pull the Docker image and boot. Poll the status endpoint until `actual_status` is `"running"`. Replace `INSTANCE_ID` with the `new_contract` value from step 4. + +```bash +curl -s -H "Authorization: Bearer $VAST_API_KEY" \ + "https://console.vast.ai/api/v0/instances/INSTANCE_ID/" +``` + +Example response: + +```json +{ + "instances": { + "actual_status": "loading", + "ssh_host": "...", + "ssh_port": 12345 + } +} +``` + +The `actual_status` field progresses through these states: + +| `actual_status` | Meaning | +|-----------------|---------| +| `null` | Instance is being provisioned | +| `"loading"` | Docker image is downloading | +| `"running"` | Ready to use | + +Poll every 10 seconds. Boot time is typically 1–5 minutes depending on the Docker image size. You can also use the `onstart` script to send a callback when the instance is ready, instead of polling. + +Once `actual_status` is `"running"`, you're ready to connect. + +## 6. Connect via SSH + +Use the `ssh_host` and `ssh_port` from the status response to connect directly to your new instance: + +```bash +ssh root@SSH_HOST -p SSH_PORT +``` + +## 7. Clean Up + +When you're done, destroy the instance to stop all billing. + +Alternatively, to pause an instance temporarily instead of destroying it, you can **stop** it. Stopping halts compute billing but disk storage charges continue. + +**Destroy** (removes everything): + +```bash +curl -s -H "Authorization: Bearer $VAST_API_KEY" \ + -X DELETE \ + "https://console.vast.ai/api/v0/instances/INSTANCE_ID/" +``` + +**Stop** (pauses compute, disk charges continue): + +```bash +curl -s -H "Authorization: Bearer $VAST_API_KEY" \ + -H "Content-Type: application/json" \ + -X PUT \ + -d '{"state": "stopped"}' \ + "https://console.vast.ai/api/v0/instances/INSTANCE_ID/" +``` + +Both return `{"success": true}`. + +## Next Steps + +You've now completed the full instance lifecycle through the API: authentication, search, creation, polling, and teardown. From here: + +- **SSH setup** — See the [SSH guide](/documentation/instances/connect/ssh) for key configuration and advanced connection options. +- **Use templates** — Avoid repeating image and config parameters on every create call. The [Templates API guide](/api-reference/creating-and-using-templates-with-api) covers creating, sharing, and launching from templates. diff --git a/api-reference/permissions.mdx b/api-reference/permissions.mdx new file mode 100644 index 0000000..1c08e4b --- /dev/null +++ b/api-reference/permissions.mdx @@ -0,0 +1,238 @@ +--- +title: "Permissions" +sidebarTitle: "Permissions" +--- + +Every API key has a set of permissions that control which endpoints it can access. This page is the comprehensive reference for permission categories, how they map to API routes, and how to build custom scoped keys. + +For an overview of API key creation and usage, see [Authentication](/api-reference/authentication). + +## Permission Categories + +Permissions are organized into categories. When you create a scoped API key, you include only the categories the key needs. The available categories are: + +| Category | Controls | +|----------|----------| +| `instance_read` | Viewing instances, logs, SSH keys, volumes, deposits | +| `instance_write` | Creating, managing, and destroying instances and volumes | +| `user_read` | Viewing account info, API keys, SSH keys, environment variables, templates | +| `user_write` | Creating/modifying API keys, SSH keys, environment variables, templates, teams | +| `billing_read` | Viewing invoices and earnings | +| `billing_write` | Transferring credit | +| `machine_read` | Viewing machines and reports (hosts) | +| `machine_write` | Managing machines, maintenance, listing/unlisting (hosts) | +| `misc` | Search offers, benchmarks, network volumes, serverless endpoints | +| `team_read` | Viewing team members and roles | +| `team_write` | Inviting/removing team members, managing roles | + +## Creating Scoped Keys + +Define permissions as a JSON object and pass it when creating a key. The top-level key is always `"api"`, containing the categories you want to grant. + +**Example — Instance management with billing access:** + +```json +{ + "api": { + "misc": {}, + "user_read": {}, + "instance_read": {}, + "instance_write": {}, + "billing_read": {}, + "billing_write": {} + } +} +``` + +**Example — Instance management without billing:** + +```json +{ + "api": { + "misc": {}, + "user_read": {}, + "instance_read": {}, + "instance_write": {} + } +} +``` + +You can create scoped keys using: +- **API**: [Create API Key](/api-reference/accounts/create-api-key) +- **CLI**: [`vastai create api-key`](/cli/reference/create-api-key) +- **SDK**: [`vast.create_api_key()`](/sdk/python/reference/create-api-key) + +## Custom Roles + +Custom roles let you assign the same set of permissions to multiple team members. + +- **Creating roles**: Use the CLI or the Manage page in the web console (requires `team_write` access). +- **Defining permissions**: Select from any combination of the categories listed above. +- **Assigning roles**: Assign created roles to team members through the team management interface or CLI. + +## Constraints + +Constraints narrow a permission category to specific parameter values. This lets you create keys that can only operate on certain resources. + +**Example — Read logs for a single instance only:** + +```json +{ + "api": { + "instance_read": { + "api.instance.request_logs": { + "constraints": { + "id": { + "eq": 1227 + } + } + } + } + } +} +``` + +**Example — Read logs for a range of instance IDs:** + +```json +{ + "api": { + "instance_read": { + "api.instance.request_logs": { + "constraints": { + "id": { + "lte": 2, + "gte": 1 + } + } + } + } + } +} +``` + +Supported constraint operators: `eq`, `lte`, `gte`. + + +API keys using constraints must be created via the CLI ([`vastai create api-key`](/cli/reference/create-api-key)) or the API ([Create API Key](/api-reference/accounts/create-api-key)). + + +You can also use **wildcards** in `params` to represent placeholder values — useful when generating many keys that perform similar operations. + +## Endpoint Reference by Category + +Below is the complete mapping of which endpoints each permission category controls. + +### instance\_read + +- [Show Instance](/api-reference/instances/show-instance) +- [Show Instances](/api-reference/instances/show-instances) +- [Show Logs](/api-reference/instances/show-logs) +- [Show SSH Keys](/api-reference/instances/show-ssh-keys) +- [Show Volumes](/api-reference/volumes/list-volumes) +- [Show Deposit](/api-reference/billing/show-deposit) + +### instance\_write + +- [Attach SSH Key](/api-reference/instances/attach-ssh-key) +- [Copy](/api-reference/instances/copy) +- [Cancel Copy](/api-reference/instances/cancel-copy) +- [Cloud Copy](/api-reference/instances/cloud-copy) +- [Cancel Sync](/api-reference/instances/cancel-sync) +- [Change Bid](/api-reference/instances/change-bid) +- [Create Instance](/api-reference/instances/create-instance) +- [Manage Instance](/api-reference/instances/manage-instance) +- [Delete Instance](/api-reference/instances/destroy-instance) +- [Detach SSH Key](/api-reference/instances/detach-ssh-key) +- [Execute](/api-reference/instances/execute) +- [Prepay Instance](/api-reference/instances/prepay-instance) +- [Reboot Instance](/api-reference/instances/reboot-instance) +- [Recycle Instance](/api-reference/instances/recycle-instance) +- [Create Volume](/api-reference/volumes/rent-volume) +- [Delete Volume](/api-reference/volumes/delete-volume) + +### user\_read + +- [Show API Keys](/api-reference/accounts/show-api-keys) +- [Show Connections](/api-reference/accounts/show-connections) +- [Show Environment Variables](/api-reference/accounts/show-env-vars) +- [Show IP Addresses](/api-reference/accounts/show-ipaddrs) +- [Show SSH Keys](/api-reference/accounts/show-ssh-keys) +- [Show Subaccounts](/api-reference/accounts/show-subaccounts) +- [Show User](/api-reference/accounts/show-user) +- [Search Templates](/api-reference/search/search-template) + +### user\_write + +- [Create API Key](/api-reference/accounts/create-api-key) +- [Delete API Key](/api-reference/accounts/delete-api-key) +- [Create Environment Variable](/api-reference/accounts/create-env-var) +- [Update Environment Variable](/api-reference/accounts/update-env-var) +- [Delete Environment Variable](/api-reference/accounts/delete-env-var) +- [Create SSH Key](/api-reference/accounts/create-ssh-key) +- [Update SSH Key](/api-reference/accounts/update-ssh-key) +- [Delete SSH Key](/api-reference/accounts/delete-ssh-key) +- [Create Subaccount](/api-reference/accounts/create-subaccount) +- [Set User](/api-reference/accounts/set-user) +- [Create Team](/api-reference/team/create-team) +- [Delete Team](/api-reference/team/destroy-team) +- [Create Template](/api-reference/templates/create-template) +- [Edit Template](/api-reference/templates/edit-template) +- [Delete Template](/api-reference/templates/delete-template) + +### billing\_read + +- [Search Invoices](/api-reference/billing/search-invoices) +- [Show Invoices](/api-reference/billing/show-invoices) +- [Show Earnings](/api-reference/billing/show-earnings) + +### billing\_write + +- [Transfer Credit](/api-reference/accounts/transfer-credit) + +### machine\_read + +- [Show Machines](/api-reference/machines/show-machines) +- [Show Reports](/api-reference/machines/show-reports) + +### machine\_write + +- [Cancel Maintenance](/api-reference/machines/cancel-maint) +- [Cleanup Machine](/api-reference/machines/cleanup-machine) +- [List Machine](/api-reference/machines/list-machine) +- [Remove Default Job](/api-reference/machines/remove-defjob) +- [Schedule Maintenance](/api-reference/machines/schedule-maint) +- [Set Default Job](/api-reference/machines/set-defjob) +- [Set Minimum Bid](/api-reference/machines/set-min-bid) +- [Unlist Machine](/api-reference/machines/unlist-machine) +- [Add Network Disk](/api-reference/network-volumes/add-network-disk) +- [Unlist Network Volume](/api-reference/network-volumes/unlist-network-volume) +- [Unlist Volume](/api-reference/volumes/unlist-volume) + +### misc + +- [Search Network Volumes](/api-reference/network-volumes/search-network-volumes) +- [Show Workergroups](/api-reference/serverless/show-workergroup) +- [Create Workergroup](/api-reference/serverless/create-workergroup) +- [Update Workergroup](/api-reference/serverless/update-workergroup) +- [Delete Workergroup](/api-reference/serverless/delete-workergroup) +- [Show Endpoints](/api-reference/serverless/show-endpoints) +- [Create Endpoint](/api-reference/serverless/create-endpoint) +- [Delete Endpoint](/api-reference/serverless/delete-endpoint) +- [Search Benchmarks](/api-reference/search/search-benchmarks) +- [Search Offers](/api-reference/search/search-offers) +- [Search Volumes](/api-reference/volumes/search-volumes) + +### team\_read + +- [Show Team Members](/api-reference/team/show-team-members) +- [Show Team Role](/api-reference/team/show-team-role) +- [Show Team Roles](/api-reference/team/show-team-roles) + +### team\_write + +- [Invite Team Member](/api-reference/team/invite-team-member) +- [Remove Team Member](/api-reference/team/remove-team-member) +- [Create Team Role](/api-reference/team/create-team-role) +- [Update Team Role](/api-reference/team/update-team-role) +- [Remove Team Role](/api-reference/team/remove-team-role) diff --git a/cli/authentication.mdx b/cli/authentication.mdx new file mode 100644 index 0000000..bfa8efc --- /dev/null +++ b/cli/authentication.mdx @@ -0,0 +1,103 @@ +--- +title: "CLI Authentication" +sidebarTitle: "Authentication" +--- + +Every request to the Vast.ai API requires an API key. The CLI stores your key locally and includes it automatically in every command. This page covers how to set up, verify, and manage API keys through the CLI. + +## Set Your API Key + +After creating a key from the [Keys page](https://cloud.vast.ai/cli/keys/), store it locally: + +```bash +vastai set api-key YOUR_API_KEY +``` + +This writes the key to `~/.config/vastai/vast_api_key` (or `$XDG_CONFIG_HOME/vastai/vast_api_key` if that env var is set). All subsequent commands use it automatically. + +## Environment Variable (CI/CD) + +Instead of storing the key in a file, you can set it as an environment variable: + +```bash +export VAST_API_KEY="your_api_key_here" +``` + +This is recommended for CI pipelines, Docker containers, and scripts — it avoids writing keys to +disk and makes it easy to inject secrets via your platform's secret manager. The environment +variable takes precedence over the file if both are set. + + +If you previously used an older version of the CLI, your key may be at the legacy location +`~/.vast_api_key`. The CLI migrates it automatically to `~/.config/vastai/vast_api_key` on next +run, so no manual action is needed. + + +## Verify Your Key + +Confirm your key works by fetching your account info: + +```bash +vastai show user +``` + +A successful response includes your user ID, email, and balance: + +```json +{ + "id": 123456, + "email": "you@example.com", + "credit": 25.00, + "ssh_key": "ssh-rsa AAAAB3..." +} +``` + + +If you get an authentication error, double-check your API key. The most common causes are a typo, an expired key, or a scoped key that lacks the required permission for the command you're running. + + +## Create an API Key + +You can create new keys from the CLI: + +```bash +vastai create api-key --name "ci-deploy-key" +``` + +The output includes the new key value. Copy it immediately -- you will not be able to retrieve it again. + +To create a key with restricted permissions, pass a JSON permissions file: + +```bash +vastai create api-key --name "ci-deploy-key" --permission_file perms.json +``` + +See the [Permissions](/cli/permissions) page for the full permissions file format and examples. + +## View and Delete Keys + +List all API keys on your account: + +```bash +vastai show api-keys +``` + +View a specific key's details by ID: + +```bash +vastai show api-key 42 +``` + +Delete a key: + +```bash +vastai delete api-key 42 +``` + +## Key Expiration + +API keys do not expire by default. You can revoke a key at any time from the [Keys page](https://cloud.vast.ai/cli/keys/) or with `vastai delete api-key`. + + +Treat your API key like a password. Do not commit keys to version control or share them in plaintext. If a key is compromised, revoke it immediately and create a new one. + diff --git a/cli/commands.mdx b/cli/commands.mdx deleted file mode 100644 index 473d831..0000000 --- a/cli/commands.mdx +++ /dev/null @@ -1,2097 +0,0 @@ ---- -title: Commands -createdAt: Mon Jan 13 2025 21:20:40 GMT+0000 (Coordinated Universal Time) -updatedAt: Sat Jul 12 2025 01:09:10 GMT+0000 (Coordinated Universal Time) ---- - -