voltagegpu-cli 1.3.1__tar.gz → 2.0.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 (53) hide show
  1. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/CHANGELOG.md +44 -0
  2. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/PKG-INFO +105 -5
  3. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/README.md +284 -184
  4. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/pyproject.toml +6 -5
  5. voltagegpu_cli-2.0.1/tests/fixtures/ark-milan.pem +37 -0
  6. voltagegpu_cli-2.0.1/tests/fixtures/bundle.json +822 -0
  7. voltagegpu_cli-2.0.1/tests/fixtures/manifest.json +11 -0
  8. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/tests/test_cli.py +261 -261
  9. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/tests/test_cli_account.py +156 -141
  10. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/tests/test_config.py +11 -0
  11. voltagegpu_cli-2.0.1/tests/test_vgpu_attest.py +252 -0
  12. voltagegpu_cli-2.0.1/tests/test_vgpu_cli.py +494 -0
  13. voltagegpu_cli-2.0.1/tests/test_vgpu_mcp.py +205 -0
  14. voltagegpu_cli-2.0.1/tests/test_vgpu_remote.py +77 -0
  15. voltagegpu_cli-2.0.1/tests/test_vgpu_ttl.py +61 -0
  16. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/volt/__init__.py +1 -1
  17. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/volt/cli/cmd_account.py +4 -1
  18. voltagegpu_cli-2.0.1/volt/cli/vgpu.py +485 -0
  19. voltagegpu_cli-2.0.1/volt/mcp/__init__.py +1 -0
  20. voltagegpu_cli-2.0.1/volt/mcp/server.py +344 -0
  21. voltagegpu_cli-2.0.1/volt/sdk/attest.py +296 -0
  22. voltagegpu_cli-2.0.1/volt/sdk/catalog.py +163 -0
  23. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/volt/sdk/client.py +240 -236
  24. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/volt/sdk/config.py +2 -1
  25. voltagegpu_cli-2.0.1/volt/sdk/fleet.py +220 -0
  26. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/volt/sdk/models.py +336 -332
  27. voltagegpu_cli-2.0.1/volt/sdk/remote.py +140 -0
  28. voltagegpu_cli-2.0.1/volt/sdk/scripts/snp-proof-in-the-vm.sh +216 -0
  29. voltagegpu_cli-2.0.1/volt/sdk/scripts/two-proofs-in-the-vm.sh +51 -0
  30. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/volt/sdk/ssh.py +157 -157
  31. voltagegpu_cli-2.0.1/volt/sdk/ttl.py +104 -0
  32. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/.gitignore +0 -0
  33. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/LICENSE +0 -0
  34. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/examples/deploy_standard_pod.py +0 -0
  35. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/tests/__init__.py +0 -0
  36. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/tests/conftest.py +0 -0
  37. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/tests/test_client.py +0 -0
  38. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/tests/test_hardening.py +0 -0
  39. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/tests/test_live.py +0 -0
  40. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/tests/test_models.py +0 -0
  41. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/tests/test_package.py +0 -0
  42. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/tests/test_ssh.py +0 -0
  43. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/volt/__main__.py +0 -0
  44. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/volt/cli/__init__.py +0 -0
  45. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/volt/cli/cmd_deploy.py +0 -0
  46. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/volt/cli/cmd_machines.py +0 -0
  47. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/volt/cli/cmd_misc.py +0 -0
  48. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/volt/cli/cmd_pods.py +0 -0
  49. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/volt/cli/main.py +0 -0
  50. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/volt/cli/output.py +0 -0
  51. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/volt/cli/state.py +0 -0
  52. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/volt/sdk/__init__.py +0 -0
  53. {voltagegpu_cli-1.3.1 → voltagegpu_cli-2.0.1}/volt/sdk/errors.py +0 -0
@@ -4,6 +4,50 @@ All notable changes to `voltagegpu-cli` are documented here. The format follows
4
4
  [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
5
5
  [Semantic Versioning](https://semver.org/).
6
6
 
7
+ ## [2.0.1] - 2026-10-27
8
+
9
+ Found by an end-to-end test of the agent offer in production.
10
+
11
+ ### Fixed
12
+ - `vgpu attest` names the NVIDIA GPU in its verdict when the GPU checks passed:
13
+ `VERIFIED: Intel TDX + NVIDIA GPU, challenge ...` (the JSON `tee` field is unchanged).
14
+ - `vgpu whoami` shows budgets and spend to the cent (it printed `0.18999999999999995`); `--json`
15
+ keeps the exact values.
16
+ - `vgpu scp` explains a Windows remote path: Git Bash rewrites an absolute remote path such as
17
+ `/tmp/out.tgz` into `C:/.../Temp/out.tgz`. Use a path relative to the remote home, or
18
+ `MSYS_NO_PATHCONV=1`.
19
+
20
+ ## [2.0.0] - 2026-10-27
21
+
22
+ ### Added
23
+ - `vgpu`, a second command for scripts and AI agents: `ls`, `up`, `ps`,
24
+ `exec` (with `-d`), `scp`, `rm`, `attest`, `whoami`. One catalogue for
25
+ Confidential VMs (Intel TDX), Confidential CPU (AMD SEV-SNP), standard GPU
26
+ pods, dedicated machines and sandboxes, cheapest first.
27
+ - `--ttl` on every `vgpu up`, translated to the auto-stop of each product and
28
+ checked against its bounds before anything is sent.
29
+ - `vgpu attest`: challenge drawn locally, embedded proof scripts pinned by
30
+ SHA-256, archive extracted safely and verified locally. For Confidential
31
+ CPU the SEV-SNP report is requested at `--vmpl` (0 by default), and its VMPL
32
+ field must be the level requested (VMPL 1 is no longer required: it was
33
+ snpguest's default request, not the guest's level).
34
+ - `vgpu mcp`, a local MCP server over stdio with the same tools and guards
35
+ (`up` needs `ttl` and `max_hourly_price`, `rm` needs `confirm`), plus
36
+ `inference` on the OpenAI-compatible API with a `vgpu_` key.
37
+ - Documented exit codes, including 6 for HTTP 402 (`API_KEY_BUDGET_EXCEEDED`)
38
+ and 4 for `API_KEY_SCOPE_MISSING`.
39
+ - `vgpu up --ssh-key-id` (`ssh_key_ids` in `vgpu mcp`) on a standard GPU too:
40
+ one key id, needed when the account has several SSH keys. Without it, the
41
+ API's 400 becomes a clear message (exit 2, `SSH_KEY_ID_REQUIRED`).
42
+
43
+ ### Changed
44
+ - `voltagegpu balance` no longer shows `$0.00` when the key cannot read the
45
+ balance (agent key without the billing scope): it says the balance is hidden.
46
+ - A `vgpu_` inference key in `VOLTAGEGPU_API_KEY` is no longer taken for the
47
+ pod API key; the next source (config file) is used.
48
+ - `voltagegpu` and `volt` are otherwise unchanged. The major version marks the new
49
+ command and its exit-code contract.
50
+
7
51
  ## [1.3.1] - 2026-10-10
8
52
 
9
53
  Security hardening after an independent review of 1.3.0. Upgrade recommended.
@@ -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.1
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
@@ -1,184 +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
- ## 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.
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.