voltagegpu-cli 2.0.1__tar.gz → 2.0.2__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-2.0.1 → voltagegpu_cli-2.0.2}/PKG-INFO +4 -4
  2. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/README.md +284 -284
  3. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/pyproject.toml +7 -6
  4. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/__init__.py +1 -1
  5. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/cli/cmd_account.py +179 -179
  6. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/cli/vgpu.py +485 -485
  7. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/mcp/__init__.py +1 -1
  8. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/mcp/server.py +344 -344
  9. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/sdk/attest.py +296 -296
  10. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/sdk/catalog.py +163 -163
  11. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/sdk/client.py +240 -240
  12. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/sdk/errors.py +14 -4
  13. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/sdk/fleet.py +220 -220
  14. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/sdk/models.py +336 -336
  15. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/sdk/ssh.py +157 -157
  16. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/sdk/ttl.py +104 -104
  17. voltagegpu_cli-2.0.1/CHANGELOG.md +0 -166
  18. voltagegpu_cli-2.0.1/examples/deploy_standard_pod.py +0 -52
  19. voltagegpu_cli-2.0.1/tests/__init__.py +0 -0
  20. voltagegpu_cli-2.0.1/tests/conftest.py +0 -130
  21. voltagegpu_cli-2.0.1/tests/fixtures/ark-milan.pem +0 -37
  22. voltagegpu_cli-2.0.1/tests/fixtures/bundle.json +0 -822
  23. voltagegpu_cli-2.0.1/tests/fixtures/manifest.json +0 -11
  24. voltagegpu_cli-2.0.1/tests/test_cli.py +0 -261
  25. voltagegpu_cli-2.0.1/tests/test_cli_account.py +0 -156
  26. voltagegpu_cli-2.0.1/tests/test_client.py +0 -171
  27. voltagegpu_cli-2.0.1/tests/test_config.py +0 -101
  28. voltagegpu_cli-2.0.1/tests/test_hardening.py +0 -165
  29. voltagegpu_cli-2.0.1/tests/test_live.py +0 -42
  30. voltagegpu_cli-2.0.1/tests/test_models.py +0 -57
  31. voltagegpu_cli-2.0.1/tests/test_package.py +0 -53
  32. voltagegpu_cli-2.0.1/tests/test_ssh.py +0 -59
  33. voltagegpu_cli-2.0.1/tests/test_vgpu_attest.py +0 -252
  34. voltagegpu_cli-2.0.1/tests/test_vgpu_cli.py +0 -494
  35. voltagegpu_cli-2.0.1/tests/test_vgpu_mcp.py +0 -205
  36. voltagegpu_cli-2.0.1/tests/test_vgpu_remote.py +0 -77
  37. voltagegpu_cli-2.0.1/tests/test_vgpu_ttl.py +0 -61
  38. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/.gitignore +0 -0
  39. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/LICENSE +0 -0
  40. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/__main__.py +0 -0
  41. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/cli/__init__.py +0 -0
  42. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/cli/cmd_deploy.py +0 -0
  43. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/cli/cmd_machines.py +0 -0
  44. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/cli/cmd_misc.py +0 -0
  45. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/cli/cmd_pods.py +0 -0
  46. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/cli/main.py +0 -0
  47. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/cli/output.py +0 -0
  48. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/cli/state.py +0 -0
  49. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/sdk/__init__.py +0 -0
  50. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/sdk/config.py +0 -0
  51. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/sdk/remote.py +0 -0
  52. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/sdk/scripts/snp-proof-in-the-vm.sh +0 -0
  53. {voltagegpu_cli-2.0.1 → voltagegpu_cli-2.0.2}/volt/sdk/scripts/two-proofs-in-the-vm.sh +0 -0
@@ -1,12 +1,12 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: voltagegpu-cli
3
- Version: 2.0.1
3
+ Version: 2.0.2
4
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/VoltageGPU/VOLTAGEGPU-CLI/tree/release/1.3
9
- Project-URL: Changelog, https://github.com/VoltageGPU/VOLTAGEGPU-CLI/blob/release/1.3/CHANGELOG.md
8
+ Project-URL: Source, https://github.com/VoltageGPU/VOLTAGEGPU-CLI/tree/release/2.0
9
+ Project-URL: Changelog, https://github.com/VoltageGPU/VOLTAGEGPU-CLI/blob/release/2.0/CHANGELOG.md
10
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
@@ -59,7 +59,7 @@ Requires-Dist: pytest>=8; extra == 'dev'
59
59
  Requires-Dist: ruff>=0.6; extra == 'dev'
60
60
  Requires-Dist: twine>=5; extra == 'dev'
61
61
  Provides-Extra: verify
62
- Requires-Dist: voltage-verify>=0.2.1; extra == 'verify'
62
+ Requires-Dist: voltage-verify>=0.2.3; extra == 'verify'
63
63
  Description-Content-Type: text/markdown
64
64
 
65
65
  # voltagegpu-cli
@@ -1,284 +1,284 @@
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
- ## `vgpu`: the short command for scripts and AI agents
118
-
119
- Installed with the package, next to `voltagegpu`. The key comes from
120
- `VOLT_API_KEY` or `VOLTAGEGPU_API_KEY` (or `voltagegpu login`) and is never
121
- printed. Give an agent a limited key (scopes, its own machines only, a
122
- daily budget) from https://voltagegpu.com/api-keys, never your full key.
123
-
124
- ```bash
125
- vgpu ls --json # every offer, cheapest first
126
- vgpu ls --kind vm --gpu H100 # vm | cpu | standard | baremetal | sandbox
127
- vgpu up rtx6000b-small --name train1 --ttl 2h -y --json
128
- vgpu ps --json
129
- vgpu exec train1 "nvidia-smi" # returns the remote exit code
130
- vgpu exec train1 -d "python train.py" # background: prints PID and log path
131
- vgpu scp train1 /home/ubuntu/out.tgz ./out.tgz # --up to copy the other way
132
- vgpu attest train1 # Confidential VM or Confidential CPU only
133
- vgpu rm train1 -y
134
- vgpu whoami # scopes, budgets, spend, balance
135
- vgpu mcp # local MCP server (stdio) for agents
136
- ```
137
-
138
- `--ttl` is mandatory and becomes the auto-stop of each product, rounded up,
139
- refused locally when out of bounds: Confidential VM and CPU up to 720h,
140
- standard pods 1h to 720h (whole hours), dedicated machines 1h to 72h (whole
141
- hours), sandboxes up to 7d. `up` asks for confirmation unless `-y` is given,
142
- and fails without `-y` when not run in a terminal. A deploy that gets no
143
- answer is never retried: run `vgpu ps` first.
144
-
145
- `exec`, `scp` and `attest` use your local SSH key (`-i`, or `VGPU_SSH_KEY`).
146
- The first connection to a machine records its host key in
147
- `~/.volt/known_hosts.d/<id>` (trust on first use); a changed key is refused.
148
- Names given at `up` are kept in `~/.volt/vgpu-names.json`; ids work too.
149
-
150
- Confidential VMs and CPU tiers bind the SSH keys already on the account.
151
- A standard GPU binds one key: the account's only key, or `--ssh-key-id ID`
152
- when the account has several (`voltagegpu ssh-keys list` shows the ids).
153
- Dedicated machines and sandboxes take key ids: by default every key of the
154
- account, but a key limited to its own machines cannot read them, so pass
155
- `--ssh-key-id ID` (repeatable). For such a key `whoami` and `voltagegpu
156
- balance` show the balance as hidden: only a full key reads it.
157
-
158
- `vgpu attest` draws a challenge on your machine, runs the published proof
159
- script in the machine (`two-proofs-in-the-vm.sh` for a Confidential VM,
160
- `snp-proof-in-the-vm.sh` for a Confidential CPU tier, both embedded and pinned
161
- by SHA-256), copies the archive back and verifies it here: `voltage-verify`
162
- for Intel TDX + NVIDIA (`pip install 'voltagegpu-cli[verify]'`, `--offline`
163
- for no network). For SEV-SNP: the report is requested at `--vmpl` (0 by
164
- default, sent as `SNP_VMPL`; if VMPL 0 is refused, the script says so and asks
165
- again at 1, and the result reports it), REPORT_DATA equals the challenge, the
166
- report policy forbids debug and its VMPL field is the level requested (the
167
- guest kernel uses VMPCK0, consistent with VMPL 0, no SVSM), then the AMD chain and the VCEK are
168
- fetched again from AMD into a new folder (`snpguest 0.11.0 fetch ca` / `fetch
169
- vcek` on your machine), the ARK must be one of the AMD roots pinned in the
170
- script, and `snpguest verify certs` / `verify attestation` run with those
171
- certificates, never the ones in the archive (they come from the VM). Without
172
- a local `snpguest`, or when the AMD key server cannot be reached, the result
173
- is `INCOMPLETE`, never `VERIFIED`. Standard pods, dedicated machines and sandboxes have no tenant
174
- attestation and are refused.
175
-
176
- | Exit code | Meaning |
177
- |---|---|
178
- | 0 | ok |
179
- | 1 | error (including a deploy that got no answer) |
180
- | 2 | usage: bad option, `--ttl` out of bounds, missing `-y` |
181
- | 3 | API key missing, malformed or refused |
182
- | 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`) |
183
- | 5 | not found (machine or tier) |
184
- | 6 | balance too low or API key budget exceeded (`API_KEY_BUDGET_EXCEEDED`, HTTP 402): stop, nothing was charged |
185
- | 7 | unavailable: sold out, over `--max-price`, rate limited, offer closed |
186
- | 8 | attestation failed |
187
- | 9 | attestation incomplete, or a local tool is missing (ssh, scp, voltage-verify) |
188
-
189
- With `--json`, an error is also printed on stdout as
190
- `{"error": {"code", "message", "exit_code", ...}}`.
191
-
192
- ### Local MCP server
193
-
194
- `vgpu mcp` serves the tools `ls`, `up`, `ps`, `exec`, `scp`, `rm`, `attest`,
195
- `inference` and `whoami` over stdio. It runs on your machine because `exec`,
196
- `scp` and `attest` use your SSH private key, which never leaves it. Same
197
- guards as the command line: `up` requires `ttl` and `max_hourly_price`, `rm`
198
- requires `confirm: true`, a 402 comes back as `API_KEY_BUDGET_EXCEEDED` with
199
- "do not retry", the key is never part of an answer, and the sudo password of
200
- a Confidential VM is never handed to the agent. `inference` calls the
201
- OpenAI-compatible API with an inference key (`vgpu_...`) in
202
- `VOLTAGEGPU_API_KEY`; a `vgpu_` value there is never sent to the pod API,
203
- which takes the `volt_` key from `VOLT_API_KEY`.
204
-
205
- ```bash
206
- claude mcp add voltagegpu -e VOLT_API_KEY=volt_... -- vgpu mcp # Claude Code
207
- ```
208
-
209
- ```toml
210
- # Codex: ~/.codex/config.toml
211
- [mcp_servers.voltagegpu]
212
- command = "vgpu"
213
- args = ["mcp"]
214
- env = { VOLT_API_KEY = "volt_..." }
215
- ```
216
-
217
- ## Python SDK
218
-
219
- ```python
220
- from volt.sdk import VoltageGPUClient
221
-
222
- with VoltageGPUClient() as client: # VOLT_API_KEY or ~/.volt/config.ini
223
- machine = client.list_machines("standard")[0] # cheapest first
224
- result = client.deploy_standard(machine.id, name="my-pod")
225
- pod = client.wait_until_reachable(result.pod_id)
226
- print(pod.ssh_command)
227
- print(client.release_pod(result.pod_id).prepaid_refund)
228
- ```
229
-
230
- A complete example is in [`examples/deploy_standard_pod.py`](examples/deploy_standard_pod.py).
231
-
232
- ## REST API
233
-
234
- The CLI is a thin client of the public API, documented at
235
- <https://docs.voltagegpu.com/api-reference>. The same deploy with curl:
236
-
237
- ```bash
238
- curl -X POST https://api.voltagegpu.com/api/volt/pods \
239
- -H "X-API-Key: $VOLT_API_KEY" -H "Content-Type: application/json" \
240
- -d '{"provider":"standard","name":"my-pod","machine_id":"<machine_id>"}'
241
-
242
- curl https://api.voltagegpu.com/api/volt/pods -H "X-API-Key: $VOLT_API_KEY"
243
- ```
244
-
245
- ## Configuration
246
-
247
- | Setting | Where |
248
- | --- | --- |
249
- | API key | `--api-key` of `login`, `VOLT_API_KEY` (or `VOLTAGEGPU_API_KEY`), then `~/.volt/config.ini` |
250
- | API base URL | `VOLT_BASE_URL` (https only, voltagegpu.com hosts unless `VOLT_ALLOW_CUSTOM_BASE_URL=1`; default `https://api.voltagegpu.com/api`) |
251
- | Debug | `VOLT_DEBUG=1` shows tracebacks |
252
-
253
- `voltagegpu config` shows where the key comes from, masked.
254
-
255
- ## Security
256
-
257
- - The key is sent only over HTTPS, in the `X-API-Key` header; redirects are
258
- never followed and certificates are always verified.
259
- - The key is never printed. `~/.volt/config.ini` is created readable by you
260
- only, and `voltagegpu config` warns if its permissions are too open.
261
- - The SSH command returned by the API is parsed into user, host and port, only
262
- that rebuilt form is ever shown, and ssh is started without a shell (and never
263
- from the current directory), so a tampered answer cannot run a command on
264
- your machine. Server text is printed literally, without terminal escapes.
265
- - `ssh-keys add` refuses private keys.
266
-
267
- Report a vulnerability to contact@voltagegpu.com.
268
-
269
- ## Upgrading from 1.2
270
-
271
- - `volt cc inventory` / `volt cc deploy`: Confidential containers were retired
272
- on 2026-10-01. Use `voltagegpu machines --confidential` and
273
- `voltagegpu deploy confidential --tier <tier>`.
274
- - `volt pods stop` now releases the pod and reports the refund.
275
- - `volt account balance` is now `voltagegpu balance`.
276
-
277
- ## Links
278
-
279
- - Docs: <https://docs.voltagegpu.com/cli>
280
- - API reference: <https://docs.voltagegpu.com/api-reference>
281
- - API keys: <https://voltagegpu.com/api-keys>
282
- - Changelog: [CHANGELOG.md](CHANGELOG.md)
283
-
284
- MIT License.
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
+ ## `vgpu`: the short command for scripts and AI agents
118
+
119
+ Installed with the package, next to `voltagegpu`. The key comes from
120
+ `VOLT_API_KEY` or `VOLTAGEGPU_API_KEY` (or `voltagegpu login`) and is never
121
+ printed. Give an agent a limited key (scopes, its own machines only, a
122
+ daily budget) from https://voltagegpu.com/api-keys, never your full key.
123
+
124
+ ```bash
125
+ vgpu ls --json # every offer, cheapest first
126
+ vgpu ls --kind vm --gpu H100 # vm | cpu | standard | baremetal | sandbox
127
+ vgpu up rtx6000b-small --name train1 --ttl 2h -y --json
128
+ vgpu ps --json
129
+ vgpu exec train1 "nvidia-smi" # returns the remote exit code
130
+ vgpu exec train1 -d "python train.py" # background: prints PID and log path
131
+ vgpu scp train1 /home/ubuntu/out.tgz ./out.tgz # --up to copy the other way
132
+ vgpu attest train1 # Confidential VM or Confidential CPU only
133
+ vgpu rm train1 -y
134
+ vgpu whoami # scopes, budgets, spend, balance
135
+ vgpu mcp # local MCP server (stdio) for agents
136
+ ```
137
+
138
+ `--ttl` is mandatory and becomes the auto-stop of each product, rounded up,
139
+ refused locally when out of bounds: Confidential VM and CPU up to 720h,
140
+ standard pods 1h to 720h (whole hours), dedicated machines 1h to 72h (whole
141
+ hours), sandboxes up to 7d. `up` asks for confirmation unless `-y` is given,
142
+ and fails without `-y` when not run in a terminal. A deploy that gets no
143
+ answer is never retried: run `vgpu ps` first.
144
+
145
+ `exec`, `scp` and `attest` use your local SSH key (`-i`, or `VGPU_SSH_KEY`).
146
+ The first connection to a machine records its host key in
147
+ `~/.volt/known_hosts.d/<id>` (trust on first use); a changed key is refused.
148
+ Names given at `up` are kept in `~/.volt/vgpu-names.json`; ids work too.
149
+
150
+ Confidential VMs and CPU tiers bind the SSH keys already on the account.
151
+ A standard GPU binds one key: the account's only key, or `--ssh-key-id ID`
152
+ when the account has several (`voltagegpu ssh-keys list` shows the ids).
153
+ Dedicated machines and sandboxes take key ids: by default every key of the
154
+ account, but a key limited to its own machines cannot read them, so pass
155
+ `--ssh-key-id ID` (repeatable). For such a key `whoami` and `voltagegpu
156
+ balance` show the balance as hidden: only a full key reads it.
157
+
158
+ `vgpu attest` draws a challenge on your machine, runs the published proof
159
+ script in the machine (`two-proofs-in-the-vm.sh` for a Confidential VM,
160
+ `snp-proof-in-the-vm.sh` for a Confidential CPU tier, both embedded and pinned
161
+ by SHA-256), copies the archive back and verifies it here: `voltage-verify`
162
+ for Intel TDX + NVIDIA (`pip install 'voltagegpu-cli[verify]'`, `--offline`
163
+ for no network). For SEV-SNP: the report is requested at `--vmpl` (0 by
164
+ default, sent as `SNP_VMPL`; if VMPL 0 is refused, the script says so and asks
165
+ again at 1, and the result reports it), REPORT_DATA equals the challenge, the
166
+ report policy forbids debug and its VMPL field is the level requested (the
167
+ guest kernel uses VMPCK0, consistent with VMPL 0, no SVSM), then the AMD chain and the VCEK are
168
+ fetched again from AMD into a new folder (`snpguest 0.11.0 fetch ca` / `fetch
169
+ vcek` on your machine), the ARK must be one of the AMD roots pinned in the
170
+ script, and `snpguest verify certs` / `verify attestation` run with those
171
+ certificates, never the ones in the archive (they come from the VM). Without
172
+ a local `snpguest`, or when the AMD key server cannot be reached, the result
173
+ is `INCOMPLETE`, never `VERIFIED`. Standard pods, dedicated machines and sandboxes have no tenant
174
+ attestation and are refused.
175
+
176
+ | Exit code | Meaning |
177
+ |---|---|
178
+ | 0 | ok |
179
+ | 1 | error (including a deploy that got no answer) |
180
+ | 2 | usage: bad option, `--ttl` out of bounds, missing `-y` |
181
+ | 3 | API key missing, malformed or refused |
182
+ | 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`) |
183
+ | 5 | not found (machine or tier) |
184
+ | 6 | balance too low or API key budget exceeded (`API_KEY_BUDGET_EXCEEDED`, HTTP 402): stop, nothing was charged |
185
+ | 7 | unavailable: sold out, over `--max-price`, rate limited, offer closed |
186
+ | 8 | attestation failed |
187
+ | 9 | attestation incomplete, or a local tool is missing (ssh, scp, voltage-verify) |
188
+
189
+ With `--json`, an error is also printed on stdout as
190
+ `{"error": {"code", "message", "exit_code", ...}}`.
191
+
192
+ ### Local MCP server
193
+
194
+ `vgpu mcp` serves the tools `ls`, `up`, `ps`, `exec`, `scp`, `rm`, `attest`,
195
+ `inference` and `whoami` over stdio. It runs on your machine because `exec`,
196
+ `scp` and `attest` use your SSH private key, which never leaves it. Same
197
+ guards as the command line: `up` requires `ttl` and `max_hourly_price`, `rm`
198
+ requires `confirm: true`, a 402 comes back as `API_KEY_BUDGET_EXCEEDED` with
199
+ "do not retry", the key is never part of an answer, and the sudo password of
200
+ a Confidential VM is never handed to the agent. `inference` calls the
201
+ OpenAI-compatible API with an inference key (`vgpu_...`) in
202
+ `VOLTAGEGPU_API_KEY`; a `vgpu_` value there is never sent to the pod API,
203
+ which takes the `volt_` key from `VOLT_API_KEY`.
204
+
205
+ ```bash
206
+ claude mcp add voltagegpu -e VOLT_API_KEY=volt_... -- vgpu mcp # Claude Code
207
+ ```
208
+
209
+ ```toml
210
+ # Codex: ~/.codex/config.toml
211
+ [mcp_servers.voltagegpu]
212
+ command = "vgpu"
213
+ args = ["mcp"]
214
+ env = { VOLT_API_KEY = "volt_..." }
215
+ ```
216
+
217
+ ## Python SDK
218
+
219
+ ```python
220
+ from volt.sdk import VoltageGPUClient
221
+
222
+ with VoltageGPUClient() as client: # VOLT_API_KEY or ~/.volt/config.ini
223
+ machine = client.list_machines("standard")[0] # cheapest first
224
+ result = client.deploy_standard(machine.id, name="my-pod")
225
+ pod = client.wait_until_reachable(result.pod_id)
226
+ print(pod.ssh_command)
227
+ print(client.release_pod(result.pod_id).prepaid_refund)
228
+ ```
229
+
230
+ A complete example is in [`examples/deploy_standard_pod.py`](examples/deploy_standard_pod.py).
231
+
232
+ ## REST API
233
+
234
+ The CLI is a thin client of the public API, documented at
235
+ <https://docs.voltagegpu.com/api-reference>. The same deploy with curl:
236
+
237
+ ```bash
238
+ curl -X POST https://api.voltagegpu.com/api/volt/pods \
239
+ -H "X-API-Key: $VOLT_API_KEY" -H "Content-Type: application/json" \
240
+ -d '{"provider":"standard","name":"my-pod","machine_id":"<machine_id>"}'
241
+
242
+ curl https://api.voltagegpu.com/api/volt/pods -H "X-API-Key: $VOLT_API_KEY"
243
+ ```
244
+
245
+ ## Configuration
246
+
247
+ | Setting | Where |
248
+ | --- | --- |
249
+ | API key | `--api-key` of `login`, `VOLT_API_KEY` (or `VOLTAGEGPU_API_KEY`), then `~/.volt/config.ini` |
250
+ | API base URL | `VOLT_BASE_URL` (https only, voltagegpu.com hosts unless `VOLT_ALLOW_CUSTOM_BASE_URL=1`; default `https://api.voltagegpu.com/api`) |
251
+ | Debug | `VOLT_DEBUG=1` shows tracebacks |
252
+
253
+ `voltagegpu config` shows where the key comes from, masked.
254
+
255
+ ## Security
256
+
257
+ - The key is sent only over HTTPS, in the `X-API-Key` header; redirects are
258
+ never followed and certificates are always verified.
259
+ - The key is never printed. `~/.volt/config.ini` is created readable by you
260
+ only, and `voltagegpu config` warns if its permissions are too open.
261
+ - The SSH command returned by the API is parsed into user, host and port, only
262
+ that rebuilt form is ever shown, and ssh is started without a shell (and never
263
+ from the current directory), so a tampered answer cannot run a command on
264
+ your machine. Server text is printed literally, without terminal escapes.
265
+ - `ssh-keys add` refuses private keys.
266
+
267
+ Report a vulnerability to contact@voltagegpu.com.
268
+
269
+ ## Upgrading from 1.2
270
+
271
+ - `volt cc inventory` / `volt cc deploy`: Confidential containers were retired
272
+ on 2026-10-01. Use `voltagegpu machines --confidential` and
273
+ `voltagegpu deploy confidential --tier <tier>`.
274
+ - `volt pods stop` now releases the pod and reports the refund.
275
+ - `volt account balance` is now `voltagegpu balance`.
276
+
277
+ ## Links
278
+
279
+ - Docs: <https://docs.voltagegpu.com/cli>
280
+ - API reference: <https://docs.voltagegpu.com/api-reference>
281
+ - API keys: <https://voltagegpu.com/api-keys>
282
+ - Changelog: [CHANGELOG.md](CHANGELOG.md)
283
+
284
+ MIT License.
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "voltagegpu-cli"
7
- version = "2.0.1"
7
+ version = "2.0.2"
8
8
  description = "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."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -46,7 +46,7 @@ dependencies = [
46
46
  ]
47
47
 
48
48
  [project.optional-dependencies]
49
- verify = ["voltage-verify>=0.2.1"]
49
+ verify = ["voltage-verify>=0.2.3"]
50
50
  dev = ["pytest>=8", "pytest-cov>=5", "ruff>=0.6", "build>=1.2", "twine>=5"]
51
51
 
52
52
  [project.scripts]
@@ -58,16 +58,17 @@ vgpu = "volt.cli.vgpu:main"
58
58
  Homepage = "https://voltagegpu.com"
59
59
  Documentation = "https://docs.voltagegpu.com/cli"
60
60
  "API reference" = "https://docs.voltagegpu.com/api-reference"
61
- Source = "https://github.com/VoltageGPU/VOLTAGEGPU-CLI/tree/release/1.3"
62
- Changelog = "https://github.com/VoltageGPU/VOLTAGEGPU-CLI/blob/release/1.3/CHANGELOG.md"
61
+ Source = "https://github.com/VoltageGPU/VOLTAGEGPU-CLI/tree/release/2.0"
62
+ Changelog = "https://github.com/VoltageGPU/VOLTAGEGPU-CLI/blob/release/2.0/CHANGELOG.md"
63
63
  Issues = "https://github.com/VoltageGPU/VOLTAGEGPU-CLI/issues"
64
64
 
65
65
  [tool.hatch.build.targets.wheel]
66
66
  packages = ["volt"]
67
67
 
68
68
  [tool.hatch.build.targets.sdist]
69
- include = ["/volt", "/tests", "/examples", "/README.md", "/CHANGELOG.md", "/LICENSE", "/pyproject.toml"]
70
- exclude = ["__pycache__", "*.pyc"]
69
+ # Only what builds the wheel: tests, example and changelog stay in the Git repository.
70
+ include = ["/volt", "/README.md", "/LICENSE", "/pyproject.toml"]
71
+ exclude = ["__pycache__", "*.py[cod]"]
71
72
 
72
73
  [tool.pytest.ini_options]
73
74
  testpaths = ["tests"]
@@ -1,5 +1,5 @@
1
1
  """VoltageGPU command-line interface and Python SDK."""
2
2
 
3
- __version__ = "2.0.1"
3
+ __version__ = "2.0.2"
4
4
 
5
5
  __all__ = ["__version__"]