From c727ee38db635ca3fb6fbb94d42141ba14d6af65 Mon Sep 17 00:00:00 2001 From: v1-backend-alpha Date: Sat, 17 Oct 2026 01:02:22 +0000 Subject: [PATCH] =?UTF-8?q?docs(HOST-1091):=20machine=20overrides=20?= =?UTF-8?q?=E2=80=94=20API=20reference,=20CLI/SDK=20reference,=20host=20lo?= =?UTF-8?q?cation=20guide?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - api-reference: set/clear machine override endpoints (POST /api/v0/machines/overrides/{set,clear}/), openapi.yaml rebuilt - cli + sdk reference: set-machine-override / clear-machine-override (vast-cli HOST-1091-machine-overrides-cli) - host guide: Fix your machine's listed location Co-Authored-By: Claude Opus 5.5 (1M context) --- api-reference/openapi.yaml | 279 ++++++++++++++++++ .../openapi/yaml/clear_machine_override.yaml | 150 ++++++++++ .../openapi/yaml/set_machine_override.yaml | 159 ++++++++++ cli/reference/clear-machine-override.mdx | 9 + cli/reference/set-machine-override.mdx | 9 + docs.json | 5 + host/machine-location.mdx | 64 ++++ .../reference/clear-machine-override.mdx | 8 + sdk/python/reference/set-machine-override.mdx | 8 + snippets/host/cli/clear-machine-override.mdx | 51 ++++ snippets/host/cli/set-machine-override.mdx | 64 ++++ snippets/host/sdk/clear-machine-override.mdx | 41 +++ snippets/host/sdk/set-machine-override.mdx | 45 +++ 13 files changed, 892 insertions(+) create mode 100644 api-reference/openapi/yaml/clear_machine_override.yaml create mode 100644 api-reference/openapi/yaml/set_machine_override.yaml create mode 100644 cli/reference/clear-machine-override.mdx create mode 100644 cli/reference/set-machine-override.mdx create mode 100644 host/machine-location.mdx create mode 100644 sdk/python/reference/clear-machine-override.mdx create mode 100644 sdk/python/reference/set-machine-override.mdx create mode 100644 snippets/host/cli/clear-machine-override.mdx create mode 100644 snippets/host/cli/set-machine-override.mdx create mode 100644 snippets/host/sdk/clear-machine-override.mdx create mode 100644 snippets/host/sdk/set-machine-override.mdx diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index ef80d560..1d8cf97a 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -670,6 +670,142 @@ paths: tags: - Machines operationId: cleanupMachine + /api/v0/machines/overrides/clear: + post: + summary: clear machine override + operationId: clearMachineOverride + description: 'Removes a value set with `set machine override`. For `geolocation` + the detected location is restored + + immediately; `inet_up` and `inet_down` return to the latest speed test. A + value set by an admin can only + + be cleared by an admin. + + + CLI Usage: `vastai clear machine-override [--ids 1,2] [--host-id ID] + [--reason TEXT]`' + security: + - BearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - field + properties: + field: + type: string + enum: + - geolocation + - inet_up + - inet_down + description: The machine field. `geolocation` can be set by the + machine's host; `inet_up` and `inet_down` (Mbps) need an admin. + machine_ids: + type: array + items: + type: integer + minItems: 1 + description: The machines to change. Omit to apply to all of the + host's machines. IDs that are not the host's are skipped and listed + in `skipped_machine_ids`. + host_id: + type: integer + description: The host whose machines to change. Defaults to the + caller; another host's machines need an admin. + reason: + type: string + maxLength: 500 + description: Why the value is changed. Required when an admin makes + the change; recorded in the audit log. + example: + field: geolocation + machine_ids: + - 12345 + responses: + '200': + description: Success response + content: + application/json: + schema: + type: object + properties: + success: + type: boolean + example: true + field: + type: string + example: geolocation + machine_ids: + type: array + items: + type: integer + description: Machines whose override was removed. + example: + - 12345 + target_machine_ids: + type: array + items: + type: integer + description: All machines the request targeted. + restored: + type: object + additionalProperties: true + description: The automatic value restored per machine ID, where + it could be re-derived now (geolocation). + locked_machine_ids: + type: array + items: + type: integer + description: Machines whose value was set by Vast support; a host + cannot change or clear it. + skipped_machine_ids: + type: array + items: + type: integer + description: Requested IDs that are not the host's machines. + msg: + type: string + example: Cleared the geolocation override on 1 machine(s). + '400': + description: "Bad Request \u2014 an unknown field, a value of the wrong\ + \ type, a geolocation that is not \"Region, CC\", an admin write without\ + \ `reason`, or no matching machines." + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: "Forbidden \u2014 another host's machines, or `inet_up`/`inet_down`,\ + \ need an admin." + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '409': + description: "Conflict \u2014 the machines' overrides changed while the\ + \ request ran; retry." + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '429': + description: Too Many Requests + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + tags: + - Machines /api/v0/auth/apikeys: post: summary: create api-key @@ -7202,6 +7338,149 @@ paths: tags: - Machines operationId: setDefjob + /api/v0/machines/overrides/set: + post: + summary: set machine override + operationId: setMachineOverride + description: "Sets a manual value for a machine field. A machine's location\ + \ normally comes from an IP lookup of its\nconnection, and its bandwidth from\ + \ speed tests; an override replaces that value everywhere it is shown\nand\ + \ searched, and automatic updates keep it until it is cleared.\n\n- `geolocation`:\ + \ the machine's host can set it, e.g. when the machine connects through a\ + \ VPN or proxy\n and is listed in the wrong place. The value is `\"Region,\ + \ CC\"` for the US, China, Canada and Russia\n (e.g. `\"Guangdong, CN\"`)\ + \ or `\"Country, CC\"` elsewhere (e.g. `\"Germany, DE\"`).\n- `inet_up` /\ + \ `inet_down`: upload and download bandwidth in Mbps; admins only.\n\nA value\ + \ an admin sets is locked: the host cannot change or clear it. Every change\ + \ is recorded in the\naudit log.\n\nCLI Usage: `vastai set machine-override\ + \ [--ids 1,2] [--host-id ID] [--reason TEXT]`" + security: + - BearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - field + - value + properties: + field: + type: string + enum: + - geolocation + - inet_up + - inet_down + description: The machine field. `geolocation` can be set by the + machine's host; `inet_up` and `inet_down` (Mbps) need an admin. + machine_ids: + type: array + items: + type: integer + minItems: 1 + description: The machines to change. Omit to apply to all of the + host's machines. IDs that are not the host's are skipped and listed + in `skipped_machine_ids`. + host_id: + type: integer + description: The host whose machines to change. Defaults to the + caller; another host's machines need an admin. + reason: + type: string + maxLength: 500 + description: Why the value is changed. Required when an admin makes + the change; recorded in the audit log. + value: + oneOf: + - type: string + - type: number + description: The value. A string `"Region, CC"` or `"Country, CC"` + for `geolocation`; a number of Mbps (greater than 0, below 100000) + for `inet_up`/`inet_down`. + example: Guangdong, CN + example: + field: geolocation + value: Guangdong, CN + machine_ids: + - 12345 + - 12346 + responses: + '200': + description: Success response + content: + application/json: + schema: + type: object + properties: + success: + type: boolean + example: true + field: + type: string + example: geolocation + value: + description: The stored value, normalized (e.g. a country name + filled in from its code). + example: Guangdong, CN + machine_ids: + type: array + items: + type: integer + description: Machines the value was set on. + example: + - 12345 + - 12346 + locked_machine_ids: + type: array + items: + type: integer + description: Machines whose value was set by Vast support; a host + cannot change or clear it. + skipped_machine_ids: + type: array + items: + type: integer + description: Requested IDs that are not the host's machines. + msg: + type: string + example: Set geolocation to 'Guangdong, CN' on 2 machine(s). + '400': + description: "Bad Request \u2014 an unknown field, a value of the wrong\ + \ type, a geolocation that is not \"Region, CC\", an admin write without\ + \ `reason`, or no matching machines." + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: "Forbidden \u2014 another host's machines, or `inet_up`/`inet_down`,\ + \ need an admin." + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '409': + description: "Conflict \u2014 the machines' overrides changed while the\ + \ request ran; retry." + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '429': + description: Too Many Requests + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + tags: + - Machines /api/v0/machines/{machine_id}/minbid: put: summary: set min-bid diff --git a/api-reference/openapi/yaml/clear_machine_override.yaml b/api-reference/openapi/yaml/clear_machine_override.yaml new file mode 100644 index 00000000..b2af74f2 --- /dev/null +++ b/api-reference/openapi/yaml/clear_machine_override.yaml @@ -0,0 +1,150 @@ +openapi: 3.0.0 +info: + title: Vast.ai Machine Overrides API + description: Remove a manual machine field value so automatic detection takes over again. + version: 1.0.0 +servers: +- url: https://console.vast.ai + description: Production server +paths: + /api/v0/machines/overrides/clear/: + post: + summary: clear machine override + operationId: clearMachineOverride + description: | + Removes a value set with `set machine override`. For `geolocation` the detected location is restored + immediately; `inet_up` and `inet_down` return to the latest speed test. A value set by an admin can only + be cleared by an admin. + + CLI Usage: `vastai clear machine-override [--ids 1,2] [--host-id ID] [--reason TEXT]` + security: + - BearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [field] + properties: + field: + type: string + enum: [geolocation, inet_up, inet_down] + description: The machine field. `geolocation` can be set by the machine's host; `inet_up` and `inet_down` (Mbps) need an admin. + machine_ids: + type: array + items: + type: integer + minItems: 1 + description: The machines to change. Omit to apply to all of the host's machines. IDs that are not the host's are skipped and listed in `skipped_machine_ids`. + host_id: + type: integer + description: The host whose machines to change. Defaults to the caller; another host's machines need an admin. + reason: + type: string + maxLength: 500 + description: Why the value is changed. Required when an admin makes the change; recorded in the audit log. + example: + field: geolocation + machine_ids: [12345] + responses: + '200': + description: Success response + content: + application/json: + schema: + type: object + properties: + success: + type: boolean + example: true + field: + type: string + example: geolocation + machine_ids: + type: array + items: + type: integer + description: Machines whose override was removed. + example: [12345] + target_machine_ids: + type: array + items: + type: integer + description: All machines the request targeted. + restored: + type: object + additionalProperties: true + description: The automatic value restored per machine ID, where it could be re-derived now (geolocation). + locked_machine_ids: + type: array + items: + type: integer + description: Machines whose value was set by Vast support; a host cannot change or clear it. + skipped_machine_ids: + type: array + items: + type: integer + description: Requested IDs that are not the host's machines. + msg: + type: string + example: Cleared the geolocation override on 1 machine(s). + '400': + description: Bad Request — an unknown field, a value of the wrong type, a geolocation that is not "Region, CC", an admin write without `reason`, or no matching machines. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: Forbidden — another host's machines, or `inet_up`/`inet_down`, need an admin. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '409': + description: Conflict — the machines' overrides changed while the request ran; retry. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '429': + description: Too Many Requests + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + tags: + - Machines +components: + securitySchemes: + BearerAuth: + type: http + scheme: bearer + description: API key must be provided in the Authorization header + schemas: + Error: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + msg: + type: string +x-rate-limit: + threshold: 2 + per: request + description: Maximum request frequency per IP address for this endpoint +x-cli-commands: +- name: clear machine-override + description: Remove a manual machine field value so automatic detection takes over. + endpoint: /api/v0/machines/overrides/clear/ + method: post + example: vastai clear machine-override geolocation --ids 12345 diff --git a/api-reference/openapi/yaml/set_machine_override.yaml b/api-reference/openapi/yaml/set_machine_override.yaml new file mode 100644 index 00000000..ca30dcd4 --- /dev/null +++ b/api-reference/openapi/yaml/set_machine_override.yaml @@ -0,0 +1,159 @@ +openapi: 3.0.0 +info: + title: Vast.ai Machine Overrides API + description: Pin a machine field to a manual value that automatic updates keep until it is cleared. + version: 1.0.0 +servers: +- url: https://console.vast.ai + description: Production server +paths: + /api/v0/machines/overrides/set/: + post: + summary: set machine override + operationId: setMachineOverride + description: | + Sets a manual value for a machine field. A machine's location normally comes from an IP lookup of its + connection, and its bandwidth from speed tests; an override replaces that value everywhere it is shown + and searched, and automatic updates keep it until it is cleared. + + - `geolocation`: the machine's host can set it, e.g. when the machine connects through a VPN or proxy + and is listed in the wrong place. The value is `"Region, CC"` for the US, China, Canada and Russia + (e.g. `"Guangdong, CN"`) or `"Country, CC"` elsewhere (e.g. `"Germany, DE"`). + - `inet_up` / `inet_down`: upload and download bandwidth in Mbps; admins only. + + A value an admin sets is locked: the host cannot change or clear it. Every change is recorded in the + audit log. + + CLI Usage: `vastai set machine-override [--ids 1,2] [--host-id ID] [--reason TEXT]` + security: + - BearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [field, value] + properties: + field: + type: string + enum: [geolocation, inet_up, inet_down] + description: The machine field. `geolocation` can be set by the machine's host; `inet_up` and `inet_down` (Mbps) need an admin. + machine_ids: + type: array + items: + type: integer + minItems: 1 + description: The machines to change. Omit to apply to all of the host's machines. IDs that are not the host's are skipped and listed in `skipped_machine_ids`. + host_id: + type: integer + description: The host whose machines to change. Defaults to the caller; another host's machines need an admin. + reason: + type: string + maxLength: 500 + description: Why the value is changed. Required when an admin makes the change; recorded in the audit log. + value: + oneOf: + - type: string + - type: number + description: The value. A string `"Region, CC"` or `"Country, CC"` for `geolocation`; a number of Mbps (greater than 0, below 100000) for `inet_up`/`inet_down`. + example: Guangdong, CN + example: + field: geolocation + value: Guangdong, CN + machine_ids: [12345, 12346] + responses: + '200': + description: Success response + content: + application/json: + schema: + type: object + properties: + success: + type: boolean + example: true + field: + type: string + example: geolocation + value: + description: The stored value, normalized (e.g. a country name filled in from its code). + example: Guangdong, CN + machine_ids: + type: array + items: + type: integer + description: Machines the value was set on. + example: [12345, 12346] + locked_machine_ids: + type: array + items: + type: integer + description: Machines whose value was set by Vast support; a host cannot change or clear it. + skipped_machine_ids: + type: array + items: + type: integer + description: Requested IDs that are not the host's machines. + msg: + type: string + example: Set geolocation to 'Guangdong, CN' on 2 machine(s). + '400': + description: Bad Request — an unknown field, a value of the wrong type, a geolocation that is not "Region, CC", an admin write without `reason`, or no matching machines. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: Forbidden — another host's machines, or `inet_up`/`inet_down`, need an admin. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '409': + description: Conflict — the machines' overrides changed while the request ran; retry. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '429': + description: Too Many Requests + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + tags: + - Machines +components: + securitySchemes: + BearerAuth: + type: http + scheme: bearer + description: API key must be provided in the Authorization header + schemas: + Error: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + msg: + type: string +x-rate-limit: + threshold: 2 + per: request + description: Maximum request frequency per IP address for this endpoint +x-cli-commands: +- name: set machine-override + description: Pin a machine field (location, bandwidth) to a manual value. + endpoint: /api/v0/machines/overrides/set/ + method: post + example: vastai set machine-override geolocation "Guangdong, CN" --ids 12345 diff --git a/cli/reference/clear-machine-override.mdx b/cli/reference/clear-machine-override.mdx new file mode 100644 index 00000000..acff06e5 --- /dev/null +++ b/cli/reference/clear-machine-override.mdx @@ -0,0 +1,9 @@ +--- +title: "vastai clear machine-override" +sidebarTitle: "clear machine-override" +description: "Host command" +--- + +import ClearMachineOverrideCLI from '/snippets/host/cli/clear-machine-override.mdx'; + + diff --git a/cli/reference/set-machine-override.mdx b/cli/reference/set-machine-override.mdx new file mode 100644 index 00000000..2d5e168f --- /dev/null +++ b/cli/reference/set-machine-override.mdx @@ -0,0 +1,9 @@ +--- +title: "vastai set machine-override" +sidebarTitle: "set machine-override" +description: "Host command" +--- + +import SetMachineOverrideCLI from '/snippets/host/cli/set-machine-override.mdx'; + + diff --git a/docs.json b/docs.json index e616acf0..a9768eb1 100644 --- a/docs.json +++ b/docs.json @@ -363,6 +363,8 @@ "cli/reference/set-defjob", "cli/reference/remove-defjob", "cli/reference/set-min-bid", + "cli/reference/set-machine-override", + "cli/reference/clear-machine-override", "cli/reference/schedule-maint", "cli/reference/cancel-maint", "cli/reference/show-maints", @@ -567,6 +569,8 @@ "sdk/python/reference/set-defjob", "sdk/python/reference/remove-defjob", "sdk/python/reference/set-min-bid", + "sdk/python/reference/set-machine-override", + "sdk/python/reference/clear-machine-override", "sdk/python/reference/schedule-maint", "sdk/python/reference/cancel-maint", "sdk/python/reference/show-maints", @@ -629,6 +633,7 @@ "host/verification-stages", "host/how-to-self-test", "host/using-your-own-machine", + "host/machine-location", "host/notifications", "host/machine-metrics", "host/market-metrics", diff --git a/host/machine-location.mdx b/host/machine-location.mdx new file mode 100644 index 00000000..847fea49 --- /dev/null +++ b/host/machine-location.mdx @@ -0,0 +1,64 @@ +--- +title: "Fix Your Machine's Listed Location" +description: "Set the location renters see for your machine when it connects through a VPN or proxy and is listed in the wrong place." +--- + +Vast lists each machine at the location of the IP address it connects from. If your machine +reaches the internet through a VPN, a proxy or a tunnel, that address belongs to the exit +point, not to your machine, and renters see the wrong country or region. + +You can set the location yourself. The value you set is shown to renters, used by location +filters in search, and kept until you clear it: the automatic lookup no longer changes it. + + +Setting the location is currently done from the [CLI](/cli/reference/set-machine-override) +or the [API](/api-reference/machines/set-machine-override). Set the place where the machine +physically is: an incorrect location may be corrected by Vast support, and a location set +by support can't be changed from your account. + + +--- + +## Set the location + +The location is written as `"Region, CC"` for machines in the United States, China, Canada +and Russia, and as `"Country, CC"` everywhere else, where `CC` is the two-letter country code: + +| Machine in | Value | +| --- | --- | +| Guangdong, China | `"Guangdong, CN"` | +| California, United States | `"California, US"` | +| Germany | `"Germany, DE"` | + +Set it on one or more machines: + +```bash +vastai set machine-override geolocation "Guangdong, CN" --ids 12345,12346 +``` + +Leave out `--ids` to set it on all of your machines: + +```bash +vastai set machine-override geolocation "Guangdong, CN" +``` + +The new location appears on your machines and their offers right away. + +## Go back to automatic detection + +Clearing the value restores the location detected from the machine's IP address: + +```bash +vastai clear machine-override geolocation --ids 12345 +``` + +## If the location can't be changed + +If the command reports that a machine has a value set by Vast support, the location was +corrected by support and can't be changed from your account. Contact support if it is wrong. + +## Related + +- [`vastai set machine-override`](/cli/reference/set-machine-override) and + [`vastai clear machine-override`](/cli/reference/clear-machine-override) +- [Set machine override](/api-reference/machines/set-machine-override) in the API reference diff --git a/sdk/python/reference/clear-machine-override.mdx b/sdk/python/reference/clear-machine-override.mdx new file mode 100644 index 00000000..1f6d7ff2 --- /dev/null +++ b/sdk/python/reference/clear-machine-override.mdx @@ -0,0 +1,8 @@ +--- +title: "VastAI.clear_machine_override" +sidebarTitle: "clear_machine_override" +--- + +import ClearMachineOverrideSDK from '/snippets/host/sdk/clear-machine-override.mdx'; + + diff --git a/sdk/python/reference/set-machine-override.mdx b/sdk/python/reference/set-machine-override.mdx new file mode 100644 index 00000000..38d73bdf --- /dev/null +++ b/sdk/python/reference/set-machine-override.mdx @@ -0,0 +1,8 @@ +--- +title: "VastAI.set_machine_override" +sidebarTitle: "set_machine_override" +--- + +import SetMachineOverrideSDK from '/snippets/host/sdk/set-machine-override.mdx'; + + diff --git a/snippets/host/cli/clear-machine-override.mdx b/snippets/host/cli/clear-machine-override.mdx new file mode 100644 index 00000000..9aad5297 --- /dev/null +++ b/snippets/host/cli/clear-machine-override.mdx @@ -0,0 +1,51 @@ +Remove a manual machine field value so automatic detection takes over + +This is a **host** command, used for managing machines you are renting out on Vast.ai. + +## Usage + +```bash +vastai clear machine-override FIELD [--ids IDS] [--host-id HOST_ID] [--reason REASON] +``` + +## Arguments + + + field whose override to remove: `geolocation`, `inet_up` or `inet_down` + + +## Options + + + comma-separated machine ids (default: all of the host's machines) + + + + host whose machines to clear (admins only) + + + + why the override is cleared (required for an admin) + + +## Description + +Removes a value set with [`vastai set machine-override`](/cli/reference/set-machine-override). For `geolocation` the detected location is restored right away; bandwidth returns to the latest speed test. A value set by Vast support can only be cleared by support. + +## Examples + +```bash +vastai clear machine-override geolocation --ids 12345 +``` + +## 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/snippets/host/cli/set-machine-override.mdx b/snippets/host/cli/set-machine-override.mdx new file mode 100644 index 00000000..80f44fac --- /dev/null +++ b/snippets/host/cli/set-machine-override.mdx @@ -0,0 +1,64 @@ +Pin a machine field (location, bandwidth) to a manual value + +This is a **host** command, used for managing machines you are renting out on Vast.ai. + +## Usage + +```bash +vastai set machine-override FIELD VALUE [--ids IDS] [--host-id HOST_ID] [--reason REASON] +``` + +## Arguments + + + field to override: `geolocation`, `inet_up` or `inet_down` + + + + the value: `"Region, CC"` for geolocation (e.g. `"Guangdong, CN"`), Mbps for inet_up/inet_down + + +## Options + + + comma-separated machine ids (default: all of the host's machines) + + + + host whose machines to set (admins only) + + + + why the value is overridden (required for an admin override) + + +## Description + +Sets a manual value for a machine field. Automatic updates (the IP location lookup, speed tests) keep it until it is cleared with [`vastai clear machine-override`](/cli/reference/clear-machine-override). + +| Field | Who can set it | Value | +| --- | --- | --- | +| `geolocation` | the machine's host, or an admin | `"Region, CC"` in the US, China, Canada and Russia (e.g. `"Guangdong, CN"`), otherwise `"Country, CC"` (e.g. `"Germany, DE"`) | +| `inet_up` | admins only | upload bandwidth in Mbps | +| `inet_down` | admins only | download bandwidth in Mbps | + +A value set by an admin is locked: the host cannot change or clear it. See [Fix your machine's listed location](/host/machine-location). + +## Examples + +```bash +vastai set machine-override geolocation "Guangdong, CN" --ids 12345,12346 +vastai set machine-override geolocation "Germany, DE" +``` + +## 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/snippets/host/sdk/clear-machine-override.mdx b/snippets/host/sdk/clear-machine-override.mdx new file mode 100644 index 00000000..85737018 --- /dev/null +++ b/snippets/host/sdk/clear-machine-override.mdx @@ -0,0 +1,41 @@ +Remove a manual machine field value so automatic detection takes over again. + +This is a **host** method, used for managing machines you are renting out on Vast.ai. + +## Signature + +```python +VastAI.clear_machine_override(field: str, machine_ids: Optional[List[int]] = None, host_id: Optional[int] = None, reason: Optional[str] = None) -> dict +``` + +## Parameters + + + `"geolocation"`, `"inet_up"` or `"inet_down"` + + + + machines to clear; omitted means all of the host's machines + + + + host whose machines to clear (admins only; defaults to the caller) + + + + why the override is cleared; required when an admin clears it + + +## Returns + +`dict`: `machine_ids` cleared, `restored` (the detected value restored per machine, for geolocation) and `msg`. + +## Example + +```python +from vastai import VastAI + +client = VastAI(api_key="YOUR_API_KEY") +result = client.clear_machine_override("geolocation", machine_ids=[12345]) +print(result["msg"]) +``` diff --git a/snippets/host/sdk/set-machine-override.mdx b/snippets/host/sdk/set-machine-override.mdx new file mode 100644 index 00000000..96317810 --- /dev/null +++ b/snippets/host/sdk/set-machine-override.mdx @@ -0,0 +1,45 @@ +Pin a machine field (geolocation, inet_up, inet_down) to a manual value until cleared. + +This is a **host** method, used for managing machines you are renting out on Vast.ai. + +## Signature + +```python +VastAI.set_machine_override(field: str, value, machine_ids: Optional[List[int]] = None, host_id: Optional[int] = None, reason: Optional[str] = None) -> dict +``` + +## Parameters + + + `"geolocation"` (the machine's host or an admin), or `"inet_up"` / `"inet_down"` in Mbps (admins only) + + + + `"Region, CC"` or `"Country, CC"` for geolocation (e.g. `"Guangdong, CN"`); a number of Mbps for bandwidth + + + + machines to set; omitted means all of the host's machines + + + + host whose machines to set (admins only; defaults to the caller) + + + + why the value is overridden; required when an admin sets it + + +## Returns + +`dict`: `machine_ids` set, `locked_machine_ids` (values set by Vast support, which a host cannot change), `skipped_machine_ids` (IDs that are not the host's) and `msg`. + +## Example + +```python +from vastai import VastAI + +client = VastAI(api_key="YOUR_API_KEY") +result = client.set_machine_override("geolocation", "Guangdong, CN", machine_ids=[12345]) +print(result["msg"]) +```