voltagegpu-cli 1.3.1__tar.gz → 2.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/CHANGELOG.md +153 -122
  2. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/PKG-INFO +105 -5
  3. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/README.md +284 -184
  4. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/pyproject.toml +90 -89
  5. voltagegpu_cli-2.0.0/tests/fixtures/ark-milan.pem +37 -0
  6. voltagegpu_cli-2.0.0/tests/fixtures/bundle.json +822 -0
  7. voltagegpu_cli-2.0.0/tests/fixtures/manifest.json +11 -0
  8. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/tests/test_cli.py +261 -261
  9. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/tests/test_cli_account.py +156 -141
  10. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/tests/test_config.py +11 -0
  11. voltagegpu_cli-2.0.0/tests/test_vgpu_attest.py +252 -0
  12. voltagegpu_cli-2.0.0/tests/test_vgpu_cli.py +465 -0
  13. voltagegpu_cli-2.0.0/tests/test_vgpu_mcp.py +205 -0
  14. voltagegpu_cli-2.0.0/tests/test_vgpu_remote.py +65 -0
  15. voltagegpu_cli-2.0.0/tests/test_vgpu_ttl.py +61 -0
  16. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/volt/__init__.py +5 -5
  17. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/volt/cli/cmd_account.py +4 -1
  18. voltagegpu_cli-2.0.0/volt/cli/vgpu.py +475 -0
  19. voltagegpu_cli-2.0.0/volt/mcp/__init__.py +1 -0
  20. voltagegpu_cli-2.0.0/volt/mcp/server.py +344 -0
  21. voltagegpu_cli-2.0.0/volt/sdk/attest.py +296 -0
  22. voltagegpu_cli-2.0.0/volt/sdk/catalog.py +163 -0
  23. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/volt/sdk/client.py +240 -236
  24. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/volt/sdk/config.py +2 -1
  25. voltagegpu_cli-2.0.0/volt/sdk/fleet.py +220 -0
  26. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/volt/sdk/models.py +336 -332
  27. voltagegpu_cli-2.0.0/volt/sdk/remote.py +129 -0
  28. voltagegpu_cli-2.0.0/volt/sdk/scripts/snp-proof-in-the-vm.sh +216 -0
  29. voltagegpu_cli-2.0.0/volt/sdk/scripts/two-proofs-in-the-vm.sh +51 -0
  30. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/volt/sdk/ssh.py +157 -157
  31. voltagegpu_cli-2.0.0/volt/sdk/ttl.py +104 -0
  32. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/.gitignore +0 -0
  33. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/LICENSE +0 -0
  34. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/examples/deploy_standard_pod.py +0 -0
  35. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/tests/__init__.py +0 -0
  36. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/tests/conftest.py +0 -0
  37. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/tests/test_client.py +0 -0
  38. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/tests/test_hardening.py +0 -0
  39. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/tests/test_live.py +0 -0
  40. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/tests/test_models.py +0 -0
  41. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/tests/test_package.py +0 -0
  42. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/tests/test_ssh.py +0 -0
  43. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/volt/__main__.py +0 -0
  44. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/volt/cli/__init__.py +0 -0
  45. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/volt/cli/cmd_deploy.py +0 -0
  46. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/volt/cli/cmd_machines.py +0 -0
  47. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/volt/cli/cmd_misc.py +0 -0
  48. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/volt/cli/cmd_pods.py +0 -0
  49. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/volt/cli/main.py +0 -0
  50. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/volt/cli/output.py +0 -0
  51. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/volt/cli/state.py +0 -0
  52. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/volt/sdk/__init__.py +0 -0
  53. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.0}/volt/sdk/errors.py +0 -0
@@ -1,122 +1,153 @@
1
- # Changelog
2
-
3
- All notable changes to `voltagegpu-cli` are documented here. The format follows
4
- [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
5
- [Semantic Versioning](https://semver.org/).
6
-
7
- ## [1.3.1] - 2026-10-10
8
-
9
- Security hardening after an independent review of 1.3.0. Upgrade recommended.
10
-
11
- ### Security
12
- - The SSH command returned by the API is only ever displayed in its validated,
13
- rebuilt form (`ssh -p PORT user@host`). A command of any other form is
14
- neither shown nor run, so a tampered answer cannot end up copied into a
15
- shell from `pods show`, `pods wait` or `deploy --wait`.
16
- - Server text (machine names, locations, error messages, ids) can no longer
17
- inject terminal escape sequences or rich markup: control characters are
18
- stripped and the text is printed literally. Before, an odd string could also
19
- crash the CLI right after a deploy.
20
- - `voltagegpu verify` calls voltage-verify in-process instead of
21
- `python -m voltage_verify`, which put the current directory first on the
22
- module path (a `voltage_verify.py` next to a downloaded bundle would run).
23
- - `voltagegpu ssh` looks for `ssh` on PATH only, never in the current
24
- directory (Windows `shutil.which` checks it first), and never runs a
25
- `.bat`/`.cmd` script.
26
- - The one-time sudo password of a Confidential VM is printed exactly as
27
- received (no markup or emoji parsing could alter it).
28
- - The API key is only sent to `voltagegpu.com` hosts (or localhost) unless
29
- `VOLT_ALLOW_CUSTOM_BASE_URL=1` is set.
30
- - A malformed `~/.volt/config.ini` no longer prints its content (which may be
31
- the key) in an error; an existing file is set to 0600 before the key is
32
- written.
33
-
34
- ### Changed
35
- - `deploy standard --cheapest --yes` requires `--max-price`, so a script never
36
- rents an expensive machine by surprise.
37
- - If the deploy request gets no answer, the CLI says the deploy may have gone
38
- through and to check `voltagegpu pods list`, instead of suggesting a retry.
39
- - A warning is printed if the hourly price rose between the listing and the
40
- deploy.
41
-
42
- ## [1.3.0] - 2026-10-10
43
-
44
- Realigns the CLI with the product as it is today: Confidential VMs (Intel TDX)
45
- and standard pods, both deployable from the public API. Every command was run
46
- against the production API before release, including a paid deploy, SSH and
47
- release of a standard pod.
48
-
49
- ### Added
50
- - `voltagegpu` command (the `volt` command still works, same program).
51
- - `voltagegpu machines [--standard | --confidential] [--gpu] [--max-price] [--min-gpus] [--json]`:
52
- standard machines and Confidential VM tiers with the hourly price charged.
53
- - `voltagegpu deploy standard --machine ID | --cheapest`: deploy a standard pod
54
- (no enclave), with `--template`, `--ssh-key`, `--jupyter`, `--ports`,
55
- `--auto-terminate`, `--wait`. Asks for confirmation before charging; scripts
56
- pass `--yes`.
57
- - `voltagegpu deploy confidential --tier TIER`: deploy a Confidential VM, with
58
- `--hardstop`, repeatable `--port 8000[/tcp|udp]` and `--wait`. Prints the
59
- one-time sudo password and the in-VM attestation commands.
60
- - `voltagegpu templates`: images available for standard pods.
61
- - `voltagegpu pods wait POD_ID`: wait until SSH is ready.
62
- - `voltagegpu ssh POD_ID [-- COMMAND]`: run ssh directly (or `--print` it).
63
- - `voltagegpu balance`: balance and running pods (`GET /api/volt/balance`).
64
- - `voltagegpu login` / `logout`: store the API key in `~/.volt/config.ini`,
65
- created with mode 0600, after checking that the API accepts it.
66
- - `voltagegpu verify ...`: verifies a Confidential VM attestation bundle by
67
- running voltage-verify (`pip install "voltagegpu-cli[verify]"`).
68
- - `VOLTAGEGPU_API_KEY` is accepted as an alias of `VOLT_API_KEY`.
69
- - SDK: `list_machines`, `list_templates`, `deploy_standard`,
70
- `deploy_confidential`, `release_pod`, `wait_until_reachable`, `get_balance`;
71
- typed immutable models; `parse_ssh_command`.
72
- - Test suite (unit, CLI and opt-in live checks) and a CI workflow.
73
-
74
- ### Changed
75
- - `pods stop` now releases the pod (`DELETE /api/volt/pods/:id`) and prints
76
- the refunded unused prepaid time. Standard pods cannot be paused, so the old
77
- `POST .../stop` call failed for them. `pods delete` and `pods get` remain as
78
- aliases of `pods stop` and `pods show`.
79
- - Errors show the API's own message (for example "Insufficient balance. One
80
- hour costs $0.59...") instead of a raw HTTP exception, and never a traceback
81
- unless `VOLT_DEBUG=1`.
82
- - Python 3.10 or newer is required (3.9 reached end of life in October 2025).
83
-
84
- ### Removed
85
- - `volt cc inventory`, `volt cc deploy` and `volt templates get`: Confidential
86
- containers were retired on 2026-10-01. The commands now print how to deploy a
87
- Confidential VM instead.
88
- - `volt account info`, which called an endpoint that does not exist.
89
-
90
- ### Fixed
91
- - `ssh-keys add` sent `publicKey`; the API expects `public_key`, so every key
92
- upload failed with HTTP 400. It also refuses a private key file now.
93
- - `account balance` called a dashboard-only endpoint and always failed with
94
- HTTP 401.
95
- - `cc inventory` called a dashboard-only endpoint and reported "no GPUs
96
- available" instead of an error.
97
- - Pod ids are validated before they are put into a URL path.
98
-
99
- ### Security
100
- - The SSH command returned by the API is parsed into user, host and port, each
101
- checked against a strict pattern, and ssh is started from a list of
102
- arguments, never through a shell. A tampered answer such as
103
- `ssh -o ProxyCommand=...` is refused.
104
- - Plain `http://` base URLs are refused (except localhost), redirects are never
105
- followed, and TLS certificates are always verified, so the API key cannot be
106
- sent in clear or to another host.
107
- - The API key is never printed (only `volt_****` and its last four
108
- characters), including in `repr()` of the configuration.
109
-
110
- ## [1.2.1] - 2026-04-11
111
-
112
- - Confidential container templates (`volt templates`), the machines list and
113
- `volt cc deploy --template`.
114
-
115
- ## [1.2.0] - 2026-04-11
116
-
117
- - `volt cc` command group for Confidential containers; default API base URL
118
- `https://api.voltagegpu.com/api`; JSON output on list commands.
119
-
120
- ## [1.1.0] and [1.0.0]
121
-
122
- - First releases of the CLI and Python SDK.
1
+ # Changelog
2
+
3
+ All notable changes to `voltagegpu-cli` are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
5
+ [Semantic Versioning](https://semver.org/).
6
+
7
+ ## [2.0.0] - 2026-10-27
8
+
9
+ ### Added
10
+ - `vgpu`, a second command for scripts and AI agents: `ls`, `up`, `ps`,
11
+ `exec` (with `-d`), `scp`, `rm`, `attest`, `whoami`. One catalogue for
12
+ Confidential VMs (Intel TDX), Confidential CPU (AMD SEV-SNP), standard GPU
13
+ pods, dedicated machines and sandboxes, cheapest first.
14
+ - `--ttl` on every `vgpu up`, translated to the auto-stop of each product and
15
+ checked against its bounds before anything is sent.
16
+ - `vgpu attest`: challenge drawn locally, embedded proof scripts pinned by
17
+ SHA-256, archive extracted safely and verified locally. For Confidential
18
+ CPU the SEV-SNP report is requested at `--vmpl` (0 by default), and its VMPL
19
+ field must be the level requested (VMPL 1 is no longer required: it was
20
+ snpguest's default request, not the guest's level).
21
+ - `vgpu mcp`, a local MCP server over stdio with the same tools and guards
22
+ (`up` needs `ttl` and `max_hourly_price`, `rm` needs `confirm`), plus
23
+ `inference` on the OpenAI-compatible API with a `vgpu_` key.
24
+ - Documented exit codes, including 6 for HTTP 402 (`API_KEY_BUDGET_EXCEEDED`)
25
+ and 4 for `API_KEY_SCOPE_MISSING`.
26
+ - `vgpu up --ssh-key-id` (`ssh_key_ids` in `vgpu mcp`) on a standard GPU too:
27
+ one key id, needed when the account has several SSH keys. Without it, the
28
+ API's 400 becomes a clear message (exit 2, `SSH_KEY_ID_REQUIRED`).
29
+
30
+ ### Changed
31
+ - `voltagegpu balance` no longer shows `$0.00` when the key cannot read the
32
+ balance (agent key without the billing scope): it says the balance is hidden.
33
+ - A `vgpu_` inference key in `VOLTAGEGPU_API_KEY` is no longer taken for the
34
+ pod API key; the next source (config file) is used.
35
+ - `voltagegpu` and `volt` are otherwise unchanged. The major version marks the new
36
+ command and its exit-code contract.
37
+
38
+ ## [1.3.1] - 2026-10-10
39
+
40
+ Security hardening after an independent review of 1.3.0. Upgrade recommended.
41
+
42
+ ### Security
43
+ - The SSH command returned by the API is only ever displayed in its validated,
44
+ rebuilt form (`ssh -p PORT user@host`). A command of any other form is
45
+ neither shown nor run, so a tampered answer cannot end up copied into a
46
+ shell from `pods show`, `pods wait` or `deploy --wait`.
47
+ - Server text (machine names, locations, error messages, ids) can no longer
48
+ inject terminal escape sequences or rich markup: control characters are
49
+ stripped and the text is printed literally. Before, an odd string could also
50
+ crash the CLI right after a deploy.
51
+ - `voltagegpu verify` calls voltage-verify in-process instead of
52
+ `python -m voltage_verify`, which put the current directory first on the
53
+ module path (a `voltage_verify.py` next to a downloaded bundle would run).
54
+ - `voltagegpu ssh` looks for `ssh` on PATH only, never in the current
55
+ directory (Windows `shutil.which` checks it first), and never runs a
56
+ `.bat`/`.cmd` script.
57
+ - The one-time sudo password of a Confidential VM is printed exactly as
58
+ received (no markup or emoji parsing could alter it).
59
+ - The API key is only sent to `voltagegpu.com` hosts (or localhost) unless
60
+ `VOLT_ALLOW_CUSTOM_BASE_URL=1` is set.
61
+ - A malformed `~/.volt/config.ini` no longer prints its content (which may be
62
+ the key) in an error; an existing file is set to 0600 before the key is
63
+ written.
64
+
65
+ ### Changed
66
+ - `deploy standard --cheapest --yes` requires `--max-price`, so a script never
67
+ rents an expensive machine by surprise.
68
+ - If the deploy request gets no answer, the CLI says the deploy may have gone
69
+ through and to check `voltagegpu pods list`, instead of suggesting a retry.
70
+ - A warning is printed if the hourly price rose between the listing and the
71
+ deploy.
72
+
73
+ ## [1.3.0] - 2026-10-10
74
+
75
+ Realigns the CLI with the product as it is today: Confidential VMs (Intel TDX)
76
+ and standard pods, both deployable from the public API. Every command was run
77
+ against the production API before release, including a paid deploy, SSH and
78
+ release of a standard pod.
79
+
80
+ ### Added
81
+ - `voltagegpu` command (the `volt` command still works, same program).
82
+ - `voltagegpu machines [--standard | --confidential] [--gpu] [--max-price] [--min-gpus] [--json]`:
83
+ standard machines and Confidential VM tiers with the hourly price charged.
84
+ - `voltagegpu deploy standard --machine ID | --cheapest`: deploy a standard pod
85
+ (no enclave), with `--template`, `--ssh-key`, `--jupyter`, `--ports`,
86
+ `--auto-terminate`, `--wait`. Asks for confirmation before charging; scripts
87
+ pass `--yes`.
88
+ - `voltagegpu deploy confidential --tier TIER`: deploy a Confidential VM, with
89
+ `--hardstop`, repeatable `--port 8000[/tcp|udp]` and `--wait`. Prints the
90
+ one-time sudo password and the in-VM attestation commands.
91
+ - `voltagegpu templates`: images available for standard pods.
92
+ - `voltagegpu pods wait POD_ID`: wait until SSH is ready.
93
+ - `voltagegpu ssh POD_ID [-- COMMAND]`: run ssh directly (or `--print` it).
94
+ - `voltagegpu balance`: balance and running pods (`GET /api/volt/balance`).
95
+ - `voltagegpu login` / `logout`: store the API key in `~/.volt/config.ini`,
96
+ created with mode 0600, after checking that the API accepts it.
97
+ - `voltagegpu verify ...`: verifies a Confidential VM attestation bundle by
98
+ running voltage-verify (`pip install "voltagegpu-cli[verify]"`).
99
+ - `VOLTAGEGPU_API_KEY` is accepted as an alias of `VOLT_API_KEY`.
100
+ - SDK: `list_machines`, `list_templates`, `deploy_standard`,
101
+ `deploy_confidential`, `release_pod`, `wait_until_reachable`, `get_balance`;
102
+ typed immutable models; `parse_ssh_command`.
103
+ - Test suite (unit, CLI and opt-in live checks) and a CI workflow.
104
+
105
+ ### Changed
106
+ - `pods stop` now releases the pod (`DELETE /api/volt/pods/:id`) and prints
107
+ the refunded unused prepaid time. Standard pods cannot be paused, so the old
108
+ `POST .../stop` call failed for them. `pods delete` and `pods get` remain as
109
+ aliases of `pods stop` and `pods show`.
110
+ - Errors show the API's own message (for example "Insufficient balance. One
111
+ hour costs $0.59...") instead of a raw HTTP exception, and never a traceback
112
+ unless `VOLT_DEBUG=1`.
113
+ - Python 3.10 or newer is required (3.9 reached end of life in October 2025).
114
+
115
+ ### Removed
116
+ - `volt cc inventory`, `volt cc deploy` and `volt templates get`: Confidential
117
+ containers were retired on 2026-10-01. The commands now print how to deploy a
118
+ Confidential VM instead.
119
+ - `volt account info`, which called an endpoint that does not exist.
120
+
121
+ ### Fixed
122
+ - `ssh-keys add` sent `publicKey`; the API expects `public_key`, so every key
123
+ upload failed with HTTP 400. It also refuses a private key file now.
124
+ - `account balance` called a dashboard-only endpoint and always failed with
125
+ HTTP 401.
126
+ - `cc inventory` called a dashboard-only endpoint and reported "no GPUs
127
+ available" instead of an error.
128
+ - Pod ids are validated before they are put into a URL path.
129
+
130
+ ### Security
131
+ - The SSH command returned by the API is parsed into user, host and port, each
132
+ checked against a strict pattern, and ssh is started from a list of
133
+ arguments, never through a shell. A tampered answer such as
134
+ `ssh -o ProxyCommand=...` is refused.
135
+ - Plain `http://` base URLs are refused (except localhost), redirects are never
136
+ followed, and TLS certificates are always verified, so the API key cannot be
137
+ sent in clear or to another host.
138
+ - The API key is never printed (only `volt_****` and its last four
139
+ characters), including in `repr()` of the configuration.
140
+
141
+ ## [1.2.1] - 2026-04-11
142
+
143
+ - Confidential container templates (`volt templates`), the machines list and
144
+ `volt cc deploy --template`.
145
+
146
+ ## [1.2.0] - 2026-04-11
147
+
148
+ - `volt cc` command group for Confidential containers; default API base URL
149
+ `https://api.voltagegpu.com/api`; JSON output on list commands.
150
+
151
+ ## [1.1.0] and [1.0.0]
152
+
153
+ - First releases of the CLI and Python SDK.
@@ -1,13 +1,13 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: voltagegpu-cli
3
- Version: 1.3.1
4
- Summary: VoltageGPU CLI and Python SDK: deploy Confidential VMs (Intel TDX) and standard GPU pods, SSH in, stop them, check your balance.
3
+ Version: 2.0.0
4
+ Summary: VoltageGPU CLI and Python SDK: Confidential VMs (Intel TDX), Confidential CPU (AMD SEV-SNP), standard GPU pods, dedicated machines and sandboxes, with the vgpu command for scripts and AI agents.
5
5
  Project-URL: Homepage, https://voltagegpu.com
6
6
  Project-URL: Documentation, https://docs.voltagegpu.com/cli
7
7
  Project-URL: API reference, https://docs.voltagegpu.com/api-reference
8
- Project-URL: Source, https://github.com/Jabsama/VOLTAGEGPU-CLI/tree/release/1.3
9
- Project-URL: Changelog, https://github.com/Jabsama/VOLTAGEGPU-CLI/blob/release/1.3/CHANGELOG.md
10
- Project-URL: Issues, https://github.com/Jabsama/VOLTAGEGPU-CLI/issues
8
+ Project-URL: Source, https://github.com/VoltageGPU/VOLTAGEGPU-CLI/tree/release/1.3
9
+ Project-URL: Changelog, https://github.com/VoltageGPU/VOLTAGEGPU-CLI/blob/release/1.3/CHANGELOG.md
10
+ Project-URL: Issues, https://github.com/VoltageGPU/VOLTAGEGPU-CLI/issues
11
11
  Author-email: "VoltageGPU (VOLTAGE EI)" <contact@voltagegpu.com>
12
12
  License: MIT License
13
13
 
@@ -178,6 +178,106 @@ voltagegpu pods stop "$POD" --yes
178
178
  Exit codes: `0` success, `1` API or runtime error, `2` usage error or missing
179
179
  confirmation.
180
180
 
181
+ ## `vgpu`: the short command for scripts and AI agents
182
+
183
+ Installed with the package, next to `voltagegpu`. The key comes from
184
+ `VOLT_API_KEY` or `VOLTAGEGPU_API_KEY` (or `voltagegpu login`) and is never
185
+ printed. Give an agent a limited key (scopes, its own machines only, a
186
+ daily budget) from https://voltagegpu.com/api-keys, never your full key.
187
+
188
+ ```bash
189
+ vgpu ls --json # every offer, cheapest first
190
+ vgpu ls --kind vm --gpu H100 # vm | cpu | standard | baremetal | sandbox
191
+ vgpu up rtx6000b-small --name train1 --ttl 2h -y --json
192
+ vgpu ps --json
193
+ vgpu exec train1 "nvidia-smi" # returns the remote exit code
194
+ vgpu exec train1 -d "python train.py" # background: prints PID and log path
195
+ vgpu scp train1 /home/ubuntu/out.tgz ./out.tgz # --up to copy the other way
196
+ vgpu attest train1 # Confidential VM or Confidential CPU only
197
+ vgpu rm train1 -y
198
+ vgpu whoami # scopes, budgets, spend, balance
199
+ vgpu mcp # local MCP server (stdio) for agents
200
+ ```
201
+
202
+ `--ttl` is mandatory and becomes the auto-stop of each product, rounded up,
203
+ refused locally when out of bounds: Confidential VM and CPU up to 720h,
204
+ standard pods 1h to 720h (whole hours), dedicated machines 1h to 72h (whole
205
+ hours), sandboxes up to 7d. `up` asks for confirmation unless `-y` is given,
206
+ and fails without `-y` when not run in a terminal. A deploy that gets no
207
+ answer is never retried: run `vgpu ps` first.
208
+
209
+ `exec`, `scp` and `attest` use your local SSH key (`-i`, or `VGPU_SSH_KEY`).
210
+ The first connection to a machine records its host key in
211
+ `~/.volt/known_hosts.d/<id>` (trust on first use); a changed key is refused.
212
+ Names given at `up` are kept in `~/.volt/vgpu-names.json`; ids work too.
213
+
214
+ Confidential VMs and CPU tiers bind the SSH keys already on the account.
215
+ A standard GPU binds one key: the account's only key, or `--ssh-key-id ID`
216
+ when the account has several (`voltagegpu ssh-keys list` shows the ids).
217
+ Dedicated machines and sandboxes take key ids: by default every key of the
218
+ account, but a key limited to its own machines cannot read them, so pass
219
+ `--ssh-key-id ID` (repeatable). For such a key `whoami` and `voltagegpu
220
+ balance` show the balance as hidden: only a full key reads it.
221
+
222
+ `vgpu attest` draws a challenge on your machine, runs the published proof
223
+ script in the machine (`two-proofs-in-the-vm.sh` for a Confidential VM,
224
+ `snp-proof-in-the-vm.sh` for a Confidential CPU tier, both embedded and pinned
225
+ by SHA-256), copies the archive back and verifies it here: `voltage-verify`
226
+ for Intel TDX + NVIDIA (`pip install 'voltagegpu-cli[verify]'`, `--offline`
227
+ for no network). For SEV-SNP: the report is requested at `--vmpl` (0 by
228
+ default, sent as `SNP_VMPL`; if VMPL 0 is refused, the script says so and asks
229
+ again at 1, and the result reports it), REPORT_DATA equals the challenge, the
230
+ report policy forbids debug and its VMPL field is the level requested (the
231
+ guest kernel uses VMPCK0, consistent with VMPL 0, no SVSM), then the AMD chain and the VCEK are
232
+ fetched again from AMD into a new folder (`snpguest 0.11.0 fetch ca` / `fetch
233
+ vcek` on your machine), the ARK must be one of the AMD roots pinned in the
234
+ script, and `snpguest verify certs` / `verify attestation` run with those
235
+ certificates, never the ones in the archive (they come from the VM). Without
236
+ a local `snpguest`, or when the AMD key server cannot be reached, the result
237
+ is `INCOMPLETE`, never `VERIFIED`. Standard pods, dedicated machines and sandboxes have no tenant
238
+ attestation and are refused.
239
+
240
+ | Exit code | Meaning |
241
+ |---|---|
242
+ | 0 | ok |
243
+ | 1 | error (including a deploy that got no answer) |
244
+ | 2 | usage: bad option, `--ttl` out of bounds, missing `-y` |
245
+ | 3 | API key missing, malformed or refused |
246
+ | 4 | API key scope missing (`API_KEY_SCOPE_MISSING`), or account resource refused to a key limited to its own machines (`API_KEY_ACCOUNT_RESOURCE`) |
247
+ | 5 | not found (machine or tier) |
248
+ | 6 | balance too low or API key budget exceeded (`API_KEY_BUDGET_EXCEEDED`, HTTP 402): stop, nothing was charged |
249
+ | 7 | unavailable: sold out, over `--max-price`, rate limited, offer closed |
250
+ | 8 | attestation failed |
251
+ | 9 | attestation incomplete, or a local tool is missing (ssh, scp, voltage-verify) |
252
+
253
+ With `--json`, an error is also printed on stdout as
254
+ `{"error": {"code", "message", "exit_code", ...}}`.
255
+
256
+ ### Local MCP server
257
+
258
+ `vgpu mcp` serves the tools `ls`, `up`, `ps`, `exec`, `scp`, `rm`, `attest`,
259
+ `inference` and `whoami` over stdio. It runs on your machine because `exec`,
260
+ `scp` and `attest` use your SSH private key, which never leaves it. Same
261
+ guards as the command line: `up` requires `ttl` and `max_hourly_price`, `rm`
262
+ requires `confirm: true`, a 402 comes back as `API_KEY_BUDGET_EXCEEDED` with
263
+ "do not retry", the key is never part of an answer, and the sudo password of
264
+ a Confidential VM is never handed to the agent. `inference` calls the
265
+ OpenAI-compatible API with an inference key (`vgpu_...`) in
266
+ `VOLTAGEGPU_API_KEY`; a `vgpu_` value there is never sent to the pod API,
267
+ which takes the `volt_` key from `VOLT_API_KEY`.
268
+
269
+ ```bash
270
+ claude mcp add voltagegpu -e VOLT_API_KEY=volt_... -- vgpu mcp # Claude Code
271
+ ```
272
+
273
+ ```toml
274
+ # Codex: ~/.codex/config.toml
275
+ [mcp_servers.voltagegpu]
276
+ command = "vgpu"
277
+ args = ["mcp"]
278
+ env = { VOLT_API_KEY = "volt_..." }
279
+ ```
280
+
181
281
  ## Python SDK
182
282
 
183
283
  ```python