voltagegpu-cli 2.0.0__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.
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/PKG-INFO +4 -4
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/README.md +284 -284
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/pyproject.toml +91 -90
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/__init__.py +5 -5
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/cli/cmd_account.py +179 -179
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/cli/vgpu.py +485 -475
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/mcp/__init__.py +1 -1
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/mcp/server.py +344 -344
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/sdk/attest.py +296 -296
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/sdk/catalog.py +163 -163
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/sdk/client.py +240 -240
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/sdk/errors.py +14 -4
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/sdk/fleet.py +220 -220
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/sdk/models.py +336 -336
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/sdk/remote.py +11 -0
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/sdk/ssh.py +157 -157
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/sdk/ttl.py +104 -104
- voltagegpu_cli-2.0.0/CHANGELOG.md +0 -153
- voltagegpu_cli-2.0.0/examples/deploy_standard_pod.py +0 -52
- voltagegpu_cli-2.0.0/tests/__init__.py +0 -0
- voltagegpu_cli-2.0.0/tests/conftest.py +0 -130
- voltagegpu_cli-2.0.0/tests/fixtures/ark-milan.pem +0 -37
- voltagegpu_cli-2.0.0/tests/fixtures/bundle.json +0 -822
- voltagegpu_cli-2.0.0/tests/fixtures/manifest.json +0 -11
- voltagegpu_cli-2.0.0/tests/test_cli.py +0 -261
- voltagegpu_cli-2.0.0/tests/test_cli_account.py +0 -156
- voltagegpu_cli-2.0.0/tests/test_client.py +0 -171
- voltagegpu_cli-2.0.0/tests/test_config.py +0 -101
- voltagegpu_cli-2.0.0/tests/test_hardening.py +0 -165
- voltagegpu_cli-2.0.0/tests/test_live.py +0 -42
- voltagegpu_cli-2.0.0/tests/test_models.py +0 -57
- voltagegpu_cli-2.0.0/tests/test_package.py +0 -53
- voltagegpu_cli-2.0.0/tests/test_ssh.py +0 -59
- voltagegpu_cli-2.0.0/tests/test_vgpu_attest.py +0 -252
- voltagegpu_cli-2.0.0/tests/test_vgpu_cli.py +0 -465
- voltagegpu_cli-2.0.0/tests/test_vgpu_mcp.py +0 -205
- voltagegpu_cli-2.0.0/tests/test_vgpu_remote.py +0 -65
- voltagegpu_cli-2.0.0/tests/test_vgpu_ttl.py +0 -61
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/.gitignore +0 -0
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/LICENSE +0 -0
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/__main__.py +0 -0
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/cli/__init__.py +0 -0
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/cli/cmd_deploy.py +0 -0
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/cli/cmd_machines.py +0 -0
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/cli/cmd_misc.py +0 -0
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/cli/cmd_pods.py +0 -0
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/cli/main.py +0 -0
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/cli/output.py +0 -0
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/cli/state.py +0 -0
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/sdk/__init__.py +0 -0
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/sdk/config.py +0 -0
- {voltagegpu_cli-2.0.0 → voltagegpu_cli-2.0.2}/volt/sdk/scripts/snp-proof-in-the-vm.sh +0 -0
- {voltagegpu_cli-2.0.0 → 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.
|
|
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/
|
|
9
|
-
Project-URL: Changelog, https://github.com/VoltageGPU/VOLTAGEGPU-CLI/blob/release/
|
|
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.
|
|
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.
|