voltagegpu-cli 1.2.1__tar.gz → 1.3.1__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 (50) hide show
  1. voltagegpu_cli-1.3.1/.gitignore +14 -0
  2. voltagegpu_cli-1.3.1/CHANGELOG.md +122 -0
  3. {voltagegpu_cli-1.2.1 → voltagegpu_cli-1.3.1}/LICENSE +21 -21
  4. voltagegpu_cli-1.3.1/PKG-INFO +248 -0
  5. voltagegpu_cli-1.3.1/README.md +184 -0
  6. voltagegpu_cli-1.3.1/examples/deploy_standard_pod.py +52 -0
  7. voltagegpu_cli-1.3.1/pyproject.toml +89 -0
  8. voltagegpu_cli-1.3.1/tests/__init__.py +0 -0
  9. voltagegpu_cli-1.3.1/tests/conftest.py +130 -0
  10. voltagegpu_cli-1.3.1/tests/test_cli.py +261 -0
  11. voltagegpu_cli-1.3.1/tests/test_cli_account.py +141 -0
  12. voltagegpu_cli-1.3.1/tests/test_client.py +171 -0
  13. voltagegpu_cli-1.3.1/tests/test_config.py +90 -0
  14. voltagegpu_cli-1.3.1/tests/test_hardening.py +165 -0
  15. voltagegpu_cli-1.3.1/tests/test_live.py +42 -0
  16. voltagegpu_cli-1.3.1/tests/test_models.py +57 -0
  17. voltagegpu_cli-1.3.1/tests/test_package.py +53 -0
  18. voltagegpu_cli-1.3.1/tests/test_ssh.py +59 -0
  19. voltagegpu_cli-1.3.1/volt/__init__.py +5 -0
  20. voltagegpu_cli-1.3.1/volt/__main__.py +5 -0
  21. voltagegpu_cli-1.3.1/volt/cli/__init__.py +5 -0
  22. voltagegpu_cli-1.3.1/volt/cli/cmd_account.py +176 -0
  23. voltagegpu_cli-1.3.1/volt/cli/cmd_deploy.py +218 -0
  24. voltagegpu_cli-1.3.1/volt/cli/cmd_machines.py +103 -0
  25. voltagegpu_cli-1.3.1/volt/cli/cmd_misc.py +102 -0
  26. voltagegpu_cli-1.3.1/volt/cli/cmd_pods.py +188 -0
  27. voltagegpu_cli-1.3.1/volt/cli/main.py +132 -0
  28. voltagegpu_cli-1.3.1/volt/cli/output.py +98 -0
  29. voltagegpu_cli-1.3.1/volt/cli/state.py +35 -0
  30. voltagegpu_cli-1.3.1/volt/sdk/__init__.py +36 -0
  31. voltagegpu_cli-1.3.1/volt/sdk/client.py +236 -0
  32. voltagegpu_cli-1.3.1/volt/sdk/config.py +201 -0
  33. voltagegpu_cli-1.3.1/volt/sdk/errors.py +72 -0
  34. voltagegpu_cli-1.3.1/volt/sdk/models.py +332 -0
  35. voltagegpu_cli-1.3.1/volt/sdk/ssh.py +157 -0
  36. voltagegpu_cli-1.2.1/.github/workflows/release.yml +0 -56
  37. voltagegpu_cli-1.2.1/.gitignore +0 -181
  38. voltagegpu_cli-1.2.1/.readthedocs.yaml +0 -15
  39. voltagegpu_cli-1.2.1/CHANGELOG.md +0 -105
  40. voltagegpu_cli-1.2.1/PKG-INFO +0 -244
  41. voltagegpu_cli-1.2.1/README.md +0 -207
  42. voltagegpu_cli-1.2.1/assets/web-app-logo.png +0 -0
  43. voltagegpu_cli-1.2.1/examples/deploy_confidential_pod.py +0 -60
  44. voltagegpu_cli-1.2.1/pyproject.toml +0 -60
  45. voltagegpu_cli-1.2.1/volt/__init__.py +0 -6
  46. voltagegpu_cli-1.2.1/volt/cli/__init__.py +0 -3
  47. voltagegpu_cli-1.2.1/volt/cli/cli.py +0 -646
  48. voltagegpu_cli-1.2.1/volt/sdk/__init__.py +0 -7
  49. voltagegpu_cli-1.2.1/volt/sdk/client.py +0 -313
  50. voltagegpu_cli-1.2.1/volt/sdk/config.py +0 -65
@@ -0,0 +1,14 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *.egg-info/
4
+ .venv*/
5
+ venv*/
6
+ build/
7
+ dist/
8
+ .pytest_cache/
9
+ .ruff_cache/
10
+ .coverage
11
+ htmlcov/
12
+ .env
13
+ *.ini
14
+ !pytest.ini
@@ -0,0 +1,122 @@
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,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2025 Datura
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2024-2026 VOLTAGE EI (VoltageGPU)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,248 @@
1
+ Metadata-Version: 2.5
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.
5
+ Project-URL: Homepage, https://voltagegpu.com
6
+ Project-URL: Documentation, https://docs.voltagegpu.com/cli
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
11
+ Author-email: "VoltageGPU (VOLTAGE EI)" <contact@voltagegpu.com>
12
+ License: MIT License
13
+
14
+ Copyright (c) 2024-2026 VOLTAGE EI (VoltageGPU)
15
+
16
+ Permission is hereby granted, free of charge, to any person obtaining a copy
17
+ of this software and associated documentation files (the "Software"), to deal
18
+ in the Software without restriction, including without limitation the rights
19
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
20
+ copies of the Software, and to permit persons to whom the Software is
21
+ furnished to do so, subject to the following conditions:
22
+
23
+ The above copyright notice and this permission notice shall be included in all
24
+ copies or substantial portions of the Software.
25
+
26
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
27
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
28
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
29
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
30
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
31
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
32
+ SOFTWARE.
33
+ License-File: LICENSE
34
+ Keywords: attestation,cli,confidential-computing,gpu,intel-tdx,pytorch,sdk,ssh,voltagegpu
35
+ Classifier: Development Status :: 5 - Production/Stable
36
+ Classifier: Environment :: Console
37
+ Classifier: Intended Audience :: Developers
38
+ Classifier: Intended Audience :: Science/Research
39
+ Classifier: License :: OSI Approved :: MIT License
40
+ Classifier: Operating System :: OS Independent
41
+ Classifier: Programming Language :: Python :: 3
42
+ Classifier: Programming Language :: Python :: 3 :: Only
43
+ Classifier: Programming Language :: Python :: 3.10
44
+ Classifier: Programming Language :: Python :: 3.11
45
+ Classifier: Programming Language :: Python :: 3.12
46
+ Classifier: Programming Language :: Python :: 3.13
47
+ Classifier: Programming Language :: Python :: 3.14
48
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
49
+ Classifier: Topic :: Security
50
+ Classifier: Topic :: System :: Systems Administration
51
+ Requires-Python: >=3.10
52
+ Requires-Dist: click>=8.1
53
+ Requires-Dist: httpx<1,>=0.27
54
+ Requires-Dist: rich>=13.0
55
+ Provides-Extra: dev
56
+ Requires-Dist: build>=1.2; extra == 'dev'
57
+ Requires-Dist: pytest-cov>=5; extra == 'dev'
58
+ Requires-Dist: pytest>=8; extra == 'dev'
59
+ Requires-Dist: ruff>=0.6; extra == 'dev'
60
+ Requires-Dist: twine>=5; extra == 'dev'
61
+ Provides-Extra: verify
62
+ Requires-Dist: voltage-verify>=0.2.1; extra == 'verify'
63
+ Description-Content-Type: text/markdown
64
+
65
+ # voltagegpu-cli
66
+
67
+ Deploy and manage VoltageGPU machines from your terminal or from Python:
68
+
69
+ - **Confidential VMs**: Intel TDX trust domains with an NVIDIA GPU, only your SSH
70
+ keys on the machine, and an attestation you generate and verify yourself.
71
+ - **Standard pods**: whole GPU machines without an enclave, for workloads that
72
+ are not sensitive.
73
+
74
+ Billing is per second. The first hour is charged when you deploy; when you stop
75
+ a standard pod, the unused part of that hour goes back to your balance.
76
+
77
+ ```bash
78
+ pip install voltagegpu-cli
79
+ ```
80
+
81
+ Python 3.10 or newer. The package installs the `voltagegpu` command (`volt` is
82
+ an alias kept from earlier releases).
83
+
84
+ ## 1. Log in
85
+
86
+ Create an API key at <https://voltagegpu.com/api-keys> (it is shown once), then:
87
+
88
+ ```bash
89
+ voltagegpu login # prompts for the key, hidden, checks it, saves it to ~/.volt/config.ini (mode 0600)
90
+ # or, for CI and scripts:
91
+ export VOLT_API_KEY=volt_...
92
+ ```
93
+
94
+ Add the SSH key you will connect with (defaults to `~/.ssh/id_ed25519.pub`):
95
+
96
+ ```bash
97
+ voltagegpu ssh-keys add
98
+ voltagegpu ssh-keys list
99
+ ```
100
+
101
+ ## 2. Pick a machine
102
+
103
+ ```bash
104
+ voltagegpu machines # Confidential VM tiers, then standard machines, cheapest first
105
+ voltagegpu machines --standard --gpu A6000 # filter by GPU model
106
+ voltagegpu machines --standard --max-price 1 --json
107
+ voltagegpu machines --confidential
108
+ voltagegpu templates # images for standard pods (PyTorch by default)
109
+ ```
110
+
111
+ ## 3a. Deploy a standard pod
112
+
113
+ ```bash
114
+ voltagegpu deploy standard --machine <machine_id>
115
+ voltagegpu deploy standard --cheapest --gpu 4090 --wait # cheapest matching machine, wait for SSH
116
+ ```
117
+
118
+ The CLI shows the price and asks before charging. In scripts, add `--yes`.
119
+ If your account has several SSH keys, choose one with `--ssh-key <key_id>`.
120
+ Other options: `--template <template_id>`, `--jupyter`, `--ports 3`,
121
+ `--auto-terminate 8` (hours), `--name my-pod`.
122
+
123
+ ## 3b. Deploy a Confidential VM
124
+
125
+ ```bash
126
+ voltagegpu deploy confidential --tier rtx6000b-small --wait
127
+ voltagegpu deploy confidential --tier h100-small --hardstop 4 --port 8000 --port 8443/tcp
128
+ ```
129
+
130
+ Every SSH key on your account is bound to the VM when it is created; a VM
131
+ cannot be given a key afterwards, so add yours first. The sudo password is
132
+ printed once and is not kept anywhere. The command also prints how to generate
133
+ the attestation inside the VM.
134
+
135
+ ## 4. Connect, inspect, stop
136
+
137
+ ```bash
138
+ voltagegpu pods list
139
+ voltagegpu pods wait <pod_id> # until SSH answers
140
+ voltagegpu ssh <pod_id> # interactive shell
141
+ voltagegpu ssh <pod_id> -- nvidia-smi -L # run one command
142
+ voltagegpu ssh <pod_id> --print # just print the ssh command
143
+ voltagegpu pods show <pod_id>
144
+ voltagegpu pods stop <pod_id> # releases it: billing stops, the disk is deleted
145
+ voltagegpu balance
146
+ ```
147
+
148
+ Fresh pods present a new host key. In non-interactive scripts you can accept it
149
+ on first use with `-o StrictHostKeyChecking=accept-new`.
150
+
151
+ ## 5. Verify a Confidential VM
152
+
153
+ Inside the VM you produce an evidence bundle (the deploy output prints the exact
154
+ commands). On your own machine:
155
+
156
+ ```bash
157
+ pip install "voltagegpu-cli[verify]" # installs voltage-verify
158
+ voltagegpu verify bundle.json --offline
159
+ voltagegpu verify bundle.json --challenge <hex-you-issued> --gpus 1
160
+ ```
161
+
162
+ `voltagegpu verify` runs [voltage-verify](https://pypi.org/project/voltage-verify/),
163
+ which checks the Intel TDX quote up to Intel's root and the NVIDIA GPU
164
+ attestation tokens, without trusting VoltageGPU.
165
+
166
+ ## Scripting
167
+
168
+ Every list command takes `--json`; deploys and stops take `--yes`.
169
+
170
+ ```bash
171
+ # Deploy the cheapest standard machine, wait for SSH, run a job, release it.
172
+ POD=$(voltagegpu deploy standard --cheapest --max-price 1 --yes --json | jq -r .deploy.pod_id)
173
+ voltagegpu pods wait "$POD"
174
+ voltagegpu ssh "$POD" -o StrictHostKeyChecking=accept-new -- nvidia-smi
175
+ voltagegpu pods stop "$POD" --yes
176
+ ```
177
+
178
+ Exit codes: `0` success, `1` API or runtime error, `2` usage error or missing
179
+ confirmation.
180
+
181
+ ## Python SDK
182
+
183
+ ```python
184
+ from volt.sdk import VoltageGPUClient
185
+
186
+ with VoltageGPUClient() as client: # VOLT_API_KEY or ~/.volt/config.ini
187
+ machine = client.list_machines("standard")[0] # cheapest first
188
+ result = client.deploy_standard(machine.id, name="my-pod")
189
+ pod = client.wait_until_reachable(result.pod_id)
190
+ print(pod.ssh_command)
191
+ print(client.release_pod(result.pod_id).prepaid_refund)
192
+ ```
193
+
194
+ A complete example is in [`examples/deploy_standard_pod.py`](examples/deploy_standard_pod.py).
195
+
196
+ ## REST API
197
+
198
+ The CLI is a thin client of the public API, documented at
199
+ <https://docs.voltagegpu.com/api-reference>. The same deploy with curl:
200
+
201
+ ```bash
202
+ curl -X POST https://api.voltagegpu.com/api/volt/pods \
203
+ -H "X-API-Key: $VOLT_API_KEY" -H "Content-Type: application/json" \
204
+ -d '{"provider":"standard","name":"my-pod","machine_id":"<machine_id>"}'
205
+
206
+ curl https://api.voltagegpu.com/api/volt/pods -H "X-API-Key: $VOLT_API_KEY"
207
+ ```
208
+
209
+ ## Configuration
210
+
211
+ | Setting | Where |
212
+ | --- | --- |
213
+ | API key | `--api-key` of `login`, `VOLT_API_KEY` (or `VOLTAGEGPU_API_KEY`), then `~/.volt/config.ini` |
214
+ | API base URL | `VOLT_BASE_URL` (https only, voltagegpu.com hosts unless `VOLT_ALLOW_CUSTOM_BASE_URL=1`; default `https://api.voltagegpu.com/api`) |
215
+ | Debug | `VOLT_DEBUG=1` shows tracebacks |
216
+
217
+ `voltagegpu config` shows where the key comes from, masked.
218
+
219
+ ## Security
220
+
221
+ - The key is sent only over HTTPS, in the `X-API-Key` header; redirects are
222
+ never followed and certificates are always verified.
223
+ - The key is never printed. `~/.volt/config.ini` is created readable by you
224
+ only, and `voltagegpu config` warns if its permissions are too open.
225
+ - The SSH command returned by the API is parsed into user, host and port, only
226
+ that rebuilt form is ever shown, and ssh is started without a shell (and never
227
+ from the current directory), so a tampered answer cannot run a command on
228
+ your machine. Server text is printed literally, without terminal escapes.
229
+ - `ssh-keys add` refuses private keys.
230
+
231
+ Report a vulnerability to contact@voltagegpu.com.
232
+
233
+ ## Upgrading from 1.2
234
+
235
+ - `volt cc inventory` / `volt cc deploy`: Confidential containers were retired
236
+ on 2026-10-01. Use `voltagegpu machines --confidential` and
237
+ `voltagegpu deploy confidential --tier <tier>`.
238
+ - `volt pods stop` now releases the pod and reports the refund.
239
+ - `volt account balance` is now `voltagegpu balance`.
240
+
241
+ ## Links
242
+
243
+ - Docs: <https://docs.voltagegpu.com/cli>
244
+ - API reference: <https://docs.voltagegpu.com/api-reference>
245
+ - API keys: <https://voltagegpu.com/api-keys>
246
+ - Changelog: [CHANGELOG.md](CHANGELOG.md)
247
+
248
+ MIT License.
@@ -0,0 +1,184 @@
1
+ # voltagegpu-cli
2
+
3
+ Deploy and manage VoltageGPU machines from your terminal or from Python:
4
+
5
+ - **Confidential VMs**: Intel TDX trust domains with an NVIDIA GPU, only your SSH
6
+ keys on the machine, and an attestation you generate and verify yourself.
7
+ - **Standard pods**: whole GPU machines without an enclave, for workloads that
8
+ are not sensitive.
9
+
10
+ Billing is per second. The first hour is charged when you deploy; when you stop
11
+ a standard pod, the unused part of that hour goes back to your balance.
12
+
13
+ ```bash
14
+ pip install voltagegpu-cli
15
+ ```
16
+
17
+ Python 3.10 or newer. The package installs the `voltagegpu` command (`volt` is
18
+ an alias kept from earlier releases).
19
+
20
+ ## 1. Log in
21
+
22
+ Create an API key at <https://voltagegpu.com/api-keys> (it is shown once), then:
23
+
24
+ ```bash
25
+ voltagegpu login # prompts for the key, hidden, checks it, saves it to ~/.volt/config.ini (mode 0600)
26
+ # or, for CI and scripts:
27
+ export VOLT_API_KEY=volt_...
28
+ ```
29
+
30
+ Add the SSH key you will connect with (defaults to `~/.ssh/id_ed25519.pub`):
31
+
32
+ ```bash
33
+ voltagegpu ssh-keys add
34
+ voltagegpu ssh-keys list
35
+ ```
36
+
37
+ ## 2. Pick a machine
38
+
39
+ ```bash
40
+ voltagegpu machines # Confidential VM tiers, then standard machines, cheapest first
41
+ voltagegpu machines --standard --gpu A6000 # filter by GPU model
42
+ voltagegpu machines --standard --max-price 1 --json
43
+ voltagegpu machines --confidential
44
+ voltagegpu templates # images for standard pods (PyTorch by default)
45
+ ```
46
+
47
+ ## 3a. Deploy a standard pod
48
+
49
+ ```bash
50
+ voltagegpu deploy standard --machine <machine_id>
51
+ voltagegpu deploy standard --cheapest --gpu 4090 --wait # cheapest matching machine, wait for SSH
52
+ ```
53
+
54
+ The CLI shows the price and asks before charging. In scripts, add `--yes`.
55
+ If your account has several SSH keys, choose one with `--ssh-key <key_id>`.
56
+ Other options: `--template <template_id>`, `--jupyter`, `--ports 3`,
57
+ `--auto-terminate 8` (hours), `--name my-pod`.
58
+
59
+ ## 3b. Deploy a Confidential VM
60
+
61
+ ```bash
62
+ voltagegpu deploy confidential --tier rtx6000b-small --wait
63
+ voltagegpu deploy confidential --tier h100-small --hardstop 4 --port 8000 --port 8443/tcp
64
+ ```
65
+
66
+ Every SSH key on your account is bound to the VM when it is created; a VM
67
+ cannot be given a key afterwards, so add yours first. The sudo password is
68
+ printed once and is not kept anywhere. The command also prints how to generate
69
+ the attestation inside the VM.
70
+
71
+ ## 4. Connect, inspect, stop
72
+
73
+ ```bash
74
+ voltagegpu pods list
75
+ voltagegpu pods wait <pod_id> # until SSH answers
76
+ voltagegpu ssh <pod_id> # interactive shell
77
+ voltagegpu ssh <pod_id> -- nvidia-smi -L # run one command
78
+ voltagegpu ssh <pod_id> --print # just print the ssh command
79
+ voltagegpu pods show <pod_id>
80
+ voltagegpu pods stop <pod_id> # releases it: billing stops, the disk is deleted
81
+ voltagegpu balance
82
+ ```
83
+
84
+ Fresh pods present a new host key. In non-interactive scripts you can accept it
85
+ on first use with `-o StrictHostKeyChecking=accept-new`.
86
+
87
+ ## 5. Verify a Confidential VM
88
+
89
+ Inside the VM you produce an evidence bundle (the deploy output prints the exact
90
+ commands). On your own machine:
91
+
92
+ ```bash
93
+ pip install "voltagegpu-cli[verify]" # installs voltage-verify
94
+ voltagegpu verify bundle.json --offline
95
+ voltagegpu verify bundle.json --challenge <hex-you-issued> --gpus 1
96
+ ```
97
+
98
+ `voltagegpu verify` runs [voltage-verify](https://pypi.org/project/voltage-verify/),
99
+ which checks the Intel TDX quote up to Intel's root and the NVIDIA GPU
100
+ attestation tokens, without trusting VoltageGPU.
101
+
102
+ ## Scripting
103
+
104
+ Every list command takes `--json`; deploys and stops take `--yes`.
105
+
106
+ ```bash
107
+ # Deploy the cheapest standard machine, wait for SSH, run a job, release it.
108
+ POD=$(voltagegpu deploy standard --cheapest --max-price 1 --yes --json | jq -r .deploy.pod_id)
109
+ voltagegpu pods wait "$POD"
110
+ voltagegpu ssh "$POD" -o StrictHostKeyChecking=accept-new -- nvidia-smi
111
+ voltagegpu pods stop "$POD" --yes
112
+ ```
113
+
114
+ Exit codes: `0` success, `1` API or runtime error, `2` usage error or missing
115
+ confirmation.
116
+
117
+ ## Python SDK
118
+
119
+ ```python
120
+ from volt.sdk import VoltageGPUClient
121
+
122
+ with VoltageGPUClient() as client: # VOLT_API_KEY or ~/.volt/config.ini
123
+ machine = client.list_machines("standard")[0] # cheapest first
124
+ result = client.deploy_standard(machine.id, name="my-pod")
125
+ pod = client.wait_until_reachable(result.pod_id)
126
+ print(pod.ssh_command)
127
+ print(client.release_pod(result.pod_id).prepaid_refund)
128
+ ```
129
+
130
+ A complete example is in [`examples/deploy_standard_pod.py`](examples/deploy_standard_pod.py).
131
+
132
+ ## REST API
133
+
134
+ The CLI is a thin client of the public API, documented at
135
+ <https://docs.voltagegpu.com/api-reference>. The same deploy with curl:
136
+
137
+ ```bash
138
+ curl -X POST https://api.voltagegpu.com/api/volt/pods \
139
+ -H "X-API-Key: $VOLT_API_KEY" -H "Content-Type: application/json" \
140
+ -d '{"provider":"standard","name":"my-pod","machine_id":"<machine_id>"}'
141
+
142
+ curl https://api.voltagegpu.com/api/volt/pods -H "X-API-Key: $VOLT_API_KEY"
143
+ ```
144
+
145
+ ## Configuration
146
+
147
+ | Setting | Where |
148
+ | --- | --- |
149
+ | API key | `--api-key` of `login`, `VOLT_API_KEY` (or `VOLTAGEGPU_API_KEY`), then `~/.volt/config.ini` |
150
+ | API base URL | `VOLT_BASE_URL` (https only, voltagegpu.com hosts unless `VOLT_ALLOW_CUSTOM_BASE_URL=1`; default `https://api.voltagegpu.com/api`) |
151
+ | Debug | `VOLT_DEBUG=1` shows tracebacks |
152
+
153
+ `voltagegpu config` shows where the key comes from, masked.
154
+
155
+ ## Security
156
+
157
+ - The key is sent only over HTTPS, in the `X-API-Key` header; redirects are
158
+ never followed and certificates are always verified.
159
+ - The key is never printed. `~/.volt/config.ini` is created readable by you
160
+ only, and `voltagegpu config` warns if its permissions are too open.
161
+ - The SSH command returned by the API is parsed into user, host and port, only
162
+ that rebuilt form is ever shown, and ssh is started without a shell (and never
163
+ from the current directory), so a tampered answer cannot run a command on
164
+ your machine. Server text is printed literally, without terminal escapes.
165
+ - `ssh-keys add` refuses private keys.
166
+
167
+ Report a vulnerability to contact@voltagegpu.com.
168
+
169
+ ## Upgrading from 1.2
170
+
171
+ - `volt cc inventory` / `volt cc deploy`: Confidential containers were retired
172
+ on 2026-10-01. Use `voltagegpu machines --confidential` and
173
+ `voltagegpu deploy confidential --tier <tier>`.
174
+ - `volt pods stop` now releases the pod and reports the refund.
175
+ - `volt account balance` is now `voltagegpu balance`.
176
+
177
+ ## Links
178
+
179
+ - Docs: <https://docs.voltagegpu.com/cli>
180
+ - API reference: <https://docs.voltagegpu.com/api-reference>
181
+ - API keys: <https://voltagegpu.com/api-keys>
182
+ - Changelog: [CHANGELOG.md](CHANGELOG.md)
183
+
184
+ MIT License.
@@ -0,0 +1,52 @@
1
+ """Deploy the cheapest standard pod, wait for SSH, run nvidia-smi, release it.
2
+
3
+ export VOLT_API_KEY=volt_...
4
+ python examples/deploy_standard_pod.py --max-price 1.0
5
+
6
+ This charges your balance: one hour up front, refunded down to the seconds used
7
+ when the pod is released (the script always releases it, even on error).
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import argparse
13
+ import shutil
14
+ import subprocess
15
+ import sys
16
+
17
+ from volt.sdk import ApiError, VoltageGPUClient, parse_ssh_command
18
+
19
+
20
+ def main() -> int:
21
+ parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
22
+ parser.add_argument("--max-price", type=float, default=1.0, help="maximum price per hour (USD)")
23
+ parser.add_argument("--ssh-key", help="SSH key id, if your account has several")
24
+ args = parser.parse_args()
25
+
26
+ with VoltageGPUClient() as client:
27
+ machines = [m for m in client.list_machines("standard") if m.price_per_hour and m.price_per_hour <= args.max_price]
28
+ if not machines:
29
+ print(f"No standard machine under ${args.max_price}/hour right now.")
30
+ return 1
31
+ machine = machines[0]
32
+ print(f"Deploying on {machine.gpu_count}x {machine.gpu_type} at ${machine.price_per_hour}/hour")
33
+ result = client.deploy_standard(machine.id, name="sdk-example", ssh_key_id=args.ssh_key)
34
+ try:
35
+ pod = client.wait_until_reachable(result.pod_id, timeout=600)
36
+ print("SSH:", pod.ssh_command)
37
+ if shutil.which("ssh") and pod.ssh_command:
38
+ argv = parse_ssh_command(pod.ssh_command).argv(
39
+ options=["StrictHostKeyChecking=accept-new", "ConnectTimeout=15"],
40
+ remote_command=["nvidia-smi", "-L"],
41
+ )
42
+ subprocess.call(argv) # noqa: S603 (argv rebuilt from validated user, host, port)
43
+ except (ApiError, TimeoutError) as exc:
44
+ print("Pod did not become reachable:", exc)
45
+ finally:
46
+ released = client.release_pod(result.pod_id)
47
+ print(f"Released {result.pod_id}, refunded ${released.prepaid_refund or 0:.4f}")
48
+ return 0
49
+
50
+
51
+ if __name__ == "__main__":
52
+ sys.exit(main())