diff --git a/api-reference/authentication.mdx b/api-reference/authentication.mdx
new file mode 100644
index 0000000..722fa71
--- /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/manage-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/manage-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..3525d7b 100644
--- a/api-reference/introduction.mdx
+++ b/api-reference/introduction.mdx
@@ -1,9 +1,190 @@
---
-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/manage-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.
+
+
+Always handle non-happy-path statuses in your poll loop. If `actual_status` becomes `"exited"` (container crashed), `"unknown"` (no heartbeat from host), or `"offline"` (host disconnected), it will never reach `"running"`. Without a timeout or error check, your script will loop forever while the instance continues accruing disk charges. Destroy the instance and retry with a different offer if you see these states.
+
+
+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/openapi.json b/api-reference/openapi.json
index 5ccc126..3917e5d 100644
--- a/api-reference/openapi.json
+++ b/api-reference/openapi.json
@@ -21,119 +21,6 @@
}
],
"paths": {
- "/api/v0/network_disk/": {
- "post": {
- "summary": "add network-disk",
- "description": "Adds a network disk to be used to create network volume offers, or adds machines to an existing network disk.\n\nCLI Usage: `vastai add network_disk ... [options]`",
- "security": [
- {
- "BearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "required": [
- "mount_point"
- ],
- "properties": {
- "machine_id": {
- "type": "integer",
- "description": "ID of the machine to add network disk to"
- },
- "machine_ids": {
- "type": "array",
- "items": {
- "type": "integer"
- },
- "description": "IDs of machines to add network disk to"
- },
- "mount_point": {
- "type": "string",
- "description": "Path to mount point of networked storage on machine or machines"
- },
- "disk_id": {
- "type": "integer",
- "description": "ID of network disk, if adding machines to existing disk"
- }
- }
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "Successful response",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "success": {
- "type": "boolean"
- },
- "disk_id": {
- "type": "integer",
- "description": "ID of disk created or added to machines"
- }
- },
- "example": {
- "success": true,
- "disk_id": 2
- }
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "error": {
- "type": "string",
- "example": "invalid_args"
- },
- "msg": {
- "type": "string",
- "example": "Invalid machine id"
- }
- }
- }
- }
- }
- },
- "403": {
- "description": "Forbidden",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "error": {
- "type": "string",
- "example": "not_authorized"
- },
- "msg": {
- "type": "string",
- "example": "Only machine owner can add network disk"
- }
- }
- }
- }
- }
- }
- },
- "tags": [
- "Network Volumes"
- ]
- }
- },
"/api/v0/instances/{id}/ssh/": {
"post": {
"summary": "attach ssh-key",
@@ -2591,247 +2478,20 @@
"429": {
"description": "Too Many Requests",
"content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "detail": {
- "type": "string",
- "example": "API requests too frequent endpoint threshold=4.5"
- }
- }
- }
- }
- }
- }
- }
- }
- },
- "/api/v0/network_volume/": {
- "put": {
- "summary": "create network-volume",
- "description": "Creates a network volume from an offer.\n\nCLI Usage: `vastai create network-volume [--name ]`",
- "security": [
- {
- "BearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "required": [
- "id",
- "size"
- ],
- "properties": {
- "id": {
- "type": "integer",
- "description": "ID of network volume ask being accepted"
- },
- "size": {
- "type": "integer",
- "description": "size of network volume in GB being created"
- },
- "name": {
- "type": "string",
- "description": "optional name for network volume being created"
- }
- }
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "Successful response",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "success": {
- "type": "boolean"
- },
- "volume_name": {
- "type": "string",
- "description": "name of network volume created"
- },
- "volume_size": {
- "type": "integer",
- "description": "size of network volume created"
- }
- },
- "example": {
- "success": true,
- "id": 6,
- "msg": "Deleted network volume listing"
- }
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "error": {
- "type": "string",
- "example": "invalid_args"
- },
- "msg": {
- "type": "string",
- "example": "You must pass in `id` in the body of the request"
- }
- }
- }
- }
- }
- },
- "403": {
- "description": "Forbidden",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "error": {
- "type": "string",
- "example": "not_authorized"
- },
- "msg": {
- "type": "string",
- "example": "Authorization Error. Check that you have proper privileges to perform this action."
- }
- }
- }
- }
- }
- }
- },
- "tags": [
- "Network Volumes"
- ]
- },
- "post": {
- "summary": "list network-volume",
- "description": "Lists a network disk for rent as network volumes, or updates an existing listing with a new price/size/end date/discount.\n\nCLI Usage: `vastai list network-volume [options]`",
- "security": [
- {
- "BearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "required": [
- "disk_id"
- ],
- "properties": {
- "price_disk": {
- "type": "number",
- "format": "float",
- "description": "Price per GB of network volume storage"
- },
- "disk_id": {
- "type": "integer",
- "description": "ID of network disk for which offer is being created"
- },
- "size": {
- "type": "integer",
- "description": "Size in GB of the amount of space available to be rented"
- },
- "credit_discount_max": {
- "type": "number",
- "format": "float",
- "description": "Maximum discount rate allowed for prepaid credits"
- },
- "end_date": {
- "type": "number",
- "format": "float",
- "description": "Unix timestamp for when the listing expires"
- }
- }
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "Successful response",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "success": {
- "type": "boolean"
- },
- "msg": {
- "type": "string",
- "description": "status message"
- }
- },
- "example": {
- "success": true,
- "disk_id": "created network volume ask with id 6 and size 24"
- }
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "error": {
- "type": "string",
- "example": "invalid_args"
- },
- "msg": {
- "type": "string",
- "example": "Invalid disk_id"
- }
- }
- }
- }
- }
- },
- "403": {
- "description": "Forbidden",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "error": {
- "type": "string",
- "example": "not_authorized"
- },
- "msg": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "detail": {
"type": "string",
- "example": "Could not find network disk with id 6 associated with user"
+ "example": "API requests too frequent endpoint threshold=4.5"
}
}
}
}
}
}
- },
- "tags": [
- "Network Volumes"
- ]
+ }
}
},
"/api/v0/ssh/": {
@@ -7949,228 +7609,6 @@
]
}
},
- "/api/v0/network_volumes/search/": {
- "post": {
- "summary": "search network volumes",
- "description": "Search for available network volume offers with advanced filtering and sorting.\n\nCLI Usage: `vastai search network-volumes [--order ]`",
- "security": [
- {
- "BearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "q": {
- "type": "object",
- "properties": {
- "verified": {
- "type": "object",
- "description": "Display offers where all machines in cluster are verified",
- "example": {
- "eq": true
- }
- },
- "order": {
- "type": "array",
- "items": {
- "type": "array",
- "items": {
- "type": "string"
- }
- },
- "description": "Sort fields and directions",
- "example": [
- [
- "storage_cost",
- "asc"
- ]
- ]
- },
- "limit": {
- "type": "integer",
- "description": "Max results to return"
- },
- "reliability2": {
- "type": "object",
- "description": "Cluster reliability score (0-1)",
- "example": {
- "gt": 0.98
- }
- },
- "inet_down": {
- "type": "object",
- "description": "Download bandwidth (MB/s)",
- "example": {
- "gt": 100.0
- }
- },
- "inet_up": {
- "type": "object",
- "description": "Upload bandwidth (MB/s)",
- "example": {
- "gt": 100.0
- }
- },
- "geolocation": {
- "type": "object",
- "description": "Cluster location (two letter country code)",
- "example": {
- "in": [
- "TW",
- "SE"
- ]
- }
- },
- "disk_bw": {
- "type": "object",
- "description": "Disk read bandwidth in MB/s",
- "example": {
- "gt": 500
- }
- },
- "duration": {
- "type": "object",
- "description": "Maximum rental duration in days",
- "example": {
- "gte": 30
- }
- },
- "storage_cost": {
- "type": "object",
- "description": "Storage cost in $/GB/month",
- "example": {
- "lte": 0.1
- }
- }
- }
- }
- }
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "Successful search response",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "success": {
- "type": "boolean",
- "example": true
- },
- "offers": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "ask_contract_id": {
- "type": "integer",
- "description": "Unique offer ID"
- },
- "disk_space": {
- "type": "number",
- "description": "Storage space in GB"
- },
- "inet_up": {
- "type": "number",
- "description": "Upload bandwidth (MB/s)"
- },
- "inet_down": {
- "type": "number",
- "description": "Download bandwidth (MB/s)"
- },
- "reliability2": {
- "type": "number",
- "description": "Cluster reliability score (0-1)"
- },
- "verified": {
- "type": "boolean",
- "description": "Cluster verification status"
- },
- "geolocation": {
- "type": "string",
- "description": "Geographic location"
- },
- "nw_disk_avg_bw": {
- "type": "integer",
- "description": "Average read bw of network disk from machines in cluster"
- },
- "nw_disk_max_bw": {
- "type": "integer",
- "description": "Max read bw of network disk from machines in cluster"
- },
- "nw_disk_min_bw": {
- "type": "integer",
- "description": "Min read bw of network disk from machines in cluster"
- },
- "start_date": {
- "type": "number",
- "description": "start date of offer, in epoch time"
- },
- "end_date": {
- "type": "number",
- "description": "end date of offer, in epoch time"
- },
- "storage_cost": {
- "type": "number",
- "description": "storage cost in $/GB/month"
- },
- "storage_cost_total": {
- "type": "number",
- "description": "total storage cost per hour for rented space"
- }
- }
- }
- }
- }
- }
- }
- }
- },
- "400": {
- "description": "Bad request - invalid query parameters",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Error"
- }
- }
- }
- },
- "401": {
- "description": "Unauthorized - invalid or missing API key",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Error"
- }
- }
- }
- },
- "429": {
- "description": "Too many requests",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Error"
- }
- }
- }
- }
- },
- "tags": [
- "Network Volumes"
- ]
- }
- },
"/api/v0/bundles/": {
"post": {
"summary": "search offers",
@@ -9511,18 +8949,47 @@
"actual_status": {
"type": "string",
"nullable": true,
+ "enum": [
+ "loading",
+ "running",
+ "stopped",
+ "frozen",
+ "exited",
+ "rebooting",
+ "unknown",
+ "offline"
+ ],
+ "description": "Current status of the instance container. `null` while provisioning.\n\n- `loading` \u2014 Docker image downloading or container starting up.\n- `running` \u2014 Container executing. GPU charges apply.\n- `stopped` \u2014 Container halted. Disk charges continue; no GPU charges.\n- `frozen` \u2014 Container paused with memory preserved. GPU charges apply.\n- `exited` \u2014 Container process exited unexpectedly.\n- `rebooting` \u2014 Container restarting (transient).\n- `unknown` \u2014 No recent heartbeat from the host.\n- `offline` \u2014 Host machine disconnected from Vast servers (computed, not stored).\n",
"example": "running"
},
"cur_state": {
"type": "string",
+ "enum": [
+ "running",
+ "stopped",
+ "unloaded"
+ ],
+ "description": "Current state of the machine contract (hardware allocation).\n\n- `running` \u2014 Allocation active.\n- `stopped` \u2014 Allocation paused.\n- `unloaded` \u2014 Allocation released (instance destroyed).\n",
"example": "running"
},
"next_state": {
"type": "string",
+ "enum": [
+ "running",
+ "stopped",
+ "unloaded"
+ ],
+ "description": "Target state for the machine contract. The daemon transitions `cur_state` toward this value.\n\n- `running` \u2014 Should be active.\n- `stopped` \u2014 Should be paused.\n- `unloaded` \u2014 Should be released.\n",
"example": "running"
},
"intended_status": {
"type": "string",
+ "enum": [
+ "running",
+ "stopped",
+ "frozen"
+ ],
+ "description": "User's desired target state for the container.\n\n- `running` \u2014 Should be executing.\n- `stopped` \u2014 Should be halted.\n- `frozen` \u2014 Should be paused with memory preserved.\n",
"example": "running"
},
"label": {
@@ -10023,7 +9490,7 @@
"/api/v1/instances/": {
"get": {
"summary": "show instances (v1)",
- "description": "Retrieve a paginated list of instances for the authenticated user.\nSupports keyset pagination (max 25 per page), filtering, column selection, and sorting.\n\nCLI Usage: `vastai show instances-v1 [OPTIONS] [--api-key API_KEY] [--raw]`",
+ "description": "Retrieve a paginated list of instances for the authenticated user.\nSupports keyset pagination (max 25 per page), filtering, column selection, and sorting.\n\nCLI Usage: `vastai show instances [OPTIONS] [--api-key API_KEY] [--raw]`",
"security": [
{
"BearerAuth": []
@@ -10134,18 +9601,47 @@
"actual_status": {
"type": "string",
"nullable": true,
+ "enum": [
+ "loading",
+ "running",
+ "stopped",
+ "frozen",
+ "exited",
+ "rebooting",
+ "unknown",
+ "offline"
+ ],
+ "description": "Current status of the instance container. `null` while provisioning.\n\n- `loading` \u2014 Docker image downloading or container starting up.\n- `running` \u2014 Container executing. GPU charges apply.\n- `stopped` \u2014 Container halted. Disk charges continue; no GPU charges.\n- `frozen` \u2014 Container paused with memory preserved. GPU charges apply.\n- `exited` \u2014 Container process exited unexpectedly.\n- `rebooting` \u2014 Container restarting (transient).\n- `unknown` \u2014 No recent heartbeat from the host.\n- `offline` \u2014 Host machine disconnected from Vast servers (computed, not stored).\n",
"example": "running"
},
"cur_state": {
"type": "string",
+ "enum": [
+ "running",
+ "stopped",
+ "unloaded"
+ ],
+ "description": "Current state of the machine contract (hardware allocation).\n\n- `running` \u2014 Allocation active.\n- `stopped` \u2014 Allocation paused.\n- `unloaded` \u2014 Allocation released (instance destroyed).\n",
"example": "running"
},
"next_state": {
"type": "string",
+ "enum": [
+ "running",
+ "stopped",
+ "unloaded"
+ ],
+ "description": "Target state for the machine contract. The daemon transitions `cur_state` toward this value.\n\n- `running` \u2014 Should be active.\n- `stopped` \u2014 Should be paused.\n- `unloaded` \u2014 Should be released.\n",
"example": "running"
},
"intended_status": {
"type": "string",
+ "enum": [
+ "running",
+ "stopped",
+ "frozen"
+ ],
+ "description": "User's desired target state for the container.\n\n- `running` \u2014 Should be executing.\n- `stopped` \u2014 Should be halted.\n- `frozen` \u2014 Should be paused with memory preserved.\n",
"example": "running"
},
"label": {
@@ -11719,109 +11215,6 @@
]
}
},
- "/api/v0/network_volumes/unlist/": {
- "post": {
- "summary": "unlist network-volume",
- "description": "Unlists a network volume for rent.\n\nCLI Usage: `vastai unlist volume `",
- "security": [
- {
- "BearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "required": [
- "id"
- ],
- "properties": {
- "id": {
- "type": "integer",
- "description": "ID of network volume ask being unlisted"
- }
- }
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "Successful response",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "success": {
- "type": "boolean"
- },
- "id": {
- "type": "integer",
- "description": "id of unlisted network volume ask"
- },
- "msg": {
- "type": "string",
- "description": "status message"
- }
- },
- "example": {
- "success": true,
- "id": 6,
- "msg": "Deleted network volume listing"
- }
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "error": {
- "type": "string",
- "example": "invalid_args"
- },
- "msg": {
- "type": "string",
- "example": "You must pass in `id` in the body of the request"
- }
- }
- }
- }
- }
- },
- "403": {
- "description": "Forbidden",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "error": {
- "type": "string",
- "example": "not_authorized"
- },
- "msg": {
- "type": "string",
- "example": "Authorization Error. Check that you have proper privileges to perform this action."
- }
- }
- }
- }
- }
- }
- },
- "tags": [
- "Network Volumes"
- ]
- }
- },
"/api/v0/volumes/unlist/": {
"post": {
"summary": "unlist volume",
@@ -12142,22 +11535,47 @@
"actual_status": {
"type": "string",
"nullable": true,
- "description": "Current status of the instance container.",
+ "enum": [
+ "loading",
+ "running",
+ "stopped",
+ "frozen",
+ "exited",
+ "rebooting",
+ "unknown",
+ "offline"
+ ],
+ "description": "Current status of the instance container. `null` while the instance is still being provisioned.\n\n- `loading` \u2014 Docker image is downloading or the container is starting up.\n- `running` \u2014 Container is actively executing. GPU charges apply.\n- `stopped` \u2014 Container is halted. Disk charges continue; no GPU charges.\n- `frozen` \u2014 Container is paused with memory preserved. GPU charges apply.\n- `exited` \u2014 Container process exited unexpectedly.\n- `rebooting` \u2014 Container is restarting (transient).\n- `unknown` \u2014 Status cannot be determined; no recent heartbeat from the host.\n- `offline` \u2014 Machine hosting this instance has disconnected from Vast servers. Computed at query time; the underlying `actual_status` value in the database is preserved.\n",
"example": "running"
},
"intended_status": {
"type": "string",
- "description": "Intended status of the instance container.",
+ "enum": [
+ "running",
+ "stopped",
+ "frozen"
+ ],
+ "description": "The user's desired target state for the container. The system continuously works to reconcile `actual_status` with this value.\n\n- `running` \u2014 Container should be executing.\n- `stopped` \u2014 Container should be halted.\n- `frozen` \u2014 Container should be paused with memory preserved.\n",
"example": "running"
},
"cur_state": {
"type": "string",
- "description": "Current state of the machine contract.",
+ "enum": [
+ "running",
+ "stopped",
+ "unloaded"
+ ],
+ "description": "Current state of the machine contract (the hardware allocation for this instance).\n\n- `running` \u2014 Allocation is active; hardware is in use.\n- `stopped` \u2014 Allocation is paused.\n- `unloaded` \u2014 Allocation has been released (instance is destroyed).\n",
"example": "running"
},
"next_state": {
"type": "string",
- "description": "Next scheduled state for the machine contract.",
+ "enum": [
+ "running",
+ "stopped",
+ "unloaded"
+ ],
+ "description": "Target state for the machine contract. The daemon transitions `cur_state` toward this value.\n\n- `running` \u2014 Allocation should be active.\n- `stopped` \u2014 Allocation should be paused.\n- `unloaded` \u2014 Allocation should be released (set when destroying an instance).\n",
"example": "running"
},
"label": {
@@ -12765,4 +12183,4 @@
}
}
}
-}
\ No newline at end of file
+}
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..42c80be
--- /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/manage-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/manage-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)
----
-
-
-
-# CLI Commands
-
-```text Text
-usage: vastai [-h] [--url URL] [--retry RETRY] [--raw] [--explain] [--curl] [--api-key API_KEY] [--version] command ...
-
-positional arguments:
- command command to run. one of:
- help print this help message
- attach ssh Attach an ssh key to an instance. This will allow you to connect to the instance with the ssh key
- cancel copy Cancel a remote copy in progress, specified by DST id
- cancel sync Cancel a remote copy in progress, specified by DST id
- change bid Change the bid price for a spot/interruptible instance
- clone volume Clone an existing volume
- copy Copy directories between instances and/or local
- cloud copy Copy files/folders to and from cloud providers
- take snapshot Schedule a snapshot of a running container and push it to your repo in a container registry
- create api-key Create a new api-key with restricted permissions. Can be sent to other users and teammates
- create env-var Create a new user environment variable
- create ssh-key Create a new ssh-key
- create autogroup Create a new autoscale group
- create endpoint Create a new endpoint group
- create instance Create a new instance
- create subaccount Create a subaccount
- create team Create a new team
- create team-role Add a new role to your team
- create template Create a new template
- create volume Create a new volume
- delete api-key Remove an api-key
- delete ssh-key Remove an ssh-key
- delete scheduled-job
- Delete a scheduled job
- delete autogroup Delete an autogroup group
- delete endpoint Delete an endpoint group
- delete env-var Delete a user environment variable
- delete template Delete a Template
- delete volume Delete a volume
- destroy instance Destroy an instance (irreversible, deletes data)
- destroy instances Destroy a list of instances (irreversible, deletes data)
- destroy team Destroy your team
- detach ssh Detach an ssh key from an instance
- execute Execute a (constrained) remote command on a machine
- get endpt-logs Fetch logs for a specific serverless endpoint group
- invite member Invite a team member
- label instance Assign a string label to an instance
- launch instance Launch the top instance from the search offers based on the given parameters
- logs Get the logs for an instance
- prepay instance Deposit credits into reserved instance
- reboot instance Reboot (stop/start) an instance
- recycle instance Recycle (destroy/create) an instance
- remove member Remove a team member
- remove team-role Remove a role from your team
- reports Get the user reports for a given machine
- reset api-key Reset your api-key (get new key from website)
- start instance Start a stopped instance
- start instances Start a list of instances
- stop instance Stop a running instance
- stop instances Stop a list of instances
- search benchmarks Search for benchmark results using custom query
- search invoices Search for benchmark results using custom query
- search offers Search for instance types using custom query
- search templates Search for template results using custom query
- search volumes Search for volume offers using custom query
- set api-key Set api-key (get your api-key from the console/CLI)
- set user Update user data from json file
- ssh-url ssh url helper
- scp-url scp url helper
- show api-key Show an api-key
- show api-keys List your api-keys associated with your account
- show audit-logs Display account's history of important actions
- show scheduled-jobs Display the list of scheduled jobs
- show ssh-keys List your ssh keys associated with your account
- show autogroups Display user's current autogroup groups
- show endpoints Display user's current endpoint groups
- show connections Display user's cloud connections
- show deposit Display reserve deposit info for an instance
- show earnings Get machine earning history reports
- show env-vars Show user environment variables
- show invoices Get billing history reports
- show instance Display user's current instances
- show instances Display user's current instances
- show ipaddrs Display user's history of ip addresses
- show user Get current user data
- show subaccounts Get current subaccounts
- show members Show your team members
- show team-role Show your team role
- show team-roles Show roles for a team
- show volumes Show stats on owned volumes.
- create cluster Create Vast cluster
- join cluster Join Machine to Cluster
- delete cluster Delete Cluster
- remove-machine-from-cluster Removes machine from cluster
- show overlays Show overlays associated with your account.
- create overlay Creates overlay network on top of a physical cluster
- join overlay Adds instance to an overlay network
- delete overlay Deletes overlay and removes all of its associated instances
- show clusters Show clusters associated with your account.
- transfer credit Transfer credits to another account
- update autogroup Update an existing autoscale group
- update endpoint Update an existing endpoint group
- update env-var Update an existing user environment variable
- update instance Update recreate an instance from a new/updated template
- update team-role Update an existing team role
- update template Update an existing template
- update ssh-key Update an existing ssh key
- cancel maint [Host] Cancel maint window
- cleanup machine [Host] Remove all expired storage instances from the machine, freeing up space
- delete machine [Host] Delete machine if the machine is not being used by clients. host jobs on their own machines are disregarded and machine is force deleted.
- list machine [Host] list a machine for rent
- list machines [Host] list machines for rent
- list volume [Host] list disk space for rent as a volume on a machine
- list volumes [Host] list disk space for rent as a volume on machines
- unlist volume [Host] unlist volume offer
- remove defjob [Host] Delete default jobs
- set defjob [Host] Create default jobs for a machine
- set min-bid [Host] Set the minimum bid/rental price for a machine
- schedule maint [Host] Schedule upcoming maint window
- show machine [Host] Show hosted machines
- show machines [Host] Show hosted machines
- show maints [Host] Show maintenance information for host machines
- unlist machine [Host] Unlist a listed machine
- self-test machine [Host] Perform a self-test on the specified machine
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to HTTPS API endpoints
- --curl show a curl equivalency to the call
- --api-key API_KEY api key. defaults to using the one stored in /home/scott_vast/.config/vastai/vast_api_key
- --version show version
-
-Use 'vast COMMAND --help' for more info about a command
-
-```
-
-# Client Commands
-
-## cancel copy
-
-Cancel a remote copy in progress, specified by DST id
-
-```text Text
-usage: vastai cancel copy DST
-
-positional arguments:
- dst instance_id:/path to target of copy operation.
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-Use this command to cancel any/all current remote copy operations copying to a specific named instance, given by DST.
-Examples:
- vastai cancel copy 12371
-
-The first example cancels all copy operations currently copying data into instance 12371
-
-```
-
-## cancel sync
-
-Cancel a remote copy in progress, specified by DST id
-
-```text Text
-usage: vastai cancel sync DST
-
-positional arguments:
- dst instance_id:/path to target of sync operation.
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-Use this command to cancel any/all current remote cloud sync operations copying to a specific named instance, given by DST.
-Examples:
- vastai cancel sync 12371
-
-The first example cancels all copy operations currently copying data into instance 12371
-
-```
-
-## change bid
-
-Change the bid price for a spot/interruptible instance
-
-```text Text
-usage: vastai change bid id [--price PRICE]
-
-positional arguments:
- id id of instance type to change bid
-
-options:
- -h, --help show this help message and exit
- --price PRICE per machine bid price in $/hour
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-Change the current bid price of instance id to PRICE.
-If PRICE is not specified, then a winning bid price is used as the default.
-
-```
-
-## cloud copy
-
-Copy files/folders to and from cloud providers
-
-```text Text
-usage: vastai cloud_copy SRC DST CLOUD_SERVICE INSTANCE_ID CLOUD_SERVICE_SELECTED TRANSFER
-
-options:
- -h, --help show this help message and exit
- --src SRC path to source of object to copy.
- --dst DST path to target of copy operation.
- --instance INSTANCE id of the instance
- --connection CONNECTION
- id of cloud connection on your account
- --transfer TRANSFER type of transfer, possible options include Instance To
- Cloud and Cloud To Instance
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-Copies a directory from a source location to a target location. Each of source and destination
-directories can be either local or remote, subject to appropriate read and write
-permissions required to carry out the action. The format for both src and dst is [instance_id:]path.
-You can find more information about the cloud copy operation here: [Cloud Sync](/documentation/instances/cloud-sync)
-
-Examples:
- vastai cloud_copy --src folder --dst /workspace --cloud_service "Amazon S3" --instance_id 6003036 --cloud_service_selected 52 --transfer "Instance To Cloud"
-
-The example copies all contents of /folder into /workspace on instance 6003036 from Amazon S3.
-
-```
-
-## copy
-
-Copy directories between instances and/or local
-
-```text Text
-usage: vastai copy SRC DST
-
-positional arguments:
- src Source location for copy operation (supports multiple formats)
- dst Target location for copy operation (supports multiple formats)
-
-options:
- -h, --help show this help message and exit
- -i IDENTITY, --identity IDENTITY Location of ssh private key
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to HTTPS API endpoints
- --curl show a curl equivalency to the call
- --api-key API_KEY api key. defaults to using the one stored in /home/anthony-benjamin/.config/vastai/vast_api_key
- --version show version
-
-Copies a directory from a source location to a target location. Each of source and destination
-directories can be either local or remote, subject to appropriate read and write
-permissions required to carry out the action.
-
-Supported location formats:
-- [instance_id:]path (legacy format, still supported)
-- C.instance_id:path (container copy format)
-- cloud_service:path (cloud service format)
-- cloud_service.cloud_service_id:path (cloud service with ID)
-- local:path (explicit local path)
-
-You should not copy to /root or / as a destination directory, as this can mess up the permissions on your instance ssh folder, breaking future copy operations (as they use ssh authentication)
-You can see more information about constraints here: [Data Movement](/documentation/instances/data-movement#constraints)
-
-Examples:
- vast copy 6003036:/workspace/ 6003038:/workspace/
- vast copy C.11824:/data/test local:data/test
- vast copy local:data/test C.11824:/data/test
- vast copy drive:/folder/file.txt C.6003036:/workspace/
- vast copy s3.101:/data/ C.6003036:/workspace/
-
-The first example copy syncs all files from the absolute directory '/workspace' on instance 6003036 to the directory '/workspace' on instance 6003038.
-The second example copy syncs files from container 11824 to the local machine using structured syntax.
-The third example copy syncs files from local to container 11824 using structured syntax.
-The fourth example copy syncs files from Google Drive to an instance.
-The fifth example copy syncs files from S3 bucket with id 101 to an instance.
-```
-
-## create api-key
-
-Create a new api-key with restricted permissions.
-
-```text Text
-usage: vastai create api-key
-
-options:
- -h, --help show this help message and exit
- --permissions PERMISSIONS
- file path for json encoded permissions, look in the
- docs for more information
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## create autoscaler
-
-Create a new autoscale group
-
-```text Text
-usage: vastai autoscaler create [OPTIONS]
-
-options:
- -h, --help show this help message and exit
- --min_load MIN_LOAD minimum floor load in perf units/s (token/s for LLms)
- --target_util TARGET_UTIL
- target capacity utilization (fraction, max 1.0,
- default 0.9)
- --cold_mult COLD_MULT
- cold/stopped instance capacity target as multiple of
- hot capacity target (default 2.5)
- --gpu_ram GPU_RAM estimated GPU RAM req (independent of search string)
- --template_hash TEMPLATE_HASH
- template hash (optional)
- --template_id TEMPLATE_ID
- template id (optional)
- --search_params SEARCH_PARAMS
- search param string for search offers ex: "gpu_ram>=23
- num_gpus=2 gpu_name=RTX_4090 inet_down>200
- direct_port_count>2 disk_space>=64"
- --launch_args LAUNCH_ARGS
- launch args string for create instance ex: "--onstart
- onstart_wget.sh --env '-e ONSTART_PATH=https://s3.amaz
- onaws.com/vast.ai/onstart_OOBA.sh' --image
- atinoda/text-generation-webui:default-nightly --disk
- 64"
- --endpoint_name ENDPOINT_NAME
- deployment endpoint name (allows multiple autoscale
- groups to share same deployment endpoint)
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-Create a new autoscaling group to manage a pool of worker instances.
-
-Example: vastai create autoscaler --min_load 100 --target_util 0.9 --cold_mult 2.0 --search_params "gpu_ram>=23 num_gpus=2 gpu_name=RTX_4090 inet_down>200 direct_port_count>2 disk_space>=64" --launch_args "--onstart onstart_wget.sh --env '-e ONSTART_PATH=https://s3.amazonaws.com/vast.ai/onstart_OOBA.sh' --image atinoda/text-generation-webui:default-nightly --disk 64" --gpu_ram 32.0 --endpoint_name "LLama"
-
-```
-
-## create instance
-
-Create a new instance
-
-```text Text
-usage: vastai create instance ID [OPTIONS] [--args ...]
-
-positional arguments:
- ID id of instance type to launch (returned from search
- offers)
-
-options:
- -h, --help show this help message and exit
- --price PRICE per machine bid price in $/hour
- --disk DISK size of local disk partition in GB
- --image IMAGE docker container image to launch
- --login LOGIN docker login arguments for private repo
- authentication, surround with ''
- --label LABEL label to set on the instance
- --onstart ONSTART filename to use as onstart script
- --onstart-cmd ONSTART_CMD
- contents of onstart script as single argument
- --entrypoint ENTRYPOINT
- override entrypoint for args launch instance
- --ssh Launch as an ssh instance type.
- --jupyter Launch as a jupyter instance instead of an ssh
- instance.
- --direct Use (faster) direct connections for jupyter & ssh.
- --jupyter-dir JUPYTER_DIR
- For runtype 'jupyter', directory in instance to use to
- launch jupyter. Defaults to image's working directory.
- --jupyter-lab For runtype 'jupyter', Launch instance with jupyter
- lab.
- --lang-utf8 Workaround for images with locale problems: install
- and generate locales before instance launch, and set
- locale to C.UTF-8.
- --python-utf8 Workaround for images with locale problems: set
- python's locale to C.UTF-8.
- --env ENV env variables and port mapping options, surround with
- ''
- --args ... list of arguments passed to container ENTRYPOINT.
- Onstart is recommended for this purpose.
- --create-from CREATE_FROM
- Existing instance id to use as basis for new instance.
- Instance configuration should usually be identical, as
- only the difference from the base image is copied.
- --force Skip sanity checks when creating from an existing
- instance
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-Performs the same action as pressing the "RENT" button on the website at https://console.vast.ai/create/
-Creates an instance from an offer ID (which is returned from "search offers"). Each offer ID can only be used to create one instance.
-Besides the offer ID, you must pass in an '--image' argument as a minimum.
-
-Examples:
-vastai create instance 6995713 --image pytorch/pytorch --disk 40 --env '-p 8081:80801/udp -h billybob' --ssh --direct --onstart-cmd "env | grep _ >> /etc/environment; echo 'starting up'";
-vastai create instance 384827 --image bobsrepo/pytorch:latest --login '-u bob -p 9d8df!fd89ufZ docker.io' --jupyter --direct --env '-e TZ=PDT -e XNAME=XX4 -p 22:22 -p 8080:8080' --disk 20
-
-Return value:
-Returns a json reporting the instance ID of the newly created instance.
-Example: {'success': True, 'new_contract': 7835610}
-
-```
-
-## create overlay
-
-Create an overlay network inside a physical cluster.
-
-
-
-```none
-usage: vastai create overlay CLUSTER_ID OVERLAY_NAME
-
-positional arguments:
- cluster_id ID of cluster to create overlay on top of
- name overlay network name
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to HTTPS API endpoints
- --curl show a curl equivalency to the call
- --api-key API_KEY api key. defaults to using the one stored in /home/edgarlin/.config/vastai/vast_api_key
- --version show version
-
-Creates an overlay network to allow local networking between instances on a physical cluster
-
-```
-
-## create subaccount
-
-Create a subaccount
-
-```text Text
-usage: vastai create subaccount --email EMAIL --username USERNAME --password PASSWORD --type TYPE
-
-options:
- -h, --help show this help message and exit
- --email EMAIL email address to use for login
- --username USERNAME username to use for login
- --password PASSWORD password to use for login
- --type TYPE host/client
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-Creates a new account that is considered a child of your current account as defined via the API key.
-
-```
-
-## create team
-
-Create a new team
-
-```text Text
-usage: vastai create-team --team_name TEAM_NAME
-
-options:
- -h, --help show this help message and exit
- --team_name TEAM_NAME
- name of the team
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## create team-role
-
-Add a new role to your
-
-```text Text
-usage: vastai create team-role name --permissions PERMISSIONS
-
-options:
- -h, --help show this help message and exit
- --name NAME name of the role
- --permissions PERMISSIONS
- file path for json encoded permissions, look in the
- docs for more information
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## delete api-key
-
-Remove an api-key
-
-```text Text
-usage: vastai delete api-key ID
-
-positional arguments:
- ID id of apikey to remove
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## delete autoscaler
-
-Delete an autoscaler group
-
-```text Text
-usage: vastai delete autoscaler ID
-
-positional arguments:
- ID id of group to delete
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-Note that deleteing an autoscaler group doesn't automatically destroy all the instances that are associated with your autoscaler group.
-Example: vastai delete autoscaler 4242
-
-```
-
-## delete overlay
-
-Deletes an overlay
-
-
-
-```none
-usage: vastai delete overlay OVERLAY_ID
-
-positional arguments:
- overlay_id ID of overlay to delete
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to HTTPS API endpoints
- --curl show a curl equivalency to the call
- --api-key API_KEY api key. defaults to using the one stored in /home/edgarlin/.config/vastai/vast_api_key
-
-```
-
-## destroy instance
-
-Destroy an instance (irreversible, deletes data)
-
-```text Text
-usage: vastai destroy instance id [-h] [--api-key API_KEY] [--raw]
-
-positional arguments:
- id id of instance to delete
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-Perfoms the same action as pressing the "DESTROY" button on the website at https://console.vast.ai/instances/
-Example: vastai destroy instance 4242
-
-```
-
-## destroy instances
-
-Destroy a list of instances (irreversible, deletes
-
-```text Text
-usage: vastai destroy instances [--raw]
-
-positional arguments:
- ids ids of instance to destroy
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## destroy team
-
-Destroy your team
-
-```text Text
-usage: vastai destroy team
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## execute
-
-Execute a (constrained) remote command on a machine
-
-```text Text
-usage: vastai execute ID COMMAND
-
-positional arguments:
- ID id of instance to execute on
- COMMAND bash command surrounded by single quotes
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-examples:
- vastai execute 99999 'ls -l -o -r'
- vastai execute 99999 'rm -r home/delete_this.txt'
- vastai execute 99999 'du -d2 -h'
-
-available commands:
- ls List directory contents
- rm Remote files or directories
- du Summarize device usage for a set of files
-
-Return value:
-Returns the output of the command which was executed on the instance, if successful. May take a few seconds to retrieve the results.
-
-```
-
-## generate pdf-invoices
-
-```text Text
-usage: vastai generate pdf-invoices [OPTIONS]
-
-options:
- -h, --help show this help message and exit
- -q, --quiet only display numeric ids
- -s START_DATE, --start_date START_DATE
- start date and time for report. Many formats accepted
- (optional)
- -e END_DATE, --end_date END_DATE
- end date and time for report. Many formats accepted
- (optional)
- -c, --only_charges Show only charge items.
- -p, --only_credits Show only credit items.
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## join overlay
-
-Attaches an instance to an overlay network
-
-```none
-usage: vastai join overlay OVERLAY_NAME INSTANCE_ID
-
-positional arguments:
- name Overlay network name to join instance to.
- instance_id Instance ID to add to overlay.
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to HTTPS API endpoints
- --curl show a curl equivalency to the call
- --api-key API_KEY api key. defaults to using the one stored in /home/edgarlin/.config/vastai/vast_api_key
- --version show version
-
-Adds an instance to a compatible overlay network.
-
-```
-
-## invite team-member
-
-Invite a team member
-
-```text Text
-usage: vastai invite team-member --email EMAIL --role ROLE
-
-options:
- -h, --help show this help message and exit
- --email EMAIL email of user to be invited
- --role ROLE role of user to be invited
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## label instance
-
-Assign a string label to an instance
-
-```text Text
-usage: vastai label instance
-
-positional arguments:
- id id of instance to label
- label label to set
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## logs
-
-Get the logs for an instance
-
-```text Text
-usage: vastai logs [OPTIONS] INSTANCE_ID
-
-positional arguments:
- INSTANCE_ID id of instance
-
-options:
- -h, --help show this help message and exit
- --tail TAIL Number of lines to show from the end of the logs (default
- '1000')
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## prepay instance
-
-Deposit credits into reserved instance.
-
-```text Text
-usage: vastai prepay instance
-
-positional arguments:
- id id of instance to prepay for
- amount amount of instance credit prepayment (default discount
- func of 0.2 for 1 month, 0.3 for 3 months)
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## reboot instance
-
-Reboot (stop/start) an instance
-
-```text Text
-usage: vastai reboot instance [--raw]
-
-positional arguments:
- id id of instance to reboot
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-Instance is stopped and started without any risk of losing GPU priority.
-
-```
-
-## remove team-member
-
-Remove a team member
-
-```text Text
-usage: vastai remove team-member ID
-
-positional arguments:
- ID id of user to remove
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## remove team-role
-
-Remove a role from your team
-
-```text Text
-usage: vastai remove team-role NAME
-
-positional arguments:
- NAME name of the role
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## reports
-
-Get the user reports for a given machine
-
-```text Text
-usage: vastai reports m_id
-
-positional arguments:
- m_id machine id
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## reset api-key
-
-Reset your api-key (get new key from website).
-
-```text Text
-usage: vastai reset api-key
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## scp-url
-
-scp url helper
-
-```text Text
-usage: vastai scp-url ID
-
-positional arguments:
- id id
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## search offers
-
-Search for instance types using custom query
-
-```text Text
-usage: vastai search offers [--help] [--api-key API_KEY] [--raw]
-
-positional arguments:
- query Query to search for. default: 'external=false
- rentable=true verified=true', pass -n to ignore
- default
-
-options:
- -h, --help show this help message and exit
- -t TYPE, --type TYPE Show 'on-demand', 'reserved', or 'bid'(interruptible)
- pricing. default: on-demand
- -i, --interruptible Alias for --type=bid
- -b, --bid Alias for --type=bid
- -r, --reserved Alias for --type=reserved
- -d, --on-demand Alias for --type=on-demand
- -n, --no-default Disable default query
- --disable-bundling Show identical offers. This request is more heavily
- rate limited.
- --storage STORAGE Amount of storage to use for pricing, in GiB.
- default=5.0GiB
- -o ORDER, --order ORDER
- Comma-separated list of fields to sort on. postfix
- field with - to sort desc. ex: -o
- 'num_gpus,total_flops-'. default='score-'
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-Query syntax:
-
- query = comparison comparison...
- comparison = field op value
- field =
- op = one of: <, <=, ==, !=, >=, >, in, notin
- value = | 'any'
- bool: True, False
-
-note: to pass '>' and '<' on the command line, make sure to use quotes
-note: to encode a string query value (ie for gpu_name), replace any spaces ' ' with underscore '_'
-
-Examples:
-
- # search for somewhat reliable single RTX 3090 instances, filter out any duplicates or offers that conflict with our existing stopped instances
- vastai search offers 'reliability > 0.98 num_gpus=1 gpu_name=RTX_3090 rented=False'
-
- # search for datacenter gpus with minimal compute_cap and total_flops
- vastai search offers 'compute_cap > 610 total_flops > 5 datacenter=True'
-
- # search for reliable machines with at least 4 gpus, unverified, order by num_gpus, allow duplicates
- vastai search offers 'reliability > 0.99 num_gpus>=4 verified=False rented=any' -o 'num_gpus-'
-
-Available fields:
-
- Name Type Description
-
- bw_nvlink float bandwidth NVLink
- compute_cap: int cuda compute capability*100 (ie: 650 for 6.5, 700 for 7.0)
- cpu_arch: string host machine cpu architecture (e.g. amd64, arm64)
- cpu_cores: int # virtual cpus
- cpu_cores_effective: float # virtual cpus you get
- cpu_ghz: float # cpu clock speed GHZ
- cpu_ram: float system RAM in gigabytes
- cuda_vers: float machine max supported cuda version (based on driver version)
- datacenter: bool show only datacenter offers
- direct_port_count int open ports on host's router
- disk_bw: float disk read bandwidth, in MB/s
- disk_space: float disk storage space, in GB
- dlperf: float DL-perf score (see FAQ for explanation)
- dlperf_usd: float DL-perf/$
- dph: float $/hour rental cost
- driver_version: string machine's nvidia/amd driver version as 3 digit string ex. "535.86.05,"
- duration: float max rental duration in days
- external: bool show external offers in addition to datacenter offers
- flops_usd: float TFLOPs/$
- geolocation: string Two letter country code. Works with operators =, !=, in, notin (e.g. geolocation not in ['XV','XZ'])
- gpu_arch: string host machine gpu architecture (e.g. nvidia, amd)
- gpu_display_active: bool True if the GPU has a display attached
- gpu_frac: float Ratio of GPUs in the offer to gpus in the system
- gpu_max_power: float GPU power limit in watts
- gpu_max_temp: float GPU temperature limit in Celsius
- gpu_mem_bw: float GPU memory bandwidth in GB/s
- gpu_name: string GPU model name (no quotes, replace spaces with underscores, ie: RTX_3090 rather than 'RTX 3090')
- gpu_ram: float per GPU RAM in GB
- gpu_frac: float Ratio of GPUs in the offer to gpus in the system
- gpu_display_active: bool True if the GPU has a display attached
- gpu_total_ram: float total GPU RAM in GB
- has_avx: bool CPU supports AVX instruction set.
- id: int instance unique ID
- inet_down: float internet download speed in Mb/s
- inet_down_cost: float internet download bandwidth cost in $/GB
- inet_up: float internet upload speed in Mb/s
- inet_up_cost: float internet upload bandwidth cost in $/GB
- machine_id int machine id of instance
- min_bid: float current minimum bid price in $/hr for interruptible
- num_gpus: int # of GPUs
- pci_gen: float PCIE generation
- pcie_bw: float PCIE bandwidth (CPU to GPU)
- reliability: float machine reliability score (see FAQ for explanation)
- rentable: bool is the instance currently rentable
- rented: bool allow/disallow duplicates and potential conflicts with existing stopped instances
- storage_cost: float storage cost in $/GB/month
- static_ip: bool is the IP addr static/stable
- total_flops: float total TFLOPs from all GPUs
- ubuntu_version string host machine ubuntu OS version
- verified: bool is the machine verified
- vms_enabled: bool is the machine a VM instance
-
-```
-
-## set api-key
-
-Set api-key (get your api-key from the console/CLI)
-
-```text Text
-usage: vastai set api-key APIKEY
-
-positional arguments:
- new_api_key Api key to set as currently logged in user
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## show api-key
-
-Show an api-key
-
-```text Text
-usage: vastai show api-key
-
-positional arguments:
- id id of apikey to get
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## show api-keys
-
-List your api-keys associated with your account
-
-```text
-usage: vastai show api-keys
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## show autoscalers
-
-Display user's current autoscaler groups
-
-```text Text
-usage: vastai show autoscalers [--api-key API_KEY]
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-Example: vastai show autoscalers
-
-```
-
-## show connections
-
-Displays user's cloud connections
-
-```text Text
-usage: vastai show connections [--api-key API_KEY] [--raw]
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## show earnings
-
-Get machine earning history reports
-
-```text Text
-usage: vastai show earnings [OPTIONS]
-
-options:
- -h, --help show this help message and exit
- -q, --quiet only display numeric ids
- -s START_DATE, --start_date START_DATE
- start date and time for report. Many formats accepted
- -e END_DATE, --end_date END_DATE
- end date and time for report. Many formats accepted
- -m MACHINE_ID, --machine_id MACHINE_ID
- Machine id (optional)
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## show instance
-
-Display user's current instances
-
-```text Text
-usage: vastai show instance [--api-key API_KEY] [--raw]
-
-positional arguments:
- id id of instance to get
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## show instances
-
-Display user's current instances
-
-```text Text
-usage: vastai show instances [OPTIONS] [--api-key API_KEY] [--raw]
-
-options:
- -h, --help show this help message and exit
- -q, --quiet only display numeric ids
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## show invoices
-
-Get billing history reports
-
-```text Text
-usage: vastai show invoices [OPTIONS]
-
-options:
- -h, --help show this help message and exit
- -q, --quiet only display numeric ids
- -s START_DATE, --start_date START_DATE
- start date and time for report. Many formats accepted
- (optional)
- -e END_DATE, --end_date END_DATE
- end date and time for report. Many formats accepted
- (optional)
- -c, --only_charges Show only charge items.
- -p, --only_credits Show only credit items.
- --instance_label INSTANCE_LABEL
- Filter charges on a particular instance label (useful
- for autoscaler groups)
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-Deprecated: use `vastai show invoices-v1` for the current invoices API (date range required, pagination supported).
-
-Date formats:
- `--start_date` and `--end_date` accept most human-readable formats. If you do not include a timezone,
- dates are parsed in your local timezone. The CLI converts them to UTC epoch seconds before calling the API.
-
-Examples:
- # Show invoice items for January 2026
- vastai show invoices --start_date 2026-01-01 --end_date 2026-01-31
-
- # Same range using UTC epoch seconds
- vastai show invoices --start_date 1767225600 --end_date 1769903999
-
- # Credits only, with a single-ended range
- vastai show invoices --only_credits --start_date 2026-01-01
-
-## show invoices-v1
-
-Get billing (invoices/charges) history reports with advanced filtering and pagination
-
-```text Text
-usage: vastai show invoices-v1 [OPTIONS]
-
-options:
- -h, --help show this help message and exit
- -i, --invoices Show invoices instead of charges
- -it, --invoice-type type [type ...]
- Filter which types of invoices to show: {transfers, stripe, bitpay, coinbase, crypto.com, reserved, payout_paypal, payout_wise}
- -c, --charges Show charges instead of invoices
- -ct, --charge-type type [type ...]
- Filter which types of charges to show: {i|instance, v|volume, s|serverless}
- -s, --start-date START_DATE
- Start date (YYYY-MM-DD or timestamp)
- -e, --end-date END_DATE
- End date (YYYY-MM-DD or timestamp)
- -l, --limit LIMIT Number of results per page (default: 20, max: 100)
- -t, --next-token NEXT_TOKEN
- Pagination token for next page
- -f, --format {table,tree}
- Output format for charges (default: table)
- -v, --verbose Include full Instance Charge details and Invoice Metadata (tree view only)
- --latest-first Sort by latest first
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-Date handling:
- `--start-date` and `--end-date` accept `YYYY-MM-DD` (interpreted as UTC) or Unix epoch seconds.
- If both are omitted, the CLI defaults to a 7-day window ending now. Use epoch seconds for exact time-of-day filtering.
-
-Examples:
- # Show the first 20 invoices from the last 7 days (default window)
- vastai show invoices-v1 --invoices
-
- # Show invoices for January 2026
- vastai show invoices-v1 -i --start-date 2026-01-01 --end-date 2026-01-31
-
- # Show the first 50 volume+serverless charges with full details
- vastai show invoices-v1 -c -ct v s -s 2026-01-01 -e 2026-01-05 --format tree --verbose -l 50
-
- # Fetch the next page of invoices
- vastai show invoices-v1 --invoices --limit 50 --next-token eyJ2YWx1ZXMiOiB7ImlkIjog....
-
-## show ipaddrs
-
-Display user's history of ip addresses
-
-```text Text
-usage: vastai show ipaddrs [--api-key API_KEY] [--raw]
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## show overlays
-
-Shows the client's created overlay networks
-
-
-
-```none
-usage: vastai show overlays
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to HTTPS API endpoints
- --curl show a curl equivalency to the call
- --api-key API_KEY api key. defaults to using the one stored in /home/edgarlin/.config/vastai/vast_api_key
- --version show version
-
-Show overlays associated with your account.
-
-```
-
-## show subaccounts
-
-Get current subaccounts
-
-```text Text
-usage: vastai show subaccounts [OPTIONS]
-
-options:
- -h, --help show this help message and exit
- -q, --quiet display subaccounts from current user
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## show team-members
-
-Show your team members
-
-```text Text
-usage: vastai show team-members
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## show team-role
-
-Show your team role
-
-```text Text
-usage: vastai show team-role NAME
-
-positional arguments:
- NAME name of the role
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## show team-roles
-
-Show roles for a team
-
-```text Text
-usage: vastai show team-roles
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## show user
-
-Get current user data
-
-```text Text
-usage: vastai show user [OPTIONS]
-
-options:
- -h, --help show this help message and exit
- -q, --quiet display information about user
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-Shows stats for logged-in user. These include user balance, email, and ssh key. Does not show API key.
-
-```
-
-## ssh-url
-
-ssh url helper
-
-```text Text
-usage: vastai ssh-url ID
-
-positional arguments:
- id id of instance
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## start instance
-
-Start a stopped instance
-
-```text Text
-usage: vastai start instance [--raw]
-
-positional arguments:
- id id of instance to start/restart
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-This command attempts to bring an instance from the "stopped" state into the "running" state. This is subject to resource availability on the machine that the instance is located on.
-If your instance is stuck in the "scheduling" state for more than 30 seconds after running this, it likely means that the required resources on the machine to run your instance are currently unavailable.
-Examples:
- vastai start instances $(vastai show instances -q)
- vastai start instance 329838
-
-```
-
-## start instances
-
-Start a list of instances
-
-```text Text
-usage: vastai start instances [--raw] ID0 ID1 ID2...
-
-positional arguments:
- ids ids of instance to start
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## stop instance
-
-Stop a running instance
-
-```text Text
-usage: vastai stop instance [--raw] ID
-
-positional arguments:
- id id of instance to stop
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-This command brings an instance from the "running" state into the "stopped" state. When an instance is "stopped" all of your data on the instance is preserved,
-and you can resume use of your instance by starting it again. Once stopped, starting an instance is subject to resource availability on the machine that the instance is located on.
-There are ways to move data off of a stopped instance, which are described here: [Data Movement](/documentation/instances/data-movement)
-
-```
-
-## stop instances
-
-Stop a list of instances
-
-```text Text
-usage: vastai stop instances [--raw] ID0 ID1 ID2...
-
-positional arguments:
- ids ids of instance to stop
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-Examples:
- vastai stop instances $(vastai show instances -q)
- vastai stop instances 329838 984849
-
-```
-
-## transfer credit
-
-Transfer credits to another account
-
-```text Text
-usage: vastai transfer credit RECIPIENT AMOUNT
-
-positional arguments:
- recipient email of recipient account
- amount $dollars of credit to transfer
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-Transfer (amount) credits to account with email (recipient).
-
-```
-
-## update autoscaler
-
-Update an existing autoscale group
-
-```text Text
-usage: vastai update autoscaler ID [OPTIONS]
-
-positional arguments:
- ID id of autoscale group to update
-
-options:
- -h, --help show this help message and exit
- --min_load MIN_LOAD minimum floor load in perf units/s (token/s for LLms)
- --target_util TARGET_UTIL
- target capacity utilization (fraction, max 1.0,
- default 0.9)
- --cold_mult COLD_MULT
- cold/stopped instance capacity target as multiple of
- hot capacity target (default 2.5)
- --gpu_ram GPU_RAM estimated GPU RAM req (independent of search string)
- --template_hash TEMPLATE_HASH
- template hash
- --template_id TEMPLATE_ID
- template id
- --search_params SEARCH_PARAMS
- search param string for search offers ex: "gpu_ram>=23
- num_gpus=2 gpu_name=RTX_4090 inet_down>200
- direct_port_count>2 disk_space>=64"
- --launch_args LAUNCH_ARGS
- launch args string for create instance ex: "--onstart
- onstart_wget.sh --env '-e ONSTART_PATH=https://s3.amaz
- onaws.com/vast.ai/onstart_OOBA.sh' --image
- atinoda/text-generation-webui:default-nightly --disk
- 64"
- --endpoint_name ENDPOINT_NAME
- deployment endpoint name (allows multiple autoscale
- groups to share same deployment endpoint)
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-Example: vastai update autoscaler 4242 --min_load 100 --target_util 0.9 --cold_mult 2.0 --search_params "gpu_ram>=23 num_gpus=2 gpu_name=RTX_4090 inet_down>200 direct_port_count>2 disk_space>=64" --launch_args "--onstart onstart_wget.sh --env '-e ONSTART_PATH=https://s3.amazonaws.com/vast.ai/onstart_OOBA.sh' --image atinoda/text-generation-webui:default-nightly --disk 64" --gpu_ram 32.0 --endpoint_name "LLama"
-
-```
-
-## update team-role
-
-Update an existing team role
-
-```text Text
-usage: vastai update team-role ID --name NAME --permissions PERMISSIONS
-
-positional arguments:
- ID id of the role
-
-options:
- -h, --help show this help message and exit
- --name NAME name of the template
- --permissions PERMISSIONS
- file path for json encoded permissions, look in the
- docs for more information
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-# Host Commands
-
-## create cluster
-
-Registers a new locally-networked cluster with the Vast.
-
-
-
-```none
-usage: vastai create cluster SUBNET MANAGER_ID
-
-positional arguments:
- subnet local subnet for cluster, ex: '0.0.0.0/24'
- manager_id Machine ID of manager node in cluster. Must exist already.
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to HTTPS API endpoints
- --curl show a curl equivalency to the call
- --api-key API_KEY api key. defaults to using the one stored in /home/edgarlin/.config/vastai/vast_api_key
- --version show version
-
-Create Vast Cluster by defining a local subnet and manager id.
-
-```
-
-## delete cluster
-
-Deregisters a cluster
-
-```none
-usage: vastai delete cluster CLUSTER_ID
-
-positional arguments:
- cluster_id ID of cluster to delete
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to HTTPS API endpoints
- --curl show a curl equivalency to the call
- --api-key API_KEY api key. defaults to using the one stored in /home/edgarlin/.config/vastai/vast_api_key
- --version show version
-
-Delete Vast Cluster
-
-```
-
-## join cluster
-
-Registers a machine or list of machines as a member of a cluster.
-
-```none
-usage: vastai join cluster CLUSTER_ID MACHINE_IDS
-
-positional arguments:
- cluster_id ID of cluster to add machine to
- machine_ids machine id(s) to join cluster
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to HTTPS API endpoints
- --curl show a curl equivalency to the call
- --api-key API_KEY api key. defaults to using the one stored in /home/edgarlin/.config/vastai/vast_api_key
- --version show version
-
-Join's Machine to Vast Cluster
-
-```
-
-## list machine
-
-\[Host] list a machine for rent
-
-```text Text
-usage: vastai list machine id [--price_gpu PRICE_GPU] [--price_inetu PRICE_INETU] [--price_inetd PRICE_INETD] [--api-key API_KEY]
-
-positional arguments:
- id id of machine to list
-
-options:
- -h, --help show this help message and exit
- -g PRICE_GPU, --price_gpu PRICE_GPU
- per gpu rental price in $/hour (price for active
- instances)
- -s PRICE_DISK, --price_disk PRICE_DISK
- storage price in $/GB/month (price for inactive
- instances), default: $0.15/GB/month
- -u PRICE_INETU, --price_inetu PRICE_INETU
- price for internet upload bandwidth in $/GB
- -d PRICE_INETD, --price_inetd PRICE_INETD
- price for internet download bandwidth in $/GB
- -r DISCOUNT_RATE, --discount_rate DISCOUNT_RATE
- Max long term prepay discount rate fraction, default:
- 0.4
- -m MIN_CHUNK, --min_chunk MIN_CHUNK
- minimum amount of gpus
- -e END_DATE, --end_date END_DATE
- unix timestamp of the available until date (optional)
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-Performs the same action as pressing the "LIST" button on the site https://cloud.vast.ai/host/machines.
-On the end date the listing will expire and your machine will unlist. However any existing client jobs will still remain until ended by their owners.
-Once you list your machine and it is rented, it is extremely important that you don't interfere with the machine in any way.
-If your machine has an active client job and then goes offline, crashes, or has performance problems, this could permanently lower your reliability rating.
-We strongly recommend you test the machine first and only list when ready.
-
-```
-
-## remove-machine-from-cluster
-
-Deregisters a machine from a cluster, changing the manager node if the machine removed is the only manager.
-
-
-
-```none
-usage: vastai remove-machine-from-cluster CLUSTER_ID MACHINE_ID NEW_MANAGER_ID
-
-positional arguments:
- cluster_id ID of cluster you want to remove machine from.
- machine_id ID of machine to remove from cluster.
- new_manager_id ID of machine to promote to manager. Must already be in cluster
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to HTTPS API endpoints
- --curl show a curl equivalency to the call
- --api-key API_KEY api key. defaults to using the one stored in /home/edgarlin/.config/vastai/vast_api_key
- --version show version
-
-Removes machine from cluster and also reassigns manager ID,
-if we're removing the manager node
-
-```
-
-## remove defjob
-
-\[Host] Delete default jobs
-
-```text Text
-usage: vastai remove defjob id
-
-positional arguments:
- id id of machine to remove default instance from
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## schedule maint
-
-\[Host] Schedule upcoming maint window
-
-```text Text
-usage: vastai schedule maintenance id [--sdate START_DATE --duration DURATION]
-
-positional arguments:
- id id of machine to schedule maintenance for
-
-options:
- -h, --help show this help message and exit
- --sdate SDATE maintenance start date in unix epoch time (UTC seconds)
- --duration DURATION maintenance duration in hours
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-The proper way to perform maintenance on your machine is to wait until all active contracts have expired or the machine is vacant.
-For unplanned or unscheduled maintenance, use this schedule maint command. That will notify the client that you have to take the machine down and that they should save their work.
-You can specify a date and duration.
-Example: vastai schedule maint 8207 --sdate 1677562671 --duration 0.5
-
-```
-
-## set defjob
-
-\[Host] Create default jobs for a machine
-
-```text Text
-usage: vastai set defjob id [--api-key API_KEY] [--price_gpu PRICE_GPU] [--price_inetu PRICE_INETU] [--price_inetd PRICE_INETD] [--image IMAGE] [--args ...]
-
-positional arguments:
- id id of machine to launch default instance on
-
-options:
- -h, --help show this help message and exit
- --price_gpu PRICE_GPU
- per gpu rental price in $/hour
- --price_inetu PRICE_INETU
- price for internet upload bandwidth in $/GB
- --price_inetd PRICE_INETD
- price for internet download bandwidth in $/GB
- --image IMAGE docker container image to launch
- --args ... list of arguments passed to container launch
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-Performs the same action as creating a background job at https://cloud.vast.ai/host/create.
-
-```
-
-## set min-bid
-
-\[Host] Set the minimum bid/rental price for a machine
-
-```text Text
-usage: vastai set min_bid id [--price PRICE]
-
-positional arguments:
- id id of machine to set min bid price for
-
-options:
- -h, --help show this help message and exit
- --price PRICE per gpu min bid price in $/hour
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-Change the current min bid price of machine id to PRICE.
-
-```
-
-## show clusters
-
-Shows information about the host's clusters
-
-```none
-usage: vastai show clusters
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to HTTPS API endpoints
- --curl show a curl equivalency to the call
- --api-key API_KEY api key. defaults to using the one stored in /home/edgarlin/.config/vastai/vast_api_key
- --version show version
-
-Show clusters associated with your account.
-
-```
-
-## show machines
-
-\[Host] Show hosted machines
-
-```text Text
-usage: vastai show machines [OPTIONS]
-
-options:
- -h, --help show this help message and exit
- -q, --quiet only display numeric ids
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
-
-## unlist machine
-
-\[Host] Unlist a listed machine
-
-```text Text
-usage: vastai unlist machine
-
-positional arguments:
- id id of machine to unlist
-
-options:
- -h, --help show this help message and exit
- --url URL server REST api url
- --retry RETRY retry limit
- --raw output machine-readable json
- --explain output verbose explanation of mapping of CLI calls to
- HTTPS API endpoints
- --api-key API_KEY api key. defaults to using the one stored in
- ~/.vast_api_key
-
-```
diff --git a/cli/hello-world.mdx b/cli/hello-world.mdx
new file mode 100644
index 0000000..e1c9d17
--- /dev/null
+++ b/cli/hello-world.mdx
@@ -0,0 +1,216 @@
+---
+title: "CLI Hello World"
+sidebarTitle: "Hello World"
+---
+
+The Vast.ai CLI gives you command-line access to the entire platform — authentication, GPU search, instance lifecycle, templates, volumes, serverless endpoints, and more. Anything you can do in the web console, you can automate from your terminal.
+
+This guide walks through the core workflow: install the CLI, authenticate, search for a GPU, rent it, wait for it to boot, connect to it, copy data, and clean up. By the end you'll understand the commands 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)
+- Python 3 installed
+
+## 1. Install the CLI
+
+Install from PyPI:
+
+```bash
+pip install vastai
+```
+
+Or grab the latest version directly from GitHub:
+
+```bash
+wget https://raw.githubusercontent.com/vast-ai/vast-python/master/vast.py -O vast && chmod +x vast
+```
+
+Verify the installation:
+
+```bash
+vastai --help
+```
+
+## 2. Set Your API Key
+
+Generate an API key from the [Keys page](https://cloud.vast.ai/manage-keys/) by clicking **+New**. Copy the key — you'll only see it once.
+
+Save it to the CLI:
+
+```bash
+vastai set api-key YOUR_API_KEY_HERE
+```
+
+This stores your key in a config file in your home directory. Do not share your API keys with anyone.
+
+
+The console creates a full-access key by default. You can also create scoped keys with limited permissions using `vastai create api-key` — useful for CI/CD or shared tooling. See the [permissions documentation](/api-reference/permissions-and-authorization) for details.
+
+
+## 3. Verify Authentication
+
+Confirm your key works by fetching your account info:
+
+```bash
+vastai show user
+```
+
+This returns your user ID, email, balance, and SSH key. If you see an authentication error, double-check your API key.
+
+## 4. Search for GPUs
+
+Find available machines using `search offers`. This query returns on-demand RTX 4090s on verified machines with direct port access, sorted by deep learning performance per dollar:
+
+```bash
+vastai search offers 'gpu_name=RTX_4090 num_gpus=1 verified=true direct_port_count>=1 rentable=true' -o 'dlperf_usd-'
+```
+
+Each parameter in the query controls a different filter:
+
+| Parameter | Meaning |
+|-----------|---------|
+| `gpu_name=RTX_4090` | Filter to a specific GPU model |
+| `num_gpus=1` | Exactly 1 GPU per instance |
+| `verified=true` | Only machines verified by Vast.ai (identity-checked hosts) |
+| `direct_port_count>=1` | At least 1 directly accessible port (needed for direct SSH) |
+| `rentable=true` | Only machines currently available to rent |
+| `-o 'dlperf_usd-'` | Sort by DL performance per dollar, best value first |
+
+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`).
+
+
+Use `vastai search offers --help` for the full list of filter fields and options, or see the [CLI commands reference](/cli/commands#search-offers).
+
+
+## 5. Register Your SSH Key
+
+**Do this before creating an instance.** Your SSH public key must be registered on your account — it is applied at container creation time.
+
+```bash
+vastai create ssh-key ~/.ssh/id_ed25519.pub
+```
+
+If you don't have a key yet, omit the argument and the CLI will generate one:
+
+```bash
+vastai create ssh-key
+```
+
+Your key persists on your account — you only need to do this once per key. If you forgot and already created an instance, use the SSH key button on the instance card in the console to add a key without recreating.
+
+## 6. Create an Instance
+
+Rent the machine using `create instance` with the offer ID from step 4 (search):
+
+```bash
+vastai create instance OFFER_ID --image pytorch/pytorch:2.4.0-cuda12.4-cudnn9-runtime --disk 20 --onstart-cmd "echo hello && nvidia-smi" --ssh --direct
+```
+
+| Flag | Meaning |
+|------|---------|
+| `--image` | Docker image to launch |
+| `--disk 20` | 20 GB of disk storage |
+| `--onstart-cmd` | Command to run when the instance boots |
+| `--ssh --direct` | Direct SSH access (lower latency than proxy SSH) |
+
+The output includes the new instance ID:
+
+```json
+{"success": true, "new_contract": 12345678}
+```
+
+Save the `new_contract` value — this is your instance ID.
+
+
+Storage charges begin at creation. GPU charges begin when the instance reaches the `running` state.
+
+
+
+`--onstart-cmd` is limited to **4048 characters**. For longer scripts, gzip and base64 encode them — see the [Template Settings](/documentation/templates/template-settings#on-start-script) page for the workaround.
+
+
+## 7. Wait Until Ready
+
+The instance needs time to pull the Docker image and boot. Check the status with:
+
+```bash
+vastai show instance INSTANCE_ID
+```
+
+The `status` field progresses through these states:
+
+| Status | Meaning |
+|--------|---------|
+| `loading` | Docker image is downloading |
+| `running` | Ready to use |
+
+Check every 10–30 seconds. Boot time is typically 1–5 minutes depending on the Docker image size.
+
+
+Always handle non-happy-path statuses in your poll loop. If `status` becomes `exited` (container crashed), `unknown` (no heartbeat from host), or `offline` (host disconnected), it will never reach `running`. Without a timeout or error check, your script will loop forever while the instance continues accruing disk charges. Destroy the instance and retry with a different offer if you see these states.
+
+
+## 8. Connect via SSH
+
+Once the instance is running, get the SSH connection details:
+
+```bash
+vastai ssh-url INSTANCE_ID
+```
+
+Then connect:
+
+```bash
+ssh root@SSH_HOST -p SSH_PORT
+```
+
+## 9. Copy Data
+
+Use `vastai copy` to transfer files between your local machine and the instance:
+
+```bash
+# Upload to instance
+vastai copy local:./data/ INSTANCE_ID:/workspace/data/
+
+# Download from instance
+vastai copy INSTANCE_ID:/workspace/results/ local:./results/
+```
+
+You can also copy between instances or to/from cloud storage:
+
+```bash
+# Instance to instance
+vastai copy INSTANCE_A:/workspace/ INSTANCE_B:/workspace/
+
+# Cloud storage (requires a configured cloud connection)
+vastai copy s3.CONNECTION_ID:/bucket/data/ INSTANCE_ID:/workspace/
+```
+
+For cloud storage syncing and instance-to-instance transfers, see the [data movement guide](/documentation/instances/storage/data-movement).
+
+## 10. 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
+vastai destroy instance INSTANCE_ID
+```
+
+**Stop** (pauses compute, disk charges continue):
+
+```bash
+vastai stop instance INSTANCE_ID
+```
+
+## Next Steps
+
+You've now completed the full instance lifecycle through the CLI: installation, authentication, search, creation, polling, data transfer, and teardown. From here:
+
+- **SSH setup** — See the [SSH guide](/documentation/instances/connect/ssh) for key configuration and advanced connection options.
+- **Full command reference** — See the [CLI commands](/cli/commands) page for every available command.
+- **Use templates** — Avoid repeating image and config parameters on every create call. See the [templates guide](/documentation/templates/introduction) for creating and managing templates.
diff --git a/cli/permissions.mdx b/cli/permissions.mdx
new file mode 100644
index 0000000..54337a2
--- /dev/null
+++ b/cli/permissions.mdx
@@ -0,0 +1,222 @@
+---
+title: "CLI Permissions"
+sidebarTitle: "Permissions"
+---
+
+Every API key has a set of permissions that control which endpoints it can access. This page covers permission categories, how to build scoped keys, and how to manage team roles through the CLI.
+
+For an overview of API key creation and setup, see [Authentication](/cli/authentication).
+
+## Permission Categories
+
+Permissions are organized into categories. When you create a scoped API key, you include only the categories the key needs:
+
+| 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 |
+
+For the complete mapping of which specific endpoints each category controls, see [Permissions (API)](/api-reference/permissions#endpoint-reference-by-category).
+
+## Creating Scoped Keys
+
+Define permissions as a JSON file. The top-level key is always `"api"`, containing the categories you want to grant:
+
+```json
+{
+ "api": {
+ "misc": {},
+ "user_read": {},
+ "instance_read": {},
+ "instance_write": {}
+ }
+}
+```
+
+Save this as `perms.json`, then pass it to the CLI:
+
+```bash
+vastai create api-key --name "ci-deploy-key" --permission_file perms.json
+```
+
+## Constraints
+
+Constraints narrow a permission category to specific parameter values. This lets you create keys that can only operate on certain resources.
+
+### Constrain by Exact ID
+
+This permissions file allows reading logs for instance 1227 only:
+
+```json
+{
+ "api": {
+ "instance_read": {
+ "api.instance.request_logs": {
+ "constraints": {
+ "id": {
+ "eq": 1227
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+### Constrain by Range
+
+You can combine `gte` (greater than or equal) and `lte` (less than or equal) operators to define a range:
+
+```json
+{
+ "api": {
+ "instance_read": {
+ "api.instance.request_logs": {
+ "constraints": {
+ "id": {
+ "gte": 1,
+ "lte": 100
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+Available constraint operators: `eq`, `gte`, `lte`.
+
+
+Keys with constraints must be created through the CLI or API. The web console only creates full-access keys.
+
+
+## Managing Team Roles
+
+Team roles use the same permission model as API keys. You define permissions in a JSON file and pass it to the team role commands.
+
+### Create a Role
+
+```bash
+vastai create team-role --name "developer" --permissions perms.json
+```
+
+### View Roles
+
+List all roles for your team:
+
+```bash
+vastai show team-roles
+```
+
+View a specific role by name:
+
+```bash
+vastai show team-role developer
+```
+
+### Update a Role
+
+```bash
+vastai update team-role 5 --name "senior-dev" --permissions updated-perms.json
+```
+
+### Remove a Role
+
+```bash
+vastai remove team-role developer
+```
+
+### Invite a Team Member
+
+Assign a role when inviting a new member:
+
+```bash
+vastai invite member --email teammate@example.com --role developer
+```
+
+### View Team Members
+
+```bash
+vastai show members
+```
+
+## Examples
+
+### Read-Only Key
+
+A key that can view instances and account info but cannot create, modify, or destroy anything:
+
+```json
+{
+ "api": {
+ "instance_read": {},
+ "user_read": {}
+ }
+}
+```
+
+```bash
+vastai create api-key --name "monitoring" --permission_file readonly.json
+```
+
+### Instance Management Without Billing
+
+A key that can create and manage instances but has no access to billing or credit transfers:
+
+```json
+{
+ "api": {
+ "misc": {},
+ "user_read": {},
+ "instance_read": {},
+ "instance_write": {}
+ }
+}
+```
+
+```bash
+vastai create api-key --name "ci-deploy" --permission_file deploy.json
+```
+
+### Constrained Key for a Specific Instance
+
+A key that can only manage a single instance (view, reboot, destroy) and nothing else:
+
+```json
+{
+ "api": {
+ "instance_read": {
+ "api.instance.show": {
+ "constraints": {
+ "id": { "eq": 1227 }
+ }
+ }
+ },
+ "instance_write": {
+ "api.instance.destroy": {
+ "constraints": {
+ "id": { "eq": 1227 }
+ }
+ },
+ "api.instance.reboot": {
+ "constraints": {
+ "id": { "eq": 1227 }
+ }
+ }
+ }
+ }
+}
+```
+
+```bash
+vastai create api-key --name "instance-1227-only" --permission_file constrained.json
+```
diff --git a/cli/rate-limits.mdx b/cli/rate-limits.mdx
new file mode 100644
index 0000000..51a6587
--- /dev/null
+++ b/cli/rate-limits.mdx
@@ -0,0 +1,84 @@
+---
+title: "CLI Rate Limits and Errors"
+sidebarTitle: "Rate Limits"
+---
+
+The Vast.ai CLI automatically retries rate-limited requests. You do not need to implement your own retry logic -- the CLI handles HTTP 429 responses with exponential backoff out of the box.
+
+This page covers the error format, how rate limits work, and how to configure the CLI's built-in retry behavior. For the full details on rate limit mechanics, see the [API Rate Limits and Errors](/api-reference/rate-limits-and-errors) page.
+
+## Error Responses
+
+When a CLI command fails, it prints the error message from the API and exits with a non-zero status code. The underlying API error shape is:
+
+```json
+{
+ "success": false,
+ "error": "invalid_args",
+ "msg": "Human-readable description of the problem."
+}
+```
+
+Some endpoints omit `success` or `error` and return only `msg` or `message`. The CLI surfaces whatever message the API returns.
+
+## How Rate Limits Work
+
+Vast.ai applies rate limits **per endpoint** and **per identity**. The identity is determined by your bearer token, session user, `api_key` parameter, and client IP.
+
+Some endpoints also enforce **method-specific** limits (GET vs POST) and **max-calls-per-period** limits for short bursts.
+
+For the full breakdown, see [How rate limits are applied](/api-reference/rate-limits-and-errors#how-rate-limits-are-applied).
+
+## Rate Limit Response
+
+When you hit a rate limit, the API returns **HTTP 429** with a message like:
+
+```
+API requests too frequent
+```
+
+or
+
+```
+API requests too frequent: endpoint threshold=...
+```
+
+The API does not return a `Retry-After` header. The CLI handles this automatically using its built-in retry logic.
+
+## Built-in Retry Behavior
+
+When the CLI receives an HTTP 429 response, it automatically retries the request using exponential backoff:
+
+- **Retried status codes:** 429 only
+- **Default retries:** 3
+- **Backoff strategy:** starts at 0.15 seconds, multiplied by 1.5x after each attempt
+- **Retry delays:** ~0.15s, ~0.225s, ~0.34s
+
+For most usage, the defaults handle transient rate limits without any intervention.
+
+
+The CLI only retries on 429 (rate limit). Other HTTP errors (4xx, 5xx) are reported immediately.
+
+
+## Configuring Retries
+
+Use the `--retry` flag on any command to change the number of retry attempts:
+
+```bash
+# Use default 3 retries
+vastai search offers 'gpu_name=RTX_4090 rentable=true'
+
+# Increase to 6 retries for a batch script
+vastai search offers 'gpu_name=RTX_4090 rentable=true' --retry 6
+
+# Disable retries entirely
+vastai search offers 'gpu_name=RTX_4090 rentable=true' --retry 0
+```
+
+Increasing the retry count is useful for scripts that make many API calls in sequence, where occasional rate limiting is expected.
+
+## Reducing Rate Limit Errors
+
+If you are consistently hitting rate limits, the best approach is to reduce the volume and frequency of your requests. See [How to reduce rate limit errors](/api-reference/rate-limits-and-errors#how-to-reduce-rate-limit-errors) for practical strategies including batching, reduced polling, and traffic spreading.
+
+If you need higher limits for production usage, contact support with the endpoint(s), your expected call rate, and your account details.
diff --git a/cli/reference/attach-ssh.mdx b/cli/reference/attach-ssh.mdx
new file mode 100644
index 0000000..8e0aeaa
--- /dev/null
+++ b/cli/reference/attach-ssh.mdx
@@ -0,0 +1,48 @@
+---
+title: "vastai attach ssh"
+sidebarTitle: "attach ssh"
+---
+
+Attach an ssh key to an instance. This will allow you to connect to the instance with the ssh key
+
+## Usage
+
+```bash
+vastai attach ssh instance_id ssh_key
+```
+
+## Arguments
+
+
+ id of instance to attach to
+
+
+
+ ssh key to attach to instance
+
+
+## Description
+
+Attach an ssh key to an instance. This will allow you to connect to the instance with the ssh key.
+
+## Examples
+
+```bash
+vast attach ssh 12371 AAAAB3NzaC1yc2EAAA...
+ vast attach ssh 12371 $(cat ~/.ssh/id_rsa.pub)
+ vast attach ssh 12371 ~/.ssh/id_rsa.pub
+
+All examples attaches the ssh key to instance 12371
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/cancel-copy.mdx b/cli/reference/cancel-copy.mdx
new file mode 100644
index 0000000..dcfaed0
--- /dev/null
+++ b/cli/reference/cancel-copy.mdx
@@ -0,0 +1,42 @@
+---
+title: "vastai cancel copy"
+sidebarTitle: "cancel copy"
+---
+
+Cancel a remote copy in progress, specified by DST id
+
+## Usage
+
+```bash
+vastai cancel copy DST
+```
+
+## Arguments
+
+
+ instance_id:/path to target of copy operation
+
+
+## Description
+
+Use this command to cancel any/all current remote copy operations copying to a specific named instance, given by DST.
+
+## Examples
+
+```bash
+vast cancel copy 12371
+
+The first example cancels all copy operations currently copying data into instance 12371
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/cancel-maint.mdx b/cli/reference/cancel-maint.mdx
new file mode 100644
index 0000000..b817c1a
--- /dev/null
+++ b/cli/reference/cancel-maint.mdx
@@ -0,0 +1,44 @@
+---
+title: "vastai cancel maint"
+sidebarTitle: "cancel maint"
+description: "Host command"
+---
+
+Cancel maint window
+
+This is a **host** command, used for managing machines you are renting out on Vast.ai.
+
+## Usage
+
+```bash
+vastai cancel maint id
+```
+
+## Arguments
+
+
+ id of machine to cancel maintenance(s) for
+
+
+## Description
+
+For deleting a machine's scheduled maintenance window(s), use this cancel maint command.
+Example: vastai cancel maint 8207
+
+## Examples
+
+```bash
+vastai cancel maint
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/cancel-sync.mdx b/cli/reference/cancel-sync.mdx
new file mode 100644
index 0000000..9282352
--- /dev/null
+++ b/cli/reference/cancel-sync.mdx
@@ -0,0 +1,42 @@
+---
+title: "vastai cancel sync"
+sidebarTitle: "cancel sync"
+---
+
+Cancel a remote copy in progress, specified by DST id
+
+## Usage
+
+```bash
+vastai cancel sync DST
+```
+
+## Arguments
+
+
+ instance_id:/path to target of sync operation
+
+
+## Description
+
+Use this command to cancel any/all current remote cloud sync operations copying to a specific named instance, given by DST.
+
+## Examples
+
+```bash
+vast cancel sync 12371
+
+The first example cancels all copy operations currently copying data into instance 12371
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/change-bid.mdx b/cli/reference/change-bid.mdx
new file mode 100644
index 0000000..e446a0b
--- /dev/null
+++ b/cli/reference/change-bid.mdx
@@ -0,0 +1,67 @@
+---
+title: "vastai change bid"
+sidebarTitle: "change bid"
+---
+
+Change the bid price for a spot/interruptible instance
+
+## Usage
+
+```bash
+vastai change bid id [--price PRICE]
+```
+
+## Arguments
+
+
+ id of instance type to change bid
+
+
+## Options
+
+
+ per machine bid price in $/hour
+
+
+
+ try to schedule a command to run hourly, daily, or monthly. Valid values are HOURLY, DAILY, WEEKLY For ex. `--schedule` DAILY Choices: `HOURLY`, `DAILY`, `WEEKLY`
+
+
+
+ Start date/time in format 'YYYY-MM-DD HH:MM:SS PM' (UTC). Default is now. (optional)
+
+
+
+ End date/time in format 'YYYY-MM-DD HH:MM:SS PM' (UTC). Default is 7 days from now. (optional)
+
+
+
+ Day of week you want scheduled job to run on (0-6, where 0=Sunday) or "*". Default will be 0. For ex. `--day` 0
+
+
+
+ Hour of day you want scheduled job to run on (0-23) or "*" (UTC). Default will be 0. For ex. `--hour` 16
+
+
+## Description
+
+Change the current bid price of instance id to PRICE.
+If PRICE is not specified, then a winning bid price is used as the default.
+
+## Examples
+
+```bash
+vastai change bid
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/cleanup-machine.mdx b/cli/reference/cleanup-machine.mdx
new file mode 100644
index 0000000..5aa1661
--- /dev/null
+++ b/cli/reference/cleanup-machine.mdx
@@ -0,0 +1,46 @@
+---
+title: "vastai cleanup machine"
+sidebarTitle: "cleanup machine"
+description: "Host command"
+---
+
+Remove all expired storage instances from the machine, freeing up space
+
+This is a **host** command, used for managing machines you are renting out on Vast.ai.
+
+## Usage
+
+```bash
+vastai cleanup machine ID [options]
+```
+
+## Arguments
+
+
+ id of machine to cleanup
+
+
+## Description
+
+Instances expire on their end date. Expired instances still pay storage fees, but can not start.
+Since hosts are still paid storage fees for expired instances, we do not auto delete them.
+Instead you can use this CLI/API function to delete all expired storage instances for a machine.
+This is useful if you are running low on storage, want to do maintenance, or are subsidizing storage, etc.
+
+## Examples
+
+```bash
+vastai cleanup machine
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/clone-volume.mdx b/cli/reference/clone-volume.mdx
new file mode 100644
index 0000000..448cba6
--- /dev/null
+++ b/cli/reference/clone-volume.mdx
@@ -0,0 +1,55 @@
+---
+title: "vastai clone volume"
+sidebarTitle: "clone volume"
+---
+
+Clone an existing volume
+
+## Usage
+
+```bash
+vastai clone volume [options]
+```
+
+## Arguments
+
+
+ id of volume contract being cloned
+
+
+
+ id of volume offer volume is being copied to
+
+
+## Options
+
+
+ Size of new volume contract, in GB. Must be greater than or equal to the source volume, and less than or equal to the destination offer. (alias: `--size`)
+
+
+
+ Do not compress volume data before copying. (alias: `--disable_compression`)
+
+
+## Description
+
+Create a new volume with the given offer, by copying the existing volume.
+Size defaults to the size of the existing volume, but can be increased if there is available space.
+
+## Examples
+
+```bash
+vastai clone volume
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/cloud-copy.mdx b/cli/reference/cloud-copy.mdx
new file mode 100644
index 0000000..19f2da8
--- /dev/null
+++ b/cli/reference/cloud-copy.mdx
@@ -0,0 +1,106 @@
+---
+title: "vastai cloud copy"
+sidebarTitle: "cloud copy"
+---
+
+Copy files/folders to and from cloud providers
+
+## Usage
+
+```bash
+vastai cloud copy --src SRC --dst DST --instance INSTANCE_ID -connection CONNECTION_ID --transfer TRANSFER_TYPE
+```
+
+## Options
+
+
+ path to source of object to copy
+
+
+
+ path to target of copy operation
+
+
+
+ id of the instance
+
+
+
+ id of cloud connection on your account (get from calling 'vastai show connections')
+
+
+
+ type of transfer, possible options include Instance To Cloud and Cloud To Instance
+
+
+
+ show what would have been transferred
+
+
+
+ skip based on size only, not mod-time or checksum
+
+
+
+ skip all files that exist on destination
+
+
+
+ skip files that are newer on the destination
+
+
+
+ delete files on dest excluded from transfer
+
+
+
+ try to schedule a command to run hourly, daily, or monthly. Valid values are HOURLY, DAILY, WEEKLY For ex. `--schedule` DAILY Choices: `HOURLY`, `DAILY`, `WEEKLY`
+
+
+
+ Start date/time in format 'YYYY-MM-DD HH:MM:SS PM' (UTC). Default is now. (optional)
+
+
+
+ End date/time in format 'YYYY-MM-DD HH:MM:SS PM' (UTC). Default is contract's end. (optional)
+
+
+
+ Day of week you want scheduled job to run on (0-6, where 0=Sunday) or "*". Default will be 0. For ex. `--day` 0
+
+
+
+ Hour of day you want scheduled job to run on (0-23) or "*" (UTC). Default will be 0. For ex. `--hour` 16
+
+
+## Description
+
+Copies a directory from a source location to a target location. Each of source and destination
+directories can be either local or remote, subject to appropriate read and write
+permissions required to carry out the action. The format for both src and dst is [instance_id:]path.
+You can find more information about the cloud copy operation here: https://vast.ai/docs/gpu-instances/cloud-sync
+
+## Examples
+
+```bash
+vastai show connections
+ ID NAME Cloud Type
+ 1001 test_dir drive
+ 1003 data_dir drive
+
+ vastai cloud copy --src /folder --dst /workspace --instance 6003036 --connection 1001 --transfer "Instance To Cloud"
+
+The example copies all contents of /folder into /workspace on instance 6003036 from gdrive connection 'test_dir'.
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/copy.mdx b/cli/reference/copy.mdx
new file mode 100644
index 0000000..0b831e8
--- /dev/null
+++ b/cli/reference/copy.mdx
@@ -0,0 +1,75 @@
+---
+title: "vastai copy"
+sidebarTitle: "copy"
+---
+
+Copy directories between instances and/or local
+
+## Usage
+
+```bash
+vastai copy SRC DST
+```
+
+## Arguments
+
+
+ Source location for copy operation (supports multiple formats)
+
+
+
+ Target location for copy operation (supports multiple formats)
+
+
+## Options
+
+
+ Location of ssh private key (alias: `--identity`)
+
+
+## Description
+
+Copies a directory from a source location to a target location. Each of source and destination
+directories can be either local or remote, subject to appropriate read and write
+permissions required to carry out the action.
+
+Supported location formats:
+- [instance_id:]path (legacy format, still supported)
+- C.instance_id:path (container copy format)
+- cloud_service:path (cloud service format)
+- cloud_service.cloud_service_id:path (cloud service with ID)
+- local:path (explicit local path)
+- V.volume_id:path (volume copy, see restrictions)
+
+You should not copy to /root or / as a destination directory, as this can mess up the permissions on your instance ssh folder, breaking future copy operations (as they use ssh authentication)
+You can see more information about constraints here: https://vast.ai/docs/gpu-instances/data-movement#constraints
+Volume copy is currently only supported for copying to other volumes or instances, not cloud services or local.
+
+## Examples
+
+```bash
+vast copy 6003036:/workspace/ 6003038:/workspace/
+ vast copy C.11824:/data/test local:data/test
+ vast copy local:data/test C.11824:/data/test
+ vast copy drive:/folder/file.txt C.6003036:/workspace/
+ vast copy s3.101:/data/ C.6003036:/workspace/
+ vast copy V.1234:/file C.5678:/workspace/
+
+The first example copy syncs all files from the absolute directory '/workspace' on instance 6003036 to the directory '/workspace' on instance 6003038.
+The second example copy syncs files from container 11824 to the local machine using structured syntax.
+The third example copy syncs files from local to container 11824 using structured syntax.
+The fourth example copy syncs files from Google Drive to an instance.
+The fifth example copy syncs files from S3 bucket with id 101 to an instance.
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/create-api-key.mdx b/cli/reference/create-api-key.mdx
new file mode 100644
index 0000000..6a2d9f2
--- /dev/null
+++ b/cli/reference/create-api-key.mdx
@@ -0,0 +1,49 @@
+---
+title: "vastai create api-key"
+sidebarTitle: "create api-key"
+---
+
+Create a new api-key with restricted permissions. Can be sent to other users and teammates
+
+## Usage
+
+```bash
+vastai create api-key --name NAME --permission_file PERMISSIONS
+```
+
+## Options
+
+
+ name of the api-key
+
+
+
+ file path for json encoded permissions, see https://vast.ai/docs/cli/roles-and-permissions for more information
+
+
+
+ optional wildcard key params for advanced keys
+
+
+## Description
+
+In order to create api keys you must understand how permissions must be sent via json format.
+You can find more information about permissions here: https://vast.ai/docs/cli/roles-and-permissions
+
+## Examples
+
+```bash
+vastai create api-key
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/create-cluster.mdx b/cli/reference/create-cluster.mdx
new file mode 100644
index 0000000..fdde9d9
--- /dev/null
+++ b/cli/reference/create-cluster.mdx
@@ -0,0 +1,44 @@
+---
+title: "vastai create cluster"
+sidebarTitle: "create cluster"
+---
+
+Create Vast cluster
+
+## Usage
+
+```bash
+vastai create cluster SUBNET MANAGER_ID
+```
+
+## Arguments
+
+
+ local subnet for cluster, ex: '0.0.0.0/24'
+
+
+
+ Machine ID of manager node in cluster. Must exist already.
+
+
+## Description
+
+Create Vast Cluster by defining a local subnet and manager id.
+
+## Examples
+
+```bash
+vastai create cluster
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/create-endpoint.mdx b/cli/reference/create-endpoint.mdx
new file mode 100644
index 0000000..79bd945
--- /dev/null
+++ b/cli/reference/create-endpoint.mdx
@@ -0,0 +1,78 @@
+---
+title: "vastai create endpoint"
+sidebarTitle: "create endpoint"
+---
+
+Create a new endpoint group
+
+## Usage
+
+```bash
+vastai create endpoint [OPTIONS]
+```
+
+## Options
+
+
+ minimum floor load in perf units/s (token/s for LLms)
+
+
+
+ minimum floor load in perf units/s (token/s for LLms), but allow handling with cold workers
+
+
+
+ target capacity utilization (fraction, max 1.0, default 0.9)
+
+
+
+ cold/stopped instance capacity target as multiple of hot capacity target (default 2.5)
+
+
+
+ min number of workers to keep 'cold' when you have no load (default 5)
+
+
+
+ max number of workers your endpoint group can have (default 20)
+
+
+
+ deployment endpoint name (allows multiple autoscale groups to share same deployment endpoint)
+
+
+
+ maximum seconds requests may be queued on each worker (default 30.0)
+
+
+
+ target seconds for the queue to be cleared (default 10.0)
+
+
+
+ seconds of no traffic before the endpoint can scale to zero active workers
+
+
+## Description
+
+Create a new endpoint group to manage many autoscaling groups
+
+Example: vastai create endpoint `--target_util` 0.9 `--cold_mult` 2.0 `--endpoint_name` "LLama"
+
+## Examples
+
+```bash
+vastai create endpoint
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/create-env-var.mdx b/cli/reference/create-env-var.mdx
new file mode 100644
index 0000000..847b549
--- /dev/null
+++ b/cli/reference/create-env-var.mdx
@@ -0,0 +1,40 @@
+---
+title: "vastai create env-var"
+sidebarTitle: "create env-var"
+---
+
+Create a new user environment variable
+
+## Usage
+
+```bash
+vastai create env-var
+```
+
+## Arguments
+
+
+ Environment variable name
+
+
+
+ Environment variable value
+
+
+## Examples
+
+```bash
+vastai create env-var
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/create-instance.mdx b/cli/reference/create-instance.mdx
new file mode 100644
index 0000000..faf04d2
--- /dev/null
+++ b/cli/reference/create-instance.mdx
@@ -0,0 +1,170 @@
+---
+title: "vastai create instance"
+sidebarTitle: "create instance"
+---
+
+Create a new instance
+
+## Usage
+
+```bash
+vastai create instance ID [OPTIONS] [--args ...]
+```
+
+## Arguments
+
+
+ id of instance type to launch (returned from search offers)
+
+
+## Options
+
+
+ Create instance from template info
+
+
+
+ User to use with docker create. This breaks some images, so only use this if you are certain you need it.
+
+
+
+ size of local disk partition in GB
+
+
+
+ docker container image to launch
+
+
+
+ docker login arguments for private repo authentication, surround with ''
+
+
+
+ label to set on the instance
+
+
+
+ filename to use as onstart script
+
+
+
+ contents of onstart script as single argument
+
+
+
+ override entrypoint for args launch instance
+
+
+
+ Launch as an ssh instance type
+
+
+
+ Launch as a jupyter instance instead of an ssh instance
+
+
+
+ Use (faster) direct connections for jupyter & ssh
+
+
+
+ For runtype 'jupyter', directory in instance to use to launch jupyter. Defaults to image's working directory
+
+
+
+ For runtype 'jupyter', Launch instance with jupyter lab
+
+
+
+ Workaround for images with locale problems: install and generate locales before instance launch, and set locale to C.UTF-8
+
+
+
+ Workaround for images with locale problems: set python's locale to C.UTF-8
+
+
+
+ env variables and port mapping options, surround with ''
+
+
+
+ list of arguments passed to container ENTRYPOINT. Onstart is recommended for this purpose. (must be last argument)
+
+
+
+ Skip sanity checks when creating from an existing instance
+
+
+
+ Return error if scheduling fails (rather than creating a stopped instance)
+
+
+
+ (OPTIONAL) create an INTERRUPTIBLE instance with per machine bid price in $/hour
+
+
+
+ Create a new local volume using an ID returned from the "search volumes" command and link it to the new instance
+
+
+
+ ID of an existing rented volume to link to the instance during creation. (returned from "show volumes" cmd)
+
+
+
+ Size of the volume to create in GB. Only usable with `--create-volume` (default 15GB)
+
+
+
+ The path to the volume from within the new instance container. e.g. /root/volume
+
+
+
+ (optional) A name to give the new volume. Only usable with `--create-volume`
+
+
+## Description
+
+Performs the same action as pressing the "RENT" button on the website at https://console.vast.ai/create/
+Creates an instance from an offer ID (which is returned from "search offers"). Each offer ID can only be used to create one instance.
+Besides the offer ID, you must pass in an '`--image`' argument as a minimum.
+
+If you use args/entrypoint launch mode, we create a container from your image as is, without attempting to inject ssh and or jupyter.
+If you use the args launch mode, you can override the entrypoint with `--entrypoint`, and pass arguments to the entrypoint with `--args`.
+If you use `--args`, that must be the last argument, as any following tokens are consumed into the args string.
+For ssh/jupyter launch types, use `--onstart-cmd` to pass in startup script, instead of `--entrypoint` and `--args`.
+
+## Examples
+
+```bash
+# create an on-demand instance with the PyTorch (cuDNN Devel) template and 64GB of disk
+vastai create instance 384826 --template_hash 661d064bbda1f2a133816b6d55da07c3 --disk 64
+
+# create an on-demand instance with the pytorch/pytorch image, 40GB of disk, open 8081 udp, direct ssh, set hostname to billybob, and a small onstart script
+vastai create instance 6995713 --image pytorch/pytorch --disk 40 --env '-p 8081:8081/udp -h billybob' --ssh --direct --onstart-cmd "env | grep _ >> /etc/environment; echo 'starting up'";
+
+# create an on-demand instance with the bobsrepo/pytorch:latest image, 20GB of disk, open 22, 8080, jupyter ssh, and set some env variables
+vastai create instance 384827 --image bobsrepo/pytorch:latest --login '-u bob -p 9d8df!fd89ufZ docker.io' --jupyter --direct --env '-e TZ=PDT -e XNAME=XX4 -p 22:22 -p 8080:8080' --disk 20
+
+# create an on-demand instance with the pytorch/pytorch image, 40GB of disk, override the entrypoint to bash and pass bash a simple command to keep the instance running. (args launch without ssh/jupyter)
+vastai create instance 5801802 --image pytorch/pytorch --disk 40 --onstart-cmd 'bash' --args -c 'echo hello; sleep infinity;'
+
+# create an interruptible (spot) instance with the PyTorch (cuDNN Devel) template, 64GB of disk, and a bid price of $0.10/hr
+vastai create instance 384826 --template_hash 661d064bbda1f2a133816b6d55da07c3 --disk 64 --bid_price 0.1
+
+Return value:
+Returns a json reporting the instance ID of the newly created instance:
+{'success': True, 'new_contract': 7835610}
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/create-overlay.mdx b/cli/reference/create-overlay.mdx
new file mode 100644
index 0000000..ea201b0
--- /dev/null
+++ b/cli/reference/create-overlay.mdx
@@ -0,0 +1,44 @@
+---
+title: "vastai create overlay"
+sidebarTitle: "create overlay"
+---
+
+Creates overlay network on top of a physical cluster
+
+## Usage
+
+```bash
+vastai create overlay CLUSTER_ID OVERLAY_NAME
+```
+
+## Arguments
+
+
+ ID of cluster to create overlay on top of
+
+
+
+ overlay network name
+
+
+## Description
+
+Creates an overlay network to allow local networking between instances on a physical cluster
+
+## Examples
+
+```bash
+vastai create overlay
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/create-ssh-key.mdx b/cli/reference/create-ssh-key.mdx
new file mode 100644
index 0000000..e147a08
--- /dev/null
+++ b/cli/reference/create-ssh-key.mdx
@@ -0,0 +1,59 @@
+---
+title: "vastai create ssh-key"
+sidebarTitle: "create ssh-key"
+---
+
+Create a new ssh-key
+
+## Usage
+
+```bash
+vastai create ssh-key [ssh_public_key] [-y]
+```
+
+## Arguments
+
+
+ add your existing ssh public key to your account (from the .pub file). If no public key is provided, a new key pair will be generated.
+
+
+## Options
+
+
+ automatically answer yes to prompts (alias: `--yes`)
+
+
+## Description
+
+You may use this command to add an existing public key, or create a new ssh key pair and add that public key, to your Vast account.
+
+If you provide an ssh_public_key.pub argument, that public key will be added to your Vast account. All ssh public keys should be in OpenSSH format.
+
+ Example: $vastai create ssh-key 'ssh_public_key.pub'
+
+If you don't provide an ssh_public_key.pub argument, a new Ed25519 key pair will be generated.
+
+ Example: $vastai create ssh-key
+
+The generated keys are saved as ~/.ssh/id_ed25519 (private) and ~/.ssh/id_ed25519.pub (public). Any existing id_ed25519 keys are backed up as .backup_<timestamp>.
+The public key will be added to your Vast account.
+
+All ssh public keys are stored in your Vast account and can be used to connect to instances they've been added to.
+
+## Examples
+
+```bash
+vastai create ssh-key
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/create-subaccount.mdx b/cli/reference/create-subaccount.mdx
new file mode 100644
index 0000000..9f45232
--- /dev/null
+++ b/cli/reference/create-subaccount.mdx
@@ -0,0 +1,56 @@
+---
+title: "vastai create subaccount"
+sidebarTitle: "create subaccount"
+---
+
+Create a subaccount
+
+## Usage
+
+```bash
+vastai create subaccount --email EMAIL --username USERNAME --password PASSWORD --type TYPE
+```
+
+## Options
+
+
+ email address to use for login
+
+
+
+ username to use for login
+
+
+
+ password to use for login
+
+
+
+ host/client
+
+
+## Description
+
+Creates a new account that is considered a child of your current account as defined via the API key.
+
+vastai create subaccount `--email` bob@gmail.com `--username` bob `--password` password `--type` host
+
+vastai create subaccount `--email` vast@gmail.com `--username` vast `--password` password `--type` host
+
+## Examples
+
+```bash
+vastai create subaccount
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/create-team-role.mdx b/cli/reference/create-team-role.mdx
new file mode 100644
index 0000000..19eb4c4
--- /dev/null
+++ b/cli/reference/create-team-role.mdx
@@ -0,0 +1,45 @@
+---
+title: "vastai create team-role"
+sidebarTitle: "create team-role"
+---
+
+Add a new role to your team
+
+## Usage
+
+```bash
+vastai create team-role --name NAME --permissions PERMISSIONS
+```
+
+## Options
+
+
+ name of the role
+
+
+
+ file path for json encoded permissions, look in the docs for more information
+
+
+## Description
+
+Creating a new team role involves understanding how permissions must be sent via json format.
+You can find more information about permissions here: https://vast.ai/docs/cli/roles-and-permissions
+
+## Examples
+
+```bash
+vastai create team-role
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/create-team.mdx b/cli/reference/create-team.mdx
new file mode 100644
index 0000000..8a24058
--- /dev/null
+++ b/cli/reference/create-team.mdx
@@ -0,0 +1,64 @@
+---
+title: "vastai create team"
+sidebarTitle: "create team"
+---
+
+Create a new team
+
+## Usage
+
+```bash
+vastai create team [OPTIONS]
+```
+
+## Options
+
+
+ name of the team
+
+
+
+ amount of personal credit to transfer to the new team
+
+
+## Description
+
+Creates a new team under your account.
+
+Unlike legacy teams, this command does NOT convert your personal account into a team.
+Each team is created as a separate account, and you can be a member of multiple teams.
+
+When you create a team:
+ - You become the team owner.
+ - The team starts as an independent account with its own billing, credits, and resources.
+ - Default roles (owner, manager, member) are automatically created.
+ - You can invite others, assign roles, and manage resources within the team.
+
+Optional:
+ You can transfer a portion of your existing personal credits to the team by using
+ the `--transfer_credit` flag. Example:
+ vastai create-team `--team_name` myteam `--transfer_credit` 25
+
+Notes:
+ - You cannot create a team from within another team account.
+
+For more details, see:
+https://vast.ai/docs/teams-quickstart
+
+## Examples
+
+```bash
+vastai create team
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/create-template.mdx b/cli/reference/create-template.mdx
new file mode 100644
index 0000000..bde973b
--- /dev/null
+++ b/cli/reference/create-template.mdx
@@ -0,0 +1,120 @@
+---
+title: "vastai create template"
+sidebarTitle: "create template"
+---
+
+Create a new template
+
+## Usage
+
+```bash
+vastai create template
+```
+
+## Options
+
+
+ name of the template
+
+
+
+ docker container image to launch
+
+
+
+ docker image tag (can also be appended to end of image_path)
+
+
+
+ link you want to provide
+
+
+
+ link to repository
+
+
+
+ docker login arguments for private repo authentication, surround with ''
+
+
+
+ Contents of the 'Docker options' field
+
+
+
+ Launch as an ssh instance type
+
+
+
+ Launch as a jupyter instance instead of an ssh instance
+
+
+
+ Use (faster) direct connections for jupyter & ssh
+
+
+
+ For runtype 'jupyter', directory in instance to use to launch jupyter. Defaults to image's working directory
+
+
+
+ For runtype 'jupyter', Launch instance with jupyter lab
+
+
+
+ contents of onstart script as single argument
+
+
+
+ search offers filters
+
+
+
+ Disable default search param query args (alias: `--no-default`)
+
+
+
+ disk storage space, in GB
+
+
+
+ readme string
+
+
+
+ hide the readme from users
+
+
+
+ description string
+
+
+
+ make template available to public
+
+
+## Description
+
+Create a template that can be used to create instances with
+
+## Examples
+
+```bash
+vastai create template --name "tgi-llama2-7B-quantized" --image "ghcr.io/huggingface/text-generation-inference:1.0.3"
+ --env "-p 3000:3000 -e MODEL_ARGS='--model-id TheBloke/Llama-2-7B-chat-GPTQ --quantize gptq'"
+ --onstart-cmd 'wget -O - https://raw.githubusercontent.com/vast-ai/vast-pyworker/main/scripts/launch_tgi.sh | bash'
+ --search_params "gpu_ram>=23 num_gpus=1 gpu_name=RTX_3090 inet_down>128 direct_port_count>3 disk_space>=192 driver_version>=535086005 rented=False"
+ --disk_space 8.0 --ssh --direct
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/create-volume.mdx b/cli/reference/create-volume.mdx
new file mode 100644
index 0000000..3bee47d
--- /dev/null
+++ b/cli/reference/create-volume.mdx
@@ -0,0 +1,51 @@
+---
+title: "vastai create volume"
+sidebarTitle: "create volume"
+---
+
+Create a new volume
+
+## Usage
+
+```bash
+vastai create volume ID [options]
+```
+
+## Arguments
+
+
+ id of volume offer
+
+
+## Options
+
+
+ size in GB of volume. Default 15 GB. (alias: `--size`)
+
+
+
+ Optional name of volume. (alias: `--name`)
+
+
+## Description
+
+Creates a volume from an offer ID (which is returned from "search volumes"). Each offer ID can be used to create multiple volumes,
+provided the size of all volumes does not exceed the size of the offer.
+
+## Examples
+
+```bash
+vastai create volume
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/create-workergroup.mdx b/cli/reference/create-workergroup.mdx
new file mode 100644
index 0000000..7a90a91
--- /dev/null
+++ b/cli/reference/create-workergroup.mdx
@@ -0,0 +1,90 @@
+---
+title: "vastai create workergroup"
+sidebarTitle: "create workergroup"
+---
+
+Create a new autoscale group
+
+## Usage
+
+```bash
+vastai create workergroup [OPTIONS]
+```
+
+## Options
+
+
+ template hash (required, but **Note**: if you use this field, you can skip search_params, as they are automatically inferred from the template)
+
+
+
+ template id (optional)
+
+
+
+ Disable default search param query args (alias: `--no-default`)
+
+
+
+ launch args string for create instance ex: "`--onstart` onstart_wget.sh `--env` '-e ONSTART_PATH=https://s3.amazonaws.com/vast.ai/onstart_OOBA.sh' `--image` atinoda/text-generation-webui:default-nightly `--disk` 64"
+
+
+
+ deployment endpoint name (allows multiple workergroups to share same deployment endpoint)
+
+
+
+ deployment endpoint id (allows multiple workergroups to share same deployment endpoint)
+
+
+
+ number of workers to create to get an performance estimate for while initializing workergroup (default 3)
+
+
+
+ estimated GPU RAM req (independent of search string)
+
+
+
+ search param string for search offers ex: "gpu_ram>=23 num_gpus=2 gpu_name=RTX_4090 inet_down>200 direct_port_count>2 disk_space>=64"
+
+
+
+ [NOTE: this field isn't currently used at the workergroup level] minimum floor load in perf units/s (token/s for LLms)
+
+
+
+ [NOTE: this field isn't currently used at the workergroup level] target capacity utilization (fraction, max 1.0, default 0.9)
+
+
+
+ [NOTE: this field isn't currently used at the workergroup level]cold/stopped instance capacity target as multiple of hot capacity target (default 2.0)
+
+
+
+ min number of workers to keep 'cold' for this workergroup
+
+
+## Description
+
+Create a new autoscaling group to manage a pool of worker instances.
+
+Example: vastai create workergroup `--template_hash` HASH `--endpoint_name` "LLama" `--test_workers` 5
+
+## Examples
+
+```bash
+vastai create workergroup
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/defrag-machines.mdx b/cli/reference/defrag-machines.mdx
new file mode 100644
index 0000000..ab97037
--- /dev/null
+++ b/cli/reference/defrag-machines.mdx
@@ -0,0 +1,43 @@
+---
+title: "vastai defrag machines"
+sidebarTitle: "defrag machines"
+description: "Host command"
+---
+
+Defragment machines
+
+This is a **host** command, used for managing machines you are renting out on Vast.ai.
+
+## Usage
+
+```bash
+vastai defragment machines IDs
+```
+
+## Arguments
+
+
+ ids of machines
+
+
+## Description
+
+Defragment some of your machines. This will rearrange GPU assignments to try and make more multi-gpu offers available.
+
+## Examples
+
+```bash
+vastai defrag machines
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/delete-api-key.mdx b/cli/reference/delete-api-key.mdx
new file mode 100644
index 0000000..3d45bfd
--- /dev/null
+++ b/cli/reference/delete-api-key.mdx
@@ -0,0 +1,36 @@
+---
+title: "vastai delete api-key"
+sidebarTitle: "delete api-key"
+---
+
+Remove an api-key
+
+## Usage
+
+```bash
+vastai delete api-key ID
+```
+
+## Arguments
+
+
+ id of apikey to remove
+
+
+## Examples
+
+```bash
+vastai delete api-key
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/delete-cluster.mdx b/cli/reference/delete-cluster.mdx
new file mode 100644
index 0000000..df9c435
--- /dev/null
+++ b/cli/reference/delete-cluster.mdx
@@ -0,0 +1,40 @@
+---
+title: "vastai delete cluster"
+sidebarTitle: "delete cluster"
+---
+
+Delete Cluster
+
+## Usage
+
+```bash
+vastai delete cluster CLUSTER_ID
+```
+
+## Arguments
+
+
+ ID of cluster to delete
+
+
+## Description
+
+Delete Vast Cluster
+
+## Examples
+
+```bash
+vastai delete cluster
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/delete-deployment.mdx b/cli/reference/delete-deployment.mdx
new file mode 100644
index 0000000..f78142b
--- /dev/null
+++ b/cli/reference/delete-deployment.mdx
@@ -0,0 +1,48 @@
+---
+title: "vastai delete deployment"
+sidebarTitle: "delete deployment"
+---
+
+Delete a deployment by id, or by name and optional tag
+
+## Usage
+
+```bash
+vastai delete deployment [ID | --name NAME [--tag TAG]]
+```
+
+## Arguments
+
+
+ id of deployment to delete
+
+
+## Options
+
+
+ name of deployment to delete (deletes all tags unless `--tag` is specified)
+
+
+
+ tag to filter by when deleting by name
+
+
+## Examples
+
+```bash
+vastai delete deployment 1234
+vastai delete deployment --name my-deployment
+vastai delete deployment --name my-deployment --tag prod
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/delete-endpoint.mdx b/cli/reference/delete-endpoint.mdx
new file mode 100644
index 0000000..5bc3307
--- /dev/null
+++ b/cli/reference/delete-endpoint.mdx
@@ -0,0 +1,40 @@
+---
+title: "vastai delete endpoint"
+sidebarTitle: "delete endpoint"
+---
+
+Delete an endpoint group
+
+## Usage
+
+```bash
+vastai delete endpoint ID
+```
+
+## Arguments
+
+
+ id of endpoint group to delete
+
+
+## Description
+
+Example: vastai delete endpoint 4242
+
+## Examples
+
+```bash
+vastai delete endpoint
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/delete-env-var.mdx b/cli/reference/delete-env-var.mdx
new file mode 100644
index 0000000..9b828ce
--- /dev/null
+++ b/cli/reference/delete-env-var.mdx
@@ -0,0 +1,36 @@
+---
+title: "vastai delete env-var"
+sidebarTitle: "delete env-var"
+---
+
+Delete a user environment variable
+
+## Usage
+
+```bash
+vastai delete env-var
+```
+
+## Arguments
+
+
+ Environment variable name to delete
+
+
+## Examples
+
+```bash
+vastai delete env-var
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/delete-machine.mdx b/cli/reference/delete-machine.mdx
new file mode 100644
index 0000000..3a01564
--- /dev/null
+++ b/cli/reference/delete-machine.mdx
@@ -0,0 +1,39 @@
+---
+title: "vastai delete machine"
+sidebarTitle: "delete machine"
+description: "Host command"
+---
+
+Delete machine if the machine is not being used by clients. host jobs on their own machines are disregarded and machine is force deleted.
+
+This is a **host** command, used for managing machines you are renting out on Vast.ai.
+
+## Usage
+
+```bash
+vastai delete machine
+```
+
+## Arguments
+
+
+ id of machine to delete
+
+
+## Examples
+
+```bash
+vastai delete machine
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/delete-overlay.mdx b/cli/reference/delete-overlay.mdx
new file mode 100644
index 0000000..7280e11
--- /dev/null
+++ b/cli/reference/delete-overlay.mdx
@@ -0,0 +1,36 @@
+---
+title: "vastai delete overlay"
+sidebarTitle: "delete overlay"
+---
+
+Deletes overlay and removes all of its associated instances
+
+## Usage
+
+```bash
+vastai delete overlay OVERLAY_IDENTIFIER
+```
+
+## Arguments
+
+
+ ID (int) or name (str) of overlay to delete
+
+
+## Examples
+
+```bash
+vastai delete overlay
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/delete-scheduled-job.mdx b/cli/reference/delete-scheduled-job.mdx
new file mode 100644
index 0000000..0870cff
--- /dev/null
+++ b/cli/reference/delete-scheduled-job.mdx
@@ -0,0 +1,36 @@
+---
+title: "vastai delete scheduled-job"
+sidebarTitle: "delete scheduled-job"
+---
+
+Delete a scheduled job
+
+## Usage
+
+```bash
+vastai delete scheduled-job ID
+```
+
+## Arguments
+
+
+ id of scheduled job to remove
+
+
+## Examples
+
+```bash
+vastai delete scheduled-job
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/delete-ssh-key.mdx b/cli/reference/delete-ssh-key.mdx
new file mode 100644
index 0000000..bcbd584
--- /dev/null
+++ b/cli/reference/delete-ssh-key.mdx
@@ -0,0 +1,36 @@
+---
+title: "vastai delete ssh-key"
+sidebarTitle: "delete ssh-key"
+---
+
+Remove an ssh-key
+
+## Usage
+
+```bash
+vastai delete ssh-key ID
+```
+
+## Arguments
+
+
+ id ssh key to delete
+
+
+## Examples
+
+```bash
+vastai delete ssh-key
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/delete-template.mdx b/cli/reference/delete-template.mdx
new file mode 100644
index 0000000..c08eb16
--- /dev/null
+++ b/cli/reference/delete-template.mdx
@@ -0,0 +1,46 @@
+---
+title: "vastai delete template"
+sidebarTitle: "delete template"
+---
+
+Delete a Template
+
+## Usage
+
+```bash
+vastai delete template [--template-id | --hash-id ]
+```
+
+## Options
+
+
+ Template ID of Template to Delete
+
+
+
+ Hash ID of Template to Delete
+
+
+## Description
+
+Note: Deleting a template only removes the user's replationship to a template. It does not get destroyed
+Example: vastai delete template `--template-id` 12345
+Example: vastai delete template `--hash-id` 49c538d097ad6437413b83711c9f61e8
+
+## Examples
+
+```bash
+vastai delete template
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/delete-volume.mdx b/cli/reference/delete-volume.mdx
new file mode 100644
index 0000000..572cd5f
--- /dev/null
+++ b/cli/reference/delete-volume.mdx
@@ -0,0 +1,40 @@
+---
+title: "vastai delete volume"
+sidebarTitle: "delete volume"
+---
+
+Delete a volume
+
+## Usage
+
+```bash
+vastai delete volume ID
+```
+
+## Arguments
+
+
+ id of volume contract
+
+
+## Description
+
+Deletes volume with the given ID. All instances using the volume must be destroyed before the volume can be deleted.
+
+## Examples
+
+```bash
+vastai delete volume
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/delete-workergroup.mdx b/cli/reference/delete-workergroup.mdx
new file mode 100644
index 0000000..2abf44d
--- /dev/null
+++ b/cli/reference/delete-workergroup.mdx
@@ -0,0 +1,41 @@
+---
+title: "vastai delete workergroup"
+sidebarTitle: "delete workergroup"
+---
+
+Delete a workergroup group
+
+## Usage
+
+```bash
+vastai delete workergroup ID
+```
+
+## Arguments
+
+
+ id of group to delete
+
+
+## Description
+
+Note that deleting a workergroup doesn't automatically destroy all the instances that are associated with your workergroup.
+Example: vastai delete workergroup 4242
+
+## Examples
+
+```bash
+vastai delete workergroup
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/destroy-instance.mdx b/cli/reference/destroy-instance.mdx
new file mode 100644
index 0000000..1bf8eaa
--- /dev/null
+++ b/cli/reference/destroy-instance.mdx
@@ -0,0 +1,41 @@
+---
+title: "vastai destroy instance"
+sidebarTitle: "destroy instance"
+---
+
+Destroy an instance (irreversible, deletes data)
+
+## Usage
+
+```bash
+vastai destroy instance id [-h] [--api-key API_KEY] [--raw]
+```
+
+## Arguments
+
+
+ id of instance to delete
+
+
+## Description
+
+Perfoms the same action as pressing the "DESTROY" button on the website at https://console.vast.ai/instances/
+Example: vastai destroy instance 4242
+
+## Examples
+
+```bash
+vastai destroy instance
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/destroy-instances.mdx b/cli/reference/destroy-instances.mdx
new file mode 100644
index 0000000..b42b7a6
--- /dev/null
+++ b/cli/reference/destroy-instances.mdx
@@ -0,0 +1,36 @@
+---
+title: "vastai destroy instances"
+sidebarTitle: "destroy instances"
+---
+
+Destroy a list of instances (irreversible, deletes data)
+
+## Usage
+
+```bash
+vastai destroy instances [--raw]
+```
+
+## Arguments
+
+
+ ids of instance to destroy
+
+
+## Examples
+
+```bash
+vastai destroy instances
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/destroy-team.mdx b/cli/reference/destroy-team.mdx
new file mode 100644
index 0000000..e55c780
--- /dev/null
+++ b/cli/reference/destroy-team.mdx
@@ -0,0 +1,30 @@
+---
+title: "vastai destroy team"
+sidebarTitle: "destroy team"
+---
+
+Destroy your team
+
+## Usage
+
+```bash
+vastai destroy team
+```
+
+## Examples
+
+```bash
+vastai destroy team
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/detach-ssh.mdx b/cli/reference/detach-ssh.mdx
new file mode 100644
index 0000000..e2e16c6
--- /dev/null
+++ b/cli/reference/detach-ssh.mdx
@@ -0,0 +1,44 @@
+---
+title: "vastai detach ssh"
+sidebarTitle: "detach ssh"
+---
+
+Detach an ssh key from an instance
+
+## Usage
+
+```bash
+vastai detach instance_id ssh_key_id
+```
+
+## Arguments
+
+
+ id of the instance
+
+
+
+ id of the key to detach to the instance
+
+
+## Description
+
+Example: vastai detach 99999 12345
+
+## Examples
+
+```bash
+vastai detach ssh
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/execute.mdx b/cli/reference/execute.mdx
new file mode 100644
index 0000000..50485c6
--- /dev/null
+++ b/cli/reference/execute.mdx
@@ -0,0 +1,76 @@
+---
+title: "vastai execute"
+sidebarTitle: "execute"
+---
+
+Execute a (constrained) remote command on a machine
+
+## Usage
+
+```bash
+vastai execute id COMMAND
+```
+
+## Arguments
+
+
+ id of instance to execute on
+
+
+
+ bash command surrounded by single quotes
+
+
+## Options
+
+
+ try to schedule a command to run hourly, daily, or monthly. Valid values are HOURLY, DAILY, WEEKLY For ex. `--schedule` DAILY Choices: `HOURLY`, `DAILY`, `WEEKLY`
+
+
+
+ Start date/time in format 'YYYY-MM-DD HH:MM:SS PM' (UTC). Default is now. (optional)
+
+
+
+ End date/time in format 'YYYY-MM-DD HH:MM:SS PM' (UTC). Default is 7 days from now. (optional)
+
+
+
+ Day of week you want scheduled job to run on (0-6, where 0=Sunday) or "*". Default will be 0. For ex. `--day` 0
+
+
+
+ Hour of day you want scheduled job to run on (0-23) or "*" (UTC). Default will be 0. For ex. `--hour` 16
+
+
+## Description
+
+Available commands:
+
+| Command | Description |
+|---------|-------------|
+| `ls` | List directory contents |
+| `rm` | Remove files or directories |
+| `du` | Summarize device usage for a set of files |
+
+Returns the output of the command executed on the instance. May take a few seconds to retrieve results.
+
+## Examples
+
+```bash
+vastai execute 99999 'ls -l -o -r'
+vastai execute 99999 'rm -r home/delete_this.txt'
+vastai execute 99999 'du -d2 -h'
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/get-endpt-logs.mdx b/cli/reference/get-endpt-logs.mdx
new file mode 100644
index 0000000..351a372
--- /dev/null
+++ b/cli/reference/get-endpt-logs.mdx
@@ -0,0 +1,50 @@
+---
+title: "vastai get endpt-logs"
+sidebarTitle: "get endpt-logs"
+---
+
+Fetch logs for a specific serverless endpoint group
+
+## Usage
+
+```bash
+vastai get endpt-logs ID [--api-key API_KEY]
+```
+
+## Arguments
+
+
+ id of endpoint group to fetch logs from
+
+
+## Options
+
+
+ log detail level (0 to 3)
+
+
+
+
+
+
+## Description
+
+Example: vastai get endpt-logs 382
+
+## Examples
+
+```bash
+vastai get endpt-logs
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/get-wrkgrp-logs.mdx b/cli/reference/get-wrkgrp-logs.mdx
new file mode 100644
index 0000000..642850e
--- /dev/null
+++ b/cli/reference/get-wrkgrp-logs.mdx
@@ -0,0 +1,50 @@
+---
+title: "vastai get wrkgrp-logs"
+sidebarTitle: "get wrkgrp-logs"
+---
+
+Fetch logs for a specific serverless worker group group
+
+## Usage
+
+```bash
+vastai get wrkgrp-logs ID [--api-key API_KEY]
+```
+
+## Arguments
+
+
+ id of endpoint group to fetch logs from
+
+
+## Options
+
+
+ log detail level (0 to 3)
+
+
+
+
+
+
+## Description
+
+Example: vastai get endpt-logs 382
+
+## Examples
+
+```bash
+vastai get wrkgrp-logs
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/invite-member.mdx b/cli/reference/invite-member.mdx
new file mode 100644
index 0000000..c0f43b6
--- /dev/null
+++ b/cli/reference/invite-member.mdx
@@ -0,0 +1,40 @@
+---
+title: "vastai invite member"
+sidebarTitle: "invite member"
+---
+
+Invite a team member
+
+## Usage
+
+```bash
+vastai invite member --email EMAIL --role ROLE
+```
+
+## Options
+
+
+ email of user to be invited
+
+
+
+ role of user to be invited
+
+
+## Examples
+
+```bash
+vastai invite member
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/join-cluster.mdx b/cli/reference/join-cluster.mdx
new file mode 100644
index 0000000..ed7a407
--- /dev/null
+++ b/cli/reference/join-cluster.mdx
@@ -0,0 +1,44 @@
+---
+title: "vastai join cluster"
+sidebarTitle: "join cluster"
+---
+
+Join Machine to Cluster
+
+## Usage
+
+```bash
+vastai join cluster CLUSTER_ID MACHINE_IDS
+```
+
+## Arguments
+
+
+ ID of cluster to add machine to
+
+
+
+ machine id(s) to join cluster
+
+
+## Description
+
+Join's Machine to Vast Cluster
+
+## Examples
+
+```bash
+vastai join cluster
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/join-overlay.mdx b/cli/reference/join-overlay.mdx
new file mode 100644
index 0000000..ee40235
--- /dev/null
+++ b/cli/reference/join-overlay.mdx
@@ -0,0 +1,44 @@
+---
+title: "vastai join overlay"
+sidebarTitle: "join overlay"
+---
+
+Adds instance to an overlay network
+
+## Usage
+
+```bash
+vastai join overlay OVERLAY_NAME INSTANCE_ID
+```
+
+## Arguments
+
+
+ Overlay network name to join instance to.
+
+
+
+ Instance ID to add to overlay.
+
+
+## Description
+
+Adds an instance to a compatible overlay network.
+
+## Examples
+
+```bash
+vastai join overlay
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/label-instance.mdx b/cli/reference/label-instance.mdx
new file mode 100644
index 0000000..77d14db
--- /dev/null
+++ b/cli/reference/label-instance.mdx
@@ -0,0 +1,40 @@
+---
+title: "vastai label instance"
+sidebarTitle: "label instance"
+---
+
+Assign a string label to an instance
+
+## Usage
+
+```bash
+vastai label instance
+```
+
+## Arguments
+
+
+ id of instance to label
+
+
+
+ label to set
+
+
+## Examples
+
+```bash
+vastai label instance
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/launch-instance.mdx b/cli/reference/launch-instance.mdx
new file mode 100644
index 0000000..027c3e1
--- /dev/null
+++ b/cli/reference/launch-instance.mdx
@@ -0,0 +1,155 @@
+---
+title: "vastai launch instance"
+sidebarTitle: "launch instance"
+---
+
+Launch the top instance from the search offers based on the given parameters
+
+## Usage
+
+```bash
+vastai launch instance [--help] [--api-key API_KEY] [geolocation] [disk_space]
+```
+
+## Options
+
+
+ Name of the GPU model, replace spaces with underscores (alias: `--gpu-name`) Choices: `A10`, `A100_PCIE`, `A100_SXM4`, `A100X`, `A10g`, `A40`, `A800_PCIE`, `B200`, `CMP_50HX`, `GTX_1050`, `GTX_1050_Ti`, `GTX_1060`, `GTX_1070`, `GTX_1070_Ti`, `GTX_1080`, `GTX_1080_Ti`, `GTX_1650`, `GTX_1650_S`, `GTX_1660`, `GTX_1660_S`, `GTX_1660_Ti`, `H100_NVL`, `H100_PCIE`, `H100_SXM`, `H200`, `H200_NVL`, `L4`, `L40`, `L40S`, `Q_RTX_4000`, `Q_RTX_5000`, `Q_RTX_6000`, `Q_RTX_8000`, `Quadro_P2000`, `Quadro_P4000`, `RTX_2000Ada`, `RTX_2060`, `RTX_2060S`, `RTX_2070`, `RTX_2070S`, `RTX_2080`, `RTX_2080S`, `RTX_2080_Ti`, `RTX_3050`, `RTX_3060`, `RTX_3060_laptop`, `RTX_3060_Ti`, `RTX_3070`, `RTX_3070_laptop`, `RTX_3070_Ti`, `RTX_3080`, `RTX_3080_Ti`, `RTX_3090`, `RTX_3090_Ti`, `RTX_4000Ada`, `RTX_4060`, `RTX_4060_Ti`, `RTX_4070`, `RTX_4070S`, `RTX_4070S_Ti`, `RTX_4070_Ti`, `RTX_4080`, `RTX_4080S`, `RTX_4090`, `RTX_4090D`, `RTX_4500Ada`, `RTX_5000Ada`, `RTX_5060`, `RTX_5060_Ti`, `RTX_5070`, `RTX_5070_Ti`, `RTX_5080`, `RTX_5090`, `RTX_5880Ada`, `RTX_6000Ada`, `RTX_A2000`, `RTX_A4000`, `RTX_A4500`, `RTX_A5000`, `RTX_A6000`, `RTX_PRO_4000`, `RTX_PRO_4500`, `RTX_PRO_5000`, `RTX_PRO_6000_S`, `RTX_PRO_6000_WS`, `Tesla_P100`, `Tesla_P4`, `Tesla_P40`, `Tesla_T4`, `Tesla_V100`, `Titan_RTX`, `Titan_V`, `Titan_Xp`
+
+
+
+ Number of GPUs required (alias: `--num-gpus`) Choices: `1`, `2`, `4`, `8`, `12`, `14`
+
+
+
+ Geographical location of the instance (alias: `--region`)
+
+
+
+ Name of the image to use for instance (alias: `--image`)
+
+
+
+ Disk space required in GB (alias: `--disk`)
+
+
+
+
+
+
+
+ Comma-separated list of fields to sort on. postfix field with - to sort desc. ex: -o 'num_gpus,total_flops-'. default='score-' (alias: `--order`)
+
+
+
+ docker login arguments for private repo authentication, surround with ''
+
+
+
+ label to set on the instance
+
+
+
+ filename to use as onstart script
+
+
+
+ contents of onstart script as single argument
+
+
+
+ override entrypoint for args launch instance
+
+
+
+ Launch as an ssh instance type
+
+
+
+ Launch as a jupyter instance instead of an ssh instance
+
+
+
+ Use (faster) direct connections for jupyter & ssh
+
+
+
+ For runtype 'jupyter', directory in instance to use to launch jupyter. Defaults to image's working directory
+
+
+
+ For runtype 'jupyter', Launch instance with jupyter lab
+
+
+
+ Workaround for images with locale problems: install and generate locales before instance launch, and set locale to C.UTF-8
+
+
+
+ Workaround for images with locale problems: set python's locale to C.UTF-8
+
+
+
+ env variables and port mapping options, surround with ''
+
+
+
+ list of arguments passed to container ENTRYPOINT. Onstart is recommended for this purpose. (must be last argument)
+
+
+
+ Skip sanity checks when creating from an existing instance
+
+
+
+ Return error if scheduling fails (rather than creating a stopped instance)
+
+
+
+ template hash which contains all relevant information about an instance. This can be used as a replacement for other parameters describing the instance configuration
+
+
+## Description
+
+Launches an instance based on the given parameters. The instance will be created with the top offer from the search results.
+Besides the gpu_name and num_gpus, you must pass in an '`--image`' argument as a minimum.
+
+If you use args/entrypoint launch mode, we create a container from your image as is, without attempting to inject ssh and or jupyter.
+If you use the args launch mode, you can override the entrypoint with `--entrypoint`, and pass arguments to the entrypoint with `--args`.
+If you use `--args`, that must be the last argument, as any following tokens are consumed into the args string.
+For ssh/jupyter launch types, use `--onstart-cmd` to pass in startup script, instead of `--entrypoint` and `--args`.
+
+## Examples
+
+```bash
+# launch a single RTX 3090 instance with the pytorch image and 16 GB of disk space located anywhere
+vastai launch instance -g RTX_3090 -n 1 -i pytorch/pytorch
+
+# launch a 4x RTX 3090 instance with the pytorch image and 32 GB of disk space located in North America
+vastai launch instance -g RTX_3090 -n 4 -i pytorch/pytorch -d 32.0 -r North_America
+```
+
+## Key Options
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `num_gpus` | int | number of GPUs |
+| `gpu_name` | string | GPU model name |
+| `region` | string | region of the instance |
+| `image` | string | Docker image name |
+| `disk_space` | float | disk space in GB |
+| `ssh`, `jupyter`, `direct` | bool | flags to specify instance type and connection method |
+| `env` | string | environment variables and port mappings, encapsulated in single quotes |
+| `args` | list | arguments passed to the container's ENTRYPOINT (only if `--args` is specified) |
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/list-machine.mdx b/cli/reference/list-machine.mdx
new file mode 100644
index 0000000..cabeaf2
--- /dev/null
+++ b/cli/reference/list-machine.mdx
@@ -0,0 +1,93 @@
+---
+title: "vastai list machine"
+sidebarTitle: "list machine"
+description: "Host command"
+---
+
+list a machine for rent
+
+This is a **host** command, used for managing machines you are renting out on Vast.ai.
+
+## Usage
+
+```bash
+vastai list machine ID [options]
+```
+
+## Arguments
+
+
+ id of machine to list
+
+
+## Options
+
+
+ per gpu rental price in $/hour (price for active instances) (alias: `--price_gpu`)
+
+
+
+ storage price in $/GB/month (price for inactive instances), default: $0.10/GB/month (alias: `--price_disk`)
+
+
+
+ price for internet upload bandwidth in $/GB (alias: `--price_inetu`)
+
+
+
+ price for internet download bandwidth in $/GB (alias: `--price_inetd`)
+
+
+
+ per gpu minimum bid price floor in $/hour (alias: `--price_min_bid`)
+
+
+
+ Max long term prepay discount rate fraction, default: 0.4 (alias: `--discount_rate`)
+
+
+
+ minimum amount of gpus (alias: `--min_chunk`)
+
+
+
+ contract offer expiration - the available until date (optional, in unix float timestamp or MM/DD/YYYY format) (alias: `--end_date`)
+
+
+
+ Updates end_date daily to be duration from current date. Cannot be combined with end_date. Format is: `n days`, `n weeks`, `n months`, `n years`, or total intended duration in seconds. (alias: `--duration`)
+
+
+
+ Size for volume contract offer. Defaults to half of available disk. Set 0 to not create a volume contract offer. (alias: `--vol_size`)
+
+
+
+ Price for disk on volume contract offer. Defaults to price_disk. Invalid if vol_size is 0. (alias: `--vol_price`)
+
+
+## Description
+
+Performs the same action as pressing the "LIST" button on the site https://cloud.vast.ai/host/machines.
+On the end date the listing will expire and your machine will unlist. However any existing client jobs will still remain until ended by their owners.
+Once you list your machine and it is rented, it is extremely important that you don't interfere with the machine in any way.
+If your machine has an active client job and then goes offline, crashes, or has performance problems, this could permanently lower your reliability rating.
+We strongly recommend you test the machine first and only list when ready.
+
+## Examples
+
+```bash
+vastai list machine
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/list-machines.mdx b/cli/reference/list-machines.mdx
new file mode 100644
index 0000000..9f38794
--- /dev/null
+++ b/cli/reference/list-machines.mdx
@@ -0,0 +1,91 @@
+---
+title: "vastai list machines"
+sidebarTitle: "list machines"
+description: "Host command"
+---
+
+list machines for rent
+
+This is a **host** command, used for managing machines you are renting out on Vast.ai.
+
+## Usage
+
+```bash
+vastai list machines IDs [options]
+```
+
+## Arguments
+
+
+ ids of instance to list
+
+
+## Options
+
+
+ per gpu on-demand rental price in $/hour (base price for active instances) (alias: `--price_gpu`)
+
+
+
+ storage price in $/GB/month (price for inactive instances), default: $0.10/GB/month (alias: `--price_disk`)
+
+
+
+ price for internet upload bandwidth in $/GB (alias: `--price_inetu`)
+
+
+
+ price for internet download bandwidth in $/GB (alias: `--price_inetd`)
+
+
+
+ per gpu minimum bid price floor in $/hour (alias: `--price_min_bid`)
+
+
+
+ Max long term prepay discount rate fraction, default: 0.4 (alias: `--discount_rate`)
+
+
+
+ minimum amount of gpus (alias: `--min_chunk`)
+
+
+
+ contract offer expiration - the available until date (optional, in unix float timestamp or MM/DD/YYYY format) (alias: `--end_date`)
+
+
+
+ Updates end_date daily to be duration from current date. Cannot be combined with end_date. Format is: `n days`, `n weeks`, `n months`, `n years`, or total intended duration in seconds. (alias: `--duration`)
+
+
+
+ Size for volume contract offer. Defaults to half of available disk. Set 0 to not create a volume contract offer. (alias: `--vol_size`)
+
+
+
+ Price for disk on volume contract offer. Defaults to price_disk. Invalid if vol_size is 0. (alias: `--vol_price`)
+
+
+## Description
+
+This variant can be used to list or update the listings for multiple machines at once with the same args.
+You could extend the end dates of all your machines using a command combo like this:
+./vast.py list machines $(./vast.py show machines -q) -e 12/31/2024 `--retry` 6
+
+## Examples
+
+```bash
+vastai list machines
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/list-volume.mdx b/cli/reference/list-volume.mdx
new file mode 100644
index 0000000..b6c10c7
--- /dev/null
+++ b/cli/reference/list-volume.mdx
@@ -0,0 +1,57 @@
+---
+title: "vastai list volume"
+sidebarTitle: "list volume"
+description: "Host command"
+---
+
+list disk space for rent as a volume on a machine
+
+This is a **host** command, used for managing machines you are renting out on Vast.ai.
+
+## Usage
+
+```bash
+vastai list volume ID [options]
+```
+
+## Arguments
+
+
+ id of machine to list
+
+
+## Options
+
+
+ storage price in $/GB/month, default: $0.1/GB/month (alias: `--price_disk`)
+
+
+
+ contract offer expiration - the available until date (optional, in unix float timestamp or MM/DD/YYYY format), default 3 months (alias: `--end_date`)
+
+
+
+ size of disk space allocated to offer in GB, default 15 GB (alias: `--size`)
+
+
+## Description
+
+Allocates a section of disk on a machine to be used for volumes.
+
+## Examples
+
+```bash
+vastai list volume
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/list-volumes.mdx b/cli/reference/list-volumes.mdx
new file mode 100644
index 0000000..b6b7e26
--- /dev/null
+++ b/cli/reference/list-volumes.mdx
@@ -0,0 +1,57 @@
+---
+title: "vastai list volumes"
+sidebarTitle: "list volumes"
+description: "Host command"
+---
+
+list disk space for rent as a volume on machines
+
+This is a **host** command, used for managing machines you are renting out on Vast.ai.
+
+## Usage
+
+```bash
+vastai list volume IDs [options]
+```
+
+## Arguments
+
+
+ id of machines list
+
+
+## Options
+
+
+ storage price in $/GB/month, default: $0.1/GB/month (alias: `--price_disk`)
+
+
+
+ contract offer expiration - the available until date (optional, in unix float timestamp or MM/DD/YYYY format), default 3 months (alias: `--end_date`)
+
+
+
+ size of disk space allocated to offer in GB, default 15 GB (alias: `--size`)
+
+
+## Description
+
+Allocates a section of disk on machines to be used for volumes.
+
+## Examples
+
+```bash
+vastai list volumes
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/logs.mdx b/cli/reference/logs.mdx
new file mode 100644
index 0000000..de053b9
--- /dev/null
+++ b/cli/reference/logs.mdx
@@ -0,0 +1,50 @@
+---
+title: "vastai logs"
+sidebarTitle: "logs"
+---
+
+Get the logs for an instance
+
+## Usage
+
+```bash
+vastai logs INSTANCE_ID [OPTIONS]
+```
+
+## Arguments
+
+
+ id of instance
+
+
+## Options
+
+
+ Number of lines to show from the end of the logs (default '1000')
+
+
+
+ Grep filter for log entries
+
+
+
+ Fetch daemon system logs instead of container logs
+
+
+## Examples
+
+```bash
+vastai logs
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/prepay-instance.mdx b/cli/reference/prepay-instance.mdx
new file mode 100644
index 0000000..a0a8404
--- /dev/null
+++ b/cli/reference/prepay-instance.mdx
@@ -0,0 +1,40 @@
+---
+title: "vastai prepay instance"
+sidebarTitle: "prepay instance"
+---
+
+Deposit credits into reserved instance
+
+## Usage
+
+```bash
+vastai prepay instance ID AMOUNT
+```
+
+## Arguments
+
+
+ id of instance to prepay for
+
+
+
+ amount of instance credit prepayment (default discount func of 0.2 for 1 month, 0.3 for 3 months)
+
+
+## Examples
+
+```bash
+vastai prepay instance
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/reboot-instance.mdx b/cli/reference/reboot-instance.mdx
new file mode 100644
index 0000000..d0bef11
--- /dev/null
+++ b/cli/reference/reboot-instance.mdx
@@ -0,0 +1,62 @@
+---
+title: "vastai reboot instance"
+sidebarTitle: "reboot instance"
+---
+
+Reboot (stop/start) an instance
+
+## Usage
+
+```bash
+vastai reboot instance ID [OPTIONS]
+```
+
+## Arguments
+
+
+ id of instance to reboot
+
+
+## Options
+
+
+ try to schedule a command to run hourly, daily, or monthly. Valid values are HOURLY, DAILY, WEEKLY For ex. `--schedule` DAILY Choices: `HOURLY`, `DAILY`, `WEEKLY`
+
+
+
+ Start date/time in format 'YYYY-MM-DD HH:MM:SS PM' (UTC). Default is now. (optional)
+
+
+
+ End date/time in format 'YYYY-MM-DD HH:MM:SS PM' (UTC). Default is 7 days from now. (optional)
+
+
+
+ Day of week you want scheduled job to run on (0-6, where 0=Sunday) or "*". Default will be 0. For ex. `--day` 0
+
+
+
+ Hour of day you want scheduled job to run on (0-23) or "*" (UTC). Default will be 0. For ex. `--hour` 16
+
+
+## Description
+
+Stops and starts container without any risk of losing GPU priority.
+
+## Examples
+
+```bash
+vastai reboot instance
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/recycle-instance.mdx b/cli/reference/recycle-instance.mdx
new file mode 100644
index 0000000..9e8b279
--- /dev/null
+++ b/cli/reference/recycle-instance.mdx
@@ -0,0 +1,40 @@
+---
+title: "vastai recycle instance"
+sidebarTitle: "recycle instance"
+---
+
+Recycle (destroy/create) an instance
+
+## Usage
+
+```bash
+vastai recycle instance ID [OPTIONS]
+```
+
+## Arguments
+
+
+ id of instance to recycle
+
+
+## Description
+
+Destroys and recreates container in place (from newly pulled image) without any risk of losing GPU priority.
+
+## Examples
+
+```bash
+vastai recycle instance
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/remove-defjob.mdx b/cli/reference/remove-defjob.mdx
new file mode 100644
index 0000000..0631468
--- /dev/null
+++ b/cli/reference/remove-defjob.mdx
@@ -0,0 +1,39 @@
+---
+title: "vastai remove defjob"
+sidebarTitle: "remove defjob"
+description: "Host command"
+---
+
+Delete default jobs
+
+This is a **host** command, used for managing machines you are renting out on Vast.ai.
+
+## Usage
+
+```bash
+vastai remove defjob id
+```
+
+## Arguments
+
+
+ id of machine to remove default instance from
+
+
+## Examples
+
+```bash
+vastai remove defjob
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/remove-machine-from-cluster.mdx b/cli/reference/remove-machine-from-cluster.mdx
new file mode 100644
index 0000000..65fecbd
--- /dev/null
+++ b/cli/reference/remove-machine-from-cluster.mdx
@@ -0,0 +1,49 @@
+---
+title: "vastai remove-machine-from-cluster"
+sidebarTitle: "remove-machine-from-cluster"
+---
+
+Removes machine from cluster
+
+## Usage
+
+```bash
+vastai remove-machine-from-cluster CLUSTER_ID MACHINE_ID NEW_MANAGER_ID
+```
+
+## Arguments
+
+
+ ID of cluster you want to remove machine from.
+
+
+
+ ID of machine to remove from cluster.
+
+
+
+ ID of machine to promote to manager. Must already be in cluster
+
+
+## Description
+
+Removes machine from cluster and also reassigns manager ID,
+if we're removing the manager node
+
+## Examples
+
+```bash
+vastai remove-machine-from-cluster
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/remove-member.mdx b/cli/reference/remove-member.mdx
new file mode 100644
index 0000000..5e329df
--- /dev/null
+++ b/cli/reference/remove-member.mdx
@@ -0,0 +1,36 @@
+---
+title: "vastai remove member"
+sidebarTitle: "remove member"
+---
+
+Remove a team member
+
+## Usage
+
+```bash
+vastai remove member ID
+```
+
+## Arguments
+
+
+ id of user to remove
+
+
+## Examples
+
+```bash
+vastai remove member
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/remove-team-role.mdx b/cli/reference/remove-team-role.mdx
new file mode 100644
index 0000000..1ea80bf
--- /dev/null
+++ b/cli/reference/remove-team-role.mdx
@@ -0,0 +1,36 @@
+---
+title: "vastai remove team-role"
+sidebarTitle: "remove team-role"
+---
+
+Remove a role from your team
+
+## Usage
+
+```bash
+vastai remove team-role NAME
+```
+
+## Arguments
+
+
+ name of the role
+
+
+## Examples
+
+```bash
+vastai remove team-role
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/reports.mdx b/cli/reference/reports.mdx
new file mode 100644
index 0000000..998fcc0
--- /dev/null
+++ b/cli/reference/reports.mdx
@@ -0,0 +1,36 @@
+---
+title: "vastai reports"
+sidebarTitle: "reports"
+---
+
+Get the user reports for a given machine
+
+## Usage
+
+```bash
+vastai reports ID
+```
+
+## Arguments
+
+
+ machine id
+
+
+## Examples
+
+```bash
+vastai reports
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/reset-api-key.mdx b/cli/reference/reset-api-key.mdx
new file mode 100644
index 0000000..55f92d4
--- /dev/null
+++ b/cli/reference/reset-api-key.mdx
@@ -0,0 +1,30 @@
+---
+title: "vastai reset api-key"
+sidebarTitle: "reset api-key"
+---
+
+Reset your api-key (get new key from website)
+
+## Usage
+
+```bash
+vastai reset api-key
+```
+
+## Examples
+
+```bash
+vastai reset api-key
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/schedule-maint.mdx b/cli/reference/schedule-maint.mdx
new file mode 100644
index 0000000..ff0001c
--- /dev/null
+++ b/cli/reference/schedule-maint.mdx
@@ -0,0 +1,61 @@
+---
+title: "vastai schedule maint"
+sidebarTitle: "schedule maint"
+description: "Host command"
+---
+
+Schedule upcoming maint window
+
+This is a **host** command, used for managing machines you are renting out on Vast.ai.
+
+## Usage
+
+```bash
+vastai schedule maintenance id [--sdate START_DATE --duration DURATION --maintenance_category MAINTENANCE_CATEGORY]
+```
+
+## Arguments
+
+
+ id of machine to schedule maintenance for
+
+
+## Options
+
+
+ maintenance start date in unix epoch time (UTC seconds)
+
+
+
+ maintenance duration in hours
+
+
+
+ (optional) can be one of [power, internet, disk, gpu, software, other]
+
+
+## Description
+
+The proper way to perform maintenance on your machine is to wait until all active contracts have expired or the machine is vacant.
+For unplanned or unscheduled maintenance, use this schedule maint command. That will notify the client that you have to take the machine down and that they should save their work.
+You can specify a date, duration, reason and category for the maintenance.
+
+Example: vastai schedule maint 8207 `--sdate` 1677562671 `--duration` 0.5 `--maintenance_category` "power"
+
+## Examples
+
+```bash
+vastai schedule maint
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/scp-url.mdx b/cli/reference/scp-url.mdx
new file mode 100644
index 0000000..e8ea8c7
--- /dev/null
+++ b/cli/reference/scp-url.mdx
@@ -0,0 +1,36 @@
+---
+title: "vastai scp-url"
+sidebarTitle: "scp-url"
+---
+
+scp url helper
+
+## Usage
+
+```bash
+vastai scp-url ID
+```
+
+## Arguments
+
+
+ id
+
+
+## Examples
+
+```bash
+vastai scp-url
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/search-benchmarks.mdx b/cli/reference/search-benchmarks.mdx
new file mode 100644
index 0000000..0e5aa55
--- /dev/null
+++ b/cli/reference/search-benchmarks.mdx
@@ -0,0 +1,67 @@
+---
+title: "vastai search benchmarks"
+sidebarTitle: "search benchmarks"
+---
+
+Search for benchmark results using custom query
+
+## Usage
+
+```bash
+vastai search benchmarks [--help] [--api-key API_KEY] [--raw]
+```
+
+## Arguments
+
+
+ Search query in simple query syntax (see below)
+
+
+## Description
+
+**Query syntax**
+
+```
+query = comparison comparison...
+comparison = field op value
+field =
+op = one of: <, <=, ==, !=, >=, >, in, notin
+value = | 'any' | [value0, value1, ...]
+bool = True | False
+```
+
+- Wrap `>` and `<` in quotes on the command line
+- For string values (e.g. `gpu_name`), replace spaces with underscores: `RTX_3090` not `RTX 3090`
+
+## Examples
+
+```bash
+# search for benchmarks with score > 100 for llama2_70B model on 2 specific machines
+vastai search benchmarks 'score > 100.0 model=llama2_70B machine_id in [302,402]'
+```
+
+## Available Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `contract_id` | int | ID of instance/contract reporting benchmark |
+| `id` | int | benchmark unique ID |
+| `image` | string | image used for benchmark |
+| `last_update` | float | date of benchmark |
+| `machine_id` | int | id of machine benchmarked |
+| `model` | string | name of model used in benchmark |
+| `name` | string | name of benchmark |
+| `num_gpus` | int | number of gpus used in benchmark |
+| `score` | float | benchmark score result |
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/search-instances.mdx b/cli/reference/search-instances.mdx
new file mode 100644
index 0000000..f051bae
--- /dev/null
+++ b/cli/reference/search-instances.mdx
@@ -0,0 +1,167 @@
+---
+title: "vastai search instances"
+sidebarTitle: "search instances"
+---
+
+Search for instance types using custom query
+
+## Usage
+
+```bash
+vastai search offers [--help] [--api-key API_KEY] [--raw]
+```
+
+## Arguments
+
+
+ Query to search for. default: 'external=false rentable=true verified=true', pass -n to ignore default
+
+
+## Options
+
+
+ Show 'on-demand', 'reserved', or 'bid'(interruptible) pricing. default: on-demand (alias: `--type`)
+
+
+
+ Alias for `--type=bid` (alias: `--interruptible`)
+
+
+
+ Alias for `--type=bid` (alias: `--bid`)
+
+
+
+ Alias for `--type=reserved` (alias: `--reserved`)
+
+
+
+ Alias for `--type=on-demand` (alias: `--on-demand`)
+
+
+
+ Disable default query (alias: `--no-default`)
+
+
+
+ New search exp
+
+
+
+
+
+
+
+ Amount of storage to use for pricing, in GiB. default=5.0GiB
+
+
+
+ Comma-separated list of fields to sort on. postfix field with - to sort desc. ex: -o 'num_gpus,total_flops-'. default='score-' (alias: `--order`)
+
+
+## Description
+
+**Query syntax**
+
+```
+query = comparison comparison...
+comparison = field op value
+field =
+op = one of: <, <=, ==, !=, >=, >, in, notin
+value = | 'any' | [value0, value1, ...]
+bool = True | False
+```
+
+- Wrap `>` and `<` in quotes on the command line
+- For string values (e.g. `gpu_name`), replace spaces with underscores: `RTX_3090` not `RTX 3090`
+
+## Examples
+
+```bash
+# reliable single RTX 3090, no conflicts with stopped instances
+vastai search offers 'reliability > 0.98 num_gpus=1 gpu_name=RTX_3090 rented=False'
+
+# datacenter GPUs with minimum compute capability and TFLOPs
+vastai search offers 'compute_cap > 610 total_flops > 5 datacenter=True'
+
+# reliable 4-GPU offers in Taiwan or Sweden
+vastai search offers 'reliability>0.99 num_gpus=4 geolocation in [TW,SE]'
+
+# reliable RTX 3090 or 4090 NOT in China or Vietnam
+vastai search offers 'reliability>0.99 gpu_name in ["RTX 4090", "RTX 3090"] geolocation notin [CN,VN]'
+
+# nvidia driver 535.86.05 or greater with various constraints
+vastai search offers 'disk_space>146 duration>24 gpu_ram>10 cuda_vers>=12.1 direct_port_count>=2 driver_version >= 535.86.05'
+
+# reliable 4+ GPU offers, unverified allowed, sort by num_gpus desc
+vastai search offers 'reliability > 0.99 num_gpus>=4 verified=False rented=any' -o 'num_gpus-'
+
+# arm64 cpu architecture only
+vastai search offers 'cpu_arch=arm64'
+```
+
+## Available Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `bw_nvlink` | float | bandwidth NVLink |
+| `compute_cap` | int | CUDA compute capability ×100 (e.g. 650 for 6.5, 700 for 7.0) |
+| `cpu_arch` | string | host machine cpu architecture (e.g. amd64, arm64) |
+| `cpu_cores` | int | number of virtual cpus |
+| `cpu_ghz` | float | cpu clock speed in GHz |
+| `cpu_cores_effective` | float | virtual cpus you get |
+| `cpu_ram` | float | system RAM in gigabytes |
+| `cuda_vers` | float | machine max supported cuda version (based on driver version) |
+| `datacenter` | bool | show only datacenter offers |
+| `direct_port_count` | int | open ports on host's router |
+| `disk_bw` | float | disk read bandwidth, in MB/s |
+| `disk_space` | float | disk storage space, in GB |
+| `dlperf` | float | DL-perf score (see FAQ for explanation) |
+| `dlperf_usd` | float | DL-perf per dollar |
+| `dph` | float | $/hour rental cost |
+| `driver_version` | string | machine's nvidia/amd driver version as 3 digit string ex. "535.86.05" |
+| `duration` | float | max rental duration in days |
+| `external` | bool | show external offers in addition to datacenter offers |
+| `flops_usd` | float | TFLOPs per dollar |
+| `geolocation` | string | two letter country code; supports =, !=, in, notin |
+| `gpu_arch` | string | host machine gpu architecture (e.g. nvidia, amd) |
+| `gpu_max_power` | float | GPU power limit (watts) |
+| `gpu_max_temp` | float | GPU temp limit (°C) |
+| `gpu_mem_bw` | float | GPU memory bandwidth in GB/s |
+| `gpu_name` | string | GPU model name (no quotes, replace spaces with underscores, ie: RTX_3090) |
+| `gpu_ram` | float | per GPU RAM in GB |
+| `gpu_total_ram` | float | total GPU RAM in GB |
+| `gpu_frac` | float | ratio of GPUs in the offer to GPUs in the system |
+| `gpu_display_active` | bool | True if the GPU has a display attached |
+| `has_avx` | bool | CPU supports AVX instruction set |
+| `id` | int | instance unique ID |
+| `inet_down` | float | internet download speed in Mb/s |
+| `inet_down_cost` | float | internet download bandwidth cost in $/GB |
+| `inet_up` | float | internet upload speed in Mb/s |
+| `inet_up_cost` | float | internet upload bandwidth cost in $/GB |
+| `machine_id` | int | machine id of instance |
+| `min_bid` | float | current minimum bid price in $/hr for interruptible |
+| `num_gpus` | int | number of GPUs |
+| `pci_gen` | float | PCIE generation |
+| `pcie_bw` | float | PCIE bandwidth (CPU to GPU) |
+| `reliability` | float | machine reliability score (see FAQ for explanation) |
+| `rentable` | bool | is the instance currently rentable |
+| `rented` | bool | allow/disallow duplicates and potential conflicts with existing stopped instances |
+| `storage_cost` | float | storage cost in $/GB/month |
+| `static_ip` | bool | is the IP addr static/stable |
+| `total_flops` | float | total TFLOPs from all GPUs |
+| `ubuntu_version` | string | host machine ubuntu OS version |
+| `verified` | bool | is the machine verified |
+| `vms_enabled` | bool | is the machine a VM instance |
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/search-invoices.mdx b/cli/reference/search-invoices.mdx
new file mode 100644
index 0000000..978c8e3
--- /dev/null
+++ b/cli/reference/search-invoices.mdx
@@ -0,0 +1,82 @@
+---
+title: "vastai search invoices"
+sidebarTitle: "search invoices"
+---
+
+Search for invoices using custom query
+
+## Usage
+
+```bash
+vastai search invoices [--help] [--api-key API_KEY] [--raw]
+```
+
+## Arguments
+
+
+ Search query in simple query syntax (see below)
+
+
+## Description
+
+**Query syntax**
+
+```
+query = comparison comparison...
+comparison = field op value
+field =
+op = one of: <, <=, ==, !=, >=, >, in, notin
+value = | 'any' | [value0, value1, ...]
+bool = True | False
+```
+
+- Wrap `>` and `<` in quotes on the command line
+- For string values (e.g. `gpu_name`), replace spaces with underscores: `RTX_3090` not `RTX 3090`
+
+## Examples
+
+```bash
+vastai search invoices 'amount_cents>3000'
+```
+
+## Available Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | int | invoice unique ID |
+| `user_id` | int | user ID |
+| `when` | float | UTC epoch timestamp of initial invoice creation |
+| `paid_on` | float | actual payment date (UTC epoch timestamp) |
+| `payment_expected` | float | expected payment date (UTC epoch timestamp) |
+| `amount_cents` | int | amount of payment in cents |
+| `is_credit` | bool | is a credit purchase |
+| `is_delayed` | bool | is not yet paid |
+| `balance_before` | float | balance before payment |
+| `balance_after` | float | balance after payment |
+| `original_amount` | int | original amount of payment |
+| `event_id` | string | associated event ID |
+| `cut_amount` | int | cut amount |
+| `cut_percent` | float | cut percentage |
+| `extra` | json | extra metadata |
+| `service` | string | type of payment |
+| `stripe_charge` | json | Stripe charge object |
+| `stripe_refund` | json | Stripe refund object |
+| `stripe_payout` | json | Stripe payout object |
+| `error` | json | error details if any |
+| `paypal_email` | string | email for PayPal/Wise payments |
+| `transfer_group` | string | transfer group identifier |
+| `failed` | bool | payment failed |
+| `refunded` | bool | payment refunded |
+| `is_check` | bool | is a check payment |
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/search-offers.mdx b/cli/reference/search-offers.mdx
new file mode 100644
index 0000000..598ea68
--- /dev/null
+++ b/cli/reference/search-offers.mdx
@@ -0,0 +1,167 @@
+---
+title: "vastai search offers"
+sidebarTitle: "search offers"
+---
+
+Search for instance types using custom query
+
+## Usage
+
+```bash
+vastai search offers [--help] [--api-key API_KEY] [--raw]
+```
+
+## Arguments
+
+
+ Query to search for. default: 'external=false rentable=true verified=true', pass -n to ignore default
+
+
+## Options
+
+
+ Show 'on-demand', 'reserved', or 'bid'(interruptible) pricing. default: on-demand (alias: `--type`)
+
+
+
+ Alias for `--type=bid` (alias: `--interruptible`)
+
+
+
+ Alias for `--type=bid` (alias: `--bid`)
+
+
+
+ Alias for `--type=reserved` (alias: `--reserved`)
+
+
+
+ Alias for `--type=on-demand` (alias: `--on-demand`)
+
+
+
+ Disable default query (alias: `--no-default`)
+
+
+
+ New search exp
+
+
+
+
+
+
+
+ Amount of storage to use for pricing, in GiB. default=5.0GiB
+
+
+
+ Comma-separated list of fields to sort on. postfix field with - to sort desc. ex: -o 'num_gpus,total_flops-'. default='score-' (alias: `--order`)
+
+
+## Description
+
+**Query syntax**
+
+```
+query = comparison comparison...
+comparison = field op value
+field =
+op = one of: <, <=, ==, !=, >=, >, in, notin
+value = | 'any' | [value0, value1, ...]
+bool = True | False
+```
+
+- Wrap `>` and `<` in quotes on the command line
+- For string values (e.g. `gpu_name`), replace spaces with underscores: `RTX_3090` not `RTX 3090`
+
+## Examples
+
+```bash
+# reliable single RTX 3090, no conflicts with stopped instances
+vastai search offers 'reliability > 0.98 num_gpus=1 gpu_name=RTX_3090 rented=False'
+
+# datacenter GPUs with minimum compute capability and TFLOPs
+vastai search offers 'compute_cap > 610 total_flops > 5 datacenter=True'
+
+# reliable 4-GPU offers in Taiwan or Sweden
+vastai search offers 'reliability>0.99 num_gpus=4 geolocation in [TW,SE]'
+
+# reliable RTX 3090 or 4090 NOT in China or Vietnam
+vastai search offers 'reliability>0.99 gpu_name in ["RTX 4090", "RTX 3090"] geolocation notin [CN,VN]'
+
+# nvidia driver 535.86.05 or greater with various constraints
+vastai search offers 'disk_space>146 duration>24 gpu_ram>10 cuda_vers>=12.1 direct_port_count>=2 driver_version >= 535.86.05'
+
+# reliable 4+ GPU offers, unverified allowed, sort by num_gpus desc
+vastai search offers 'reliability > 0.99 num_gpus>=4 verified=False rented=any' -o 'num_gpus-'
+
+# arm64 cpu architecture only
+vastai search offers 'cpu_arch=arm64'
+```
+
+## Available Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `bw_nvlink` | float | bandwidth NVLink |
+| `compute_cap` | int | CUDA compute capability ×100 (e.g. 650 for 6.5, 700 for 7.0) |
+| `cpu_arch` | string | host machine cpu architecture (e.g. amd64, arm64) |
+| `cpu_cores` | int | number of virtual cpus |
+| `cpu_ghz` | float | cpu clock speed in GHz |
+| `cpu_cores_effective` | float | virtual cpus you get |
+| `cpu_ram` | float | system RAM in gigabytes |
+| `cuda_vers` | float | machine max supported cuda version (based on driver version) |
+| `datacenter` | bool | show only datacenter offers |
+| `direct_port_count` | int | open ports on host's router |
+| `disk_bw` | float | disk read bandwidth, in MB/s |
+| `disk_space` | float | disk storage space, in GB |
+| `dlperf` | float | DL-perf score (see FAQ for explanation) |
+| `dlperf_usd` | float | DL-perf per dollar |
+| `dph` | float | $/hour rental cost |
+| `driver_version` | string | machine's nvidia/amd driver version as 3 digit string ex. "535.86.05" |
+| `duration` | float | max rental duration in days |
+| `external` | bool | show external offers in addition to datacenter offers |
+| `flops_usd` | float | TFLOPs per dollar |
+| `geolocation` | string | two letter country code; supports =, !=, in, notin |
+| `gpu_arch` | string | host machine gpu architecture (e.g. nvidia, amd) |
+| `gpu_max_power` | float | GPU power limit (watts) |
+| `gpu_max_temp` | float | GPU temp limit (°C) |
+| `gpu_mem_bw` | float | GPU memory bandwidth in GB/s |
+| `gpu_name` | string | GPU model name (no quotes, replace spaces with underscores, ie: RTX_3090) |
+| `gpu_ram` | float | per GPU RAM in GB |
+| `gpu_total_ram` | float | total GPU RAM in GB |
+| `gpu_frac` | float | ratio of GPUs in the offer to GPUs in the system |
+| `gpu_display_active` | bool | True if the GPU has a display attached |
+| `has_avx` | bool | CPU supports AVX instruction set |
+| `id` | int | instance unique ID |
+| `inet_down` | float | internet download speed in Mb/s |
+| `inet_down_cost` | float | internet download bandwidth cost in $/GB |
+| `inet_up` | float | internet upload speed in Mb/s |
+| `inet_up_cost` | float | internet upload bandwidth cost in $/GB |
+| `machine_id` | int | machine id of instance |
+| `min_bid` | float | current minimum bid price in $/hr for interruptible |
+| `num_gpus` | int | number of GPUs |
+| `pci_gen` | float | PCIE generation |
+| `pcie_bw` | float | PCIE bandwidth (CPU to GPU) |
+| `reliability` | float | machine reliability score (see FAQ for explanation) |
+| `rentable` | bool | is the instance currently rentable |
+| `rented` | bool | allow/disallow duplicates and potential conflicts with existing stopped instances |
+| `storage_cost` | float | storage cost in $/GB/month |
+| `static_ip` | bool | is the IP addr static/stable |
+| `total_flops` | float | total TFLOPs from all GPUs |
+| `ubuntu_version` | string | host machine ubuntu OS version |
+| `verified` | bool | is the machine verified |
+| `vms_enabled` | bool | is the machine a VM instance |
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/search-templates.mdx b/cli/reference/search-templates.mdx
new file mode 100644
index 0000000..56cf78d
--- /dev/null
+++ b/cli/reference/search-templates.mdx
@@ -0,0 +1,73 @@
+---
+title: "vastai search templates"
+sidebarTitle: "search templates"
+---
+
+Search for template results using custom query
+
+## Usage
+
+```bash
+vastai search templates [--help] [--api-key API_KEY] [--raw]
+```
+
+## Arguments
+
+
+ Search query in simple query syntax (see below)
+
+
+## Description
+
+**Query syntax**
+
+```
+query = comparison comparison...
+comparison = field op value
+field =
+op = one of: <, <=, ==, !=, >=, >, in, notin
+value = | 'any' | [value0, value1, ...]
+bool = True | False
+```
+
+- Wrap `>` and `<` in quotes on the command line
+- For string values (e.g. `gpu_name`), replace spaces with underscores: `RTX_3090` not `RTX 3090`
+
+## Examples
+
+```bash
+vastai search templates 'count_created > 100 creator_id in [38382,48982]'
+```
+
+## Available Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `creator_id` | int | ID of creator |
+| `created_at` | float | time of initial template creation (UTC epoch timestamp) |
+| `count_created` | int | number of instances created (popularity) |
+| `default_tag` | string | image default tag |
+| `docker_login_repo` | string | image docker repository |
+| `id` | int | template unique ID |
+| `image` | string | image used for template |
+| `jup_direct` | bool | supports jupyter direct |
+| `hash_id` | string | unique hash ID of template |
+| `name` | string | displayable name |
+| `recent_create_date` | float | last time of instance creation (UTC epoch timestamp) |
+| `recommended_disk_space` | float | min disk space required |
+| `recommended` | bool | is on our recommended list |
+| `ssh_direct` | bool | supports ssh direct |
+| `tag` | string | image tag |
+| `use_ssh` | bool | supports ssh (direct or proxy) |
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/search-volumes.mdx b/cli/reference/search-volumes.mdx
new file mode 100644
index 0000000..713dcd7
--- /dev/null
+++ b/cli/reference/search-volumes.mdx
@@ -0,0 +1,99 @@
+---
+title: "vastai search volumes"
+sidebarTitle: "search volumes"
+---
+
+Search for volume offers using custom query
+
+## Usage
+
+```bash
+vastai search volumes [--help] [--api-key API_KEY] [--raw]
+```
+
+## Arguments
+
+
+ Query to search for. default: 'external=false verified=true disk_space>=1', pass -n to ignore default
+
+
+## Options
+
+
+ Disable default query (alias: `--no-default`)
+
+
+
+
+
+
+
+ Amount of storage to use for pricing, in GiB. default=1.0GiB
+
+
+
+ Comma-separated list of fields to sort on. postfix field with - to sort desc. ex: -o 'disk_space,inet_up-'. default='score-' (alias: `--order`)
+
+
+## Description
+
+**Query syntax**
+
+```
+query = comparison comparison...
+comparison = field op value
+field =
+op = one of: <, <=, ==, !=, >=, >, in, notin
+value = | 'any' | [value0, value1, ...]
+bool = True | False
+```
+
+- Wrap `>` and `<` in quotes on the command line
+- For string values (e.g. `gpu_name`), replace spaces with underscores: `RTX_3090` not `RTX 3090`
+
+## Examples
+
+```bash
+# search for volumes with greater than 50GB of available storage and greater than 500 Mb/s upload and download speed
+vastai search volumes "disk_space>50 inet_up>500 inet_down>500"
+```
+
+## Available Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `cpu_arch` | string | host machine cpu architecture (e.g. amd64, arm64) |
+| `cuda_vers` | float | machine max supported cuda version (based on driver version) |
+| `datacenter` | bool | show only datacenter offers |
+| `disk_bw` | float | disk read bandwidth, in MB/s |
+| `disk_space` | float | disk storage space, in GB |
+| `driver_version` | string | machine's nvidia/amd driver version as 3 digit string ex. "535.86.05" |
+| `duration` | float | max rental duration in days |
+| `geolocation` | string | Two letter country code. Works with operators =, !=, in, notin (e.g. geolocation not in ['XV','XZ']) |
+| `gpu_arch` | string | host machine gpu architecture (e.g. nvidia, amd) |
+| `gpu_name` | string | GPU model name (no quotes, replace spaces with underscores, ie: RTX_3090 rather than 'RTX 3090') |
+| `has_avx` | bool | CPU supports AVX instruction set |
+| `id` | int | volume offer unique ID |
+| `inet_down` | float | internet download speed in Mb/s |
+| `inet_up` | float | internet upload speed in Mb/s |
+| `machine_id` | int | machine id of volume offer |
+| `pci_gen` | float | PCIE generation |
+| `pcie_bw` | float | PCIE bandwidth (CPU to GPU) |
+| `reliability` | float | machine reliability score (see FAQ for explanation) |
+| `storage_cost` | float | storage cost in $/GB/month |
+| `static_ip` | bool | is the IP addr static/stable |
+| `total_flops` | float | total TFLOPs from all GPUs |
+| `ubuntu_version` | string | host machine ubuntu OS version |
+| `verified` | bool | is the machine verified |
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/self-test-machine.mdx b/cli/reference/self-test-machine.mdx
new file mode 100644
index 0000000..40cf480
--- /dev/null
+++ b/cli/reference/self-test-machine.mdx
@@ -0,0 +1,57 @@
+---
+title: "vastai self-test machine"
+sidebarTitle: "self-test machine"
+description: "Host command"
+---
+
+Perform a self-test on the specified machine
+
+This is a **host** command, used for managing machines you are renting out on Vast.ai.
+
+## Usage
+
+```bash
+vastai self-test machine [--debugging] [--explain] [--api_key API_KEY] [--url URL] [--retry RETRY] [--raw] [--ignore-requirements]
+```
+
+## Arguments
+
+
+ Machine ID
+
+
+## Options
+
+
+ Enable debugging output
+
+
+
+ Ignore the minimum system requirements and run the self test regardless
+
+
+## Description
+
+This command tests if a machine meets specific requirements and
+runs a series of tests to ensure it's functioning correctly.
+
+## Examples
+
+```bash
+vast self-test machine 12345
+ vast self-test machine 12345 --debugging
+ vast self-test machine 12345 --explain
+ vast self-test machine 12345 --api_key
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/set-api-key.mdx b/cli/reference/set-api-key.mdx
new file mode 100644
index 0000000..f426468
--- /dev/null
+++ b/cli/reference/set-api-key.mdx
@@ -0,0 +1,36 @@
+---
+title: "vastai set api-key"
+sidebarTitle: "set api-key"
+---
+
+Set api-key (get your api-key from the console/CLI)
+
+## Usage
+
+```bash
+vastai set api-key APIKEY
+```
+
+## Arguments
+
+
+ Api key to set as currently logged in user
+
+
+## Examples
+
+```bash
+vastai set api-key
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/set-defjob.mdx b/cli/reference/set-defjob.mdx
new file mode 100644
index 0000000..67aed4a
--- /dev/null
+++ b/cli/reference/set-defjob.mdx
@@ -0,0 +1,65 @@
+---
+title: "vastai set defjob"
+sidebarTitle: "set defjob"
+description: "Host command"
+---
+
+Create default jobs for a machine
+
+This is a **host** command, used for managing machines you are renting out on Vast.ai.
+
+## Usage
+
+```bash
+vastai set defjob id [--api-key API_KEY] [--price_gpu PRICE_GPU] [--price_inetu PRICE_INETU] [--price_inetd PRICE_INETD] [--image IMAGE] [--args ...]
+```
+
+## Arguments
+
+
+ id of machine to launch default instance on
+
+
+## Options
+
+
+ per gpu rental price in $/hour
+
+
+
+ price for internet upload bandwidth in $/GB
+
+
+
+ price for internet download bandwidth in $/GB
+
+
+
+ docker container image to launch
+
+
+
+ list of arguments passed to container launch
+
+
+## Description
+
+Performs the same action as creating a background job at https://cloud.vast.ai/host/create.
+
+## Examples
+
+```bash
+vastai set defjob
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/set-min-bid.mdx b/cli/reference/set-min-bid.mdx
new file mode 100644
index 0000000..fd5eb54
--- /dev/null
+++ b/cli/reference/set-min-bid.mdx
@@ -0,0 +1,49 @@
+---
+title: "vastai set min-bid"
+sidebarTitle: "set min-bid"
+description: "Host command"
+---
+
+Set the minimum bid/rental price for a machine
+
+This is a **host** command, used for managing machines you are renting out on Vast.ai.
+
+## Usage
+
+```bash
+vastai set min_bid id [--price PRICE]
+```
+
+## Arguments
+
+
+ id of machine to set min bid price for
+
+
+## Options
+
+
+ per gpu min bid price in $/hour
+
+
+## Description
+
+Change the current min bid price of machine id to PRICE.
+
+## Examples
+
+```bash
+vastai set min-bid
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/set-user.mdx b/cli/reference/set-user.mdx
new file mode 100644
index 0000000..c3a2d45
--- /dev/null
+++ b/cli/reference/set-user.mdx
@@ -0,0 +1,58 @@
+---
+title: "vastai set user"
+sidebarTitle: "set user"
+---
+
+Update user data from json file
+
+## Usage
+
+```bash
+vastai set user --file FILE
+```
+
+## Options
+
+
+ file path for params in json format
+
+
+## Available Fields
+
+| Field | Type |
+|-------|------|
+| `ssh_key` | string |
+| `paypal_email` | string |
+| `wise_email` | string |
+| `email` | string |
+| `normalized_email` | string |
+| `username` | string |
+| `fullname` | string |
+| `billaddress_line1` | string |
+| `billaddress_line2` | string |
+| `billaddress_city` | string |
+| `billaddress_zip` | string |
+| `billaddress_country` | string |
+| `billaddress_taxinfo` | string |
+| `balance_threshold_enabled` | string |
+| `balance_threshold` | string |
+| `autobill_threshold` | string |
+| `phone_number` | string |
+
+## Examples
+
+```bash
+vastai set user
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-api-key.mdx b/cli/reference/show-api-key.mdx
new file mode 100644
index 0000000..28fb089
--- /dev/null
+++ b/cli/reference/show-api-key.mdx
@@ -0,0 +1,36 @@
+---
+title: "vastai show api-key"
+sidebarTitle: "show api-key"
+---
+
+Show an api-key
+
+## Usage
+
+```bash
+vastai show api-key
+```
+
+## Arguments
+
+
+ id of apikey to get
+
+
+## Examples
+
+```bash
+vastai show api-key
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-api-keys.mdx b/cli/reference/show-api-keys.mdx
new file mode 100644
index 0000000..de6324b
--- /dev/null
+++ b/cli/reference/show-api-keys.mdx
@@ -0,0 +1,30 @@
+---
+title: "vastai show api-keys"
+sidebarTitle: "show api-keys"
+---
+
+List your api-keys associated with your account
+
+## Usage
+
+```bash
+vastai show api-keys
+```
+
+## Examples
+
+```bash
+vastai show api-keys
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-audit-logs.mdx b/cli/reference/show-audit-logs.mdx
new file mode 100644
index 0000000..5efd940
--- /dev/null
+++ b/cli/reference/show-audit-logs.mdx
@@ -0,0 +1,30 @@
+---
+title: "vastai show audit-logs"
+sidebarTitle: "show audit-logs"
+---
+
+Display account's history of important actions
+
+## Usage
+
+```bash
+vastai show audit-logs [--api-key API_KEY] [--raw]
+```
+
+## Examples
+
+```bash
+vastai show audit-logs
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-clusters.mdx b/cli/reference/show-clusters.mdx
new file mode 100644
index 0000000..3ad8e67
--- /dev/null
+++ b/cli/reference/show-clusters.mdx
@@ -0,0 +1,34 @@
+---
+title: "vastai show clusters"
+sidebarTitle: "show clusters"
+---
+
+Show clusters associated with your account.
+
+## Usage
+
+```bash
+vastai show clusters
+```
+
+## Description
+
+Show clusters associated with your account.
+
+## Examples
+
+```bash
+vastai show clusters
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-connections.mdx b/cli/reference/show-connections.mdx
new file mode 100644
index 0000000..6bce96c
--- /dev/null
+++ b/cli/reference/show-connections.mdx
@@ -0,0 +1,30 @@
+---
+title: "vastai show connections"
+sidebarTitle: "show connections"
+---
+
+Display user's cloud connections
+
+## Usage
+
+```bash
+vastai show connections [--api-key API_KEY] [--raw]
+```
+
+## Examples
+
+```bash
+vastai show connections
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-deployment-versions.mdx b/cli/reference/show-deployment-versions.mdx
new file mode 100644
index 0000000..634eb12
--- /dev/null
+++ b/cli/reference/show-deployment-versions.mdx
@@ -0,0 +1,40 @@
+---
+title: "vastai show deployment-versions"
+sidebarTitle: "show deployment-versions"
+---
+
+Display versions for a deployment
+
+## Usage
+
+```bash
+vastai show deployment-versions ID
+```
+
+## Arguments
+
+
+ id of deployment to show versions for
+
+
+## Description
+
+Example: vastai show deployment-versions 1234
+
+## Examples
+
+```bash
+vastai show deployment-versions
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-deployment.mdx b/cli/reference/show-deployment.mdx
new file mode 100644
index 0000000..e56a5d5
--- /dev/null
+++ b/cli/reference/show-deployment.mdx
@@ -0,0 +1,40 @@
+---
+title: "vastai show deployment"
+sidebarTitle: "show deployment"
+---
+
+Display details of a single deployment
+
+## Usage
+
+```bash
+vastai show deployment ID
+```
+
+## Arguments
+
+
+ id of deployment to show
+
+
+## Description
+
+Example: vastai show deployment 1234
+
+## Examples
+
+```bash
+vastai show deployment
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-deployments.mdx b/cli/reference/show-deployments.mdx
new file mode 100644
index 0000000..51e1de6
--- /dev/null
+++ b/cli/reference/show-deployments.mdx
@@ -0,0 +1,34 @@
+---
+title: "vastai show deployments"
+sidebarTitle: "show deployments"
+---
+
+Display user's current deployments
+
+## Usage
+
+```bash
+vastai show deployments [--api-key API_KEY]
+```
+
+## Description
+
+Example: vastai show deployments
+
+## Examples
+
+```bash
+vastai show deployments
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-deposit.mdx b/cli/reference/show-deposit.mdx
new file mode 100644
index 0000000..351f88b
--- /dev/null
+++ b/cli/reference/show-deposit.mdx
@@ -0,0 +1,36 @@
+---
+title: "vastai show deposit"
+sidebarTitle: "show deposit"
+---
+
+Display reserve deposit info for an instance
+
+## Usage
+
+```bash
+vastai show deposit ID [options]
+```
+
+## Arguments
+
+
+ id of instance to get info for
+
+
+## Examples
+
+```bash
+vastai show deposit
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-earnings.mdx b/cli/reference/show-earnings.mdx
new file mode 100644
index 0000000..762fc56
--- /dev/null
+++ b/cli/reference/show-earnings.mdx
@@ -0,0 +1,48 @@
+---
+title: "vastai show earnings"
+sidebarTitle: "show earnings"
+---
+
+Get machine earning history reports
+
+## Usage
+
+```bash
+vastai show earnings [OPTIONS]
+```
+
+## Options
+
+
+ only display numeric ids (alias: `--quiet`)
+
+
+
+ start date and time for report. Many formats accepted (alias: `--start_date`)
+
+
+
+ end date and time for report. Many formats accepted (alias: `--end_date`)
+
+
+
+ Machine id (optional) (alias: `--machine_id`)
+
+
+## Examples
+
+```bash
+vastai show earnings
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-endpoints.mdx b/cli/reference/show-endpoints.mdx
new file mode 100644
index 0000000..f414a51
--- /dev/null
+++ b/cli/reference/show-endpoints.mdx
@@ -0,0 +1,34 @@
+---
+title: "vastai show endpoints"
+sidebarTitle: "show endpoints"
+---
+
+Display user's current endpoint groups
+
+## Usage
+
+```bash
+vastai show endpoints [--api-key API_KEY]
+```
+
+## Description
+
+Example: vastai show endpoints
+
+## Examples
+
+```bash
+vastai show endpoints
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-env-vars.mdx b/cli/reference/show-env-vars.mdx
new file mode 100644
index 0000000..3e5b196
--- /dev/null
+++ b/cli/reference/show-env-vars.mdx
@@ -0,0 +1,36 @@
+---
+title: "vastai show env-vars"
+sidebarTitle: "show env-vars"
+---
+
+Show user environment variables
+
+## Usage
+
+```bash
+vastai show env-vars [-s]
+```
+
+## Options
+
+
+ Show the values of environment variables (alias: `--show-values`)
+
+
+## Examples
+
+```bash
+vastai show env-vars
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-instance.mdx b/cli/reference/show-instance.mdx
new file mode 100644
index 0000000..947753a
--- /dev/null
+++ b/cli/reference/show-instance.mdx
@@ -0,0 +1,60 @@
+---
+title: "vastai show instance"
+sidebarTitle: "show instance"
+---
+
+Display user's current instances
+
+## Usage
+
+```bash
+vastai show instance [--api-key API_KEY] [--raw]
+```
+
+## Arguments
+
+
+ id of instance to get
+
+
+## Description
+
+Returns an instance object. Key status fields:
+
+**actual_status** — current container state:
+
+| Value | Meaning |
+|-------|---------|
+| `null` | Instance is being provisioned |
+| `loading` | Docker image is downloading or container is starting up |
+| `running` | Container is actively executing. GPU charges apply. |
+| `stopped` | Container is halted. Disk charges continue; no GPU charges. |
+| `frozen` | Container is paused with memory preserved. GPU charges apply. |
+| `exited` | Container process exited unexpectedly |
+| `rebooting` | Container is restarting (transient) |
+| `unknown` | No recent heartbeat from the host |
+| `offline` | Host machine disconnected from Vast servers (computed, not stored in DB) |
+
+**intended_status** — user's desired target state: `running`, `stopped`, or `frozen`.
+
+**cur_state** — machine contract / hardware allocation state: `running`, `stopped`, or `unloaded` (released on destroy).
+
+**status_msg** — human-readable detail on the current status.
+
+## Examples
+
+```bash
+vastai show instance
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-instances-v1.mdx b/cli/reference/show-instances-v1.mdx
new file mode 100644
index 0000000..35fbdab
--- /dev/null
+++ b/cli/reference/show-instances-v1.mdx
@@ -0,0 +1,116 @@
+---
+title: "vastai show instances-v1"
+sidebarTitle: "show instances-v1"
+---
+
+List your running instances with filtering, sorting, and pagination
+
+## Usage
+
+```bash
+vastai show instances-v1 [OPTIONS] [--api-key API_KEY] [--raw]
+```
+
+## Options
+
+
+ only print instance IDs, one per line (alias: `--quiet`)
+
+
+
+ show additional columns (SSH, location, template, etc.) (alias: `--verbose`)
+
+
+
+ fetch all pages automatically and send to pager; useful for scripting (alias: `--all`)
+
+
+
+ filter by container status: running loading exited (space-separated for multiple) (alias: `--status`)
+
+
+
+ filter by instance label; pass empty string '' to match unlabeled instances
+
+
+
+ filter by GPU model name, e.g. 'RTX A5000' 'GTX 1070' (space-separated for multiple)
+
+
+
+ filter by machine verification status: verified unverified deverified Choices: `verified`, `unverified`, `deverified`
+
+
+
+ max instances per page (1–25, default 25) (alias: `--limit`)
+
+
+
+ resume from a pagination token printed at the end of a previous page (alias: `--next-token`)
+
+
+
+ sort by column with optional direction (default asc); repeat for multiple keys, e.g. `--order-by` start_date desc `--order-by` id
+
+
+
+ override displayed columns with a comma-separated list (available: id,status,label,gpu,disk,volumes,dph,image,age,verified,machine,net,location,template,ssh,msg)
+
+
+## Description
+
+Returns a paginated list of instance objects. Key status fields per instance:
+
+**actual_status** — current container state:
+
+| Value | Meaning |
+|-------|---------|
+| `null` | Instance is being provisioned |
+| `loading` | Docker image is downloading or container is starting up |
+| `running` | Container is actively executing. GPU charges apply. |
+| `stopped` | Container is halted. Disk charges continue; no GPU charges. |
+| `frozen` | Container is paused with memory preserved. GPU charges apply. |
+| `exited` | Container process exited unexpectedly |
+| `rebooting` | Container is restarting (transient) |
+| `unknown` | No recent heartbeat from the host |
+| `offline` | Host machine disconnected from Vast servers (computed, not stored in DB) |
+
+**intended_status** — user's desired target state: `running`, `stopped`, or `frozen`.
+
+**cur_state** — machine contract / hardware allocation state: `running`, `stopped`, or `unloaded` (released on destroy).
+
+**status_msg** — human-readable detail on the current status.
+
+Displays your instances in a table with auto-sizing columns. Narrow terminals
+drop lower-priority columns automatically; use `--cols` to override. Sorted by
+id asc by default. Paginated at 25 results; follow the next-page prompt or
+pass `--next-token` to continue.
+
+A 'Filterable Values' panel is always shown on the first page, listing the exact values
+accepted by `--status`, `--verification`, and `--gpu-name` for your instances.
+
+## Examples
+
+```bash
+vastai show instances-v1
+vastai show instances-v1 -v
+vastai show instances-v1 --status running loading
+vastai show instances-v1 --gpu-name 'RTX A5000' 'GTX 1070'
+vastai show instances-v1 --label training --order-by start_date desc
+vastai show instances-v1 --verification verified --status running --limit 10
+vastai show instances-v1 --order-by start_date desc --order-by label
+vastai show instances-v1 --next-token eyJ2YWx1ZXMiOiB7ImlkIjogMjUwNzgyMzR9...
+vastai show instances-v1 --cols id,status,gpu,dph
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-instances.mdx b/cli/reference/show-instances.mdx
new file mode 100644
index 0000000..dc3841c
--- /dev/null
+++ b/cli/reference/show-instances.mdx
@@ -0,0 +1,60 @@
+---
+title: "vastai show instances"
+sidebarTitle: "show instances"
+---
+
+Display user's current instances
+
+## Usage
+
+```bash
+vastai show instances [OPTIONS] [--api-key API_KEY] [--raw]
+```
+
+## Options
+
+
+ only display numeric ids (alias: `--quiet`)
+
+
+## Description
+
+Returns a list of instance objects. Key status fields per instance:
+
+**actual_status** — current container state:
+
+| Value | Meaning |
+|-------|---------|
+| `null` | Instance is being provisioned |
+| `loading` | Docker image is downloading or container is starting up |
+| `running` | Container is actively executing. GPU charges apply. |
+| `stopped` | Container is halted. Disk charges continue; no GPU charges. |
+| `frozen` | Container is paused with memory preserved. GPU charges apply. |
+| `exited` | Container process exited unexpectedly |
+| `rebooting` | Container is restarting (transient) |
+| `unknown` | No recent heartbeat from the host |
+| `offline` | Host machine disconnected from Vast servers (computed, not stored in DB) |
+
+**intended_status** — user's desired target state: `running`, `stopped`, or `frozen`.
+
+**cur_state** — machine contract / hardware allocation state: `running`, `stopped`, or `unloaded` (released on destroy).
+
+**status_msg** — human-readable detail on the current status.
+
+## Examples
+
+```bash
+vastai show instances
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-invoices-v1.mdx b/cli/reference/show-invoices-v1.mdx
new file mode 100644
index 0000000..377683c
--- /dev/null
+++ b/cli/reference/show-invoices-v1.mdx
@@ -0,0 +1,96 @@
+---
+title: "vastai show invoices-v1"
+sidebarTitle: "show invoices-v1"
+---
+
+Get billing (invoices/charges) history reports with advanced filtering and pagination
+
+## Usage
+
+```bash
+vastai show invoices-v1 [OPTIONS]
+```
+
+## Options
+
+
+ Show invoices instead of charges (alias: `--invoices`)
+
+
+
+ Filter which types of invoices to show: {transfers, stripe, bitpay, coinbase, crypto.com, reserved, payout_paypal, payout_wise} (alias: `--invoice-type`) Choices: `transfers`, `stripe`, `bitpay`, `coinbase`, `crypto.com`, `reserved`, `payout_paypal`, `payout_wise`
+
+
+
+ Show charges instead of invoices (alias: `--charges`)
+
+
+
+ Filter which types of charges to show: {i|instance, v|volume, s|serverless} (alias: `--charge-type`) Choices: `instance`, `volume`, `serverless`, `i`, `v`, `s`
+
+
+
+ Start date (YYYY-MM-DD or timestamp) (alias: `--start-date`)
+
+
+
+ End date (YYYY-MM-DD or timestamp) (alias: `--end-date`)
+
+
+
+ Number of results per page (default: 20, max: 100) (alias: `--limit`)
+
+
+
+ Pagination token for next page (alias: `--next-token`)
+
+
+
+ Output format for charges (default: table) (alias: `--format`) Choices: `table`, `tree`
+
+
+
+ Include full Instance Charge details and Invoice Metadata (tree view only) (alias: `--verbose`)
+
+
+
+ Sort by latest first
+
+
+## Description
+
+This command supports colored output and rich formatting if the 'rich' python module is installed!
+
+## Examples
+
+```bash
+# Show the first 20 invoices in the last week (default window is a 7 day period ending today)
+vastai show invoices-v1 --invoices
+
+# Show the first 50 charges over a 7 day period starting from 2025-11-30 in tree format
+vastai show invoices-v1 --charges -s 2025-11-30 -f tree -l 50
+
+# Show the first 20 invoices of specific types for the month of November 2025
+vastai show invoices-v1 -i -it stripe bitpay transfers --start-date 2025-11-01 --end-date 2025-11-30
+
+# Show the first 20 charges for only volumes and serverless instances between two dates, including all details and metadata
+vastai show invoices-v1 -c --charge-type v s -s 2025-11-01 -e 2025-11-05 --format tree --verbose
+
+# Get the next page of paginated invoices, limit to 50 per page (type/date filters MUST match previous request)
+vastai show invoices-v1 --invoices --limit 50 --next-token eyJ2YWx1ZXMiOiB7ImlkIjogMjUwNzgyMzR9LCAib3NfcGFnZSI6IDB9
+
+# Show the last 10 instance charges over a 7 day period ending 2025-12-25, sorted latest first
+vastai show invoices-v1 --charges -ct instance --end-date 2025-12-25 -l 10 --latest-first
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-invoices.mdx b/cli/reference/show-invoices.mdx
new file mode 100644
index 0000000..f9ad859
--- /dev/null
+++ b/cli/reference/show-invoices.mdx
@@ -0,0 +1,56 @@
+---
+title: "vastai show invoices"
+sidebarTitle: "show invoices"
+---
+
+(DEPRECATED) Get billing history reports
+
+## Usage
+
+```bash
+vastai (DEPRECATED) vastai show invoices [OPTIONS]
+```
+
+## Options
+
+
+ only display numeric ids (alias: `--quiet`)
+
+
+
+ start date and time for report. Many formats accepted (optional) (alias: `--start_date`)
+
+
+
+ end date and time for report. Many formats accepted (optional) (alias: `--end_date`)
+
+
+
+ Show only charge items (alias: `--only_charges`)
+
+
+
+ Show only credit items (alias: `--only_credits`)
+
+
+
+ Filter charges on a particular instance label (useful for autoscaler groups)
+
+
+## Examples
+
+```bash
+vastai show invoices
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-ipaddrs.mdx b/cli/reference/show-ipaddrs.mdx
new file mode 100644
index 0000000..a26cccd
--- /dev/null
+++ b/cli/reference/show-ipaddrs.mdx
@@ -0,0 +1,30 @@
+---
+title: "vastai show ipaddrs"
+sidebarTitle: "show ipaddrs"
+---
+
+Display user's history of ip addresses
+
+## Usage
+
+```bash
+vastai show ipaddrs [--api-key API_KEY] [--raw]
+```
+
+## Examples
+
+```bash
+vastai show ipaddrs
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-machine.mdx b/cli/reference/show-machine.mdx
new file mode 100644
index 0000000..eaed530
--- /dev/null
+++ b/cli/reference/show-machine.mdx
@@ -0,0 +1,45 @@
+---
+title: "vastai show machine"
+sidebarTitle: "show machine"
+description: "Host command"
+---
+
+Show hosted machines
+
+This is a **host** command, used for managing machines you are renting out on Vast.ai.
+
+## Usage
+
+```bash
+vastai show machine ID [OPTIONS]
+```
+
+## Arguments
+
+
+ id of machine to display
+
+
+## Options
+
+
+ only display numeric ids (alias: `--quiet`)
+
+
+## Examples
+
+```bash
+vastai show machine
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-machines.mdx b/cli/reference/show-machines.mdx
new file mode 100644
index 0000000..5ca7352
--- /dev/null
+++ b/cli/reference/show-machines.mdx
@@ -0,0 +1,39 @@
+---
+title: "vastai show machines"
+sidebarTitle: "show machines"
+description: "Host command"
+---
+
+Show hosted machines
+
+This is a **host** command, used for managing machines you are renting out on Vast.ai.
+
+## Usage
+
+```bash
+vastai show machines [OPTIONS]
+```
+
+## Options
+
+
+ only display numeric ids (alias: `--quiet`)
+
+
+## Examples
+
+```bash
+vastai show machines
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-maints.mdx b/cli/reference/show-maints.mdx
new file mode 100644
index 0000000..5894a40
--- /dev/null
+++ b/cli/reference/show-maints.mdx
@@ -0,0 +1,44 @@
+---
+title: "vastai show maints"
+sidebarTitle: "show maints"
+description: "Host command"
+---
+
+Show maintenance information for host machines
+
+This is a **host** command, used for managing machines you are renting out on Vast.ai.
+
+## Usage
+
+```bash
+vastai show maints -ids 'machine_id_1' [OPTIONS]
+vastai show maints -ids 'machine_id_1, machine_id_2' [OPTIONS]
+```
+
+## Options
+
+
+ comma seperated string of machine_ids for which to get maintenance information
+
+
+
+ only display numeric ids of the machines in maintenance (alias: `--quiet`)
+
+
+## Examples
+
+```bash
+vastai show maints
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-members.mdx b/cli/reference/show-members.mdx
new file mode 100644
index 0000000..8152814
--- /dev/null
+++ b/cli/reference/show-members.mdx
@@ -0,0 +1,30 @@
+---
+title: "vastai show members"
+sidebarTitle: "show members"
+---
+
+Show your team members
+
+## Usage
+
+```bash
+vastai show members
+```
+
+## Examples
+
+```bash
+vastai show members
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-overlays.mdx b/cli/reference/show-overlays.mdx
new file mode 100644
index 0000000..6cfc074
--- /dev/null
+++ b/cli/reference/show-overlays.mdx
@@ -0,0 +1,34 @@
+---
+title: "vastai show overlays"
+sidebarTitle: "show overlays"
+---
+
+Show overlays associated with your account.
+
+## Usage
+
+```bash
+vastai show overlays
+```
+
+## Description
+
+Show overlays associated with your account.
+
+## Examples
+
+```bash
+vastai show overlays
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-scheduled-jobs.mdx b/cli/reference/show-scheduled-jobs.mdx
new file mode 100644
index 0000000..73675f9
--- /dev/null
+++ b/cli/reference/show-scheduled-jobs.mdx
@@ -0,0 +1,30 @@
+---
+title: "vastai show scheduled-jobs"
+sidebarTitle: "show scheduled-jobs"
+---
+
+Display the list of scheduled jobs
+
+## Usage
+
+```bash
+vastai show scheduled-jobs [--api-key API_KEY] [--raw]
+```
+
+## Examples
+
+```bash
+vastai show scheduled-jobs
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-ssh-keys.mdx b/cli/reference/show-ssh-keys.mdx
new file mode 100644
index 0000000..5672a46
--- /dev/null
+++ b/cli/reference/show-ssh-keys.mdx
@@ -0,0 +1,30 @@
+---
+title: "vastai show ssh-keys"
+sidebarTitle: "show ssh-keys"
+---
+
+List your ssh keys associated with your account
+
+## Usage
+
+```bash
+vastai show ssh-keys
+```
+
+## Examples
+
+```bash
+vastai show ssh-keys
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-subaccounts.mdx b/cli/reference/show-subaccounts.mdx
new file mode 100644
index 0000000..ac38661
--- /dev/null
+++ b/cli/reference/show-subaccounts.mdx
@@ -0,0 +1,36 @@
+---
+title: "vastai show subaccounts"
+sidebarTitle: "show subaccounts"
+---
+
+Get current subaccounts
+
+## Usage
+
+```bash
+vastai show subaccounts [OPTIONS]
+```
+
+## Options
+
+
+ display subaccounts from current user (alias: `--quiet`)
+
+
+## Examples
+
+```bash
+vastai show subaccounts
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-team-role.mdx b/cli/reference/show-team-role.mdx
new file mode 100644
index 0000000..ec83235
--- /dev/null
+++ b/cli/reference/show-team-role.mdx
@@ -0,0 +1,36 @@
+---
+title: "vastai show team-role"
+sidebarTitle: "show team-role"
+---
+
+Show your team role
+
+## Usage
+
+```bash
+vastai show team-role NAME
+```
+
+## Arguments
+
+
+ name of the role
+
+
+## Examples
+
+```bash
+vastai show team-role
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-team-roles.mdx b/cli/reference/show-team-roles.mdx
new file mode 100644
index 0000000..26c206b
--- /dev/null
+++ b/cli/reference/show-team-roles.mdx
@@ -0,0 +1,30 @@
+---
+title: "vastai show team-roles"
+sidebarTitle: "show team-roles"
+---
+
+Show roles for a team
+
+## Usage
+
+```bash
+vastai show team-roles
+```
+
+## Examples
+
+```bash
+vastai show team-roles
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-user.mdx b/cli/reference/show-user.mdx
new file mode 100644
index 0000000..ce47463
--- /dev/null
+++ b/cli/reference/show-user.mdx
@@ -0,0 +1,40 @@
+---
+title: "vastai show user"
+sidebarTitle: "show user"
+---
+
+Get current user data
+
+## Usage
+
+```bash
+vastai show user [OPTIONS]
+```
+
+## Options
+
+
+ display information about user (alias: `--quiet`)
+
+
+## Description
+
+Shows stats for logged-in user. These include user balance, email, and ssh key. Does not show API key.
+
+## Examples
+
+```bash
+vastai show user
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-volumes.mdx b/cli/reference/show-volumes.mdx
new file mode 100644
index 0000000..101dad8
--- /dev/null
+++ b/cli/reference/show-volumes.mdx
@@ -0,0 +1,40 @@
+---
+title: "vastai show volumes"
+sidebarTitle: "show volumes"
+---
+
+Show stats on owned volumes.
+
+## Usage
+
+```bash
+vastai show volumes [OPTIONS]
+```
+
+## Options
+
+
+ volume type to display. Default to all. Possible values are "local", "all", "network" (alias: `--type`)
+
+
+## Description
+
+Show stats on owned volumes
+
+## Examples
+
+```bash
+vastai show volumes
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/show-workergroups.mdx b/cli/reference/show-workergroups.mdx
new file mode 100644
index 0000000..3284643
--- /dev/null
+++ b/cli/reference/show-workergroups.mdx
@@ -0,0 +1,34 @@
+---
+title: "vastai show workergroups"
+sidebarTitle: "show workergroups"
+---
+
+Display user's current workergroups
+
+## Usage
+
+```bash
+vastai show workergroups [--api-key API_KEY]
+```
+
+## Description
+
+Example: vastai show workergroups
+
+## Examples
+
+```bash
+vastai show workergroups
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/ssh-url.mdx b/cli/reference/ssh-url.mdx
new file mode 100644
index 0000000..2c74bee
--- /dev/null
+++ b/cli/reference/ssh-url.mdx
@@ -0,0 +1,36 @@
+---
+title: "vastai ssh-url"
+sidebarTitle: "ssh-url"
+---
+
+ssh url helper
+
+## Usage
+
+```bash
+vastai ssh-url ID
+```
+
+## Arguments
+
+
+ id of instance
+
+
+## Examples
+
+```bash
+vastai ssh-url
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/start-instance.mdx b/cli/reference/start-instance.mdx
new file mode 100644
index 0000000..5c61e08
--- /dev/null
+++ b/cli/reference/start-instance.mdx
@@ -0,0 +1,42 @@
+---
+title: "vastai start instance"
+sidebarTitle: "start instance"
+---
+
+Start a stopped instance
+
+## Usage
+
+```bash
+vastai start instance ID [OPTIONS]
+```
+
+## Arguments
+
+
+ ID of instance to start/restart
+
+
+## Description
+
+This command attempts to bring an instance from the "stopped" state into the "running" state. This is subject to resource availability on the machine that the instance is located on.
+If your instance is stuck in the "scheduling" state for more than 30 seconds after running this, it likely means that the required resources on the machine to run your instance are currently unavailable.
+
+## Examples
+
+```bash
+vastai start instances $(vastai show instances -q)
+vastai start instance 329838
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/start-instances.mdx b/cli/reference/start-instances.mdx
new file mode 100644
index 0000000..3e985f3
--- /dev/null
+++ b/cli/reference/start-instances.mdx
@@ -0,0 +1,36 @@
+---
+title: "vastai start instances"
+sidebarTitle: "start instances"
+---
+
+Start a list of instances
+
+## Usage
+
+```bash
+vastai start instances [OPTIONS] ID0 ID1 ID2...
+```
+
+## Arguments
+
+
+ ids of instance to start
+
+
+## Examples
+
+```bash
+vastai start instances
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/stop-instance.mdx b/cli/reference/stop-instance.mdx
new file mode 100644
index 0000000..cc7b89e
--- /dev/null
+++ b/cli/reference/stop-instance.mdx
@@ -0,0 +1,42 @@
+---
+title: "vastai stop instance"
+sidebarTitle: "stop instance"
+---
+
+Stop a running instance
+
+## Usage
+
+```bash
+vastai stop instance ID [OPTIONS]
+```
+
+## Arguments
+
+
+ id of instance to stop
+
+
+## Description
+
+This command brings an instance from the "running" state into the "stopped" state. When an instance is "stopped" all of your data on the instance is preserved,
+and you can resume use of your instance by starting it again. Once stopped, starting an instance is subject to resource availability on the machine that the instance is located on.
+There are ways to move data off of a stopped instance, which are described here: https://vast.ai/docs/gpu-instances/data-movement
+
+## Examples
+
+```bash
+vastai stop instance
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/stop-instances.mdx b/cli/reference/stop-instances.mdx
new file mode 100644
index 0000000..c492d16
--- /dev/null
+++ b/cli/reference/stop-instances.mdx
@@ -0,0 +1,37 @@
+---
+title: "vastai stop instances"
+sidebarTitle: "stop instances"
+---
+
+Stop a list of instances
+
+## Usage
+
+```bash
+vastai stop instances [OPTIONS] ID0 ID1 ID2...
+```
+
+## Arguments
+
+
+ ids of instance to stop
+
+
+## Examples
+
+```bash
+vastai stop instances $(vastai show instances -q)
+vastai stop instances 329838 984849
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/transfer-credit.mdx b/cli/reference/transfer-credit.mdx
new file mode 100644
index 0000000..5fcef41
--- /dev/null
+++ b/cli/reference/transfer-credit.mdx
@@ -0,0 +1,50 @@
+---
+title: "vastai transfer credit"
+sidebarTitle: "transfer credit"
+---
+
+Transfer credits to another account
+
+## Usage
+
+```bash
+vastai transfer credit RECIPIENT AMOUNT
+```
+
+## Arguments
+
+
+ email (or id) of recipient account
+
+
+
+ $dollars of credit to transfer
+
+
+## Options
+
+
+ skip confirmation
+
+
+## Description
+
+Transfer (amount) credits to account with email (recipient).
+
+## Examples
+
+```bash
+vastai transfer credit
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/unlist-machine.mdx b/cli/reference/unlist-machine.mdx
new file mode 100644
index 0000000..af38b50
--- /dev/null
+++ b/cli/reference/unlist-machine.mdx
@@ -0,0 +1,39 @@
+---
+title: "vastai unlist machine"
+sidebarTitle: "unlist machine"
+description: "Host command"
+---
+
+Unlist a listed machine
+
+This is a **host** command, used for managing machines you are renting out on Vast.ai.
+
+## Usage
+
+```bash
+vastai unlist machine
+```
+
+## Arguments
+
+
+ id of machine to unlist
+
+
+## Examples
+
+```bash
+vastai unlist machine
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/unlist-volume.mdx b/cli/reference/unlist-volume.mdx
new file mode 100644
index 0000000..b214d20
--- /dev/null
+++ b/cli/reference/unlist-volume.mdx
@@ -0,0 +1,39 @@
+---
+title: "vastai unlist volume"
+sidebarTitle: "unlist volume"
+description: "Host command"
+---
+
+unlist volume offer
+
+This is a **host** command, used for managing machines you are renting out on Vast.ai.
+
+## Usage
+
+```bash
+vastai unlist volume ID
+```
+
+## Arguments
+
+
+ volume ID you want to unlist
+
+
+## Examples
+
+```bash
+vastai unlist volume
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/update-endpoint.mdx b/cli/reference/update-endpoint.mdx
new file mode 100644
index 0000000..1356e14
--- /dev/null
+++ b/cli/reference/update-endpoint.mdx
@@ -0,0 +1,86 @@
+---
+title: "vastai update endpoint"
+sidebarTitle: "update endpoint"
+---
+
+Update an existing endpoint group
+
+## Usage
+
+```bash
+vastai update endpoint ID [OPTIONS]
+```
+
+## Arguments
+
+
+ id of endpoint group to update
+
+
+## Options
+
+
+ minimum floor load in perf units/s (token/s for LLms)
+
+
+
+ minimum floor load in perf units/s (token/s for LLms), but allow handling with cold workers
+
+
+
+ active, suspended, or stopped
+
+
+
+ target capacity utilization (fraction, max 1.0, default 0.9)
+
+
+
+ cold/stopped instance capacity target as multiple of hot capacity target (default 2.5)
+
+
+
+ min number of workers to keep 'cold' when you have no load (default 5)
+
+
+
+ max number of workers your endpoint group can have (default 20)
+
+
+
+ deployment endpoint name (allows multiple workergroups to share same deployment endpoint)
+
+
+
+ maximum seconds requests may be queued on each worker (default 30.0)
+
+
+
+ target seconds for the queue to be cleared (default 10.0)
+
+
+
+ seconds of no traffic before the endpoint can scale to zero active workers
+
+
+## Description
+
+Example: vastai update endpoint 4242 `--min_load` 100 `--target_util` 0.9 `--cold_mult` 2.0 `--endpoint_name` "LLama"
+
+## Examples
+
+```bash
+vastai update endpoint
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/update-env-var.mdx b/cli/reference/update-env-var.mdx
new file mode 100644
index 0000000..0040715
--- /dev/null
+++ b/cli/reference/update-env-var.mdx
@@ -0,0 +1,40 @@
+---
+title: "vastai update env-var"
+sidebarTitle: "update env-var"
+---
+
+Update an existing user environment variable
+
+## Usage
+
+```bash
+vastai update env-var
+```
+
+## Arguments
+
+
+ Environment variable name to update
+
+
+
+ New environment variable value
+
+
+## Examples
+
+```bash
+vastai update env-var
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/update-instance.mdx b/cli/reference/update-instance.mdx
new file mode 100644
index 0000000..d3e01ce
--- /dev/null
+++ b/cli/reference/update-instance.mdx
@@ -0,0 +1,66 @@
+---
+title: "vastai update instance"
+sidebarTitle: "update instance"
+---
+
+Update recreate an instance from a new/updated template
+
+## Usage
+
+```bash
+vastai update instance ID [OPTIONS]
+```
+
+## Arguments
+
+
+ id of instance to update
+
+
+## Options
+
+
+ new template ID to associate with the instance
+
+
+
+ new template hash ID to associate with the instance
+
+
+
+ new image UUID for the instance
+
+
+
+ new arguments for the instance
+
+
+
+ new environment variables for the instance
+
+
+
+ new onstart script for the instance
+
+
+## Description
+
+Example: vastai update instance 1234 `--template_hash_id` 661d064bbda1f2a133816b6d55da07c3
+
+## Examples
+
+```bash
+vastai update instance
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/update-ssh-key.mdx b/cli/reference/update-ssh-key.mdx
new file mode 100644
index 0000000..a826c75
--- /dev/null
+++ b/cli/reference/update-ssh-key.mdx
@@ -0,0 +1,40 @@
+---
+title: "vastai update ssh-key"
+sidebarTitle: "update ssh-key"
+---
+
+Update an existing SSH key
+
+## Usage
+
+```bash
+vastai update ssh-key ID SSH_KEY
+```
+
+## Arguments
+
+
+ id of the ssh key to update
+
+
+
+ new public key value
+
+
+## Examples
+
+```bash
+vastai update ssh-key
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/update-team-role.mdx b/cli/reference/update-team-role.mdx
new file mode 100644
index 0000000..7147977
--- /dev/null
+++ b/cli/reference/update-team-role.mdx
@@ -0,0 +1,46 @@
+---
+title: "vastai update team-role"
+sidebarTitle: "update team-role"
+---
+
+Update an existing team role
+
+## Usage
+
+```bash
+vastai update team-role ID --name NAME --permissions PERMISSIONS
+```
+
+## Arguments
+
+
+ id of the role
+
+
+## Options
+
+
+ name of the template
+
+
+
+ file path for json encoded permissions, look in the docs for more information
+
+
+## Examples
+
+```bash
+vastai update team-role
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/update-template.mdx b/cli/reference/update-template.mdx
new file mode 100644
index 0000000..07fb51b
--- /dev/null
+++ b/cli/reference/update-template.mdx
@@ -0,0 +1,126 @@
+---
+title: "vastai update template"
+sidebarTitle: "update template"
+---
+
+Update an existing template
+
+## Usage
+
+```bash
+vastai update template HASH_ID
+```
+
+## Arguments
+
+
+ hash id of the template
+
+
+## Options
+
+
+ name of the template
+
+
+
+ docker container image to launch
+
+
+
+ docker image tag (can also be appended to end of image_path)
+
+
+
+ link you want to provide
+
+
+
+ link to repository
+
+
+
+ docker login arguments for private repo authentication, surround with ''
+
+
+
+ Contents of the 'Docker options' field
+
+
+
+ Launch as an ssh instance type
+
+
+
+ Launch as a jupyter instance instead of an ssh instance
+
+
+
+ Use (faster) direct connections for jupyter & ssh
+
+
+
+ For runtype 'jupyter', directory in instance to use to launch jupyter. Defaults to image's working directory
+
+
+
+ For runtype 'jupyter', Launch instance with jupyter lab
+
+
+
+ contents of onstart script as single argument
+
+
+
+ search offers filters
+
+
+
+ Disable default search param query args (alias: `--no-default`)
+
+
+
+ disk storage space, in GB
+
+
+
+ readme string
+
+
+
+ hide the readme from users
+
+
+
+ description string
+
+
+
+ make template available to public
+
+
+## Description
+
+Update a template
+
+## Examples
+
+```bash
+vastai update template c81e7ab0e928a508510d1979346de10d --name "tgi-llama2-7B-quantized" --image "ghcr.io/huggingface/text-generation-inference:1.0.3"
+ --env "-p 3000:3000 -e MODEL_ARGS='--model-id TheBloke/Llama-2-7B-chat-GPTQ --quantize gptq'"
+ --onstart-cmd 'wget -O - https://raw.githubusercontent.com/vast-ai/vast-pyworker/main/scripts/launch_tgi.sh | bash'
+ --search_params "gpu_ram>=23 num_gpus=1 gpu_name=RTX_3090 inet_down>128 direct_port_count>3 disk_space>=192 driver_version>=535086005 rented=False"
+ --disk 8.0 --ssh --direct
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/update-workergroup.mdx b/cli/reference/update-workergroup.mdx
new file mode 100644
index 0000000..e5b0ade
--- /dev/null
+++ b/cli/reference/update-workergroup.mdx
@@ -0,0 +1,94 @@
+---
+title: "vastai update workergroup"
+sidebarTitle: "update workergroup"
+---
+
+Update an existing autoscale group
+
+## Usage
+
+```bash
+vastai update workergroup WORKERGROUP_ID --endpoint_id ENDPOINT_ID [options]
+```
+
+## Arguments
+
+
+ id of autoscale group to update
+
+
+## Options
+
+
+ minimum floor load in perf units/s (token/s for LLms)
+
+
+
+ target capacity utilization (fraction, max 1.0, default 0.9)
+
+
+
+ cold/stopped instance capacity target as multiple of hot capacity target (default 2.5)
+
+
+
+ min number of workers to keep 'cold' for this workergroup
+
+
+
+ number of workers to create to get an performance estimate for while initializing workergroup (default 3)
+
+
+
+ estimated GPU RAM req (independent of search string)
+
+
+
+ template hash (**Note**: if you use this field, you can skip search_params, as they are automatically inferred from the template)
+
+
+
+ template id
+
+
+
+ search param string for search offers ex: "gpu_ram>=23 num_gpus=2 gpu_name=RTX_4090 inet_down>200 direct_port_count>2 disk_space>=64"
+
+
+
+ Disable default search param query args (alias: `--no-default`)
+
+
+
+ launch args string for create instance ex: "`--onstart` onstart_wget.sh `--env` '-e ONSTART_PATH=https://s3.amazonaws.com/public.vast.ai/onstart_OOBA.sh' `--image` atinoda/text-generation-webui:default-nightly `--disk` 64"
+
+
+
+ deployment endpoint name (allows multiple workergroups to share same deployment endpoint)
+
+
+
+ deployment endpoint id (allows multiple workergroups to share same deployment endpoint)
+
+
+## Description
+
+Example: vastai update workergroup 4242 `--min_load` 100 `--target_util` 0.9 `--cold_mult` 2.0 `--search_params` "gpu_ram>=23 num_gpus=2 gpu_name=RTX_4090 inet_down>200 direct_port_count>2 disk_space>=64" `--launch_args` "`--onstart` onstart_wget.sh `--env` '-e ONSTART_PATH=https://s3.amazonaws.com/public.vast.ai/onstart_OOBA.sh' `--image` atinoda/text-generation-webui:default-nightly `--disk` 64" `--gpu_ram` 32.0 `--endpoint_name` "LLama" `--endpoint_id` 2
+
+## Examples
+
+```bash
+vastai update workergroup
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/update-workers.mdx b/cli/reference/update-workers.mdx
new file mode 100644
index 0000000..cff2d3b
--- /dev/null
+++ b/cli/reference/update-workers.mdx
@@ -0,0 +1,50 @@
+---
+title: "vastai update workers"
+sidebarTitle: "update workers"
+---
+
+Trigger a rolling update of all workers in a workergroup, or cancel an in-progress update
+
+## Usage
+
+```bash
+vastai update workers WORKERGROUP_ID [--cancel]
+```
+
+## Arguments
+
+
+ id of workergroup to update workers for
+
+
+## Options
+
+
+ cancel an in-progress update for the workergroup
+
+
+## Description
+
+Starts a rolling update of all workers in the specified workergroup. The autoscaler
+will cycle through workers, updating them while maintaining capacity.
+
+Use `--cancel` to cancel an update that is currently in progress.
+
+## Examples
+
+```bash
+vastai update workers 4242
+vastai update workers 4242 --cancel
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/templates.mdx b/cli/templates.mdx
new file mode 100644
index 0000000..b3e1ad2
--- /dev/null
+++ b/cli/templates.mdx
@@ -0,0 +1,289 @@
+---
+title: "CLI Templates"
+sidebarTitle: "Templates"
+---
+
+A **template** is a configuration bundle that stores default settings for instance creation. Instead of passing every parameter each time you create an instance, you define a template once and reference it by its `hash_id`. You can optionally override specific values at creation time.
+
+Templates are useful for:
+- **Standardization** -- ensure all team members launch instances with consistent configurations
+- **Convenience** -- avoid repeating the same image, env, and onstart parameters across commands
+- **Sharing** -- distribute configurations via template hash ID
+
+For information about managing templates in the web interface, see [Templates Introduction](/documentation/templates/introduction).
+
+## Template Fields Reference
+
+When creating or editing a template, the following fields can be configured:
+
+| Field | Type | CLI Flag | Description |
+|-------|------|----------|-------------|
+| `name` | string | `--name` | Human-readable name for the template |
+| `image` | string | `--image` | Docker image path (e.g., `vllm/vllm-openai`) |
+| `tag` | string | `--image_tag` | Docker image tag. Defaults to `latest` |
+| `desc` | string | `--desc` | Short description of the template |
+| `readme` | string | `--readme` | Longer documentation/readme content |
+| `env` | string | `--env` | Environment variables and port mappings in Docker flag format (e.g., `"-e VAR=val -p 8000:8000"`) |
+| `onstart` | string | `--onstart-cmd` | Shell commands to run when the instance starts |
+| `runtype` | string | `--ssh` / `--jupyter` | Launch mode: `ssh`, `jupyter`, or `args` (default). Set via flags |
+| `ssh_direct` | boolean | `--ssh --direct` | Enable direct SSH (set by combining `--ssh` and `--direct`) |
+| `use_ssh` | boolean | `--ssh` | Enable SSH access |
+| `jup_direct` | boolean | `--jupyter --direct` | Enable direct Jupyter (set by combining `--jupyter` and `--direct`) |
+| `jupyter_dir` | string | `--jupyter-dir` | Directory to launch Jupyter from |
+| `use_jupyter_lab` | boolean | `--jupyter-lab` | Use JupyterLab instead of Jupyter Notebook |
+| `docker_login_repo` | string | `--login` | Private Docker registry URL (first token of the login string) |
+| `extra_filters` | object | `--search_params` | Default machine search filters (parsed from query string) |
+| `recommended_disk_space` | number | `--disk_space` | Recommended disk space in GB |
+| `private` | boolean | `--public` | Private by default; pass `--public` to make it public |
+| `href` | string | `--href` | Link to Docker Hub or image documentation |
+| `repo` | string | `--repo` | Repository identifier |
+
+## Template Identifiers
+
+Templates have two identifiers. Which one you use depends on the operation:
+
+| Identifier | Type | Used For |
+|------------|------|----------|
+| `id` | integer | Deleting templates (`--template-id`) |
+| `hash_id` | string | Creating instances (`--template_hash`), editing templates (positional arg) |
+
+
+The `hash_id` is derived from the template's content. After editing a template, the `hash_id` changes. Always retrieve the latest `hash_id` from the command output or by searching for the template.
+
+
+## Create a Template
+
+Use `vastai create template` to define a reusable configuration:
+
+```bash
+vastai create template \
+ --name "vLLM Inference Server" \
+ --image "vllm/vllm-openai" \
+ --image_tag "latest" \
+ --env "-e MODEL_ID=deepseek-ai/DeepSeek-R1-Distill-Llama-8B -p 8000:8000" \
+ --onstart-cmd 'echo "Starting vLLM server"; vllm serve $MODEL_ID' \
+ --disk_space 50 \
+ --ssh --direct \
+ --desc "Template for running vLLM inference server"
+```
+
+The output includes both identifiers:
+
+```
+New Template: {'id': 334548, 'hash_id': '4e17788f74f075dd9aab7d0d4427968f', ...}
+```
+
+Save both the `id` and `hash_id` -- you'll need them for different operations.
+
+You can also attach default machine search filters using `--search_params`:
+
+```bash
+vastai create template \
+ --name "tgi-llama2-7B-quantized" \
+ --image "ghcr.io/huggingface/text-generation-inference:1.0.3" \
+ --env "-p 3000:3000 -e MODEL_ARGS='--model-id TheBloke/Llama-2-7B-chat-GPTQ --quantize gptq'" \
+ --onstart-cmd 'wget -O - https://raw.githubusercontent.com/vast-ai/vast-pyworker/main/scripts/launch_tgi.sh | bash' \
+ --search_params "gpu_ram>=23 num_gpus=1 gpu_name=RTX_3090 inet_down>128 direct_port_count>3 disk_space>=192" \
+ --disk_space 8.0 --ssh --direct
+```
+
+## Search for Templates
+
+Find templates using `vastai search templates` with the same query syntax used by `search offers`:
+
+```bash
+# Search for popular templates (more than 100 instances created)
+vastai search templates 'count_created > 100'
+
+# Search for templates by specific creators
+vastai search templates 'count_created > 100 creator_id in [38382,48982]'
+
+# Search for recommended templates with SSH support
+vastai search templates 'recommended == True use_ssh == True'
+```
+
+### Query Syntax
+
+```
+query = comparison comparison ...
+comparison = field op value
+op = one of: <, <=, ==, !=, >=, >, in, notin
+```
+
+
+Quote the query string to prevent shell interpretation of `>` and `<` characters.
+
+
+### Searchable Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `creator_id` | int | ID of the creator |
+| `created_at` | float | Time of initial creation (UTC epoch) |
+| `count_created` | int | Number of instances created (popularity) |
+| `default_tag` | string | Image default tag |
+| `docker_login_repo` | string | Image docker repository |
+| `id` | int | Template unique ID |
+| `image` | string | Image used for the template |
+| `jup_direct` | bool | Supports Jupyter direct |
+| `hash_id` | string | Unique hash ID |
+| `name` | string | Displayable name |
+| `recent_create_date` | float | Last time of instance creation (UTC epoch) |
+| `recommended_disk_space` | float | Minimum disk space required |
+| `recommended` | bool | On the recommended list |
+| `ssh_direct` | bool | Supports SSH direct |
+| `tag` | string | Image tag |
+| `use_ssh` | bool | Supports SSH (direct or proxy) |
+
+## Create an Instance from a Template
+
+Pass `--template_hash` to `create instance` to use a template as the base configuration. You don't need to specify `--image` or other fields already defined in the template:
+
+```bash
+vastai create instance 12345678 --template_hash 4e17788f74f075dd9aab7d0d4427968f --disk 20
+```
+
+Output:
+
+```json
+{"success": true, "new_contract": 7835610}
+```
+
+You can combine a template with an interruptible (spot) bid:
+
+```bash
+vastai create instance 12345678 --template_hash 4e17788f74f075dd9aab7d0d4427968f --disk 64 --bid_price 0.1
+```
+
+## Override Template Values
+
+When you create an instance with both a template and additional flags, the following precedence rules apply:
+
+| Field Type | Behavior |
+|------------|----------|
+| **Scalar fields** (image, disk, runtype, etc.) | Request value **overrides** template value |
+| **`env`** (string) | **Merged**. Template values retained, request values appended. Conflicting keys use the request value |
+| **`extra_filters`** (dict) | **Merged** by key. Request values win on conflicts |
+
+### Example: Overriding the Image
+
+```bash
+# Use template config but swap the Docker image
+vastai create instance 12345678 \
+ --template_hash 4e17788f74f075dd9aab7d0d4427968f \
+ --image nvidia/cuda:12.1-devel-ubuntu22.04 \
+ --disk 20
+```
+
+### Example: Merging Environment Variables
+
+If your template defines:
+```
+env: "-e MODEL_ID=deepseek-ai/DeepSeek-R1-Distill-Llama-8B -e MAX_TOKENS=4096"
+```
+
+And you create an instance with:
+```bash
+vastai create instance 12345678 \
+ --template_hash 4e17788f74f075dd9aab7d0d4427968f \
+ --env "-e MODEL_ID=mistralai/Mistral-7B-v0.1 -e HF_TOKEN=hf_xxx" \
+ --disk 20
+```
+
+The resulting environment will be:
+- `MODEL_ID=mistralai/Mistral-7B-v0.1` -- request overrides template
+- `MAX_TOKENS=4096` -- retained from template
+- `HF_TOKEN=hf_xxx` -- added from request
+
+## Edit a Template
+
+Update an existing template using `vastai update template` with the template's `hash_id` as the positional argument. Include only the flags you want to change:
+
+```bash
+vastai update template 5915f1dc1ce881defb572015eb9d8178 \
+ --desc "Updated description" \
+ --disk_space 16
+```
+
+You can change any of the same flags available in `create template`:
+
+```bash
+vastai update template c81e7ab0e928a508510d1979346de10d \
+ --name "tgi-llama2-7B-quantized" \
+ --image "ghcr.io/huggingface/text-generation-inference:1.0.3" \
+ --env "-p 3000:3000 -e MODEL_ARGS='--model-id TheBloke/Llama-2-7B-chat-GPTQ --quantize gptq'" \
+ --onstart-cmd 'wget -O - https://raw.githubusercontent.com/vast-ai/vast-pyworker/main/scripts/launch_tgi.sh | bash' \
+ --ssh --direct
+```
+
+
+The `hash_id` changes after editing because it is derived from the template's content. Use the new `hash_id` returned in the output for subsequent operations.
+
+
+## Delete a Template
+
+Delete a template using either its numeric `id` or its `hash_id`:
+
+```bash
+# Delete by numeric ID
+vastai delete template --template-id 334548
+
+# Delete by hash ID
+vastai delete template --hash-id 49c538d097ad6437413b83711c9f61e8
+```
+
+
+Deleting a template removes your relationship to it. It does not destroy the underlying template record.
+
+
+## Common Pitfalls
+
+
+
+ Templates have two identifiers and each is used in different contexts:
+ - `create instance --template_hash` takes the **hash_id** (string)
+ - `update template` takes the **hash_id** as a positional argument
+ - `delete template --template-id` takes the numeric **id** (integer)
+
+ If you pass the numeric `id` where a `hash_id` is expected (or vice versa), the operation will fail.
+
+
+
+ The `--env` flag expects Docker flag format as a single string, not key=value pairs:
+
+ ```bash
+ # Correct
+ --env "-e VAR1=value1 -e VAR2=value2 -p 8000:8000"
+
+ # Wrong -- missing -e prefix
+ --env "VAR1=value1 VAR2=value2"
+ ```
+
+ Port mappings are also specified in this string using `-p`:
+ ```bash
+ --env "-e MY_VAR=hello -p 8080:8080 -p 8081:8081/udp"
+ ```
+
+
+
+ When you specify both `--template_hash` and `--image`, the `--image` flag overrides the template's image. If you want to use the template's image, omit the `--image` flag entirely.
+
+
+
+ The `volume_info` field stored in templates is a **UI hint only**. To actually mount a volume, pass the volume flags in the `create instance` command:
+
+ ```bash
+ # Link an existing volume
+ vastai create instance 12345678 --template_hash abc123 \
+ --link-volume 12345 --mount-path /workspace
+
+ # Create a new volume
+ vastai create instance 12345678 --template_hash abc123 \
+ --create-volume 28908979 --volume-size 10 --mount-path /workspace
+ ```
+
+
+
+ This is expected behavior. The `hash_id` is content-based, so any edit produces a new hash. Always capture the new `hash_id` from the update command output or search for your template again before referencing it.
+
+
diff --git a/docs.json b/docs.json
index f46d5c6..f6044d9 100644
--- a/docs.json
+++ b/docs.json
@@ -1,7 +1,7 @@
{
"$schema": "https://mintlify.com/docs.json",
"theme": "mint",
- "name": "Vast.ai Documentation – Affordable GPU Cloud Marketplace",
+ "name": "Vast.ai Documentation \u2013 Affordable GPU Cloud Marketplace",
"colors": {
"primary": "#315FFF",
"light": "#315FFF",
@@ -318,7 +318,8 @@
"icon": "desktop",
"pages": [
"linux-virtual-desktop",
- "linux-virtual-machines" ]
+ "linux-virtual-machines"
+ ]
},
{
"group": "Graphics Rendering",
@@ -362,10 +363,229 @@
"tab": "SDK",
"groups": [
{
- "group": "Python",
+ "group": "Get Started",
+ "icon": "book",
+ "pages": [
+ "sdk/python/quickstart",
+ {
+ "group": "Authentication",
+ "pages": [
+ "sdk/python/authentication",
+ "sdk/python/permissions"
+ ]
+ },
+ "sdk/python/templates"
+ ]
+ },
+ {
+ "group": "VastAI Client",
"icon": "python",
"pages": [
- "sdk/python/quickstart"
+ "sdk/python/reference/vastai"
+ ]
+ },
+ {
+ "group": "Methods",
+ "icon": "code",
+ "pages": [
+ {
+ "group": "Accounts",
+ "pages": [
+ "sdk/python/reference/create-api-key",
+ "sdk/python/reference/delete-api-key",
+ "sdk/python/reference/reset-api-key",
+ "sdk/python/reference/show-api-key",
+ "sdk/python/reference/show-api-keys",
+ "sdk/python/reference/set-api-key",
+ "sdk/python/reference/create-ssh-key",
+ "sdk/python/reference/delete-ssh-key",
+ "sdk/python/reference/show-ssh-keys",
+ "sdk/python/reference/update-ssh-key",
+ "sdk/python/reference/create-env-var",
+ "sdk/python/reference/show-env-vars",
+ "sdk/python/reference/update-env-var",
+ "sdk/python/reference/delete-env-var",
+ "sdk/python/reference/show-user",
+ "sdk/python/reference/set-user",
+ "sdk/python/reference/create-subaccount",
+ "sdk/python/reference/show-subaccounts",
+ "sdk/python/reference/show-connections",
+ "sdk/python/reference/show-ipaddrs",
+ "sdk/python/reference/show-audit-logs"
+ ]
+ },
+ {
+ "group": "Billing",
+ "pages": [
+ "sdk/python/reference/show-deposit",
+ "sdk/python/reference/show-earnings",
+ "sdk/python/reference/show-invoices",
+ "sdk/python/reference/show-invoices-v1",
+ "sdk/python/reference/generate-pdf-invoices",
+ "sdk/python/reference/transfer-credit",
+ "sdk/python/reference/reports"
+ ]
+ },
+ {
+ "group": "Instances",
+ "pages": [
+ "sdk/python/reference/create-instance",
+ "sdk/python/reference/create-instances",
+ "sdk/python/reference/launch-instance",
+ "sdk/python/reference/start-instance",
+ "sdk/python/reference/start-instances",
+ "sdk/python/reference/stop-instance",
+ "sdk/python/reference/stop-instances",
+ "sdk/python/reference/reboot-instance",
+ "sdk/python/reference/recycle-instance",
+ "sdk/python/reference/destroy-instance",
+ "sdk/python/reference/destroy-instances",
+ "sdk/python/reference/label-instance",
+ "sdk/python/reference/prepay-instance",
+ "sdk/python/reference/update-instance",
+ "sdk/python/reference/show-instance",
+ "sdk/python/reference/show-instances",
+ "sdk/python/reference/show-instances-v1",
+ "sdk/python/reference/change-bid",
+ "sdk/python/reference/logs",
+ "sdk/python/reference/execute",
+ "sdk/python/reference/attach-ssh",
+ "sdk/python/reference/detach-ssh",
+ "sdk/python/reference/ssh-url",
+ "sdk/python/reference/scp-url",
+ "sdk/python/reference/copy",
+ "sdk/python/reference/cloud-copy",
+ "sdk/python/reference/cancel-copy",
+ "sdk/python/reference/cancel-sync"
+ ]
+ },
+ {
+ "group": "Search",
+ "pages": [
+ "sdk/python/reference/search-offers",
+ "sdk/python/reference/search-benchmarks",
+ "sdk/python/reference/search-invoices",
+ "sdk/python/reference/search-templates",
+ "sdk/python/reference/search-volumes"
+ ]
+ },
+ {
+ "group": "Serverless",
+ "pages": [
+ "sdk/python/reference/create-endpoint",
+ "sdk/python/reference/update-endpoint",
+ "sdk/python/reference/delete-endpoint",
+ "sdk/python/reference/show-endpoints",
+ "sdk/python/reference/create-workergroup",
+ "sdk/python/reference/update-workergroup",
+ "sdk/python/reference/update-workers",
+ "sdk/python/reference/delete-workergroup",
+ "sdk/python/reference/show-workergroups",
+ "sdk/python/reference/get-endpt-logs",
+ "sdk/python/reference/get-wrkgrp-logs",
+ "sdk/python/reference/show-scheduled-jobs",
+ "sdk/python/reference/delete-scheduled-job"
+ ]
+ },
+ {
+ "group": "Deployments",
+ "pages": [
+ "sdk/python/reference/delete-deployment",
+ "sdk/python/reference/show-deployment",
+ "sdk/python/reference/show-deployment-versions",
+ "sdk/python/reference/show-deployments"
+ ]
+ },
+ {
+ "group": "Team",
+ "pages": [
+ "sdk/python/reference/create-team",
+ "sdk/python/reference/destroy-team",
+ "sdk/python/reference/invite-member",
+ "sdk/python/reference/remove-member",
+ "sdk/python/reference/show-members",
+ "sdk/python/reference/create-team-role",
+ "sdk/python/reference/show-team-role",
+ "sdk/python/reference/show-team-roles",
+ "sdk/python/reference/update-team-role",
+ "sdk/python/reference/remove-team-role"
+ ]
+ },
+ {
+ "group": "Templates",
+ "pages": [
+ "sdk/python/reference/create-template",
+ "sdk/python/reference/update-template",
+ "sdk/python/reference/delete-template"
+ ]
+ },
+ {
+ "group": "Volumes",
+ "pages": [
+ "sdk/python/reference/create-volume",
+ "sdk/python/reference/clone-volume",
+ "sdk/python/reference/list-volume",
+ "sdk/python/reference/list-volumes",
+ "sdk/python/reference/show-volumes",
+ "sdk/python/reference/unlist-volume",
+ "sdk/python/reference/delete-volume"
+ ]
+ },
+ {
+ "group": "Machines",
+ "pages": [
+ "sdk/python/reference/cleanup-machine",
+ "sdk/python/reference/delete-machine",
+ "sdk/python/reference/list-machine",
+ "sdk/python/reference/list-machines",
+ "sdk/python/reference/show-machine",
+ "sdk/python/reference/show-machines",
+ "sdk/python/reference/remove-defjob",
+ "sdk/python/reference/set-defjob",
+ "sdk/python/reference/set-min-bid",
+ "sdk/python/reference/schedule-maint",
+ "sdk/python/reference/cancel-maint",
+ "sdk/python/reference/show-maints",
+ "sdk/python/reference/unlist-machine",
+ "sdk/python/reference/defrag-machines",
+ "sdk/python/reference/self-test-machine",
+ "sdk/python/reference/create-cluster",
+ "sdk/python/reference/delete-cluster",
+ "sdk/python/reference/show-clusters",
+ "sdk/python/reference/join-cluster",
+ "sdk/python/reference/remove-machine-from-cluster",
+ "sdk/python/reference/create-overlay",
+ "sdk/python/reference/delete-overlay",
+ "sdk/python/reference/show-overlays",
+ "sdk/python/reference/join-overlay"
+ ]
+ }
+ ]
+ },
+ {
+ "group": "Serverless",
+ "icon": "bolt",
+ "pages": [
+ {
+ "group": "Client",
+ "pages": [
+ "sdk/python/serverless/serverless",
+ "sdk/python/serverless/serverless-request",
+ "sdk/python/serverless/endpoint",
+ "sdk/python/serverless/session",
+ "sdk/python/serverless/client-worker"
+ ]
+ },
+ {
+ "group": "Server",
+ "pages": [
+ "sdk/python/serverless/server-worker",
+ "sdk/python/serverless/worker-config",
+ "sdk/python/serverless/handler-config",
+ "sdk/python/serverless/log-action-config",
+ "sdk/python/serverless/benchmark-config"
+ ]
+ }
]
}
]
@@ -374,11 +594,195 @@
"tab": "CLI",
"groups": [
{
- "group": "Getting Started",
+ "group": "Get Started",
+ "icon": "book",
+ "pages": [
+ "cli/hello-world",
+ {
+ "group": "Authentication",
+ "pages": [
+ "cli/authentication",
+ "cli/permissions"
+ ]
+ },
+ "cli/templates"
+ ]
+ },
+ {
+ "group": "Commands",
"icon": "terminal",
"pages": [
- "cli/get-started",
- "cli/commands"
+ {
+ "group": "Accounts",
+ "pages": [
+ "cli/reference/create-api-key",
+ "cli/reference/delete-api-key",
+ "cli/reference/reset-api-key",
+ "cli/reference/set-api-key",
+ "cli/reference/show-api-key",
+ "cli/reference/show-api-keys",
+ "cli/reference/create-ssh-key",
+ "cli/reference/delete-ssh-key",
+ "cli/reference/show-ssh-keys",
+ "cli/reference/update-ssh-key",
+ "cli/reference/create-env-var",
+ "cli/reference/delete-env-var",
+ "cli/reference/show-env-vars",
+ "cli/reference/update-env-var",
+ "cli/reference/show-user",
+ "cli/reference/set-user",
+ "cli/reference/create-subaccount",
+ "cli/reference/show-subaccounts",
+ "cli/reference/show-connections",
+ "cli/reference/show-ipaddrs",
+ "cli/reference/show-audit-logs"
+ ]
+ },
+ {
+ "group": "Billing",
+ "pages": [
+ "cli/reference/show-deposit",
+ "cli/reference/show-earnings",
+ "cli/reference/show-invoices",
+ "cli/reference/show-invoices-v1",
+ "cli/reference/transfer-credit",
+ "cli/reference/reports"
+ ]
+ },
+ {
+ "group": "Instances",
+ "pages": [
+ "cli/reference/create-instance",
+ "cli/reference/launch-instance",
+ "cli/reference/start-instance",
+ "cli/reference/start-instances",
+ "cli/reference/stop-instance",
+ "cli/reference/stop-instances",
+ "cli/reference/reboot-instance",
+ "cli/reference/recycle-instance",
+ "cli/reference/destroy-instance",
+ "cli/reference/destroy-instances",
+ "cli/reference/label-instance",
+ "cli/reference/prepay-instance",
+ "cli/reference/update-instance",
+ "cli/reference/change-bid",
+ "cli/reference/show-instance",
+ "cli/reference/show-instances",
+ "cli/reference/show-instances-v1",
+ "cli/reference/logs",
+ "cli/reference/execute",
+ "cli/reference/attach-ssh",
+ "cli/reference/detach-ssh",
+ "cli/reference/ssh-url",
+ "cli/reference/scp-url",
+ "cli/reference/copy",
+ "cli/reference/cloud-copy",
+ "cli/reference/cancel-copy",
+ "cli/reference/cancel-sync"
+ ]
+ },
+ {
+ "group": "Search",
+ "pages": [
+ "cli/reference/search-offers",
+ "cli/reference/search-benchmarks",
+ "cli/reference/search-instances",
+ "cli/reference/search-invoices",
+ "cli/reference/search-templates",
+ "cli/reference/search-volumes"
+ ]
+ },
+ {
+ "group": "Serverless",
+ "pages": [
+ "cli/reference/create-endpoint",
+ "cli/reference/update-endpoint",
+ "cli/reference/delete-endpoint",
+ "cli/reference/show-endpoints",
+ "cli/reference/create-workergroup",
+ "cli/reference/update-workergroup",
+ "cli/reference/update-workers",
+ "cli/reference/delete-workergroup",
+ "cli/reference/show-workergroups",
+ "cli/reference/get-endpt-logs",
+ "cli/reference/get-wrkgrp-logs",
+ "cli/reference/show-scheduled-jobs",
+ "cli/reference/delete-scheduled-job"
+ ]
+ },
+ {
+ "group": "Deployments",
+ "pages": [
+ "cli/reference/delete-deployment",
+ "cli/reference/show-deployment",
+ "cli/reference/show-deployment-versions",
+ "cli/reference/show-deployments"
+ ]
+ },
+ {
+ "group": "Team",
+ "pages": [
+ "cli/reference/create-team",
+ "cli/reference/destroy-team",
+ "cli/reference/invite-member",
+ "cli/reference/remove-member",
+ "cli/reference/show-members",
+ "cli/reference/create-team-role",
+ "cli/reference/show-team-role",
+ "cli/reference/show-team-roles",
+ "cli/reference/update-team-role",
+ "cli/reference/remove-team-role"
+ ]
+ },
+ {
+ "group": "Templates",
+ "pages": [
+ "cli/reference/create-template",
+ "cli/reference/update-template",
+ "cli/reference/delete-template"
+ ]
+ },
+ {
+ "group": "Volumes",
+ "pages": [
+ "cli/reference/create-volume",
+ "cli/reference/clone-volume",
+ "cli/reference/list-volume",
+ "cli/reference/list-volumes",
+ "cli/reference/show-volumes",
+ "cli/reference/unlist-volume",
+ "cli/reference/delete-volume"
+ ]
+ },
+ {
+ "group": "Machines",
+ "pages": [
+ "cli/reference/cleanup-machine",
+ "cli/reference/delete-machine",
+ "cli/reference/list-machine",
+ "cli/reference/list-machines",
+ "cli/reference/show-machine",
+ "cli/reference/show-machines",
+ "cli/reference/set-defjob",
+ "cli/reference/remove-defjob",
+ "cli/reference/set-min-bid",
+ "cli/reference/schedule-maint",
+ "cli/reference/cancel-maint",
+ "cli/reference/show-maints",
+ "cli/reference/unlist-machine",
+ "cli/reference/defrag-machines",
+ "cli/reference/self-test-machine",
+ "cli/reference/create-cluster",
+ "cli/reference/delete-cluster",
+ "cli/reference/show-clusters",
+ "cli/reference/join-cluster",
+ "cli/reference/remove-machine-from-cluster",
+ "cli/reference/create-overlay",
+ "cli/reference/delete-overlay",
+ "cli/reference/show-overlays",
+ "cli/reference/join-overlay"
+ ]
+ }
]
}
]
@@ -387,11 +791,17 @@
"tab": "API",
"groups": [
{
- "group": "API Reference",
- "icon": "webhook",
+ "group": "Get Started",
+ "icon": "book",
"pages": [
"api-reference/introduction",
- "api-reference/permissions-and-authorization",
+ {
+ "group": "Authentication",
+ "pages": [
+ "api-reference/authentication",
+ "api-reference/permissions"
+ ]
+ },
"api-reference/creating-and-using-templates-with-api",
"api-reference/creating-instances-with-api",
"api-reference/rate-limits-and-errors"
@@ -405,9 +815,7 @@
]
}
],
- "global": {
-
- }
+ "global": {}
},
"logo": {
"light": "/logo/light.svg",
@@ -428,15 +836,15 @@
},
"contextual": {
"options": [
- "copy",
- "view",
- "chatgpt",
- "claude",
- "perplexity",
- "mcp",
- "cursor",
- "vscode"
- ]
+ "copy",
+ "view",
+ "chatgpt",
+ "claude",
+ "perplexity",
+ "mcp",
+ "cursor",
+ "vscode"
+ ]
},
"footer": {
"socials": {
@@ -446,21 +854,33 @@
}
},
"redirects": [
+ {
+ "source": "/api-reference/permissions-and-authorization",
+ "destination": "/api-reference/permissions"
+ },
{
"source": "/jDpX-XUZdy-zKWbAZQPNKh",
"destination": "/rtx-5-series"
},
{
"source": "/cli",
- "destination": "/cli/get-started"
+ "destination": "/cli/hello-world"
+ },
+ {
+ "source": "/cli/get-started",
+ "destination": "/cli/hello-world"
+ },
+ {
+ "source": "/cli/commands",
+ "destination": "/cli/hello-world"
},
{
"source": "/api-reference/commands",
- "destination": "/cli/commands"
+ "destination": "/cli/hello-world"
},
{
"source": "/api-reference/overview-and-quickstart",
- "destination": "/cli/get-started"
+ "destination": "/cli/hello-world"
},
{
"source": "/index",
@@ -770,6 +1190,10 @@
"source": "/api",
"destination": "/api-reference/introduction"
},
+ {
+ "source": "/api-reference/hello-world",
+ "destination": "/api-reference/introduction"
+ },
{
"source": "/api/:slug*",
"destination": "/api-reference/:slug*"
@@ -781,7 +1205,7 @@
{
"source": "/vms",
"destination": "/linux-virtual-machines"
- }
+ }
],
"seo": {
"metatags": {
@@ -829,7 +1253,7 @@
"attributes": {
"type": "application/ld+json"
},
- "content": "{\"@context\":\"https://schema.org\",\"@type\":\"TechArticle\",\"headline\":\"Vast.ai Documentation – Affordable GPU Cloud Marketplace\",\"description\":\"Comprehensive documentation for Vast.ai GPU cloud computing platform including guides, API reference, and tutorials\",\"author\":{\"@type\":\"Organization\",\"name\":\"Vast.ai Team\"},\"publisher\":{\"@type\":\"Organization\",\"name\":\"Vast.ai\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://docs.vast.ai/logo/light.svg\"}},\"dateModified\":\"2025-09-25\",\"datePublished\":\"2024-01-01\",\"mainEntityOfPage\":{\"@type\":\"WebPage\",\"@id\":\"https://docs.vast.ai\"},\"articleSection\":\"Documentation\",\"keywords\":[\"GPU cloud\",\"AI training\",\"machine learning\",\"cloud computing\",\"documentation\",\"API\"]}"
+ "content": "{\"@context\":\"https://schema.org\",\"@type\":\"TechArticle\",\"headline\":\"Vast.ai Documentation \u2013 Affordable GPU Cloud Marketplace\",\"description\":\"Comprehensive documentation for Vast.ai GPU cloud computing platform including guides, API reference, and tutorials\",\"author\":{\"@type\":\"Organization\",\"name\":\"Vast.ai Team\"},\"publisher\":{\"@type\":\"Organization\",\"name\":\"Vast.ai\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://docs.vast.ai/logo/light.svg\"}},\"dateModified\":\"2025-09-25\",\"datePublished\":\"2024-01-01\",\"mainEntityOfPage\":{\"@type\":\"WebPage\",\"@id\":\"https://docs.vast.ai\"},\"articleSection\":\"Documentation\",\"keywords\":[\"GPU cloud\",\"AI training\",\"machine learning\",\"cloud computing\",\"documentation\",\"API\"]}"
}
]
}
diff --git a/sdk/python/authentication.mdx b/sdk/python/authentication.mdx
new file mode 100644
index 0000000..0929617
--- /dev/null
+++ b/sdk/python/authentication.mdx
@@ -0,0 +1,128 @@
+---
+title: "SDK Authentication"
+sidebarTitle: "Authentication"
+---
+
+Every request to the Vast.ai API requires an API key. The Python SDK accepts your key at initialization and includes it automatically in every call. This page covers how to set up, verify, and manage API keys through the SDK.
+
+## Set Your API Key
+
+Create a key from the [Keys page](https://cloud.vast.ai/manage-keys/), then pass it when initializing the client:
+
+```python
+from vastai import VastAI
+
+vast = VastAI(api_key="your-api-key")
+```
+
+If you omit `api_key`, the SDK reads from `~/.config/vastai/vast_api_key` (the same file the CLI uses). You can also use an environment variable:
+
+```python
+import os
+from vastai import VastAI
+
+vast = VastAI(api_key=os.environ["VAST_API_KEY"])
+```
+
+
+You can also create keys programmatically via the API ([Create API Key](/api-reference/accounts/create-api-key)) or CLI ([`vastai create api-key`](/cli/reference/create-api-key)).
+
+
+## Verify Your Key
+
+Confirm your key works by fetching your account info:
+
+```python
+user = vast.show_user()
+print(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 method you're calling.
+
+
+## Create an API Key
+
+You can create new keys from the SDK:
+
+```python
+result = vast.create_api_key(name="ci-deploy-key")
+print(result)
+```
+
+The response includes the new key value. Store it immediately -- you will not be able to retrieve it again.
+
+To create a key with restricted permissions, pass a JSON permissions file:
+
+```python
+result = vast.create_api_key(
+ name="ci-deploy-key",
+ permission_file="perms.json"
+)
+print(result)
+```
+
+See the [Permissions](/sdk/python/permissions) page for the full permissions file format and examples.
+
+## View and Delete Keys
+
+List all API keys on your account:
+
+```python
+keys = vast.show_api_keys()
+print(keys)
+```
+
+View a specific key's details by ID:
+
+```python
+key = vast.show_api_key(id=42)
+print(key)
+```
+
+Delete a key:
+
+```python
+vast.delete_api_key(id=42)
+```
+
+## Using a Scoped Key
+
+Once you have a scoped key, initialize a separate SDK client with it:
+
+```python
+from vastai import VastAI
+
+# Main client (full access)
+admin = VastAI(api_key="full-access-key")
+
+# Create a scoped key
+result = admin.create_api_key(
+ name="worker-key",
+ permission_file="readonly.json"
+)
+scoped_key = result["api_key"]
+
+# Use the scoped key in a separate client
+worker = VastAI(api_key=scoped_key)
+instances = worker.show_instances()
+```
+
+## 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/manage-keys/) or with `vast.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/sdk/python/hello-world.mdx b/sdk/python/hello-world.mdx
new file mode 100644
index 0000000..4975cc6
--- /dev/null
+++ b/sdk/python/hello-world.mdx
@@ -0,0 +1,292 @@
+---
+title: "SDK Hello World"
+sidebarTitle: "Hello World"
+---
+
+This guide walks through the core Vast.ai workflow using the Python SDK: authenticate, search for a GPU, rent it, wait for it to boot, connect, and clean up. It mirrors the [API Hello World](/api-reference/introduction) but uses the SDK instead of raw REST calls.
+
+## Prerequisites
+
+- A Vast.ai account with credit (~$0.01–0.05, depending on test instance run time)
+- Python 3 with the `vastai-sdk` package installed
+
+## Install the SDK
+
+```bash
+pip install vastai-sdk
+```
+
+## Import and Initialize
+
+```python
+from vastai_sdk import VastAI
+
+vast = VastAI(api_key="your-api-key-here")
+```
+
+You can also read the key from an environment variable:
+
+```python
+import os
+from vastai_sdk import VastAI
+
+vast = VastAI(api_key=os.environ["VAST_API_KEY"])
+```
+
+## Resource Methods
+
+Most CLI commands have a direct SDK equivalent. For example, `vastai show instances` becomes `vast.show_instances()`. Your IDE will surface type hints and available parameters automatically.
+
+
+Use `help(vast.search_offers)` (or any method) to view its description, parameters, and examples in your terminal.
+
+
+---
+
+## 1. Get Your API Key
+
+Generate an API key from the [Keys page](https://cloud.vast.ai/manage-keys/) by clicking **+New**. Copy the key — you'll only see it once.
+
+Export it so scripts can pick it up:
+
+```bash
+export VAST_API_KEY="your-api-key-here"
+```
+
+
+The console creates a full-access key by default. You can also create scoped API keys with limited permissions using [`vast.create_api_key()`](/sdk/python/reference/create-api-key) — useful for CI/CD or shared tooling where you want to restrict access.
+
+
+## 2. Verify Authentication
+
+Confirm your key works by fetching your account info:
+
+```python
+import os
+from vastai_sdk import VastAI
+
+vast = VastAI(api_key=os.environ["VAST_API_KEY"])
+print(vast.show_user())
+```
+
+```json
+{
+ "id": 123456,
+ "email": "you@example.com",
+ "credit": 25.00,
+ "ssh_key": "ssh-rsa AAAAB3..."
+}
+```
+
+The `credit` field shows your available balance, and `ssh_key` is the public key that will be injected into new instances.
+
+
+If you get an authentication error, double-check your API key.
+
+
+## 3. Search for GPUs
+
+Find available machines using [`search_offers()`](/sdk/python/reference/search-offers). This query returns the top 5 on-demand RTX 4090s sorted by deep learning performance per dollar:
+
+```python
+import json
+
+result = vast.search_offers(
+ query="gpu_name=RTX_4090 num_gpus=1 verified=True rentable=True direct_port_count>=1",
+ type="on-demand",
+ order="dlperf_per_dphtotal-",
+ limit=5,
+)
+offers = json.loads(result)
+for offer in offers:
+ print(f"ID: {offer['id']} GPU: {offer['gpu_name']} $/hr: {offer['dph_total']:.4f}")
+```
+
+Each part of the `query` string controls a different filter:
+
+| Filter | Meaning |
+|--------|---------|
+| `gpu_name=RTX_4090` | Filter to a specific GPU model |
+| `num_gpus=1` | Exactly 1 GPU per instance |
+| `verified=True` | Only machines verified by Vast.ai |
+| `rentable=True` | Only machines currently available to rent |
+| `direct_port_count>=1` | At least 1 directly accessible port (needed for SSH) |
+
+The `order` parameter sorts results — a trailing `-` means descending. The `type` parameter selects on-demand pricing (vs. interruptible spot/bid).
+
+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>=1`).
+
+
+See the [Search Offers](/api-reference/search/search-offers) API reference for the full list of filter parameters and operators.
+
+
+## 4. Register Your SSH Key
+
+**Do this before creating an instance.** Your SSH public key must be registered on your account — it is applied at container creation time.
+
+```python
+pubkey = open(os.path.expanduser("~/.ssh/id_ed25519.pub")).read().strip()
+vast.create_ssh_key(ssh_key=pubkey)
+```
+
+Your key persists on your account — you only need to do this once per key. If you forgot and already created an instance, use the SSH key button on the instance card in the console to add a key without recreating.
+
+## 5. Create an Instance
+
+Rent a machine by calling [`create_instance()`](/sdk/python/reference/create-instance) with an offer `id` from step 3 (search):
+
+```python
+offer_id = offers[0]["id"] # from step 3
+
+result = vast.create_instance(
+ id=offer_id,
+ image="pytorch/pytorch:2.4.0-cuda12.4-cudnn9-runtime",
+ disk=20,
+ onstart_cmd="echo hello && nvidia-smi",
+ direct=True,
+)
+result = json.loads(result)
+print(result)
+```
+
+```json
+{
+ "success": true,
+ "new_contract": 12345678
+}
+```
+
+Save the `new_contract` value — this is your **instance ID**.
+
+| Parameter | Meaning |
+|-----------|---------|
+| `id` | The offer ID from `search_offers()` |
+| `image` | Docker image to run |
+| `disk` | Disk space in GB |
+| `onstart_cmd` | Shell command(s) to run when the instance boots |
+| `direct` | `True` for direct SSH (lower latency than proxy SSH) |
+
+
+Setting `direct=True` is equivalent to `"runtype": "ssh_direct"` in the REST API. Recommended for interactive work.
+
+
+
+`onstart_cmd` is limited to **4048 characters**. For longer scripts, gzip and base64 encode them — see the [Template Settings](/documentation/templates/template-settings#on-start-script) page for the workaround.
+
+
+If you have a **template**, you can use it instead of specifying image and startup commands:
+
+```python
+result = vast.create_instance(
+ id=offer_id,
+ template_hash="YOUR_TEMPLATE_HASH",
+ disk=20,
+ direct=True,
+)
+```
+
+
+**Shortcut:** [`launch_instance()`](/sdk/python/reference/launch-instance) combines search and create into a single call:
+
+```python
+vast.launch_instance(
+ num_gpus="1",
+ gpu_name="RTX_4090",
+ image="pytorch/pytorch:2.4.0-cuda12.4-cudnn9-runtime",
+ disk=20,
+ direct=True,
+)
+```
+
+This searches for available offers matching your criteria and immediately creates an instance on the best match. Useful for scripts where you don't need to inspect offers first.
+
+
+## 6. Wait Until Ready
+
+The instance needs time to pull the Docker image and boot. Poll with [`show_instance()`](/sdk/python/reference/show-instance) until `actual_status` is `"running"`:
+
+```python
+import time
+
+instance_id = result["new_contract"]
+
+while True:
+ info = json.loads(vast.show_instance(id=instance_id))
+ status = info.get("actual_status")
+ print(f"Status: {status}")
+ if status == "running":
+ break
+ time.sleep(10)
+
+ssh_host = info["ssh_host"]
+ssh_port = info["ssh_port"]
+print(f"SSH: ssh -p {ssh_port} root@{ssh_host}")
+```
+
+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 Docker image size.
+
+## 7. Connect via SSH
+
+Use the `ssh_host` and `ssh_port` from the status response to connect:
+
+```bash
+ssh root@SSH_HOST -p SSH_PORT
+```
+
+Replace `SSH_HOST` and `SSH_PORT` with the values printed by the polling loop above.
+
+## 8. Copy Data
+
+The SDK provides [`copy()`](/sdk/python/reference/copy) for file transfers. Use the instance ID to reference remote paths:
+
+```python
+# Upload to instance
+vast.copy(src="./data/", dst=f"{instance_id}:/workspace/data/")
+
+# Download from instance
+vast.copy(src=f"{instance_id}:/workspace/results/", dst="./results/")
+```
+
+
+You can also use standard tools like `rsync` or `scp` with the SSH connection from step 6:
+
+```bash
+rsync -avz -e "ssh -p SSH_PORT" ./data/ root@SSH_HOST:/workspace/data/
+```
+
+For cloud storage syncing and instance-to-instance transfers, see the [data movement guide](/documentation/instances/storage/data-movement).
+
+
+## 9. Clean Up
+
+When you're done, destroy the instance to stop all billing:
+
+```python
+vast.destroy_instance(id=instance_id)
+```
+
+To **pause** an instance temporarily instead, use [`stop_instance()`](/sdk/python/reference/stop-instance). Stopping halts compute billing but disk storage charges continue:
+
+```python
+vast.stop_instance(id=instance_id)
+```
+
+
+A stopped instance still incurs disk storage charges. Destroy the instance to stop all billing entirely.
+
+
+## Next Steps
+
+You've completed the full instance lifecycle through the SDK. 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.
+- **Full method reference** — Browse all available SDK methods in the [VastAI Client reference](/sdk/python/reference/vastai).
diff --git a/sdk/python/permissions.mdx b/sdk/python/permissions.mdx
new file mode 100644
index 0000000..b1e6519
--- /dev/null
+++ b/sdk/python/permissions.mdx
@@ -0,0 +1,255 @@
+---
+title: "SDK Permissions"
+sidebarTitle: "Permissions"
+---
+
+Every API key has a set of permissions that control which endpoints it can access. This page covers permission categories, how to build scoped keys, and how to manage team roles through the Python SDK.
+
+For an overview of API key creation and setup, see [Authentication](/sdk/python/authentication).
+
+## Permission Categories
+
+Permissions are organized into categories. When you create a scoped API key, you include only the categories the key needs:
+
+| 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 |
+
+For the complete mapping of which specific endpoints each category controls, see [Permissions (API)](/api-reference/permissions#endpoint-reference-by-category).
+
+## Creating Scoped Keys
+
+Define permissions as a JSON file. The top-level key is always `"api"`, containing the categories you want to grant:
+
+```json
+{
+ "api": {
+ "misc": {},
+ "user_read": {},
+ "instance_read": {},
+ "instance_write": {}
+ }
+}
+```
+
+Save this as `perms.json`, then pass it to the SDK:
+
+```python
+from vastai import VastAI
+
+vast = VastAI(api_key="your-api-key")
+
+result = vast.create_api_key(
+ name="ci-deploy-key",
+ permission_file="perms.json"
+)
+print(result)
+```
+
+## Constraints
+
+Constraints narrow a permission category to specific parameter values. This lets you create keys that can only operate on certain resources.
+
+### Constrain by Exact ID
+
+This permissions file allows reading logs for instance 1227 only:
+
+```json
+{
+ "api": {
+ "instance_read": {
+ "api.instance.request_logs": {
+ "constraints": {
+ "id": {
+ "eq": 1227
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+### Constrain by Range
+
+You can combine `gte` (greater than or equal) and `lte` (less than or equal) operators to define a range:
+
+```json
+{
+ "api": {
+ "instance_read": {
+ "api.instance.request_logs": {
+ "constraints": {
+ "id": {
+ "gte": 1,
+ "lte": 100
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+Available constraint operators: `eq`, `gte`, `lte`.
+
+
+Keys with constraints must be created through the SDK, CLI, or API. The web console only creates full-access keys.
+
+
+## Managing Team Roles
+
+Team roles use the same permission model as API keys. You define permissions in a JSON file and pass its path to the SDK methods.
+
+### Create a Role
+
+```python
+vast.create_team_role(
+ name="developer",
+ permissions="perms.json"
+)
+```
+
+### View Roles
+
+List all roles for your team:
+
+```python
+roles = vast.show_team_roles()
+print(roles)
+```
+
+View a specific role by name:
+
+```python
+role = vast.show_team_role(NAME="developer")
+print(role)
+```
+
+### Update a Role
+
+```python
+vast.update_team_role(
+ id=5,
+ name="senior-dev",
+ permissions="updated-perms.json"
+)
+```
+
+### Remove a Role
+
+```python
+vast.remove_team_role(NAME="developer")
+```
+
+### Invite a Team Member
+
+Assign a role when inviting a new member:
+
+```python
+vast.invite_member(
+ email="teammate@example.com",
+ role="developer"
+)
+```
+
+### View Team Members
+
+```python
+members = vast.show_members()
+print(members)
+```
+
+## Examples
+
+### Read-Only Key
+
+A key that can view instances and account info but cannot create, modify, or destroy anything:
+
+```json
+{
+ "api": {
+ "instance_read": {},
+ "user_read": {}
+ }
+}
+```
+
+```python
+result = vast.create_api_key(
+ name="monitoring",
+ permission_file="readonly.json"
+)
+print(result)
+```
+
+### Instance Management Without Billing
+
+A key that can create and manage instances but has no access to billing or credit transfers:
+
+```json
+{
+ "api": {
+ "misc": {},
+ "user_read": {},
+ "instance_read": {},
+ "instance_write": {}
+ }
+}
+```
+
+```python
+result = vast.create_api_key(
+ name="ci-deploy",
+ permission_file="deploy.json"
+)
+print(result)
+```
+
+### Constrained Key for a Specific Instance
+
+A key that can only manage a single instance (view, reboot, destroy) and nothing else:
+
+```json
+{
+ "api": {
+ "instance_read": {
+ "api.instance.show": {
+ "constraints": {
+ "id": { "eq": 1227 }
+ }
+ }
+ },
+ "instance_write": {
+ "api.instance.destroy": {
+ "constraints": {
+ "id": { "eq": 1227 }
+ }
+ },
+ "api.instance.reboot": {
+ "constraints": {
+ "id": { "eq": 1227 }
+ }
+ }
+ }
+ }
+}
+```
+
+```python
+result = vast.create_api_key(
+ name="instance-1227-only",
+ permission_file="constrained.json"
+)
+print(result)
+```
diff --git a/sdk/python/quickstart.mdx b/sdk/python/quickstart.mdx
index 5b18783..e5693a6 100644
--- a/sdk/python/quickstart.mdx
+++ b/sdk/python/quickstart.mdx
@@ -1,253 +1,224 @@
---
-title: Python SDK Usage
-createdAt: Mon Jan 13 2025 21:20:40 GMT+0000 (Coordinated Universal Time)
-updatedAt: Mon Apr 28 2025 17:22:01 GMT+0000 (Coordinated Universal Time)
+title: "SDK Hello World"
+sidebarTitle: "Hello World"
---
-
-
-We provide a [PyPI package](https://pypi.org/project/vastai/), `vastai-sdk`, for convenient Python usage.
-
-## PyPI Install
-
-You can install the latest stable PyPI release with:
-
-```text Text
+The Vast.ai Python SDK gives you programmatic access to the entire platform from Python — authentication, GPU search, instance lifecycle, templates, volumes, serverless endpoints, and more. Anything you can do in the web console, you can automate from a Python script.
+
+This guide walks through the core workflow: install the SDK, authenticate, search for a GPU, rent it, wait for it to boot, connect to it, copy data, and clean up. By the end you'll understand the method 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)
+- Python 3 installed
+
+## 1. Install the SDK
+
+Install from PyPI:
+
+```bash
pip install vastai-sdk
```
-## Usage
+## 2. Authenticate
+
+Import the SDK and create a client with your API key. Generate an API key from the [Keys page](https://cloud.vast.ai/manage-keys/) by clicking **+New**. Copy the key — you'll only see it once.
+
+```python
+from vastai import VastAI
+
+vast = VastAI(api_key="YOUR_API_KEY")
+```
+
+If you've previously set a key via the CLI (`vastai set api-key`), the SDK reads it automatically from `~/.config/vastai/vast_api_key` — no need to pass it explicitly:
+
+```python
+vast = VastAI()
+```
+
+
+The console creates a full-access key by default. You can also create scoped keys with limited permissions using `vast.create_api_key()` — useful for CI/CD or shared tooling. See the [permissions guide](/sdk/python/permissions) for details.
+
-Import the package:
+## 3. Verify Authentication
-```text Text
-from vastai_sdk import VastAI
+Confirm your key works by fetching your account info:
+
+```python
+user = vast.show_user()
+print(user)
```
-Construct a Vast client with your API key:
+This returns your user ID, email, balance, and SSH key. If you see an authentication error, double-check your API key.
+
+## 4. Search for GPUs
-```text Text
-vast_sdk = VastAI(api_key='YOUR_API_KEY')
+Find available machines using `search_offers`. This query returns on-demand RTX 4090s on verified machines with direct port access, sorted by deep learning performance per dollar:
+
+```python
+offers = vast.search_offers(
+ query="gpu_name=RTX_4090 num_gpus=1 verified=true direct_port_count>=1 rentable=true",
+ order="dlperf_usd-",
+ limit="5",
+)
+print(offers)
```
-## Resource Methods
+Each parameter in the query string controls a different filter:
+
+| Parameter | Meaning |
+|-----------|---------|
+| `gpu_name=RTX_4090` | Filter to a specific GPU model |
+| `num_gpus=1` | Exactly 1 GPU per instance |
+| `verified=true` | Only machines verified by Vast.ai (identity-checked hosts) |
+| `direct_port_count>=1` | At least 1 directly accessible port (needed for direct SSH) |
+| `rentable=true` | Only machines currently available to rent |
+| `order="dlperf_usd-"` | Sort by DL performance per dollar, best value first |
+
+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`).
+
+
+Use `help(vast.search_offers)` for the full list of filter fields and options, or see the [search_offers reference](/sdk/python/reference/search-offers).
+
+
+## 5. Create an Instance
+
+Rent the machine using `create_instance` with the offer ID from step 4:
+
+```python
+result = vast.create_instance(
+ id=OFFER_ID,
+ image="pytorch/pytorch:2.4.0-cuda12.4-cudnn9-runtime",
+ disk=20,
+ onstart_cmd="echo hello && nvidia-smi",
+ ssh=True,
+ direct=True,
+)
+print(result)
+```
-Most CLI commands have direct equivalents in the Python SDK. Your VastAI client exposes the same functionality through class methods and IDE's will surface type hints and arguments automatically.
+| Parameter | Meaning |
+|-----------|---------|
+| `image` | Docker image to launch |
+| `disk` | Disk storage in GB |
+| `onstart_cmd` | Command to run when the instance boots |
+| `ssh=True, direct=True` | Direct SSH access (lower latency than proxy SSH) |
-For example, the CLI command `vastai show instances` has the equivalent, `vast_sdk.show_instances()`.
+The output includes the new instance ID:
-```text Text
-output = vast_sdk.show_instances()
-print(output)
+```json
+{"success": true, "new_contract": 12345678}
```
-### Getting help
+Save the `new_contract` value — this is your instance ID.
-Use the built-in `help()` method to view detailed documentation for any SDK method. This will show you the method’s description, parameters, query syntax, and usage examples.
+
+Storage charges begin at creation. GPU charges begin when the instance reaches the `running` state.
+
-```text Text
-help(vast_sdk.search_offers)
+## 6. Wait Until Ready
+
+The instance needs time to pull the Docker image and boot. Check the status:
+
+```python
+import time
+
+instance_id = result["new_contract"]
+
+while True:
+ info = vast.show_instance(id=instance_id)
+ status = info.get("actual_status")
+ print(f"Status: {status}")
+ if status == "running":
+ break
+ time.sleep(10)
```
-## Example Usage
+The status progresses through these states:
+
+| Status | Meaning |
+|--------|---------|
+| `loading` | Docker image is downloading |
+| `running` | Ready to use |
-Here are some example usages of our Python SDK class `VastAI`:
+Boot time is typically 1-5 minutes depending on the Docker image size.
-### Search offers
+
+Always handle non-happy-path statuses in your poll loop. If `actual_status` becomes `"exited"` (container crashed), `"unknown"` (no heartbeat from host), or `"offline"` (host disconnected), it will never reach `"running"`. Without a timeout or error check, your script will loop forever while the instance continues accruing disk charges. Destroy the instance and retry with a different offer if you see these states.
+
+
+## 7. Connect via SSH
+
+Once the instance is running, get the SSH connection details:
+
+```python
+ssh_url = vast.ssh_url(id=instance_id)
+print(ssh_url)
+```
-Find an available RTX 3090 GPU
+Then connect from your terminal:
-```text Text
-vast_sdk.search_offers(query='gpu_name=RTX_5090 rented=False rentable=True)
+```bash
+ssh root@SSH_HOST -p SSH_PORT
```
-### Starting and Stopping Instances
+## 8. Copy Data
-```text Text
-vast_sdk.start_instance(ID=12345678)
+Use `copy` to transfer files between your local machine and the instance:
-vast_sdk.stop_instance(ID=12345678)
+```python
+# Upload to instance
+vast.copy(src="local:./data/", dst=f"{instance_id}:/workspace/data/")
+
+# Download from instance
+vast.copy(src=f"{instance_id}:/workspace/results/", dst="local:./results/")
```
-### Creating a New Instance
+You can also copy between instances or to/from cloud storage:
-Create a new instance based on given parameters (performs search offers + create instance).
+```python
+# Instance to instance
+vast.copy(src=f"{instance_a}:/workspace/", dst=f"{instance_b}:/workspace/")
-```text Text
-vast_sdk.launch_instance(num_gpus="1", gpu_name="RTX_3090", image="pytorch/pytorch")
+# Cloud storage (requires a configured cloud connection)
+vast.cloud_copy(src=f"s3.CONNECTION_ID:/bucket/data/", dst=f"{instance_id}:/workspace/")
```
-### Copying Files Between Instances
+For cloud storage syncing and instance-to-instance transfers, see the [data movement guide](/documentation/instances/storage/data-movement).
+
+## 9. 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):
-```text Text
-vast_sdk.copy(src='source_path', dst='destination_path', identity='identity_file')
+```python
+vast.destroy_instance(id=instance_id)
```
-### Managing SSH Keys
+**Stop** (pauses compute, disk charges continue):
-Create a new SSH key, show all SSH keys, and delete an SSH key.
+```python
+vast.stop_instance(id=instance_id)
+```
-```text Text
-vast_sdk.create_ssh_key(ssh_key='your_ssh_key')
+## Getting Help
-ssh_keys = vast_sdk.show_ssh_keys()
-print(ssh_keys)
+Use Python's built-in `help()` to view detailed documentation for any SDK method:
-vast_sdk.delete_ssh_key(ID=123456)
+```python
+help(vast.search_offers)
```
-## Contribution and Issue Reporting
-
-This [code repository](https://github.com/vast-ai/vast-python) is open source and can be rapidly changing at times. If you find a potential bug, please open an issue on GitHub. If you wish to contribute to improving this code and its functionality, feel welcome to open a PR with any improvements on our [GitHub repository](https://github.com/vast-ai/vast-python).
-
-## Available Methods
-
-Below is a list of the available methods you can call on the `VastAI` client. These methods are categorized for better readability.
-
-### Instance Management
-
-| Method | Description |
-| ------ | ----------- |
-| `start_instance(ID: int)` | Start an instance. |
-| `stop_instance(ID: int)` | Stop an instance. |
-| `reboot_instance(ID: int)` | Reboot an instance. |
-| `destroy_instance(id: int)` | Destroy an instance. |
-| `destroy_instances(ids: List[int])` | Destroy multiple instances. |
-| `recycle_instance(ID: int)` | Recycle an instance. |
-| `label_instance(id: int, label: str)` | Label an instance. |
-| `show_instance(id: int)` | Show details of an instance. |
-| `show_instances(quiet: bool = False)` | Show all instances. |
-| `logs(INSTANCE_ID: int, tail: Optional[str] = None)` | Retrieve logs for an instance. |
-| `execute(ID: int, COMMAND: str)` | Execute a command on an instance. |
-| `launch_instance(...)` | Launch a new instance with various parameters. |
-
-### SSH Key Management
-
-| Method | Description |
-| ------ | ----------- |
-| `create_ssh_key(ssh_key: str)` | Create a new SSH key. |
-| `delete_ssh_key(ID: int)` | Delete an SSH key. |
-| `show_ssh_keys()` | Show all SSH keys. |
-| `attach_ssh(instance_id: int, ssh_key: str)` | Attach an SSH key to an instance. |
-| `detach_ssh(instance_id: int, ssh_key_id: str)` | Detach an SSH key from an instance. |
-
-### API Key Management
-
-| Method | Description |
-| ------ | ----------- |
-| `create_api_key(name: Optional[str] = None, ...)` | Create a new API key. |
-| `delete_api_key(ID: int)` | Delete an API key. |
-| `reset_api_key()` | Reset the API key. |
-| `show_api_key(id: int)` | Show details of an API key. |
-| `show_api_keys()` | Show all API keys. |
-| `set_api_key(new_api_key: str)` | Set a new API key. |
-
-### Autoscaler Management
-
-| Method | Description |
-| ------ | ----------- |
-| `create_autoscaler(test_workers: int = 3, ...)` | Create a new autoscaler. |
-| `update_autoscaler(ID: int, min_load: Optional[float] = None, ...)` | Update an autoscaler. |
-| `delete_autoscaler(ID: int)` | Delete an autoscaler. |
-| `show_autoscalers()` | Show all autoscalers. |
-
-### Endpoint Management
-
-| Method | Description |
-| ------ | ----------- |
-| `create_endpoint(min_load: float = 0.0, ...)` | Create a new endpoint. |
-| `update_endpoint(ID: int, min_load: Optional[float] = None, ...)` | Update an endpoint. |
-| `delete_endpoint(ID: int)` | Delete an endpoint. |
-| `show_endpoints()` | Show all endpoints. |
-
-### File Management
-
-| Method | Description |
-| ------ | ----------- |
-| `copy(src: str, dst: str, identity: Optional[str] = None)` | Copy files between instances. |
-| `cloud_copy(src: Optional[str] = None, dst: Optional[str] = "/workspace", ...)` | Copy files between cloud and instance. |
-| `cancel_copy(dst: str)` | Cancel a file copy operation. |
-| `cancel_sync(dst: str)` | Cancel a file sync operation. |
-| `scp_url(id: int)` | Get the SCP URL for transferring files to/from an instance. |
-
-### Team Management
-
-| Method | Description |
-| ------ | ----------- |
-| `create_team(team_name: Optional[str] = None)` | Create a new team. |
-| `destroy_team()` | Destroy a team. |
-| `invite_team_member(email: Optional[str] = None, role: Optional[str] = None)` | Invite a new member to the team. |
-| `remove_team_member(ID: int)` | Remove a member from the team. |
-| `create_team_role(name: Optional[str] = None, permissions: Optional[str] = None)` | Create a new team role. |
-| `remove_team_role(NAME: str)` | Remove a role from the team. |
-| `update_team_role(ID: int, name: Optional[str] = None, permissions: Optional[str] = None)` | Update details of a team role. |
-| `show_team_members()` | Show all team members. |
-| `show_team_role(NAME: str)` | Show details of a specific team role. |
-| `show_team_roles()` | Show all team roles. |
-
-### Host Management
-
-| Method | Description |
-| ------ | ----------- |
-| `cleanup_machine(ID: int)` | Clean up a machine's configuration and resources. |
-| `list_machine(ID: int, price_gpu: Optional[float] = None, price_disk: Optional[float] = None, price_inetu: Optional[float] = None, price_inetd: Optional[float] = None, discount_rate: Optional[float] = None, min_chunk: Optional[int] = None, end_date: Optional[str] = None)` | List details of a single machine with optional pricing and configuration parameters. |
-| `list_machines(IDs: List[int], price_gpu: Optional[float] = None, price_disk: Optional[float] = None, price_inetu: Optional[float] = None, price_inetd: Optional[float] = None, discount_rate: Optional[float] = None, min_chunk: Optional[int] = None, end_date: Optional[str] = None)` | List details of multiple machines with optional pricing and configuration parameters. |
-| `remove_defjob(id: int)` | Remove the default job from a machine. |
-| `set_defjob(id: int, price_gpu: Optional[float] = None, price_inetu: Optional[float] = None, price_inetd: Optional[float] = None, image: Optional[str] = None, args: Optional[List[str]] = None)` | Set a default job on a machine with specified parameters. |
-| `set_min_bid(id: int, price: Optional[float] = None)` | Set the minimum bid price for a machine. |
-| `schedule_maint(id: int, sdate: Optional[float] = None, duration: Optional[float] = None)` | Schedule maintenance for a machine. |
-| `cancel_maint(id: int)` | Cancel scheduled maintenance for a machine. |
-| `unlist_machine(id: int)` | Unlist a machine from being available for new jobs. |
-| `show_machines(quiet: bool = False, filter: Optional[str] = None)` | Retrieve and display a list of machines based on specified criteria. |
-
-### Other Methods
-
-| Method | Description |
-| ------ | ----------- |
-| `get_gpu_names()` | Returns a set of GPU names available on Vast.ai. |
-| `show_connections()` | Show all connections. |
-| `show_deposit(ID: int)` | Show deposit details for an instance. |
-| `show_earnings(quiet: bool = False, start_date: Optional[str] = None, end_date: Optional[str] = None, machine_id: Optional[int] = None)` | Show earnings information. |
-| `show_invoices(quiet: bool = False, start_date: Optional[str] = None, end_date: Optional[str] = None, ...)` | Show invoice details. |
-| `show_ipaddrs()` | Show IP addresses. |
-| `show_user(quiet: bool = False)` | Show user details. |
-| `show_subaccounts(quiet: bool = False)` | Show all subaccounts of the current user. |
-| `transfer_credit(recipient: str, amount: float)` | Transfer credit to another account. |
-| `update_ssh_key(id: int, ssh_key: str)` | Update an SSH key. |
-| `generate_pdf_invoices(quiet: bool = False, start_date: Optional[str] = None, end_date: Optional[str] = None, only_charges: bool = False, only_credits: bool = False)` | Generate PDF invoices based on filters. |
-
-For a complete list of methods and their usage, please refer to [Commands](https://docs.vast.ai/cli/commands).
+Your IDE will also surface type hints and available methods automatically.
+
+## Next Steps
+
+You've now completed the full instance lifecycle through the SDK: installation, authentication, search, creation, polling, data transfer, and teardown. From here:
+
+- **SSH setup** — See the [SSH guide](/documentation/instances/connect/ssh) for key configuration and advanced connection options.
+- **Full method reference** — See the [SDK reference](/sdk/python/reference/vastai) for every available method.
+- **Use templates** — Avoid repeating image and config parameters on every create call. See the [templates guide](/sdk/python/templates) for creating and managing templates.
+- **Permissions** — Create scoped API keys for CI/CD or shared tooling. See the [permissions guide](/sdk/python/permissions).
diff --git a/sdk/python/rate-limits.mdx b/sdk/python/rate-limits.mdx
new file mode 100644
index 0000000..813057f
--- /dev/null
+++ b/sdk/python/rate-limits.mdx
@@ -0,0 +1,112 @@
+---
+title: "SDK Rate Limits and Errors"
+sidebarTitle: "Rate Limits"
+---
+
+The Vast.ai Python SDK automatically retries rate-limited requests. You do not need to implement your own retry logic -- both the `VastAI` client and the serverless client handle retries with exponential backoff out of the box.
+
+This page covers the error format, how rate limits work, and how to configure retry behavior for each client. For the full details on rate limit mechanics, see the [API Rate Limits and Errors](/api-reference/rate-limits-and-errors) page.
+
+## Error Responses
+
+The underlying API error shape is:
+
+```json
+{
+ "success": false,
+ "error": "invalid_args",
+ "msg": "Human-readable description of the problem."
+}
+```
+
+Some endpoints omit `success` or `error` and return only `msg` or `message`.
+
+The `VastAI` client returns the error as a dictionary when `raw=True` is set, or prints the message otherwise. The serverless client raises an exception after exhausting all retries.
+
+## How Rate Limits Work
+
+Vast.ai applies rate limits **per endpoint** and **per identity**. The identity is determined by your bearer token, session user, `api_key` parameter, and client IP.
+
+Some endpoints also enforce **method-specific** limits (GET vs POST) and **max-calls-per-period** limits for short bursts.
+
+For the full breakdown, see [How rate limits are applied](/api-reference/rate-limits-and-errors#how-rate-limits-are-applied).
+
+## Rate Limit Response
+
+When you hit a rate limit, the API returns **HTTP 429** with a message like:
+
+```
+API requests too frequent
+```
+
+or
+
+```
+API requests too frequent: endpoint threshold=...
+```
+
+The API does not return a `Retry-After` header. The SDK handles this automatically using its built-in retry logic.
+
+## Built-in Retry Behavior
+
+The SDK includes two clients with different retry strategies.
+
+### VastAI Client
+
+The main `VastAI` client retries on rate limit responses:
+
+- **Retried status codes:** 429 only
+- **Default retries:** 3
+- **Backoff strategy:** starts at 0.15 seconds, multiplied by 1.5x after each attempt
+- **Retry delays:** ~0.15s, ~0.225s, ~0.34s
+
+```python
+from vastai import VastAI
+
+# Uses default retry behavior (3 retries)
+vast = VastAI(api_key="your-api-key")
+vast.search_offers(query="gpu_name=RTX_4090 rentable=true")
+```
+
+### Serverless Client
+
+The serverless client has a broader retry scope, covering transient server errors in addition to rate limits:
+
+- **Retried status codes:** 408 (timeout), 429 (rate limit), and 5xx (server errors)
+- **Default retries:** 5
+- **Backoff strategy:** exponential with jitter -- `min(2^attempt + random(0, 1), 5.0)` seconds
+- **Max delay:** 5 seconds per retry
+
+The jitter (random 0--1 second addition) prevents multiple clients from retrying in lockstep, which reduces the chance of repeated collisions.
+
+
+The serverless client retries on a wider range of errors than the `VastAI` client. Server errors (5xx) and timeouts (408) are retried automatically -- you do not need to handle these yourself.
+
+
+## Configuring Retries
+
+### VastAI Client
+
+Pass the `retry` parameter to the constructor to change the number of retry attempts:
+
+```python
+from vastai import VastAI
+
+# Increase to 6 retries for a batch script
+vast = VastAI(api_key="your-api-key", retry=6)
+
+# Disable retries entirely
+vast = VastAI(api_key="your-api-key", retry=0)
+```
+
+The retry count applies to all requests made through that client instance.
+
+### Serverless Client
+
+The serverless client defaults to 5 retries. The retry count is configured internally per request through the `_make_request()` method's `retries` parameter.
+
+## Reducing Rate Limit Errors
+
+If you are consistently hitting rate limits, the best approach is to reduce the volume and frequency of your requests. See [How to reduce rate limit errors](/api-reference/rate-limits-and-errors#how-to-reduce-rate-limit-errors) for practical strategies including batching, reduced polling, and traffic spreading.
+
+If you need higher limits for production usage, contact support with the endpoint(s), your expected call rate, and your account details.
diff --git a/sdk/python/reference/attach-ssh.mdx b/sdk/python/reference/attach-ssh.mdx
new file mode 100644
index 0000000..352a084
--- /dev/null
+++ b/sdk/python/reference/attach-ssh.mdx
@@ -0,0 +1,36 @@
+---
+title: "VastAI.attach_ssh"
+sidebarTitle: "attach_ssh"
+---
+
+Attach an SSH key to an instance.
+
+## Signature
+
+```python
+VastAI.attach_ssh(instance_id: int, ssh_key: str) -> str
+```
+
+## Parameters
+
+
+ instance_id
+
+
+
+ ssh_key
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.attach_ssh(instance_id=12345, ssh_key="...")
+print(result)
+```
diff --git a/sdk/python/reference/cancel-copy.mdx b/sdk/python/reference/cancel-copy.mdx
new file mode 100644
index 0000000..6de8d41
--- /dev/null
+++ b/sdk/python/reference/cancel-copy.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.cancel_copy"
+sidebarTitle: "cancel_copy"
+---
+
+Cancel a file copy operation.
+
+## Signature
+
+```python
+VastAI.cancel_copy(dst: str) -> str
+```
+
+## Parameters
+
+
+ dst
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.cancel_copy(dst="...")
+print(result)
+```
diff --git a/sdk/python/reference/cancel-maint.mdx b/sdk/python/reference/cancel-maint.mdx
new file mode 100644
index 0000000..b7b2744
--- /dev/null
+++ b/sdk/python/reference/cancel-maint.mdx
@@ -0,0 +1,34 @@
+---
+title: "VastAI.cancel_maint"
+sidebarTitle: "cancel_maint"
+---
+
+Cancel scheduled maintenance for a machine.
+
+This is a **host** method, used for managing machines you are renting out on Vast.ai.
+
+## Signature
+
+```python
+VastAI.cancel_maint(id: int) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.cancel_maint(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/cancel-sync.mdx b/sdk/python/reference/cancel-sync.mdx
new file mode 100644
index 0000000..cbd2d31
--- /dev/null
+++ b/sdk/python/reference/cancel-sync.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.cancel_sync"
+sidebarTitle: "cancel_sync"
+---
+
+Cancel a file sync operation.
+
+## Signature
+
+```python
+VastAI.cancel_sync(dst: str) -> str
+```
+
+## Parameters
+
+
+ dst
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.cancel_sync(dst="...")
+print(result)
+```
diff --git a/sdk/python/reference/change-bid.mdx b/sdk/python/reference/change-bid.mdx
new file mode 100644
index 0000000..10ae13c
--- /dev/null
+++ b/sdk/python/reference/change-bid.mdx
@@ -0,0 +1,36 @@
+---
+title: "VastAI.change_bid"
+sidebarTitle: "change_bid"
+---
+
+Change the bid price for a machine.
+
+## Signature
+
+```python
+VastAI.change_bid(id: int, price: Optional[float] = None) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+
+ price
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.change_bid(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/cleanup-machine.mdx b/sdk/python/reference/cleanup-machine.mdx
new file mode 100644
index 0000000..ac403b7
--- /dev/null
+++ b/sdk/python/reference/cleanup-machine.mdx
@@ -0,0 +1,34 @@
+---
+title: "VastAI.cleanup_machine"
+sidebarTitle: "cleanup_machine"
+---
+
+Clean up a machine's configuration and resources.
+
+This is a **host** method, used for managing machines you are renting out on Vast.ai.
+
+## Signature
+
+```python
+VastAI.cleanup_machine(id: int) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.cleanup_machine(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/clone-volume.mdx b/sdk/python/reference/clone-volume.mdx
new file mode 100644
index 0000000..26cb1fc
--- /dev/null
+++ b/sdk/python/reference/clone-volume.mdx
@@ -0,0 +1,49 @@
+---
+title: "VastAI.clone_volume"
+sidebarTitle: "clone_volume"
+---
+
+Clone an existing volume to create a new volume with optional size increase.
+
+## Signature
+
+```python
+VastAI.clone_volume(
+ source: int,
+ dest: int,
+ size: Optional[float] = None,
+ disable_compression: bool = False
+) -> str
+```
+
+## Parameters
+
+
+ source
+
+
+
+ dest
+
+
+
+ size
+
+
+
+ disable_compression
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.clone_volume(source=12345, dest=12345)
+print(result)
+```
diff --git a/sdk/python/reference/cloud-copy.mdx b/sdk/python/reference/cloud-copy.mdx
new file mode 100644
index 0000000..94db4ab
--- /dev/null
+++ b/sdk/python/reference/cloud-copy.mdx
@@ -0,0 +1,54 @@
+---
+title: "VastAI.cloud_copy"
+sidebarTitle: "cloud_copy"
+---
+
+Copy files between cloud and instance.
+
+## Signature
+
+```python
+VastAI.cloud_copy(
+ src: Optional[str] = None,
+ dst: Optional[str] = "/workspace",
+ instance: Optional[str] = None,
+ connection: Optional[str] = None,
+ transfer: str = "Instance to Cloud"
+) -> str
+```
+
+## Parameters
+
+
+ src
+
+
+
+ dst
+
+
+
+ instance
+
+
+
+ connection
+
+
+
+ transfer
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.cloud_copy()
+print(result)
+```
diff --git a/sdk/python/reference/copy.mdx b/sdk/python/reference/copy.mdx
new file mode 100644
index 0000000..9e8ea5b
--- /dev/null
+++ b/sdk/python/reference/copy.mdx
@@ -0,0 +1,40 @@
+---
+title: "VastAI.copy"
+sidebarTitle: "copy"
+---
+
+Copy files between instances.
+
+## Signature
+
+```python
+VastAI.copy(src: str, dst: str, identity: Optional[str] = None) -> str
+```
+
+## Parameters
+
+
+ src
+
+
+
+ dst
+
+
+
+ identity
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.copy(src="...", dst="...")
+print(result)
+```
diff --git a/sdk/python/reference/create-api-key.mdx b/sdk/python/reference/create-api-key.mdx
new file mode 100644
index 0000000..fb0d7eb
--- /dev/null
+++ b/sdk/python/reference/create-api-key.mdx
@@ -0,0 +1,40 @@
+---
+title: "VastAI.create_api_key"
+sidebarTitle: "create_api_key"
+---
+
+Create a new API key.
+
+## Signature
+
+```python
+VastAI.create_api_key(name: Optional[str] = None, permission_file: Optional[str] = None, key_params: Optional[str] = None) -> str
+```
+
+## Parameters
+
+
+ name
+
+
+
+ permission_file
+
+
+
+ key_params
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.create_api_key()
+print(result)
+```
diff --git a/sdk/python/reference/create-cluster.mdx b/sdk/python/reference/create-cluster.mdx
new file mode 100644
index 0000000..7c5050d
--- /dev/null
+++ b/sdk/python/reference/create-cluster.mdx
@@ -0,0 +1,36 @@
+---
+title: "VastAI.create_cluster"
+sidebarTitle: "create_cluster"
+---
+
+Create a Vast cluster.
+
+## Signature
+
+```python
+VastAI.create_cluster(subnet: str, manager_id: int) -> str
+```
+
+## Parameters
+
+
+ subnet
+
+
+
+ manager_id
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.create_cluster(subnet="...", manager_id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/create-endpoint.mdx b/sdk/python/reference/create-endpoint.mdx
new file mode 100644
index 0000000..69e23a5
--- /dev/null
+++ b/sdk/python/reference/create-endpoint.mdx
@@ -0,0 +1,59 @@
+---
+title: "VastAI.create_endpoint"
+sidebarTitle: "create_endpoint"
+---
+
+Create a new serverless endpoint group.
+
+## Signature
+
+```python
+VastAI.create_endpoint(
+ min_load: float = 0.0,
+ target_util: float = 0.9,
+ cold_mult: float = 2.5,
+ cold_workers: int = 5,
+ max_workers: int = 20,
+ endpoint_name: Optional[str] = None
+) -> str
+```
+
+## Parameters
+
+
+ Minimum load (requests/sec) below which idle workers are scaled down.
+
+
+
+ Target worker utilization ratio (0.0–1.0); workers are added to stay at this level.
+
+
+
+ Multiplier applied to warm worker count for pre-warming cold workers.
+
+
+
+ Number of pre-warmed (cold) workers to keep ready.
+
+
+
+ Maximum number of workers allowed in this endpoint.
+
+
+
+ Human-readable name for the endpoint.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.create_endpoint()
+print(result)
+```
diff --git a/sdk/python/reference/create-env-var.mdx b/sdk/python/reference/create-env-var.mdx
new file mode 100644
index 0000000..6eec1c7
--- /dev/null
+++ b/sdk/python/reference/create-env-var.mdx
@@ -0,0 +1,36 @@
+---
+title: "VastAI.create_env_var"
+sidebarTitle: "create_env_var"
+---
+
+Create a new user environment variable.
+
+## Signature
+
+```python
+VastAI.create_env_var(name: str, value: str) -> str
+```
+
+## Parameters
+
+
+ name
+
+
+
+ value
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.create_env_var(name="...", value="...")
+print(result)
+```
diff --git a/sdk/python/reference/create-instance.mdx b/sdk/python/reference/create-instance.mdx
new file mode 100644
index 0000000..18e77c7
--- /dev/null
+++ b/sdk/python/reference/create-instance.mdx
@@ -0,0 +1,139 @@
+---
+title: "VastAI.create_instance"
+sidebarTitle: "create_instance"
+---
+
+Create a new instance from a contract offer ID.
+
+## Signature
+
+```python
+VastAI.create_instance(
+ id: int,
+ price: Optional[float] = None,
+ disk: Optional[float] = 10,
+ image: Optional[str] = None,
+ login: Optional[str] = None,
+ label: Optional[str] = None,
+ onstart: Optional[str] = None,
+ onstart_cmd: Optional[str] = None,
+ entrypoint: Optional[str] = None,
+ ssh: bool = False,
+ jupyter: bool = False,
+ direct: bool = False,
+ jupyter_dir: Optional[str] = None,
+ jupyter_lab: bool = False,
+ lang_utf8: bool = False,
+ python_utf8: bool = False,
+ extra: Optional[str] = None,
+ env: Optional[str] = None,
+ args: Optional[List[str]] = None,
+ force: bool = False,
+ cancel_unavail: bool = False,
+ template_hash: Optional[str] = None
+) -> str
+```
+
+## Parameters
+
+
+ ID of the offer/contract to create the instance from (returned by search_offers).
+
+
+
+ (OPTIONAL) Per-machine bid price in $/hour for interruptible (spot) instances.
+
+
+
+ Disk space to allocate in GB.
+
+
+
+ Docker image name to use for the instance.
+
+
+
+ Docker login credentials for private registry authentication.
+
+
+
+ Label to attach to the instance.
+
+
+
+ Filename of an onstart script to run on instance start.
+
+
+
+ Shell command to run on instance start.
+
+
+
+ Override the Docker image entrypoint.
+
+
+
+ Enable SSH access to the instance.
+
+
+
+ Enable Jupyter notebook server.
+
+
+
+ Enable direct (peer-to-peer) connections.
+
+
+
+ Directory to serve Jupyter from.
+
+
+
+ Enable JupyterLab instead of classic Jupyter.
+
+
+
+ Set system language encoding to UTF-8.
+
+
+
+ Set Python I/O encoding to UTF-8.
+
+
+
+ Extra Docker run arguments passed verbatim.
+
+
+
+ Environment variables to set (formatted as Docker -e flags).
+
+
+
+ Additional positional arguments.
+
+
+
+ Skip sanity checks when creating from an existing instance.
+
+
+
+ Return an error if scheduling fails rather than creating a stopped instance.
+
+
+
+ Hash of an instance template to use for configuration.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.create_instance(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/create-instances.mdx b/sdk/python/reference/create-instances.mdx
new file mode 100644
index 0000000..efeae87
--- /dev/null
+++ b/sdk/python/reference/create-instances.mdx
@@ -0,0 +1,169 @@
+---
+title: "VastAI.create_instances"
+sidebarTitle: "create_instances"
+---
+
+Create multiple instances from a list of offer IDs.
+
+## Signature
+
+```python
+VastAI.create_instances(
+ ids: List[int],
+ template_hash: Optional[str] = None,
+ user: Optional[str] = None,
+ disk: float = 10,
+ image: Optional[str] = None,
+ login: Optional[str] = None,
+ label: Optional[str] = None,
+ onstart: Optional[str] = None,
+ onstart_cmd: Optional[str] = None,
+ entrypoint: Optional[str] = None,
+ ssh: bool = False,
+ jupyter: bool = False,
+ direct: bool = False,
+ jupyter_dir: Optional[str] = None,
+ jupyter_lab: bool = False,
+ lang_utf8: bool = False,
+ python_utf8: bool = False,
+ extra: Optional[str] = None,
+ env: Optional[str] = None,
+ args: Optional[List[str]] = None,
+ force: bool = False,
+ cancel_unavail: bool = False,
+ bid_price: Optional[float] = None,
+ create_volume: Optional[int] = None,
+ link_volume: Optional[int] = None,
+ volume_size: Optional[int] = None,
+ mount_path: Optional[str] = None,
+ volume_label: Optional[str] = None
+) -> str
+```
+
+## Parameters
+
+
+ List of offer/contract IDs to create instances from.
+
+
+
+ Hash of the instance template to use.
+
+
+
+ Subaccount username to create the instances under.
+
+
+
+ Disk space to allocate in GB.
+
+
+
+ Docker image name to use for the instance.
+
+
+
+ Docker login credentials for private registry authentication.
+
+
+
+ Label to attach to the instances.
+
+
+
+ Filename of an onstart script to run on instance start.
+
+
+
+ Shell command to run on instance start.
+
+
+
+ Override the Docker image entrypoint.
+
+
+
+ Enable SSH access to the instances.
+
+
+
+ Enable Jupyter notebook server.
+
+
+
+ Enable direct (peer-to-peer) connections.
+
+
+
+ Directory to serve Jupyter from.
+
+
+
+ Enable JupyterLab instead of classic Jupyter.
+
+
+
+ Set system language encoding to UTF-8.
+
+
+
+ Set Python I/O encoding to UTF-8.
+
+
+
+ Extra Docker run arguments passed verbatim.
+
+
+
+ Environment variables to set (formatted as Docker -e flags).
+
+
+
+ Additional positional arguments.
+
+
+
+ Skip sanity checks when creating from an existing instance.
+
+
+
+ Return an error if scheduling fails rather than creating a stopped instance.
+
+
+
+ Per-machine bid price in $/hour for interruptible (spot) instances.
+
+
+
+ Offer ID from "search volumes" to create a new local volume linked to each instance.
+
+
+
+ ID of an existing rented volume to link to each instance.
+
+
+
+ Size of the volume to create in GiB.
+
+
+
+ Filesystem path inside the instance where the volume is mounted.
+
+
+
+ Label to attach to the created volume.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.create_instances(ids=[12345])
+print(result)
+```
diff --git a/sdk/python/reference/create-overlay.mdx b/sdk/python/reference/create-overlay.mdx
new file mode 100644
index 0000000..f30086b
--- /dev/null
+++ b/sdk/python/reference/create-overlay.mdx
@@ -0,0 +1,36 @@
+---
+title: "VastAI.create_overlay"
+sidebarTitle: "create_overlay"
+---
+
+Create an overlay network on top of a physical cluster.
+
+## Signature
+
+```python
+VastAI.create_overlay(cluster_id: int, name: str) -> str
+```
+
+## Parameters
+
+
+ cluster_id
+
+
+
+ name
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.create_overlay(cluster_id=12345, name="...")
+print(result)
+```
diff --git a/sdk/python/reference/create-ssh-key.mdx b/sdk/python/reference/create-ssh-key.mdx
new file mode 100644
index 0000000..75a6890
--- /dev/null
+++ b/sdk/python/reference/create-ssh-key.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.create_ssh_key"
+sidebarTitle: "create_ssh_key"
+---
+
+Create a new SSH key.
+
+## Signature
+
+```python
+VastAI.create_ssh_key(ssh_key: str) -> str
+```
+
+## Parameters
+
+
+ ssh_key
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.create_ssh_key(ssh_key="...")
+print(result)
+```
diff --git a/sdk/python/reference/create-subaccount.mdx b/sdk/python/reference/create-subaccount.mdx
new file mode 100644
index 0000000..685fc6d
--- /dev/null
+++ b/sdk/python/reference/create-subaccount.mdx
@@ -0,0 +1,49 @@
+---
+title: "VastAI.create_subaccount"
+sidebarTitle: "create_subaccount"
+---
+
+Create a new subaccount under the current account.
+
+## Signature
+
+```python
+VastAI.create_subaccount(
+ email: Optional[str] = None,
+ username: Optional[str] = None,
+ password: Optional[str] = None,
+ type: Optional[str] = None
+) -> str
+```
+
+## Parameters
+
+
+ Email address for the new subaccount.
+
+
+
+ Username for the new subaccount.
+
+
+
+ Password for the new subaccount.
+
+
+
+ Account type for the subaccount.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.create_subaccount()
+print(result)
+```
diff --git a/sdk/python/reference/create-team-role.mdx b/sdk/python/reference/create-team-role.mdx
new file mode 100644
index 0000000..f76b1a1
--- /dev/null
+++ b/sdk/python/reference/create-team-role.mdx
@@ -0,0 +1,36 @@
+---
+title: "VastAI.create_team_role"
+sidebarTitle: "create_team_role"
+---
+
+Create a new team role.
+
+## Signature
+
+```python
+VastAI.create_team_role(name: Optional[str] = None, permissions: Optional[str] = None) -> str
+```
+
+## Parameters
+
+
+ name
+
+
+
+ permissions
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.create_team_role()
+print(result)
+```
diff --git a/sdk/python/reference/create-team.mdx b/sdk/python/reference/create-team.mdx
new file mode 100644
index 0000000..18006dc
--- /dev/null
+++ b/sdk/python/reference/create-team.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.create_team"
+sidebarTitle: "create_team"
+---
+
+Create a new team.
+
+## Signature
+
+```python
+VastAI.create_team(team_name: Optional[str] = None) -> str
+```
+
+## Parameters
+
+
+ team_name
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.create_team()
+print(result)
+```
diff --git a/sdk/python/reference/create-template.mdx b/sdk/python/reference/create-template.mdx
new file mode 100644
index 0000000..5886207
--- /dev/null
+++ b/sdk/python/reference/create-template.mdx
@@ -0,0 +1,94 @@
+---
+title: "VastAI.create_template"
+sidebarTitle: "create_template"
+---
+
+Create a new template.
+
+## Signature
+
+```python
+VastAI.create_template(
+ name: Optional[str] = None,
+ image: Optional[str] = None,
+ image_tag: Optional[str] = None,
+ login: Optional[str] = None,
+ env: Optional[str] = None,
+ ssh: bool = False,
+ jupyter: bool = False,
+ direct: bool = False,
+ jupyter_dir: Optional[str] = None,
+ jupyter_lab: bool = False,
+ onstart_cmd: Optional[str] = None,
+ search_params: Optional[str] = None,
+ disk_space: Optional[str] = None
+) -> str
+```
+
+## Parameters
+
+
+ name
+
+
+
+ image
+
+
+
+ image_tag
+
+
+
+ login
+
+
+
+ env
+
+
+
+ ssh
+
+
+
+ jupyter
+
+
+
+ direct
+
+
+
+ jupyter_dir
+
+
+
+ jupyter_lab
+
+
+
+ onstart_cmd
+
+
+
+ search_params
+
+
+
+ disk_space
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.create_template()
+print(result)
+```
diff --git a/sdk/python/reference/create-volume.mdx b/sdk/python/reference/create-volume.mdx
new file mode 100644
index 0000000..34eb5cb
--- /dev/null
+++ b/sdk/python/reference/create-volume.mdx
@@ -0,0 +1,40 @@
+---
+title: "VastAI.create_volume"
+sidebarTitle: "create_volume"
+---
+
+Create a new volume from an offer ID.
+
+## Signature
+
+```python
+VastAI.create_volume(id: int, size: float = 15, name: Optional[str] = None) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+
+ size
+
+
+
+ name
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.create_volume(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/create-workergroup.mdx b/sdk/python/reference/create-workergroup.mdx
new file mode 100644
index 0000000..d88e45b
--- /dev/null
+++ b/sdk/python/reference/create-workergroup.mdx
@@ -0,0 +1,94 @@
+---
+title: "VastAI.create_workergroup"
+sidebarTitle: "create_workergroup"
+---
+
+Create a new autoscale worker group.
+
+## Signature
+
+```python
+VastAI.create_workergroup(
+ template_hash: Optional[str] = None,
+ template_id: Optional[int] = None,
+ no_default: bool = False,
+ launch_args: Optional[str] = None,
+ endpoint_name: Optional[str] = None,
+ endpoint_id: Optional[int] = None,
+ test_workers: int = 3,
+ gpu_ram: Optional[float] = None,
+ search_params: Optional[str] = None,
+ min_load: Optional[float] = None,
+ target_util: Optional[float] = None,
+ cold_mult: Optional[float] = None,
+ cold_workers: Optional[int] = None
+) -> str
+```
+
+## Parameters
+
+
+ Hash of the instance template to use for workers.
+
+
+
+ ID of the instance template to use for workers.
+
+
+
+ Disable the default search query filters when finding offers.
+
+
+
+ Additional CLI arguments passed when launching worker instances.
+
+
+
+ Human-readable name for the endpoint this group belongs to.
+
+
+
+ ID of the endpoint this worker group belongs to.
+
+
+
+ Number of test workers to spin up during initial scaling evaluation.
+
+
+
+ Minimum GPU RAM in GiB required per worker.
+
+
+
+ Query string for filtering available GPU offers (e.g. "gpu_name=RTX_4090 num_gpus=1").
+
+
+
+ Minimum load (requests/sec) below which idle workers are scaled down.
+
+
+
+ Target worker utilization ratio (0.0–1.0); workers are added to stay at this level.
+
+
+
+ Multiplier applied to warm worker count for pre-warming cold workers.
+
+
+
+ Number of pre-warmed (cold) workers to keep ready.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.create_workergroup()
+print(result)
+```
diff --git a/sdk/python/reference/defrag-machines.mdx b/sdk/python/reference/defrag-machines.mdx
new file mode 100644
index 0000000..da5e698
--- /dev/null
+++ b/sdk/python/reference/defrag-machines.mdx
@@ -0,0 +1,34 @@
+---
+title: "VastAI.defrag_machines"
+sidebarTitle: "defrag_machines"
+---
+
+Defragment machines.
+
+This is a **host** method, used for managing machines you are renting out on Vast.ai.
+
+## Signature
+
+```python
+VastAI.defrag_machines(IDs: List[int]) -> str
+```
+
+## Parameters
+
+
+ IDs
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.defrag_machines(IDs=[12345])
+print(result)
+```
diff --git a/sdk/python/reference/delete-api-key.mdx b/sdk/python/reference/delete-api-key.mdx
new file mode 100644
index 0000000..15b0ab3
--- /dev/null
+++ b/sdk/python/reference/delete-api-key.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.delete_api_key"
+sidebarTitle: "delete_api_key"
+---
+
+Delete an API key.
+
+## Signature
+
+```python
+VastAI.delete_api_key(id: int) -> str
+```
+
+## Parameters
+
+
+ ID of the API key to delete.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.delete_api_key(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/delete-cluster.mdx b/sdk/python/reference/delete-cluster.mdx
new file mode 100644
index 0000000..122e213
--- /dev/null
+++ b/sdk/python/reference/delete-cluster.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.delete_cluster"
+sidebarTitle: "delete_cluster"
+---
+
+Delete a cluster.
+
+## Signature
+
+```python
+VastAI.delete_cluster(cluster_id: int) -> str
+```
+
+## Parameters
+
+
+ cluster_id
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.delete_cluster(cluster_id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/delete-deployment.mdx b/sdk/python/reference/delete-deployment.mdx
new file mode 100644
index 0000000..46e03c9
--- /dev/null
+++ b/sdk/python/reference/delete-deployment.mdx
@@ -0,0 +1,40 @@
+---
+title: "VastAI.delete_deployment"
+sidebarTitle: "delete_deployment"
+---
+
+Delete a deployment by ID or name.
+
+## Signature
+
+```python
+VastAI.delete_deployment(id: Optional[int] = None, name: Optional[str] = None, tag: Optional[str] = None) -> str
+```
+
+## Parameters
+
+
+ ID of the deployment to delete.
+
+
+
+ Name of the deployment to delete (deletes all tags unless `--tag` is specified).
+
+
+
+ Tag to filter by when deleting by name.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.delete_deployment()
+print(result)
+```
diff --git a/sdk/python/reference/delete-endpoint.mdx b/sdk/python/reference/delete-endpoint.mdx
new file mode 100644
index 0000000..0db27d7
--- /dev/null
+++ b/sdk/python/reference/delete-endpoint.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.delete_endpoint"
+sidebarTitle: "delete_endpoint"
+---
+
+Delete a serverless endpoint group.
+
+## Signature
+
+```python
+VastAI.delete_endpoint(id: int) -> str
+```
+
+## Parameters
+
+
+ ID of the endpoint to delete.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.delete_endpoint(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/delete-env-var.mdx b/sdk/python/reference/delete-env-var.mdx
new file mode 100644
index 0000000..df4a10e
--- /dev/null
+++ b/sdk/python/reference/delete-env-var.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.delete_env_var"
+sidebarTitle: "delete_env_var"
+---
+
+Delete a user environment variable.
+
+## Signature
+
+```python
+VastAI.delete_env_var(name: str) -> str
+```
+
+## Parameters
+
+
+ name
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.delete_env_var(name="...")
+print(result)
+```
diff --git a/sdk/python/reference/delete-machine.mdx b/sdk/python/reference/delete-machine.mdx
new file mode 100644
index 0000000..37aee3a
--- /dev/null
+++ b/sdk/python/reference/delete-machine.mdx
@@ -0,0 +1,34 @@
+---
+title: "VastAI.delete_machine"
+sidebarTitle: "delete_machine"
+---
+
+Delete a machine if not being used by clients.
+
+This is a **host** method, used for managing machines you are renting out on Vast.ai.
+
+## Signature
+
+```python
+VastAI.delete_machine(id: int) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.delete_machine(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/delete-overlay.mdx b/sdk/python/reference/delete-overlay.mdx
new file mode 100644
index 0000000..e2a7bf3
--- /dev/null
+++ b/sdk/python/reference/delete-overlay.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.delete_overlay"
+sidebarTitle: "delete_overlay"
+---
+
+Delete an overlay and remove all associated instances.
+
+## Signature
+
+```python
+VastAI.delete_overlay(overlay_identifier: Optional[str] = None) -> str
+```
+
+## Parameters
+
+
+ overlay_identifier
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.delete_overlay()
+print(result)
+```
diff --git a/sdk/python/reference/delete-scheduled-job.mdx b/sdk/python/reference/delete-scheduled-job.mdx
new file mode 100644
index 0000000..05dd58f
--- /dev/null
+++ b/sdk/python/reference/delete-scheduled-job.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.delete_scheduled_job"
+sidebarTitle: "delete_scheduled_job"
+---
+
+Delete a scheduled job.
+
+## Signature
+
+```python
+VastAI.delete_scheduled_job(id: int) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.delete_scheduled_job(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/delete-ssh-key.mdx b/sdk/python/reference/delete-ssh-key.mdx
new file mode 100644
index 0000000..5e79ce6
--- /dev/null
+++ b/sdk/python/reference/delete-ssh-key.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.delete_ssh_key"
+sidebarTitle: "delete_ssh_key"
+---
+
+Delete an SSH key from your account.
+
+## Signature
+
+```python
+VastAI.delete_ssh_key(id: int) -> str
+```
+
+## Parameters
+
+
+ ID of the SSH key to delete.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.delete_ssh_key(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/delete-template.mdx b/sdk/python/reference/delete-template.mdx
new file mode 100644
index 0000000..4b4af02
--- /dev/null
+++ b/sdk/python/reference/delete-template.mdx
@@ -0,0 +1,36 @@
+---
+title: "VastAI.delete_template"
+sidebarTitle: "delete_template"
+---
+
+Delete a template by template ID or hash ID.
+
+## Signature
+
+```python
+VastAI.delete_template(template_id: Optional[int] = None, hash_id: Optional[str] = None) -> str
+```
+
+## Parameters
+
+
+ template_id
+
+
+
+ hash_id
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.delete_template()
+print(result)
+```
diff --git a/sdk/python/reference/delete-volume.mdx b/sdk/python/reference/delete-volume.mdx
new file mode 100644
index 0000000..8c47bb5
--- /dev/null
+++ b/sdk/python/reference/delete-volume.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.delete_volume"
+sidebarTitle: "delete_volume"
+---
+
+Delete a volume by ID.
+
+## Signature
+
+```python
+VastAI.delete_volume(id: int) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.delete_volume(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/delete-workergroup.mdx b/sdk/python/reference/delete-workergroup.mdx
new file mode 100644
index 0000000..211c39d
--- /dev/null
+++ b/sdk/python/reference/delete-workergroup.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.delete_workergroup"
+sidebarTitle: "delete_workergroup"
+---
+
+Delete a worker group.
+
+## Signature
+
+```python
+VastAI.delete_workergroup(id: int) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.delete_workergroup(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/destroy-instance.mdx b/sdk/python/reference/destroy-instance.mdx
new file mode 100644
index 0000000..fa0ee72
--- /dev/null
+++ b/sdk/python/reference/destroy-instance.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.destroy_instance"
+sidebarTitle: "destroy_instance"
+---
+
+Destroy (permanently delete) a running or stopped instance.
+
+## Signature
+
+```python
+VastAI.destroy_instance(id: int) -> str
+```
+
+## Parameters
+
+
+ ID of the instance to destroy.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.destroy_instance(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/destroy-instances.mdx b/sdk/python/reference/destroy-instances.mdx
new file mode 100644
index 0000000..9ed470e
--- /dev/null
+++ b/sdk/python/reference/destroy-instances.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.destroy_instances"
+sidebarTitle: "destroy_instances"
+---
+
+Destroy multiple instances at once.
+
+## Signature
+
+```python
+VastAI.destroy_instances(ids: List[int]) -> str
+```
+
+## Parameters
+
+
+ List of instance IDs to destroy.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.destroy_instances(ids=[12345])
+print(result)
+```
diff --git a/sdk/python/reference/destroy-team.mdx b/sdk/python/reference/destroy-team.mdx
new file mode 100644
index 0000000..d7993b9
--- /dev/null
+++ b/sdk/python/reference/destroy-team.mdx
@@ -0,0 +1,26 @@
+---
+title: "VastAI.destroy_team"
+sidebarTitle: "destroy_team"
+---
+
+Permanently delete your team and remove all members.
+
+## Signature
+
+```python
+VastAI.destroy_team() -> str
+```
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.destroy_team()
+print(result)
+```
diff --git a/sdk/python/reference/detach-ssh.mdx b/sdk/python/reference/detach-ssh.mdx
new file mode 100644
index 0000000..cd9dff6
--- /dev/null
+++ b/sdk/python/reference/detach-ssh.mdx
@@ -0,0 +1,36 @@
+---
+title: "VastAI.detach_ssh"
+sidebarTitle: "detach_ssh"
+---
+
+Detach an SSH key from an instance.
+
+## Signature
+
+```python
+VastAI.detach_ssh(instance_id: int, ssh_key_id: str) -> str
+```
+
+## Parameters
+
+
+ ID of the instance to detach the SSH key from.
+
+
+
+ ID of the SSH key to detach from the instance.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.detach_ssh(instance_id=12345, ssh_key_id="...")
+print(result)
+```
diff --git a/sdk/python/reference/execute.mdx b/sdk/python/reference/execute.mdx
new file mode 100644
index 0000000..86e4c9b
--- /dev/null
+++ b/sdk/python/reference/execute.mdx
@@ -0,0 +1,36 @@
+---
+title: "VastAI.execute"
+sidebarTitle: "execute"
+---
+
+Execute a command on an instance.
+
+## Signature
+
+```python
+VastAI.execute(id: int, COMMAND: str) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+
+ COMMAND
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.execute(id=12345, COMMAND="...")
+print(result)
+```
diff --git a/sdk/python/reference/generate-pdf-invoices.mdx b/sdk/python/reference/generate-pdf-invoices.mdx
new file mode 100644
index 0000000..e955df3
--- /dev/null
+++ b/sdk/python/reference/generate-pdf-invoices.mdx
@@ -0,0 +1,54 @@
+---
+title: "VastAI.generate_pdf_invoices"
+sidebarTitle: "generate_pdf_invoices"
+---
+
+Generate PDF invoices based on filters.
+
+## Signature
+
+```python
+VastAI.generate_pdf_invoices(
+ quiet: bool = False,
+ start_date: Optional[str] = None,
+ end_date: Optional[str] = None,
+ only_charges: bool = False,
+ only_credits: bool = False
+) -> str
+```
+
+## Parameters
+
+
+ Suppress non-essential output.
+
+
+
+ Start date for the invoice period (e.g. "2024-01-01").
+
+
+
+ End date for the invoice period (e.g. "2024-01-31").
+
+
+
+ Include only charge items in the output.
+
+
+
+ Include only credit items in the output.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.generate_pdf_invoices()
+print(result)
+```
diff --git a/sdk/python/reference/get-endpt-logs.mdx b/sdk/python/reference/get-endpt-logs.mdx
new file mode 100644
index 0000000..c0b2236
--- /dev/null
+++ b/sdk/python/reference/get-endpt-logs.mdx
@@ -0,0 +1,40 @@
+---
+title: "VastAI.get_endpt_logs"
+sidebarTitle: "get_endpt_logs"
+---
+
+Fetch logs for a specific serverless endpoint group.
+
+## Signature
+
+```python
+VastAI.get_endpt_logs(id: int, level: int = 1, tail: Optional[int] = None) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+
+ level
+
+
+
+ tail
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.get_endpt_logs(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/get-wrkgrp-logs.mdx b/sdk/python/reference/get-wrkgrp-logs.mdx
new file mode 100644
index 0000000..699269f
--- /dev/null
+++ b/sdk/python/reference/get-wrkgrp-logs.mdx
@@ -0,0 +1,40 @@
+---
+title: "VastAI.get_wrkgrp_logs"
+sidebarTitle: "get_wrkgrp_logs"
+---
+
+Fetch logs for a specific serverless worker group.
+
+## Signature
+
+```python
+VastAI.get_wrkgrp_logs(id: int, level: int = 1, tail: Optional[int] = None) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+
+ level
+
+
+
+ tail
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.get_wrkgrp_logs(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/invite-member.mdx b/sdk/python/reference/invite-member.mdx
new file mode 100644
index 0000000..b836247
--- /dev/null
+++ b/sdk/python/reference/invite-member.mdx
@@ -0,0 +1,36 @@
+---
+title: "VastAI.invite_member"
+sidebarTitle: "invite_member"
+---
+
+Invite a team member to your current team.
+
+## Signature
+
+```python
+VastAI.invite_member(email: str, role: str) -> str
+```
+
+## Parameters
+
+
+ email
+
+
+
+ role
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.invite_member(email="...", role="...")
+print(result)
+```
diff --git a/sdk/python/reference/join-cluster.mdx b/sdk/python/reference/join-cluster.mdx
new file mode 100644
index 0000000..676ebc5
--- /dev/null
+++ b/sdk/python/reference/join-cluster.mdx
@@ -0,0 +1,36 @@
+---
+title: "VastAI.join_cluster"
+sidebarTitle: "join_cluster"
+---
+
+Join machines to a cluster.
+
+## Signature
+
+```python
+VastAI.join_cluster(cluster_id: int, machine_ids: List[int]) -> str
+```
+
+## Parameters
+
+
+ cluster_id
+
+
+
+ machine_ids
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.join_cluster(cluster_id=12345, machine_ids=[12345])
+print(result)
+```
diff --git a/sdk/python/reference/join-overlay.mdx b/sdk/python/reference/join-overlay.mdx
new file mode 100644
index 0000000..a19a142
--- /dev/null
+++ b/sdk/python/reference/join-overlay.mdx
@@ -0,0 +1,36 @@
+---
+title: "VastAI.join_overlay"
+sidebarTitle: "join_overlay"
+---
+
+Add an instance to an overlay network.
+
+## Signature
+
+```python
+VastAI.join_overlay(name: str, instance_id: int) -> str
+```
+
+## Parameters
+
+
+ name
+
+
+
+ instance_id
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.join_overlay(name="...", instance_id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/label-instance.mdx b/sdk/python/reference/label-instance.mdx
new file mode 100644
index 0000000..c38974f
--- /dev/null
+++ b/sdk/python/reference/label-instance.mdx
@@ -0,0 +1,36 @@
+---
+title: "VastAI.label_instance"
+sidebarTitle: "label_instance"
+---
+
+Label an instance.
+
+## Signature
+
+```python
+VastAI.label_instance(id: int, label: str) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+
+ label
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.label_instance(id=12345, label="...")
+print(result)
+```
diff --git a/sdk/python/reference/launch-instance.mdx b/sdk/python/reference/launch-instance.mdx
new file mode 100644
index 0000000..c660164
--- /dev/null
+++ b/sdk/python/reference/launch-instance.mdx
@@ -0,0 +1,166 @@
+---
+title: "VastAI.launch_instance"
+sidebarTitle: "launch_instance"
+---
+
+Launch the best matching instance based on GPU/image criteria.
+
+ Searches for available offers and creates an instance from the top result.
+
+## Signature
+
+```python
+VastAI.launch_instance(
+ gpu_name: str,
+ num_gpus: str,
+ image: str,
+ region: str = None,
+ disk: float = 16.0,
+ limit: int = 3,
+ order: str = "score-",
+ login: str = None,
+ label: str = None,
+ onstart: str = None,
+ onstart_cmd: str = None,
+ entrypoint: str = None,
+ ssh: bool = False,
+ jupyter: bool = False,
+ direct: bool = False,
+ jupyter_dir: str = None,
+ jupyter_lab: bool = False,
+ lang_utf8: bool = False,
+ python_utf8: bool = False,
+ extra: str = None,
+ env: str = None,
+ args: list = None,
+ force: bool = False,
+ cancel_unavail: bool = False,
+ template_hash: str = None,
+ explain: bool = False,
+ raw: bool = False
+) -> str
+```
+
+## Parameters
+
+
+ Name of the GPU model (replace spaces with underscores, e.g. "RTX_4090").
+
+
+
+ Number of GPUs required (choices: 1, 2, 4, 8, 12, 14).
+
+
+
+ Docker image name to use for the instance.
+
+
+
+ Geographical region filter for the instance location.
+
+
+
+ Disk space to allocate in GB.
+
+
+
+ Maximum number of offers to consider when selecting the best match.
+
+
+
+ Sort order for offers; append '-' to sort descending (e.g. "score-").
+
+
+
+ Docker login credentials for private registry authentication.
+
+
+
+ Label to attach to the instance.
+
+
+
+ Filename of an onstart script to run on instance start.
+
+
+
+ Shell command to run on instance start.
+
+
+
+ Override the Docker image entrypoint.
+
+
+
+ Enable SSH access to the instance.
+
+
+
+ Enable Jupyter notebook server.
+
+
+
+ Enable direct (peer-to-peer) connections.
+
+
+
+ Directory to serve Jupyter from.
+
+
+
+ Enable JupyterLab instead of classic Jupyter.
+
+
+
+ Set system language encoding to UTF-8.
+
+
+
+ Set Python I/O encoding to UTF-8.
+
+
+
+ Extra Docker run arguments passed verbatim.
+
+
+
+ Environment variables to set (formatted as Docker -e flags).
+
+
+
+ Additional positional arguments.
+
+
+
+ Skip sanity checks when creating from an existing instance.
+
+
+
+ Return an error if scheduling fails rather than creating a stopped instance.
+
+
+
+ Hash of an instance template to use for configuration.
+
+
+
+ Print verbose explanations of API calls made.
+
+
+
+ Return raw JSON responses.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.launch_instance(gpu_name="...", num_gpus="...", image="...")
+print(result)
+```
diff --git a/sdk/python/reference/list-machine.mdx b/sdk/python/reference/list-machine.mdx
new file mode 100644
index 0000000..af5e918
--- /dev/null
+++ b/sdk/python/reference/list-machine.mdx
@@ -0,0 +1,71 @@
+---
+title: "VastAI.list_machine"
+sidebarTitle: "list_machine"
+---
+
+List details of a single machine with optional pricing and configuration parameters.
+
+This is a **host** method, used for managing machines you are renting out on Vast.ai.
+
+## Signature
+
+```python
+VastAI.list_machine(
+ id: int,
+ price_gpu: Optional[float] = None,
+ price_disk: Optional[float] = None,
+ price_inetu: Optional[float] = None,
+ price_inetd: Optional[float] = None,
+ discount_rate: Optional[float] = None,
+ min_chunk: Optional[int] = None,
+ end_date: Optional[str] = None
+) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+
+ price_gpu
+
+
+
+ price_disk
+
+
+
+ price_inetu
+
+
+
+ price_inetd
+
+
+
+ discount_rate
+
+
+
+ min_chunk
+
+
+
+ end_date
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.list_machine(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/list-machines.mdx b/sdk/python/reference/list-machines.mdx
new file mode 100644
index 0000000..183c423
--- /dev/null
+++ b/sdk/python/reference/list-machines.mdx
@@ -0,0 +1,71 @@
+---
+title: "VastAI.list_machines"
+sidebarTitle: "list_machines"
+---
+
+List details of multiple machines with optional pricing and configuration parameters.
+
+This is a **host** method, used for managing machines you are renting out on Vast.ai.
+
+## Signature
+
+```python
+VastAI.list_machines(
+ ids: List[int],
+ price_gpu: Optional[float] = None,
+ price_disk: Optional[float] = None,
+ price_inetu: Optional[float] = None,
+ price_inetd: Optional[float] = None,
+ discount_rate: Optional[float] = None,
+ min_chunk: Optional[int] = None,
+ end_date: Optional[str] = None
+) -> str
+```
+
+## Parameters
+
+
+ ids
+
+
+
+ price_gpu
+
+
+
+ price_disk
+
+
+
+ price_inetu
+
+
+
+ price_inetd
+
+
+
+ discount_rate
+
+
+
+ min_chunk
+
+
+
+ end_date
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.list_machines(ids=[12345])
+print(result)
+```
diff --git a/sdk/python/reference/list-volume.mdx b/sdk/python/reference/list-volume.mdx
new file mode 100644
index 0000000..a685d95
--- /dev/null
+++ b/sdk/python/reference/list-volume.mdx
@@ -0,0 +1,49 @@
+---
+title: "VastAI.list_volume"
+sidebarTitle: "list_volume"
+---
+
+List disk space for rent as a volume on a machine.
+
+## Signature
+
+```python
+VastAI.list_volume(
+ id: int,
+ price_disk: float = 0.1,
+ end_date: Optional[str] = None,
+ size: int = 15
+) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+
+ price_disk
+
+
+
+ end_date
+
+
+
+ size
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.list_volume(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/list-volumes.mdx b/sdk/python/reference/list-volumes.mdx
new file mode 100644
index 0000000..fc8bb36
--- /dev/null
+++ b/sdk/python/reference/list-volumes.mdx
@@ -0,0 +1,49 @@
+---
+title: "VastAI.list_volumes"
+sidebarTitle: "list_volumes"
+---
+
+List disk space for rent as volumes on multiple machines.
+
+## Signature
+
+```python
+VastAI.list_volumes(
+ ids: List[int],
+ price_disk: float = 0.1,
+ end_date: Optional[str] = None,
+ size: int = 15
+) -> str
+```
+
+## Parameters
+
+
+ ids
+
+
+
+ price_disk
+
+
+
+ end_date
+
+
+
+ size
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.list_volumes(ids=[12345])
+print(result)
+```
diff --git a/sdk/python/reference/logs.mdx b/sdk/python/reference/logs.mdx
new file mode 100644
index 0000000..9ce42c9
--- /dev/null
+++ b/sdk/python/reference/logs.mdx
@@ -0,0 +1,36 @@
+---
+title: "VastAI.logs"
+sidebarTitle: "logs"
+---
+
+Retrieve logs for an instance.
+
+## Signature
+
+```python
+VastAI.logs(INSTANCE_ID: int, tail: Optional[str] = None) -> str
+```
+
+## Parameters
+
+
+ INSTANCE_ID
+
+
+
+ tail
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.logs(INSTANCE_ID=12345)
+print(result)
+```
diff --git a/sdk/python/reference/prepay-instance.mdx b/sdk/python/reference/prepay-instance.mdx
new file mode 100644
index 0000000..9bd114b
--- /dev/null
+++ b/sdk/python/reference/prepay-instance.mdx
@@ -0,0 +1,36 @@
+---
+title: "VastAI.prepay_instance"
+sidebarTitle: "prepay_instance"
+---
+
+Prepay for an instance.
+
+## Signature
+
+```python
+VastAI.prepay_instance(id: int, amount: float) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+
+ amount
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.prepay_instance(id=12345, amount=1.0)
+print(result)
+```
diff --git a/sdk/python/reference/reboot-instance.mdx b/sdk/python/reference/reboot-instance.mdx
new file mode 100644
index 0000000..753ef3a
--- /dev/null
+++ b/sdk/python/reference/reboot-instance.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.reboot_instance"
+sidebarTitle: "reboot_instance"
+---
+
+Reboot an instance.
+
+## Signature
+
+```python
+VastAI.reboot_instance(id: int) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.reboot_instance(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/recycle-instance.mdx b/sdk/python/reference/recycle-instance.mdx
new file mode 100644
index 0000000..408a38a
--- /dev/null
+++ b/sdk/python/reference/recycle-instance.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.recycle_instance"
+sidebarTitle: "recycle_instance"
+---
+
+Recycle an instance.
+
+## Signature
+
+```python
+VastAI.recycle_instance(id: int) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.recycle_instance(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/remove-defjob.mdx b/sdk/python/reference/remove-defjob.mdx
new file mode 100644
index 0000000..f3c6626
--- /dev/null
+++ b/sdk/python/reference/remove-defjob.mdx
@@ -0,0 +1,34 @@
+---
+title: "VastAI.remove_defjob"
+sidebarTitle: "remove_defjob"
+---
+
+Remove the default job from a machine.
+
+This is a **host** method, used for managing machines you are renting out on Vast.ai.
+
+## Signature
+
+```python
+VastAI.remove_defjob(id: int) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.remove_defjob(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/remove-machine-from-cluster.mdx b/sdk/python/reference/remove-machine-from-cluster.mdx
new file mode 100644
index 0000000..1c94804
--- /dev/null
+++ b/sdk/python/reference/remove-machine-from-cluster.mdx
@@ -0,0 +1,40 @@
+---
+title: "VastAI.remove_machine_from_cluster"
+sidebarTitle: "remove_machine_from_cluster"
+---
+
+Remove a machine from a cluster.
+
+## Signature
+
+```python
+VastAI.remove_machine_from_cluster(cluster_id: int, machine_id: int, new_manager_id: Optional[int] = None) -> str
+```
+
+## Parameters
+
+
+ cluster_id
+
+
+
+ machine_id
+
+
+
+ new_manager_id
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.remove_machine_from_cluster(cluster_id=12345, machine_id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/remove-member.mdx b/sdk/python/reference/remove-member.mdx
new file mode 100644
index 0000000..d13e793
--- /dev/null
+++ b/sdk/python/reference/remove-member.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.remove_member"
+sidebarTitle: "remove_member"
+---
+
+Remove a team member by user ID.
+
+## Signature
+
+```python
+VastAI.remove_member(id: int) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.remove_member(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/remove-team-role.mdx b/sdk/python/reference/remove-team-role.mdx
new file mode 100644
index 0000000..d31b590
--- /dev/null
+++ b/sdk/python/reference/remove-team-role.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.remove_team_role"
+sidebarTitle: "remove_team_role"
+---
+
+Remove a role from the team.
+
+## Signature
+
+```python
+VastAI.remove_team_role(NAME: str) -> str
+```
+
+## Parameters
+
+
+ NAME
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.remove_team_role(NAME="...")
+print(result)
+```
diff --git a/sdk/python/reference/reports.mdx b/sdk/python/reference/reports.mdx
new file mode 100644
index 0000000..9d21403
--- /dev/null
+++ b/sdk/python/reference/reports.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.reports"
+sidebarTitle: "reports"
+---
+
+Generate reports for a machine.
+
+## Signature
+
+```python
+VastAI.reports(id: int) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.reports(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/reset-api-key.mdx b/sdk/python/reference/reset-api-key.mdx
new file mode 100644
index 0000000..2510499
--- /dev/null
+++ b/sdk/python/reference/reset-api-key.mdx
@@ -0,0 +1,26 @@
+---
+title: "VastAI.reset_api_key"
+sidebarTitle: "reset_api_key"
+---
+
+Reset the API key.
+
+## Signature
+
+```python
+VastAI.reset_api_key() -> str
+```
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.reset_api_key()
+print(result)
+```
diff --git a/sdk/python/reference/schedule-maint.mdx b/sdk/python/reference/schedule-maint.mdx
new file mode 100644
index 0000000..51ed101
--- /dev/null
+++ b/sdk/python/reference/schedule-maint.mdx
@@ -0,0 +1,42 @@
+---
+title: "VastAI.schedule_maint"
+sidebarTitle: "schedule_maint"
+---
+
+Schedule maintenance for a machine.
+
+This is a **host** method, used for managing machines you are renting out on Vast.ai.
+
+## Signature
+
+```python
+VastAI.schedule_maint(id: int, sdate: Optional[float] = None, duration: Optional[float] = None) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+
+ sdate
+
+
+
+ duration
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.schedule_maint(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/scp-url.mdx b/sdk/python/reference/scp-url.mdx
new file mode 100644
index 0000000..c00feea
--- /dev/null
+++ b/sdk/python/reference/scp-url.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.scp_url"
+sidebarTitle: "scp_url"
+---
+
+Get the SCP URL for transferring files to/from an instance.
+
+## Signature
+
+```python
+VastAI.scp_url(id: int) -> str
+```
+
+## Parameters
+
+
+ ID of the instance.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.scp_url(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/search-benchmarks.mdx b/sdk/python/reference/search-benchmarks.mdx
new file mode 100644
index 0000000..006d9fc
--- /dev/null
+++ b/sdk/python/reference/search-benchmarks.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.search_benchmarks"
+sidebarTitle: "search_benchmarks"
+---
+
+Search for benchmarks based on a query.
+
+## Signature
+
+```python
+VastAI.search_benchmarks(query: Optional[str] = None) -> str
+```
+
+## Parameters
+
+
+ query
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.search_benchmarks()
+print(result)
+```
diff --git a/sdk/python/reference/search-invoices.mdx b/sdk/python/reference/search-invoices.mdx
new file mode 100644
index 0000000..99be362
--- /dev/null
+++ b/sdk/python/reference/search-invoices.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.search_invoices"
+sidebarTitle: "search_invoices"
+---
+
+Search for invoices based on a query.
+
+## Signature
+
+```python
+VastAI.search_invoices(query: Optional[str] = None) -> str
+```
+
+## Parameters
+
+
+ query
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.search_invoices()
+print(result)
+```
diff --git a/sdk/python/reference/search-offers.mdx b/sdk/python/reference/search-offers.mdx
new file mode 100644
index 0000000..b906501
--- /dev/null
+++ b/sdk/python/reference/search-offers.mdx
@@ -0,0 +1,69 @@
+---
+title: "VastAI.search_offers"
+sidebarTitle: "search_offers"
+---
+
+Search for offers based on various criteria.
+
+## Signature
+
+```python
+VastAI.search_offers(
+ type: Optional[str] = None,
+ no_default: bool = False,
+ new: bool = False,
+ limit: Optional[int] = None,
+ disable_bundling: bool = False,
+ storage: Optional[float] = None,
+ order: Optional[str] = None,
+ query: Optional[str] = None
+) -> str
+```
+
+## Parameters
+
+
+ Instance type filter: 'bid' for interruptible, 'reserved' for reserved, 'on-demand' for on-demand.
+
+
+
+ Disable the default query filters (external=false rentable=true verified=true).
+
+
+
+ Use the new search algorithm (experimental).
+
+
+
+ Maximum number of results to return.
+
+
+
+ Disable offer bundling (show individual machine slots).
+
+
+
+ Amount of storage in GiB to include in pricing calculations.
+
+
+
+ Comma-separated list of fields to sort on; append '-' to sort descending (e.g. "score-").
+
+
+
+ Search query string (e.g. "gpu_name=RTX_4090 num_gpus>=2 rentable=True").
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.search_offers()
+print(result)
+```
diff --git a/sdk/python/reference/search-templates.mdx b/sdk/python/reference/search-templates.mdx
new file mode 100644
index 0000000..affc99e
--- /dev/null
+++ b/sdk/python/reference/search-templates.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.search_templates"
+sidebarTitle: "search_templates"
+---
+
+Search for templates based on a query.
+
+## Signature
+
+```python
+VastAI.search_templates(query: Optional[str] = None) -> str
+```
+
+## Parameters
+
+
+ query
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.search_templates()
+print(result)
+```
diff --git a/sdk/python/reference/search-volumes.mdx b/sdk/python/reference/search-volumes.mdx
new file mode 100644
index 0000000..4d46c0f
--- /dev/null
+++ b/sdk/python/reference/search-volumes.mdx
@@ -0,0 +1,40 @@
+---
+title: "VastAI.search_volumes"
+sidebarTitle: "search_volumes"
+---
+
+Search for volume offers using custom query.
+
+## Signature
+
+```python
+VastAI.search_volumes(query: Optional[str] = None, storage: float = 1.0, order: str = "score-") -> str
+```
+
+## Parameters
+
+
+ query
+
+
+
+ storage
+
+
+
+ order
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.search_volumes()
+print(result)
+```
diff --git a/sdk/python/reference/self-test-machine.mdx b/sdk/python/reference/self-test-machine.mdx
new file mode 100644
index 0000000..a63d1b7
--- /dev/null
+++ b/sdk/python/reference/self-test-machine.mdx
@@ -0,0 +1,66 @@
+---
+title: "VastAI.self_test_machine"
+sidebarTitle: "self_test_machine"
+---
+
+Perform a self-test on the specified machine.
+
+This is a **host** method, used for managing machines you are renting out on Vast.ai.
+
+## Signature
+
+```python
+VastAI.self_test_machine(
+ machine_id: str,
+ debugging: bool = False,
+ explain: bool = False,
+ raw: bool = False,
+ url: str = "https://console.vast.ai",
+ retry: int = 3,
+ ignore_requirements: bool = False
+) -> str
+```
+
+## Parameters
+
+
+ ID of the machine to self-test.
+
+
+
+ Enable debug output during the test.
+
+
+
+ Print verbose explanations of API calls made.
+
+
+
+ Return raw JSON responses.
+
+
+
+ API server URL.
+
+
+
+ Number of retry attempts for failed API requests.
+
+
+
+ Skip requirement checks during the test.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.self_test_machine(machine_id="...")
+print(result)
+```
diff --git a/sdk/python/reference/set-api-key.mdx b/sdk/python/reference/set-api-key.mdx
new file mode 100644
index 0000000..540dd86
--- /dev/null
+++ b/sdk/python/reference/set-api-key.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.set_api_key"
+sidebarTitle: "set_api_key"
+---
+
+Set a new API key.
+
+## Signature
+
+```python
+VastAI.set_api_key(new_api_key: str) -> str
+```
+
+## Parameters
+
+
+ new_api_key
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.set_api_key(new_api_key="...")
+print(result)
+```
diff --git a/sdk/python/reference/set-defjob.mdx b/sdk/python/reference/set-defjob.mdx
new file mode 100644
index 0000000..7d9e270
--- /dev/null
+++ b/sdk/python/reference/set-defjob.mdx
@@ -0,0 +1,61 @@
+---
+title: "VastAI.set_defjob"
+sidebarTitle: "set_defjob"
+---
+
+Set a default job on a machine with specified parameters.
+
+This is a **host** method, used for managing machines you are renting out on Vast.ai.
+
+## Signature
+
+```python
+VastAI.set_defjob(
+ id: int,
+ price_gpu: Optional[float] = None,
+ price_inetu: Optional[float] = None,
+ price_inetd: Optional[float] = None,
+ image: Optional[str] = None,
+ args: Optional[List[str]] = None
+) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+
+ price_gpu
+
+
+
+ price_inetu
+
+
+
+ price_inetd
+
+
+
+ image
+
+
+
+ args
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.set_defjob(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/set-min-bid.mdx b/sdk/python/reference/set-min-bid.mdx
new file mode 100644
index 0000000..a02cd66
--- /dev/null
+++ b/sdk/python/reference/set-min-bid.mdx
@@ -0,0 +1,38 @@
+---
+title: "VastAI.set_min_bid"
+sidebarTitle: "set_min_bid"
+---
+
+Set the minimum bid price for a machine.
+
+This is a **host** method, used for managing machines you are renting out on Vast.ai.
+
+## Signature
+
+```python
+VastAI.set_min_bid(id: int, price: Optional[float] = None) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+
+ price
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.set_min_bid(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/set-user.mdx b/sdk/python/reference/set-user.mdx
new file mode 100644
index 0000000..b7680d9
--- /dev/null
+++ b/sdk/python/reference/set-user.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.set_user"
+sidebarTitle: "set_user"
+---
+
+Set user parameters from a file.
+
+## Signature
+
+```python
+VastAI.set_user(file: Optional[str] = None) -> str
+```
+
+## Parameters
+
+
+ file
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.set_user()
+print(result)
+```
diff --git a/sdk/python/reference/show-api-key.mdx b/sdk/python/reference/show-api-key.mdx
new file mode 100644
index 0000000..af210cf
--- /dev/null
+++ b/sdk/python/reference/show-api-key.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.show_api_key"
+sidebarTitle: "show_api_key"
+---
+
+Show details of an API key.
+
+## Signature
+
+```python
+VastAI.show_api_key(id: int) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_api_key(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/show-api-keys.mdx b/sdk/python/reference/show-api-keys.mdx
new file mode 100644
index 0000000..d858807
--- /dev/null
+++ b/sdk/python/reference/show-api-keys.mdx
@@ -0,0 +1,26 @@
+---
+title: "VastAI.show_api_keys"
+sidebarTitle: "show_api_keys"
+---
+
+Show all API keys.
+
+## Signature
+
+```python
+VastAI.show_api_keys() -> str
+```
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_api_keys()
+print(result)
+```
diff --git a/sdk/python/reference/show-audit-logs.mdx b/sdk/python/reference/show-audit-logs.mdx
new file mode 100644
index 0000000..0550bde
--- /dev/null
+++ b/sdk/python/reference/show-audit-logs.mdx
@@ -0,0 +1,26 @@
+---
+title: "VastAI.show_audit_logs"
+sidebarTitle: "show_audit_logs"
+---
+
+Display account's history of important actions.
+
+## Signature
+
+```python
+VastAI.show_audit_logs() -> str
+```
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_audit_logs()
+print(result)
+```
diff --git a/sdk/python/reference/show-clusters.mdx b/sdk/python/reference/show-clusters.mdx
new file mode 100644
index 0000000..78bdba3
--- /dev/null
+++ b/sdk/python/reference/show-clusters.mdx
@@ -0,0 +1,26 @@
+---
+title: "VastAI.show_clusters"
+sidebarTitle: "show_clusters"
+---
+
+Show clusters associated with your account.
+
+## Signature
+
+```python
+VastAI.show_clusters() -> str
+```
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_clusters()
+print(result)
+```
diff --git a/sdk/python/reference/show-connections.mdx b/sdk/python/reference/show-connections.mdx
new file mode 100644
index 0000000..382f5f4
--- /dev/null
+++ b/sdk/python/reference/show-connections.mdx
@@ -0,0 +1,26 @@
+---
+title: "VastAI.show_connections"
+sidebarTitle: "show_connections"
+---
+
+Show all connections.
+
+## Signature
+
+```python
+VastAI.show_connections() -> str
+```
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_connections()
+print(result)
+```
diff --git a/sdk/python/reference/show-deployment-versions.mdx b/sdk/python/reference/show-deployment-versions.mdx
new file mode 100644
index 0000000..35e6c8b
--- /dev/null
+++ b/sdk/python/reference/show-deployment-versions.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.show_deployment_versions"
+sidebarTitle: "show_deployment_versions"
+---
+
+Show version history for a deployment.
+
+## Signature
+
+```python
+VastAI.show_deployment_versions(id: int) -> str
+```
+
+## Parameters
+
+
+ ID of the deployment to show versions for.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_deployment_versions(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/show-deployment.mdx b/sdk/python/reference/show-deployment.mdx
new file mode 100644
index 0000000..223e0fb
--- /dev/null
+++ b/sdk/python/reference/show-deployment.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.show_deployment"
+sidebarTitle: "show_deployment"
+---
+
+Show details for a single deployment.
+
+## Signature
+
+```python
+VastAI.show_deployment(id: int) -> str
+```
+
+## Parameters
+
+
+ ID of the deployment to show.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_deployment(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/show-deployments.mdx b/sdk/python/reference/show-deployments.mdx
new file mode 100644
index 0000000..c524bd9
--- /dev/null
+++ b/sdk/python/reference/show-deployments.mdx
@@ -0,0 +1,26 @@
+---
+title: "VastAI.show_deployments"
+sidebarTitle: "show_deployments"
+---
+
+Show all deployments.
+
+## Signature
+
+```python
+VastAI.show_deployments() -> str
+```
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_deployments()
+print(result)
+```
diff --git a/sdk/python/reference/show-deposit.mdx b/sdk/python/reference/show-deposit.mdx
new file mode 100644
index 0000000..3bb2923
--- /dev/null
+++ b/sdk/python/reference/show-deposit.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.show_deposit"
+sidebarTitle: "show_deposit"
+---
+
+Show deposit/credit details for a user account.
+
+## Signature
+
+```python
+VastAI.show_deposit(Id: int) -> str
+```
+
+## Parameters
+
+
+ ID of the user account to show deposit details for.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_deposit(Id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/show-earnings.mdx b/sdk/python/reference/show-earnings.mdx
new file mode 100644
index 0000000..48b4aeb
--- /dev/null
+++ b/sdk/python/reference/show-earnings.mdx
@@ -0,0 +1,49 @@
+---
+title: "VastAI.show_earnings"
+sidebarTitle: "show_earnings"
+---
+
+Show earnings information.
+
+## Signature
+
+```python
+VastAI.show_earnings(
+ quiet: bool = False,
+ start_date: Optional[str] = None,
+ end_date: Optional[str] = None,
+ machine_id: Optional[int] = None
+) -> str
+```
+
+## Parameters
+
+
+ quiet
+
+
+
+ start_date
+
+
+
+ end_date
+
+
+
+ machine_id
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_earnings()
+print(result)
+```
diff --git a/sdk/python/reference/show-endpoints.mdx b/sdk/python/reference/show-endpoints.mdx
new file mode 100644
index 0000000..b0eefd0
--- /dev/null
+++ b/sdk/python/reference/show-endpoints.mdx
@@ -0,0 +1,26 @@
+---
+title: "VastAI.show_endpoints"
+sidebarTitle: "show_endpoints"
+---
+
+Show all endpoints.
+
+## Signature
+
+```python
+VastAI.show_endpoints() -> str
+```
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_endpoints()
+print(result)
+```
diff --git a/sdk/python/reference/show-env-vars.mdx b/sdk/python/reference/show-env-vars.mdx
new file mode 100644
index 0000000..7cd6373
--- /dev/null
+++ b/sdk/python/reference/show-env-vars.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.show_env_vars"
+sidebarTitle: "show_env_vars"
+---
+
+Show user environment variables.
+
+## Signature
+
+```python
+VastAI.show_env_vars(show_values: bool = False) -> str
+```
+
+## Parameters
+
+
+ show_values
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_env_vars()
+print(result)
+```
diff --git a/sdk/python/reference/show-instance.mdx b/sdk/python/reference/show-instance.mdx
new file mode 100644
index 0000000..bc4e0ac
--- /dev/null
+++ b/sdk/python/reference/show-instance.mdx
@@ -0,0 +1,54 @@
+---
+title: "VastAI.show_instance"
+sidebarTitle: "show_instance"
+---
+
+Show details of an instance.
+
+ Returns an instance object. Key status fields:
+
+ **actual_status** — current container state:
+
+ | Value | Meaning |
+ |-------|---------|
+ | `null` | Instance is being provisioned |
+ | `loading` | Docker image is downloading or container is starting up |
+ | `running` | Container is actively executing. GPU charges apply. |
+ | `stopped` | Container is halted. Disk charges continue; no GPU charges. |
+ | `frozen` | Container is paused with memory preserved. GPU charges apply. |
+ | `exited` | Container process exited unexpectedly |
+ | `rebooting` | Container is restarting (transient) |
+ | `unknown` | No recent heartbeat from the host |
+ | `offline` | Host machine disconnected from Vast servers (computed, not stored in DB) |
+
+ **intended_status** — user's desired target state: `running`, `stopped`, or `frozen`.
+
+ **cur_state** — machine contract / hardware allocation state: `running`, `stopped`, or `unloaded` (released on destroy).
+
+ **status_msg** — human-readable detail on the current status.
+
+## Signature
+
+```python
+VastAI.show_instance(id: int) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_instance(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/show-instances-v1.mdx b/sdk/python/reference/show-instances-v1.mdx
new file mode 100644
index 0000000..cb3ad68
--- /dev/null
+++ b/sdk/python/reference/show-instances-v1.mdx
@@ -0,0 +1,106 @@
+---
+title: "VastAI.show_instances_v1"
+sidebarTitle: "show_instances_v1"
+---
+
+Show instances with pagination and filtering (v1).
+
+ Returns a paginated list of instance objects. Key status fields per instance:
+
+ **actual_status** — current container state:
+
+ | Value | Meaning |
+ |-------|---------|
+ | `null` | Instance is being provisioned |
+ | `loading` | Docker image is downloading or container is starting up |
+ | `running` | Container is actively executing. GPU charges apply. |
+ | `stopped` | Container is halted. Disk charges continue; no GPU charges. |
+ | `frozen` | Container is paused with memory preserved. GPU charges apply. |
+ | `exited` | Container process exited unexpectedly |
+ | `rebooting` | Container is restarting (transient) |
+ | `unknown` | No recent heartbeat from the host |
+ | `offline` | Host machine disconnected from Vast servers (computed, not stored in DB) |
+
+ **intended_status** — user's desired target state: `running`, `stopped`, or `frozen`.
+
+ **cur_state** — machine contract / hardware allocation state: `running`, `stopped`, or `unloaded` (released on destroy).
+
+ **status_msg** — human-readable detail on the current status.
+
+## Signature
+
+```python
+VastAI.show_instances_v1(
+ quiet: bool = False,
+ verbose: bool = False,
+ all: bool = False,
+ status: Optional[List[str]] = None,
+ label: Optional[List[str]] = None,
+ gpu_name: Optional[List[str]] = None,
+ verification: Optional[List[str]] = None,
+ limit: Optional[int] = None,
+ next_token: Optional[str] = None,
+ order_by: Optional[str] = None,
+ cols: Optional[str] = None
+) -> str
+```
+
+## Parameters
+
+
+ Only print instance IDs, one per line.
+
+
+
+ Show additional columns (SSH, location, template, etc.).
+
+
+
+ Fetch all pages automatically and send to pager.
+
+
+
+ Filter by container status: running, loading, exited.
+
+
+
+ Filter by instance label; pass empty string to match unlabeled.
+
+
+
+ Filter by GPU model name (e.g. 'RTX A5000').
+
+
+
+ Filter by machine verification: verified, unverified, deverified.
+
+
+
+ Max instances per page (1–25, default 25).
+
+
+
+ Resume from a pagination token from a previous page.
+
+
+
+ Sort column with optional direction, e.g. 'start_date desc'.
+
+
+
+ Override displayed columns with a comma-separated list.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_instances_v1()
+print(result)
+```
diff --git a/sdk/python/reference/show-instances.mdx b/sdk/python/reference/show-instances.mdx
new file mode 100644
index 0000000..d48a5bd
--- /dev/null
+++ b/sdk/python/reference/show-instances.mdx
@@ -0,0 +1,54 @@
+---
+title: "VastAI.show_instances"
+sidebarTitle: "show_instances"
+---
+
+Show all instances.
+
+ Returns a list of instance objects. Key status fields per instance:
+
+ **actual_status** — current container state:
+
+ | Value | Meaning |
+ |-------|---------|
+ | `null` | Instance is being provisioned |
+ | `loading` | Docker image is downloading or container is starting up |
+ | `running` | Container is actively executing. GPU charges apply. |
+ | `stopped` | Container is halted. Disk charges continue; no GPU charges. |
+ | `frozen` | Container is paused with memory preserved. GPU charges apply. |
+ | `exited` | Container process exited unexpectedly |
+ | `rebooting` | Container is restarting (transient) |
+ | `unknown` | No recent heartbeat from the host |
+ | `offline` | Host machine disconnected from Vast servers (computed, not stored in DB) |
+
+ **intended_status** — user's desired target state: `running`, `stopped`, or `frozen`.
+
+ **cur_state** — machine contract / hardware allocation state: `running`, `stopped`, or `unloaded` (released on destroy).
+
+ **status_msg** — human-readable detail on the current status.
+
+## Signature
+
+```python
+VastAI.show_instances(quiet: bool = False) -> str
+```
+
+## Parameters
+
+
+ quiet
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_instances()
+print(result)
+```
diff --git a/sdk/python/reference/show-invoices-v1.mdx b/sdk/python/reference/show-invoices-v1.mdx
new file mode 100644
index 0000000..3fc4d6e
--- /dev/null
+++ b/sdk/python/reference/show-invoices-v1.mdx
@@ -0,0 +1,84 @@
+---
+title: "VastAI.show_invoices_v1"
+sidebarTitle: "show_invoices_v1"
+---
+
+Get billing history reports with advanced filtering and pagination.
+
+## Signature
+
+```python
+VastAI.show_invoices_v1(
+ invoices: bool = False,
+ invoice_type: Optional[List[str]] = None,
+ charges: bool = False,
+ charge_type: Optional[List[str]] = None,
+ start_date: Optional[str] = None,
+ end_date: Optional[str] = None,
+ limit: int = 20,
+ next_token: Optional[str] = None,
+ format: str = "table",
+ verbose: bool = False,
+ latest_first: bool = False
+) -> str
+```
+
+## Parameters
+
+
+ invoices
+
+
+
+ invoice_type
+
+
+
+ charges
+
+
+
+ charge_type
+
+
+
+ start_date
+
+
+
+ end_date
+
+
+
+ limit
+
+
+
+ next_token
+
+
+
+ format
+
+
+
+ verbose
+
+
+
+ latest_first
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_invoices_v1()
+print(result)
+```
diff --git a/sdk/python/reference/show-invoices.mdx b/sdk/python/reference/show-invoices.mdx
new file mode 100644
index 0000000..4febaf1
--- /dev/null
+++ b/sdk/python/reference/show-invoices.mdx
@@ -0,0 +1,59 @@
+---
+title: "VastAI.show_invoices"
+sidebarTitle: "show_invoices"
+---
+
+Show invoice details.
+
+## Signature
+
+```python
+VastAI.show_invoices(
+ quiet: bool = False,
+ start_date: Optional[str] = None,
+ end_date: Optional[str] = None,
+ only_charges: bool = False,
+ only_credits: bool = False,
+ instance_label: Optional[str] = None
+) -> str
+```
+
+## Parameters
+
+
+ quiet
+
+
+
+ start_date
+
+
+
+ end_date
+
+
+
+ only_charges
+
+
+
+ only_credits
+
+
+
+ instance_label
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_invoices()
+print(result)
+```
diff --git a/sdk/python/reference/show-ipaddrs.mdx b/sdk/python/reference/show-ipaddrs.mdx
new file mode 100644
index 0000000..a1bd9f0
--- /dev/null
+++ b/sdk/python/reference/show-ipaddrs.mdx
@@ -0,0 +1,26 @@
+---
+title: "VastAI.show_ipaddrs"
+sidebarTitle: "show_ipaddrs"
+---
+
+Show IP addresses.
+
+## Signature
+
+```python
+VastAI.show_ipaddrs() -> str
+```
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_ipaddrs()
+print(result)
+```
diff --git a/sdk/python/reference/show-machine.mdx b/sdk/python/reference/show-machine.mdx
new file mode 100644
index 0000000..2a0e93b
--- /dev/null
+++ b/sdk/python/reference/show-machine.mdx
@@ -0,0 +1,38 @@
+---
+title: "VastAI.show_machine"
+sidebarTitle: "show_machine"
+---
+
+Show details of a hosted machine.
+
+This is a **host** method, used for managing machines you are renting out on Vast.ai.
+
+## Signature
+
+```python
+VastAI.show_machine(Machine: int, quiet: bool = False) -> str
+```
+
+## Parameters
+
+
+ Machine
+
+
+
+ quiet
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_machine(Machine=12345)
+print(result)
+```
diff --git a/sdk/python/reference/show-machines.mdx b/sdk/python/reference/show-machines.mdx
new file mode 100644
index 0000000..dc442e6
--- /dev/null
+++ b/sdk/python/reference/show-machines.mdx
@@ -0,0 +1,38 @@
+---
+title: "VastAI.show_machines"
+sidebarTitle: "show_machines"
+---
+
+Retrieve and display a list of machines based on specified criteria.
+
+This is a **host** method, used for managing machines you are renting out on Vast.ai.
+
+## Signature
+
+```python
+VastAI.show_machines(quiet: bool = False, filter: Optional[str] = None) -> str
+```
+
+## Parameters
+
+
+ If True, limit the output to minimal details such as IDs.
+
+
+
+ A string used to filter the machines based on specific criteria.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_machines()
+print(result)
+```
diff --git a/sdk/python/reference/show-maints.mdx b/sdk/python/reference/show-maints.mdx
new file mode 100644
index 0000000..2689ac3
--- /dev/null
+++ b/sdk/python/reference/show-maints.mdx
@@ -0,0 +1,38 @@
+---
+title: "VastAI.show_maints"
+sidebarTitle: "show_maints"
+---
+
+Show maintenance information for host machines.
+
+This is a **host** method, used for managing machines you are renting out on Vast.ai.
+
+## Signature
+
+```python
+VastAI.show_maints(ids: str, quiet: bool = False) -> str
+```
+
+## Parameters
+
+
+ ids
+
+
+
+ quiet
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_maints(ids="...")
+print(result)
+```
diff --git a/sdk/python/reference/show-members.mdx b/sdk/python/reference/show-members.mdx
new file mode 100644
index 0000000..dfa3daa
--- /dev/null
+++ b/sdk/python/reference/show-members.mdx
@@ -0,0 +1,26 @@
+---
+title: "VastAI.show_members"
+sidebarTitle: "show_members"
+---
+
+Show your team members.
+
+## Signature
+
+```python
+VastAI.show_members() -> str
+```
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_members()
+print(result)
+```
diff --git a/sdk/python/reference/show-overlays.mdx b/sdk/python/reference/show-overlays.mdx
new file mode 100644
index 0000000..d204552
--- /dev/null
+++ b/sdk/python/reference/show-overlays.mdx
@@ -0,0 +1,26 @@
+---
+title: "VastAI.show_overlays"
+sidebarTitle: "show_overlays"
+---
+
+Show overlays associated with your account.
+
+## Signature
+
+```python
+VastAI.show_overlays() -> str
+```
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_overlays()
+print(result)
+```
diff --git a/sdk/python/reference/show-scheduled-jobs.mdx b/sdk/python/reference/show-scheduled-jobs.mdx
new file mode 100644
index 0000000..c5956bc
--- /dev/null
+++ b/sdk/python/reference/show-scheduled-jobs.mdx
@@ -0,0 +1,26 @@
+---
+title: "VastAI.show_scheduled_jobs"
+sidebarTitle: "show_scheduled_jobs"
+---
+
+Show the list of scheduled jobs for the account.
+
+## Signature
+
+```python
+VastAI.show_scheduled_jobs() -> str
+```
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_scheduled_jobs()
+print(result)
+```
diff --git a/sdk/python/reference/show-ssh-keys.mdx b/sdk/python/reference/show-ssh-keys.mdx
new file mode 100644
index 0000000..e44ce46
--- /dev/null
+++ b/sdk/python/reference/show-ssh-keys.mdx
@@ -0,0 +1,26 @@
+---
+title: "VastAI.show_ssh_keys"
+sidebarTitle: "show_ssh_keys"
+---
+
+Show all SSH keys.
+
+## Signature
+
+```python
+VastAI.show_ssh_keys() -> str
+```
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_ssh_keys()
+print(result)
+```
diff --git a/sdk/python/reference/show-subaccounts.mdx b/sdk/python/reference/show-subaccounts.mdx
new file mode 100644
index 0000000..88cdbc4
--- /dev/null
+++ b/sdk/python/reference/show-subaccounts.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.show_subaccounts"
+sidebarTitle: "show_subaccounts"
+---
+
+Show all subaccounts of the current user.
+
+## Signature
+
+```python
+VastAI.show_subaccounts(quiet: bool = False) -> str
+```
+
+## Parameters
+
+
+ quiet
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_subaccounts()
+print(result)
+```
diff --git a/sdk/python/reference/show-team-role.mdx b/sdk/python/reference/show-team-role.mdx
new file mode 100644
index 0000000..14e244c
--- /dev/null
+++ b/sdk/python/reference/show-team-role.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.show_team_role"
+sidebarTitle: "show_team_role"
+---
+
+Show details of a specific team role.
+
+## Signature
+
+```python
+VastAI.show_team_role(NAME: str) -> str
+```
+
+## Parameters
+
+
+ NAME
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_team_role(NAME="...")
+print(result)
+```
diff --git a/sdk/python/reference/show-team-roles.mdx b/sdk/python/reference/show-team-roles.mdx
new file mode 100644
index 0000000..2a72513
--- /dev/null
+++ b/sdk/python/reference/show-team-roles.mdx
@@ -0,0 +1,26 @@
+---
+title: "VastAI.show_team_roles"
+sidebarTitle: "show_team_roles"
+---
+
+Show all team roles.
+
+## Signature
+
+```python
+VastAI.show_team_roles() -> str
+```
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_team_roles()
+print(result)
+```
diff --git a/sdk/python/reference/show-user.mdx b/sdk/python/reference/show-user.mdx
new file mode 100644
index 0000000..41b890d
--- /dev/null
+++ b/sdk/python/reference/show-user.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.show_user"
+sidebarTitle: "show_user"
+---
+
+Show user details.
+
+## Signature
+
+```python
+VastAI.show_user(quiet: bool = False) -> str
+```
+
+## Parameters
+
+
+ quiet
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_user()
+print(result)
+```
diff --git a/sdk/python/reference/show-volumes.mdx b/sdk/python/reference/show-volumes.mdx
new file mode 100644
index 0000000..970ed0c
--- /dev/null
+++ b/sdk/python/reference/show-volumes.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.show_volumes"
+sidebarTitle: "show_volumes"
+---
+
+Show stats on owned volumes.
+
+## Signature
+
+```python
+VastAI.show_volumes(type: str = "all") -> str
+```
+
+## Parameters
+
+
+ type
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_volumes()
+print(result)
+```
diff --git a/sdk/python/reference/show-workergroups.mdx b/sdk/python/reference/show-workergroups.mdx
new file mode 100644
index 0000000..5f62ba1
--- /dev/null
+++ b/sdk/python/reference/show-workergroups.mdx
@@ -0,0 +1,26 @@
+---
+title: "VastAI.show_workergroups"
+sidebarTitle: "show_workergroups"
+---
+
+Display current worker groups.
+
+## Signature
+
+```python
+VastAI.show_workergroups() -> str
+```
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.show_workergroups()
+print(result)
+```
diff --git a/sdk/python/reference/ssh-url.mdx b/sdk/python/reference/ssh-url.mdx
new file mode 100644
index 0000000..ff5cfcd
--- /dev/null
+++ b/sdk/python/reference/ssh-url.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.ssh_url"
+sidebarTitle: "ssh_url"
+---
+
+Get the SSH URL for an instance.
+
+## Signature
+
+```python
+VastAI.ssh_url(id: int) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.ssh_url(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/start-instance.mdx b/sdk/python/reference/start-instance.mdx
new file mode 100644
index 0000000..20d4ab8
--- /dev/null
+++ b/sdk/python/reference/start-instance.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.start_instance"
+sidebarTitle: "start_instance"
+---
+
+Start an instance.
+
+## Signature
+
+```python
+VastAI.start_instance(id: int) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.start_instance(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/start-instances.mdx b/sdk/python/reference/start-instances.mdx
new file mode 100644
index 0000000..886d71f
--- /dev/null
+++ b/sdk/python/reference/start-instances.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.start_instances"
+sidebarTitle: "start_instances"
+---
+
+Start multiple instances.
+
+## Signature
+
+```python
+VastAI.start_instances(ids: List[int]) -> str
+```
+
+## Parameters
+
+
+ ids
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.start_instances(ids=[12345])
+print(result)
+```
diff --git a/sdk/python/reference/stop-instance.mdx b/sdk/python/reference/stop-instance.mdx
new file mode 100644
index 0000000..1cbda38
--- /dev/null
+++ b/sdk/python/reference/stop-instance.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.stop_instance"
+sidebarTitle: "stop_instance"
+---
+
+Stop an instance.
+
+## Signature
+
+```python
+VastAI.stop_instance(id: int) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.stop_instance(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/stop-instances.mdx b/sdk/python/reference/stop-instances.mdx
new file mode 100644
index 0000000..082a42e
--- /dev/null
+++ b/sdk/python/reference/stop-instances.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.stop_instances"
+sidebarTitle: "stop_instances"
+---
+
+Stop multiple instances.
+
+## Signature
+
+```python
+VastAI.stop_instances(ids: List[int]) -> str
+```
+
+## Parameters
+
+
+ ids
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.stop_instances(ids=[12345])
+print(result)
+```
diff --git a/sdk/python/reference/transfer-credit.mdx b/sdk/python/reference/transfer-credit.mdx
new file mode 100644
index 0000000..348c8ff
--- /dev/null
+++ b/sdk/python/reference/transfer-credit.mdx
@@ -0,0 +1,36 @@
+---
+title: "VastAI.transfer_credit"
+sidebarTitle: "transfer_credit"
+---
+
+Transfer credit to another account.
+
+## Signature
+
+```python
+VastAI.transfer_credit(recipient: str, amount: float) -> str
+```
+
+## Parameters
+
+
+ recipient
+
+
+
+ amount
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.transfer_credit(recipient="...", amount=1.0)
+print(result)
+```
diff --git a/sdk/python/reference/unlist-machine.mdx b/sdk/python/reference/unlist-machine.mdx
new file mode 100644
index 0000000..d46ab67
--- /dev/null
+++ b/sdk/python/reference/unlist-machine.mdx
@@ -0,0 +1,34 @@
+---
+title: "VastAI.unlist_machine"
+sidebarTitle: "unlist_machine"
+---
+
+Unlist a machine from being available for new jobs.
+
+This is a **host** method, used for managing machines you are renting out on Vast.ai.
+
+## Signature
+
+```python
+VastAI.unlist_machine(id: int) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.unlist_machine(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/unlist-volume.mdx b/sdk/python/reference/unlist-volume.mdx
new file mode 100644
index 0000000..99f0906
--- /dev/null
+++ b/sdk/python/reference/unlist-volume.mdx
@@ -0,0 +1,32 @@
+---
+title: "VastAI.unlist_volume"
+sidebarTitle: "unlist_volume"
+---
+
+Unlist a volume offer.
+
+## Signature
+
+```python
+VastAI.unlist_volume(id: int) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.unlist_volume(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/update-endpoint.mdx b/sdk/python/reference/update-endpoint.mdx
new file mode 100644
index 0000000..ae336da
--- /dev/null
+++ b/sdk/python/reference/update-endpoint.mdx
@@ -0,0 +1,64 @@
+---
+title: "VastAI.update_endpoint"
+sidebarTitle: "update_endpoint"
+---
+
+Update an existing serverless endpoint group.
+
+## Signature
+
+```python
+VastAI.update_endpoint(
+ id: int,
+ min_load: Optional[float] = None,
+ target_util: Optional[float] = None,
+ cold_mult: Optional[float] = None,
+ cold_workers: Optional[int] = None,
+ max_workers: Optional[int] = None,
+ endpoint_name: Optional[str] = None
+) -> str
+```
+
+## Parameters
+
+
+ ID of the endpoint to update.
+
+
+
+ Minimum load (requests/sec) below which idle workers are scaled down.
+
+
+
+ Target worker utilization ratio (0.0–1.0).
+
+
+
+ Multiplier applied to warm worker count for pre-warming cold workers.
+
+
+
+ Number of pre-warmed (cold) workers to keep ready.
+
+
+
+ Maximum number of workers allowed in this endpoint.
+
+
+
+ Human-readable name for the endpoint.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.update_endpoint(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/update-env-var.mdx b/sdk/python/reference/update-env-var.mdx
new file mode 100644
index 0000000..be94f44
--- /dev/null
+++ b/sdk/python/reference/update-env-var.mdx
@@ -0,0 +1,36 @@
+---
+title: "VastAI.update_env_var"
+sidebarTitle: "update_env_var"
+---
+
+Update an existing user environment variable.
+
+## Signature
+
+```python
+VastAI.update_env_var(name: str, value: str) -> str
+```
+
+## Parameters
+
+
+ name
+
+
+
+ value
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.update_env_var(name="...", value="...")
+print(result)
+```
diff --git a/sdk/python/reference/update-instance.mdx b/sdk/python/reference/update-instance.mdx
new file mode 100644
index 0000000..8ccb42b
--- /dev/null
+++ b/sdk/python/reference/update-instance.mdx
@@ -0,0 +1,64 @@
+---
+title: "VastAI.update_instance"
+sidebarTitle: "update_instance"
+---
+
+Update/recreate an instance from a new/updated template.
+
+## Signature
+
+```python
+VastAI.update_instance(
+ id: int,
+ template_id: Optional[int] = None,
+ template_hash_id: Optional[str] = None,
+ image: Optional[str] = None,
+ args: Optional[str] = None,
+ env: Optional[str] = None,
+ onstart: Optional[str] = None
+) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+
+ template_id
+
+
+
+ template_hash_id
+
+
+
+ image
+
+
+
+ args
+
+
+
+ env
+
+
+
+ onstart
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.update_instance(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/update-ssh-key.mdx b/sdk/python/reference/update-ssh-key.mdx
new file mode 100644
index 0000000..ef1f6ed
--- /dev/null
+++ b/sdk/python/reference/update-ssh-key.mdx
@@ -0,0 +1,36 @@
+---
+title: "VastAI.update_ssh_key"
+sidebarTitle: "update_ssh_key"
+---
+
+Update an SSH key.
+
+## Signature
+
+```python
+VastAI.update_ssh_key(id: int, ssh_key: str) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+
+ ssh_key
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.update_ssh_key(id=12345, ssh_key="...")
+print(result)
+```
diff --git a/sdk/python/reference/update-team-role.mdx b/sdk/python/reference/update-team-role.mdx
new file mode 100644
index 0000000..25be43d
--- /dev/null
+++ b/sdk/python/reference/update-team-role.mdx
@@ -0,0 +1,40 @@
+---
+title: "VastAI.update_team_role"
+sidebarTitle: "update_team_role"
+---
+
+Update details of a team role.
+
+## Signature
+
+```python
+VastAI.update_team_role(id: int, name: Optional[str] = None, permissions: Optional[str] = None) -> str
+```
+
+## Parameters
+
+
+ id
+
+
+
+ name
+
+
+
+ permissions
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.update_team_role(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/update-template.mdx b/sdk/python/reference/update-template.mdx
new file mode 100644
index 0000000..f239a53
--- /dev/null
+++ b/sdk/python/reference/update-template.mdx
@@ -0,0 +1,79 @@
+---
+title: "VastAI.update_template"
+sidebarTitle: "update_template"
+---
+
+Update an existing template.
+
+## Signature
+
+```python
+VastAI.update_template(
+ HASH_ID: str,
+ name: Optional[str] = None,
+ image: Optional[str] = None,
+ env: Optional[str] = None,
+ onstart_cmd: Optional[str] = None,
+ search_params: Optional[str] = None,
+ disk: Optional[float] = None,
+ ssh: bool = False,
+ direct: bool = False,
+ jupyter: bool = False
+) -> str
+```
+
+## Parameters
+
+
+ Hash ID of the template to update.
+
+
+
+ New name for the template.
+
+
+
+ New Docker image for the template.
+
+
+
+ Environment variables to set (formatted as Docker -e flags).
+
+
+
+ Shell command to run on instance start.
+
+
+
+ Default search query parameters for this template.
+
+
+
+ Disk space allocation in GB.
+
+
+
+ Enable SSH access for instances created from this template.
+
+
+
+ Enable direct (peer-to-peer) connections.
+
+
+
+ Enable Jupyter notebook server.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.update_template(HASH_ID="...")
+print(result)
+```
diff --git a/sdk/python/reference/update-workergroup.mdx b/sdk/python/reference/update-workergroup.mdx
new file mode 100644
index 0000000..434f8af
--- /dev/null
+++ b/sdk/python/reference/update-workergroup.mdx
@@ -0,0 +1,99 @@
+---
+title: "VastAI.update_workergroup"
+sidebarTitle: "update_workergroup"
+---
+
+Update an existing autoscale worker group.
+
+## Signature
+
+```python
+VastAI.update_workergroup(
+ id: int,
+ min_load: Optional[float] = None,
+ target_util: Optional[float] = None,
+ cold_mult: Optional[float] = None,
+ cold_workers: Optional[int] = None,
+ test_workers: Optional[int] = None,
+ gpu_ram: Optional[float] = None,
+ template_hash: Optional[str] = None,
+ template_id: Optional[int] = None,
+ search_params: Optional[str] = None,
+ no_default: bool = False,
+ launch_args: Optional[str] = None,
+ endpoint_name: Optional[str] = None,
+ endpoint_id: Optional[int] = None
+) -> str
+```
+
+## Parameters
+
+
+ ID of the worker group to update.
+
+
+
+ Minimum load (requests/sec) below which idle workers are scaled down.
+
+
+
+ Target worker utilization ratio (0.0–1.0).
+
+
+
+ Multiplier applied to warm worker count for pre-warming cold workers.
+
+
+
+ Number of pre-warmed (cold) workers to keep ready.
+
+
+
+ Number of test workers to spin up during scaling evaluation.
+
+
+
+ Minimum GPU RAM in GiB required per worker.
+
+
+
+ Hash of the instance template to use for workers.
+
+
+
+ ID of the instance template to use for workers.
+
+
+
+ Query string for filtering available GPU offers.
+
+
+
+ Disable the default search query filters when finding offers.
+
+
+
+ Additional CLI arguments passed when launching worker instances.
+
+
+
+ Human-readable name for the endpoint.
+
+
+
+ ID of the endpoint this worker group belongs to.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.update_workergroup(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/update-workers.mdx b/sdk/python/reference/update-workers.mdx
new file mode 100644
index 0000000..eff2d3e
--- /dev/null
+++ b/sdk/python/reference/update-workers.mdx
@@ -0,0 +1,36 @@
+---
+title: "VastAI.update_workers"
+sidebarTitle: "update_workers"
+---
+
+Trigger a rolling update of all workers in a workergroup.
+
+## Signature
+
+```python
+VastAI.update_workers(id: int, cancel: bool = False) -> str
+```
+
+## Parameters
+
+
+ ID of the workergroup to update workers for.
+
+
+
+ Cancel an in-progress update for the workergroup.
+
+
+## Returns
+
+`str` — Result from the API call.
+
+## Example
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+result = client.update_workers(id=12345)
+print(result)
+```
diff --git a/sdk/python/reference/vastai.mdx b/sdk/python/reference/vastai.mdx
new file mode 100644
index 0000000..599ec01
--- /dev/null
+++ b/sdk/python/reference/vastai.mdx
@@ -0,0 +1,80 @@
+---
+title: "VastAI"
+sidebarTitle: "VastAI"
+---
+
+The `VastAI` class is the main client for interacting with the Vast.ai platform. It wraps the CLI commands as Python methods with typed signatures.
+
+## Installation
+
+```bash
+pip install vastai-sdk
+```
+
+## Quick Start
+
+```python
+from vastai import VastAI
+
+client = VastAI(api_key="YOUR_API_KEY")
+
+# Search for GPU offers
+offers = client.search_offers(query="gpu_name=RTX_3090 rentable=True")
+print(offers)
+
+# Show your instances
+instances = client.show_instances()
+print(instances)
+```
+
+## Constructor
+
+```python
+VastAI(
+ api_key=None,
+ server_url="https://console.vast.ai",
+ retry=3,
+ raw=True,
+ explain=False,
+ quiet=False,
+ curl=False
+)
+```
+
+
+ Your Vast.ai API key. If not provided, reads from `~/.config/vastai/vast_api_key`.
+
+
+
+ The Vast.ai API server URL.
+
+
+
+ Number of retry attempts for failed API requests.
+
+
+
+ Return raw JSON responses instead of formatted output.
+
+
+
+ Print verbose explanations of API calls.
+
+
+
+ Suppress non-essential output.
+
+
+
+ Print equivalent curl commands for API calls.
+
+
+If `api_key` is not provided, the SDK reads it from `~/.config/vastai/vast_api_key`.
+
+## Getting Help
+
+Use Python's built-in `help()` to view documentation for any method:
+
+```python
+help(client.search_offers)
+```
diff --git a/sdk/python/serverless/benchmark-config.mdx b/sdk/python/serverless/benchmark-config.mdx
new file mode 100644
index 0000000..7142385
--- /dev/null
+++ b/sdk/python/serverless/benchmark-config.mdx
@@ -0,0 +1,34 @@
+---
+title: "BenchmarkConfig"
+sidebarTitle: "BenchmarkConfig"
+---
+
+Configuration for defining a benchmark
+
+## Import
+
+```python
+from vastai import BenchmarkConfig
+```
+
+## Fields
+
+
+ dataset
+
+
+
+ generator
+
+
+
+ runs
+
+
+
+ concurrency
+
+
+
+ do_warmup
+
diff --git a/sdk/python/serverless/client-worker.mdx b/sdk/python/serverless/client-worker.mdx
new file mode 100644
index 0000000..86bb1d0
--- /dev/null
+++ b/sdk/python/serverless/client-worker.mdx
@@ -0,0 +1,80 @@
+---
+title: "Worker"
+sidebarTitle: "Worker (Client)"
+---
+
+## Import
+
+```python
+from vastai.serverless.client.worker import Worker
+```
+
+## Fields
+
+
+ id
+
+
+
+ status
+
+
+
+ cur_load
+
+
+
+ new_load
+
+
+
+ cur_load_rolling_avg
+
+
+
+ cur_perf
+
+
+
+ perf
+
+
+
+ measured_perf
+
+
+
+ dlperf
+
+
+
+ reliability
+
+
+
+ reqs_working
+
+
+
+ disk_usage
+
+
+
+ loaded_at
+
+
+
+ started_at
+
+
+## Methods
+
+### from_dict
+
+```python
+from_dict(d: Dict[str, Any]) -> 'Worker'
+```
+
+
+ d
+
diff --git a/sdk/python/serverless/endpoint.mdx b/sdk/python/serverless/endpoint.mdx
new file mode 100644
index 0000000..500b3de
--- /dev/null
+++ b/sdk/python/serverless/endpoint.mdx
@@ -0,0 +1,162 @@
+---
+title: "Endpoint"
+sidebarTitle: "Endpoint"
+---
+
+## Import
+
+```python
+from vastai import Endpoint
+```
+
+## Constructor
+
+```python
+Endpoint(
+ client,
+ name,
+ id,
+ api_key
+)
+```
+
+
+ client
+
+
+
+ name
+
+
+
+ id
+
+
+
+ api_key
+
+
+## Methods
+
+### request
+
+```python
+request(
+ route,
+ payload,
+ serverless_request = None,
+ cost: int = 100,
+ retry: bool = True,
+ stream: bool = False,
+ timeout: float = None,
+ session: 'Session' = None
+)
+```
+
+
+ route
+
+
+
+ payload
+
+
+
+ serverless_request
+
+
+
+ cost
+
+
+
+ retry
+
+
+
+ stream
+
+
+
+ timeout
+
+
+
+ session
+
+
+### close_session
+
+```python
+close_session(session: 'Session')
+```
+
+
+ session
+
+
+### session_healthcheck
+
+```python
+async session_healthcheck(session: 'Session')
+```
+
+
+ session
+
+
+### get_session
+
+```python
+get_session(session_id: int, session_auth: dict, timeout: float = 10)
+```
+
+
+ session_id
+
+
+
+ session_auth
+
+
+
+ timeout
+
+
+### session
+
+```python
+session(
+ cost: int = 100,
+ lifetime: float = 60,
+ on_close_route: str = None,
+ on_close_payload: dict = None,
+ timeout: float = None
+) -> 'Session'
+```
+
+
+ cost
+
+
+
+ lifetime
+
+
+
+ on_close_route
+
+
+
+ on_close_payload
+
+
+
+ timeout
+
+
+### get_workers
+
+```python
+get_workers()
+```
diff --git a/sdk/python/serverless/handler-config.mdx b/sdk/python/serverless/handler-config.mdx
new file mode 100644
index 0000000..1b4ba5d
--- /dev/null
+++ b/sdk/python/serverless/handler-config.mdx
@@ -0,0 +1,58 @@
+---
+title: "HandlerConfig"
+sidebarTitle: "HandlerConfig"
+---
+
+Configuration for defining handlers
+
+## Import
+
+```python
+from vastai import HandlerConfig
+```
+
+## Fields
+
+
+ route
+
+
+
+ healthcheck
+
+
+
+ allow_parallel_requests
+
+
+
+ max_queue_time
+
+
+
+ benchmark_config
+
+
+
+ handler_class
+
+
+
+ payload_class
+
+
+
+ request_parser
+
+
+
+ response_generator
+
+
+
+ workload_calculator
+
+
+
+ remote_function
+
diff --git a/sdk/python/serverless/log-action-config.mdx b/sdk/python/serverless/log-action-config.mdx
new file mode 100644
index 0000000..d143cb1
--- /dev/null
+++ b/sdk/python/serverless/log-action-config.mdx
@@ -0,0 +1,34 @@
+---
+title: "LogActionConfig"
+sidebarTitle: "LogActionConfig"
+---
+
+Configuration for defining log actions
+
+## Import
+
+```python
+from vastai import LogActionConfig
+```
+
+## Fields
+
+
+ on_load
+
+
+
+ on_error
+
+
+
+ on_info
+
+
+## Properties
+
+### log_actions
+
+```python
+log_actions -> list[LogAction]
+```
diff --git a/sdk/python/serverless/server-worker.mdx b/sdk/python/serverless/server-worker.mdx
new file mode 100644
index 0000000..ea550b1
--- /dev/null
+++ b/sdk/python/serverless/server-worker.mdx
@@ -0,0 +1,38 @@
+---
+title: "Worker"
+sidebarTitle: "Worker (Server)"
+---
+
+This class provides a simple to use abstraction over the pyworker backend.
+All custom implementations of pyworker can be created by configuring a Worker object.
+The pyworker starts by calling Worker.run()
+
+## Import
+
+```python
+from vastai import Worker
+```
+
+## Constructor
+
+```python
+Worker(config: WorkerConfig)
+```
+
+
+ config
+
+
+## Methods
+
+### run_async
+
+```python
+async run_async()
+```
+
+### run
+
+```python
+run()
+```
diff --git a/sdk/python/serverless/serverless-request.mdx b/sdk/python/serverless/serverless-request.mdx
new file mode 100644
index 0000000..3669566
--- /dev/null
+++ b/sdk/python/serverless/serverless-request.mdx
@@ -0,0 +1,24 @@
+---
+title: "ServerlessRequest"
+sidebarTitle: "ServerlessRequest"
+---
+
+A request to a Serverless endpoint managed by the client
+
+## Import
+
+```python
+from vastai import ServerlessRequest
+```
+
+## Methods
+
+### then
+
+```python
+then(callback) -> 'ServerlessRequest'
+```
+
+
+ callback
+
diff --git a/sdk/python/serverless/serverless.mdx b/sdk/python/serverless/serverless.mdx
new file mode 100644
index 0000000..5bcab48
--- /dev/null
+++ b/sdk/python/serverless/serverless.mdx
@@ -0,0 +1,238 @@
+---
+title: "Serverless"
+sidebarTitle: "Serverless"
+---
+
+## Import
+
+```python
+from vastai import Serverless
+```
+
+## Constructor
+
+```python
+Serverless(
+ api_key: Optional[str] = os.environ.get('VAST_API_KEY', None),
+ *,
+ debug: bool = False,
+ instance: str = 'prod',
+ connection_limit: int = 500,
+ default_request_timeout: float = 600.0,
+ max_poll_interval: float = 5.0
+)
+```
+
+
+ api_key
+
+
+
+ debug
+
+
+
+ instance
+
+
+
+ connection_limit
+
+
+
+ default_request_timeout
+
+
+
+ max_poll_interval
+
+
+## Methods
+
+### is_open
+
+```python
+is_open()
+```
+
+### close
+
+```python
+async close()
+```
+
+### get_ssl_context
+
+```python
+async get_ssl_context() -> ssl.SSLContext
+```
+
+Download Vast.ai root cert and build SSL context (cached).
+
+### get_endpoint
+
+```python
+async get_endpoint(name = '') -> Endpoint
+```
+
+
+ name
+
+
+### get_endpoints
+
+```python
+async get_endpoints() -> list[Endpoint]
+```
+
+### get_endpoint_workers
+
+```python
+async get_endpoint_workers(endpoint: Endpoint) -> List[Worker]
+```
+
+
+ endpoint
+
+
+### get_endpoint_session
+
+```python
+async get_endpoint_session(
+ endpoint,
+ session_id: int,
+ session_auth: str,
+ timeout: float = 10.0
+)
+```
+
+
+ endpoint
+
+
+
+ session_id
+
+
+
+ session_auth
+
+
+
+ timeout
+
+
+### end_endpoint_session
+
+```python
+async end_endpoint_session(session: Session, timeout: float = 10.0)
+```
+
+
+ session
+
+
+
+ timeout
+
+
+### start_endpoint_session
+
+```python
+async start_endpoint_session(
+ endpoint: Endpoint,
+ cost: int = 100,
+ lifetime: float = 60,
+ on_close_route: str = None,
+ on_close_payload: dict = None,
+ timeout: float = None
+) -> Session
+```
+
+
+ endpoint
+
+
+
+ cost
+
+
+
+ lifetime
+
+
+
+ on_close_route
+
+
+
+ on_close_payload
+
+
+
+ timeout
+
+
+### queue_endpoint_request
+
+```python
+queue_endpoint_request(
+ endpoint: Endpoint,
+ worker_route: str,
+ worker_payload: dict,
+ session: Session = None,
+ serverless_request: Optional[ServerlessRequest] = None,
+ cost: int = 100,
+ timeout: Optional[float] = None,
+ worker_timeout: Optional[float] = 600,
+ retry: bool = True,
+ max_retries: int = None,
+ stream: bool = False
+) -> ServerlessRequest
+```
+
+Return a Future that will resolve once the request completes.
+
+
+ endpoint
+
+
+
+ worker_route
+
+
+
+ worker_payload
+
+
+
+ session
+
+
+
+ serverless_request
+
+
+
+ cost
+
+
+
+ timeout
+
+
+
+ worker_timeout
+
+
+
+ retry
+
+
+
+ max_retries
+
+
+
+ stream
+
diff --git a/sdk/python/serverless/session.mdx b/sdk/python/serverless/session.mdx
new file mode 100644
index 0000000..eb3f7b3
--- /dev/null
+++ b/sdk/python/serverless/session.mdx
@@ -0,0 +1,113 @@
+---
+title: "Session"
+sidebarTitle: "Session"
+---
+
+## Import
+
+```python
+from vastai.serverless.client.session import Session
+```
+
+## Constructor
+
+```python
+Session(
+ endpoint: Endpoint,
+ session_id: str,
+ lifetime: float,
+ expiration: str,
+ url: str,
+ auth_data: dict,
+ on_close_route: str = None,
+ on_close_payload: dict = None
+)
+```
+
+
+ endpoint
+
+
+
+ session_id
+
+
+
+ lifetime
+
+
+
+ expiration
+
+
+
+ url
+
+
+
+ auth_data
+
+
+
+ on_close_route
+
+
+
+ on_close_payload
+
+
+## Methods
+
+### is_open
+
+```python
+async is_open()
+```
+
+### close
+
+```python
+async close()
+```
+
+Explicit close for non-async contexts.
+Returns an awaitable if async work is required.
+
+### request
+
+```python
+request(
+ route,
+ payload,
+ serverless_request = None,
+ cost: int = 100,
+ retry: bool = True,
+ stream: bool = False
+)
+```
+
+Forward requests to the endpoint
+
+
+ route
+
+
+
+ payload
+
+
+
+ serverless_request
+
+
+
+ cost
+
+
+
+ retry
+
+
+
+ stream
+
diff --git a/sdk/python/serverless/worker-config.mdx b/sdk/python/serverless/worker-config.mdx
new file mode 100644
index 0000000..50440f9
--- /dev/null
+++ b/sdk/python/serverless/worker-config.mdx
@@ -0,0 +1,48 @@
+---
+title: "WorkerConfig"
+sidebarTitle: "WorkerConfig"
+---
+
+## Import
+
+```python
+from vastai import WorkerConfig
+```
+
+## Fields
+
+
+ model_server_url
+
+
+
+ model_server_port
+
+
+
+ model_log_file
+
+
+
+ benchmark_data
+
+
+
+ handlers
+
+
+
+ model_healthcheck_url
+
+
+
+ benchmark_route
+
+
+
+ log_action_config
+
+
+
+ max_sessions
+
diff --git a/sdk/python/templates.mdx b/sdk/python/templates.mdx
new file mode 100644
index 0000000..acd25c4
--- /dev/null
+++ b/sdk/python/templates.mdx
@@ -0,0 +1,382 @@
+---
+title: "Python SDK Templates"
+sidebarTitle: "Templates"
+---
+
+A **template** is a configuration bundle that stores default settings for instance creation. Instead of passing every parameter each time you create an instance, you define a template once and reference it by its `hash_id`. You can optionally override specific values at creation time.
+
+Templates are useful for:
+- **Standardization** -- ensure all team members launch instances with consistent configurations
+- **Convenience** -- avoid repeating the same image, env, and onstart parameters across calls
+- **Sharing** -- distribute configurations via template hash ID
+
+For information about managing templates in the web interface, see [Templates Introduction](/documentation/templates/introduction).
+
+## Setup
+
+```python
+from vastai import VastAI
+
+vast_sdk = VastAI(api_key="YOUR_API_KEY")
+```
+
+## Template Fields Reference
+
+When creating or editing a template, the following fields can be configured:
+
+| Field | Type | SDK Parameter | Description |
+|-------|------|---------------|-------------|
+| `name` | string | `name` | Human-readable name for the template |
+| `image` | string | `image` | Docker image path (e.g., `vllm/vllm-openai`) |
+| `tag` | string | `image_tag` | Docker image tag. Defaults to `latest` |
+| `desc` | string | `desc` | Short description of the template |
+| `readme` | string | `readme` | Longer documentation/readme content |
+| `env` | string | `env` | Environment variables and port mappings in Docker flag format (e.g., `"-e VAR=val -p 8000:8000"`) |
+| `onstart` | string | `onstart_cmd` | Shell commands to run when the instance starts |
+| `runtype` | string | `ssh` / `jupyter` | Launch mode: `ssh`, `jupyter`, or `args` (default). Set via boolean flags |
+| `ssh_direct` | boolean | `ssh=True, direct=True` | Enable direct SSH (set by combining `ssh` and `direct`) |
+| `use_ssh` | boolean | `ssh` | Enable SSH access |
+| `jup_direct` | boolean | `jupyter=True, direct=True` | Enable direct Jupyter (set by combining `jupyter` and `direct`) |
+| `jupyter_dir` | string | `jupyter_dir` | Directory to launch Jupyter from |
+| `use_jupyter_lab` | boolean | `jupyter_lab` | Use JupyterLab instead of Jupyter Notebook |
+| `docker_login_repo` | string | `login` | Private Docker registry URL (first token of the login string) |
+| `extra_filters` | object | `search_params` | Default machine search filters (parsed from query string) |
+| `recommended_disk_space` | number | `disk_space` | Recommended disk space in GB |
+| `private` | boolean | (private by default) | Templates are private by default |
+| `href` | string | `href` | Link to Docker Hub or image documentation |
+| `repo` | string | `repo` | Repository identifier |
+
+## Template Identifiers
+
+Templates have two identifiers. Which one you use depends on the operation:
+
+| Identifier | Type | Used For |
+|------------|------|----------|
+| `id` | integer | Deleting templates (`template_id` parameter) |
+| `hash_id` | string | Creating instances (`template_hash` parameter), editing templates (`HASH_ID` parameter) |
+
+
+The `hash_id` is derived from the template's content. After editing a template, the `hash_id` changes. Always retrieve the latest `hash_id` from the method return value or by searching for the template.
+
+
+## Create a Template
+
+Use `create_template()` to define a reusable configuration:
+
+```python
+result = vast_sdk.create_template(
+ name="vLLM Inference Server",
+ image="vllm/vllm-openai",
+ image_tag="latest",
+ env="-e MODEL_ID=deepseek-ai/DeepSeek-R1-Distill-Llama-8B -p 8000:8000",
+ onstart_cmd='echo "Starting vLLM server"; vllm serve $MODEL_ID',
+ disk_space="50",
+ ssh=True,
+ direct=True
+)
+print(result)
+```
+
+The result includes both identifiers:
+
+```
+New Template: {'id': 334548, 'hash_id': '4e17788f74f075dd9aab7d0d4427968f', ...}
+```
+
+Save both the `id` and `hash_id` -- you'll need them for different operations.
+
+You can also attach default machine search filters using `search_params`:
+
+```python
+result = vast_sdk.create_template(
+ name="tgi-llama2-7B-quantized",
+ image="ghcr.io/huggingface/text-generation-inference:1.0.3",
+ env="-p 3000:3000 -e MODEL_ARGS='--model-id TheBloke/Llama-2-7B-chat-GPTQ --quantize gptq'",
+ onstart_cmd="wget -O - https://raw.githubusercontent.com/vast-ai/vast-pyworker/main/scripts/launch_tgi.sh | bash",
+ search_params="gpu_ram>=23 num_gpus=1 gpu_name=RTX_3090 inet_down>128 direct_port_count>3 disk_space>=192",
+ disk_space="8.0",
+ ssh=True,
+ direct=True
+)
+```
+
+### Method Signature
+
+```python
+VastAI.create_template(
+ name: Optional[str] = None,
+ image: Optional[str] = None,
+ image_tag: Optional[str] = None,
+ login: Optional[str] = None,
+ env: Optional[str] = None,
+ ssh: bool = False,
+ jupyter: bool = False,
+ direct: bool = False,
+ jupyter_dir: Optional[str] = None,
+ jupyter_lab: bool = False,
+ onstart_cmd: Optional[str] = None,
+ search_params: Optional[str] = None,
+ disk_space: Optional[str] = None
+) -> str
+```
+
+## Search for Templates
+
+Use `search_templates()` with the same query syntax used by `search_offers()`:
+
+```python
+# Search for popular templates (more than 100 instances created)
+result = vast_sdk.search_templates(query="count_created > 100")
+print(result)
+
+# Search for templates by specific creators
+result = vast_sdk.search_templates(
+ query="count_created > 100 creator_id in [38382,48982]"
+)
+
+# Search for recommended templates with SSH support
+result = vast_sdk.search_templates(
+ query="recommended == True use_ssh == True"
+)
+```
+
+### Query Syntax
+
+```
+query = comparison comparison ...
+comparison = field op value
+op = one of: <, <=, ==, !=, >=, >, in, notin
+```
+
+### Searchable Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `creator_id` | int | ID of the creator |
+| `created_at` | float | Time of initial creation (UTC epoch) |
+| `count_created` | int | Number of instances created (popularity) |
+| `default_tag` | string | Image default tag |
+| `docker_login_repo` | string | Image docker repository |
+| `id` | int | Template unique ID |
+| `image` | string | Image used for the template |
+| `jup_direct` | bool | Supports Jupyter direct |
+| `hash_id` | string | Unique hash ID |
+| `name` | string | Displayable name |
+| `recent_create_date` | float | Last time of instance creation (UTC epoch) |
+| `recommended_disk_space` | float | Minimum disk space required |
+| `recommended` | bool | On the recommended list |
+| `ssh_direct` | bool | Supports SSH direct |
+| `tag` | string | Image tag |
+| `use_ssh` | bool | Supports SSH (direct or proxy) |
+
+### Method Signature
+
+```python
+VastAI.search_templates(query: Optional[str] = None) -> str
+```
+
+## Create an Instance from a Template
+
+Pass `template_hash` to `create_instance()` to use a template as the base configuration. You don't need to specify `image` or other fields already defined in the template:
+
+```python
+result = vast_sdk.create_instance(
+ id=12345678,
+ template_hash="4e17788f74f075dd9aab7d0d4427968f",
+ disk=20
+)
+print(result)
+```
+
+Output:
+
+```json
+{"success": true, "new_contract": 7835610}
+```
+
+You can combine a template with an interruptible (spot) bid:
+
+```python
+result = vast_sdk.create_instance(
+ id=12345678,
+ template_hash="4e17788f74f075dd9aab7d0d4427968f",
+ disk=64,
+ price=0.10
+)
+```
+
+## Override Template Values
+
+When you create an instance with both a template and additional parameters, the following precedence rules apply:
+
+| Field Type | Behavior |
+|------------|----------|
+| **Scalar fields** (image, disk, runtype, etc.) | Request value **overrides** template value |
+| **`env`** (string) | **Merged**. Template values retained, request values appended. Conflicting keys use the request value |
+| **`extra_filters`** (dict) | **Merged** by key. Request values win on conflicts |
+
+### Example: Overriding the Image
+
+```python
+# Use template config but swap the Docker image
+result = vast_sdk.create_instance(
+ id=12345678,
+ template_hash="4e17788f74f075dd9aab7d0d4427968f",
+ image="nvidia/cuda:12.1-devel-ubuntu22.04",
+ disk=20
+)
+```
+
+### Example: Merging Environment Variables
+
+If your template defines:
+```
+env: "-e MODEL_ID=deepseek-ai/DeepSeek-R1-Distill-Llama-8B -e MAX_TOKENS=4096"
+```
+
+And you create an instance with:
+```python
+result = vast_sdk.create_instance(
+ id=12345678,
+ template_hash="4e17788f74f075dd9aab7d0d4427968f",
+ env="-e MODEL_ID=mistralai/Mistral-7B-v0.1 -e HF_TOKEN=hf_xxx",
+ disk=20
+)
+```
+
+The resulting environment will be:
+- `MODEL_ID=mistralai/Mistral-7B-v0.1` -- request overrides template
+- `MAX_TOKENS=4096` -- retained from template
+- `HF_TOKEN=hf_xxx` -- added from request
+
+## Edit a Template
+
+Update an existing template using `update_template()` with the template's `hash_id` as the `HASH_ID` parameter. Include only the parameters you want to change:
+
+```python
+result = vast_sdk.update_template(
+ HASH_ID="5915f1dc1ce881defb572015eb9d8178",
+ name="Updated Template Name",
+ onstart_cmd="echo 'new startup script'"
+)
+print(result)
+```
+
+You can change any of the same parameters available in `create_template()`:
+
+```python
+result = vast_sdk.update_template(
+ HASH_ID="c81e7ab0e928a508510d1979346de10d",
+ name="tgi-llama2-7B-quantized",
+ image="ghcr.io/huggingface/text-generation-inference:1.0.3",
+ env="-p 3000:3000 -e MODEL_ARGS='--model-id TheBloke/Llama-2-7B-chat-GPTQ --quantize gptq'",
+ onstart_cmd="wget -O - https://raw.githubusercontent.com/vast-ai/vast-pyworker/main/scripts/launch_tgi.sh | bash",
+ ssh=True,
+ direct=True
+)
+```
+
+
+The `hash_id` changes after editing because it is derived from the template's content. Use the new `hash_id` returned in the result for subsequent operations.
+
+
+### Method Signature
+
+```python
+VastAI.update_template(
+ HASH_ID: str,
+ name: Optional[str] = None,
+ image: Optional[str] = None,
+ env: Optional[str] = None,
+ onstart_cmd: Optional[str] = None,
+ search_params: Optional[str] = None,
+ disk: Optional[float] = None,
+ ssh: bool = False,
+ direct: bool = False,
+ jupyter: bool = False
+) -> str
+```
+
+## Delete a Template
+
+Delete a template using either its numeric `id` or its `hash_id`:
+
+```python
+# Delete by numeric ID
+result = vast_sdk.delete_template(template_id=334548)
+print(result)
+
+# Delete by hash ID
+result = vast_sdk.delete_template(hash_id="49c538d097ad6437413b83711c9f61e8")
+print(result)
+```
+
+
+Deleting a template removes your relationship to it. It does not destroy the underlying template record.
+
+
+### Method Signature
+
+```python
+VastAI.delete_template(
+ template_id: Optional[int] = None,
+ hash_id: Optional[str] = None
+) -> str
+```
+
+## Common Pitfalls
+
+
+
+ Templates have two identifiers and each is used in different contexts:
+ - `create_instance(template_hash=...)` takes the **hash_id** (string)
+ - `update_template(HASH_ID=...)` takes the **hash_id** (string)
+ - `delete_template(template_id=...)` takes the numeric **id** (integer)
+
+ If you pass the numeric `id` where a `hash_id` is expected (or vice versa), the operation will fail. You can also call `delete_template(hash_id=...)` with the hash if you don't have the numeric ID.
+
+
+
+ The `env` parameter expects Docker flag format as a single string, not key=value pairs or a dictionary:
+
+ ```python
+ # Correct
+ env="-e VAR1=value1 -e VAR2=value2 -p 8000:8000"
+
+ # Wrong -- missing -e prefix
+ env="VAR1=value1 VAR2=value2"
+
+ # Wrong -- not a dict
+ env={"VAR1": "value1"}
+ ```
+
+ Port mappings are also specified in this string using `-p`:
+ ```python
+ env="-e MY_VAR=hello -p 8080:8080 -p 8081:8081/udp"
+ ```
+
+
+
+ When you specify both `template_hash` and `image` in `create_instance()`, the `image` parameter overrides the template's image. If you want to use the template's image, omit the `image` parameter entirely.
+
+
+
+ The `volume_info` field stored in templates is a **UI hint only**. To actually mount a volume, you must pass volume information in the instance creation request. Use the API directly or the CLI volume flags for this:
+
+ ```bash
+ # Link an existing volume (CLI)
+ vastai create instance 12345678 --template_hash abc123 \
+ --link-volume 12345 --mount-path /workspace
+
+ # Create a new volume (CLI)
+ vastai create instance 12345678 --template_hash abc123 \
+ --create-volume 28908979 --volume-size 10 --mount-path /workspace
+ ```
+
+ See the [API templates page](/api-reference/creating-and-using-templates-with-api#create-instance-with-volume) for the JSON `volume_info` structure.
+
+
+
+ This is expected behavior. The `hash_id` is content-based, so any edit produces a new hash. Always capture the new `hash_id` from the `update_template()` return value or search for your template again before referencing it.
+
+