cloudgpu-mcp 0.2.0 → 0.4.0

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.
package/README.md CHANGED
@@ -129,6 +129,10 @@ The same guidance is available as two [Agent Skills](https://agentskills.io):
129
129
  | `upload` / `download` | Files and folders between your computer and the instance (SFTP) |
130
130
  | `stop_instance` | Destroys the instance and stops billing |
131
131
  | `list_models` | Models on the OpenAI-compatible API, for inference without renting a GPU |
132
+ | `run_job` | Starts a GPU, runs one command and destroys the GPU, all on CloudGPU's servers; safe to retry with the same `idempotency_key` |
133
+ | `get_job` / `list_jobs` | Job status, exit code, cost, the last ~4 KB of output and the job's history |
134
+ | `cancel_job` | Stops a job and destroys its GPU |
135
+ | `connect_account` / `finish_connect` | Gets a key without copying one: the user approves this assistant in the browser with a spending limit and a number of GPUs at once |
132
136
 
133
137
  The server also provides a `train_on_cloudgpu` prompt.
134
138
 
@@ -140,13 +144,15 @@ The server also provides a `train_on_cloudgpu` prompt.
140
144
  - **Results before shutdown.** After commands have run, `stop_instance` refuses until something has been downloaded, unless the user confirms `force=true`.
141
145
  - **Secrets stay out of the chat.** The instance's SSH login is used inside this process and never returned to the model. Tool output is scrubbed of the API key and login details. Uploading `.ssh`, `.env`, key files or your whole home directory needs `allow_sensitive=true`.
142
146
  - **The instance stays manageable.** Commands that change the root password, SSH configuration, firewall or the platform's monitoring agent are refused. CloudGPU shuts down instances that it can no longer monitor.
147
+ - **Jobs are not started twice.** `run_job` sends an `Idempotency-Key`. Resending the same job returns the same job instead of starting a second GPU, and the server refuses the same key with different parameters.
148
+ - **Keys with a budget.** A key from `connect_account` has a total spending limit, a number of GPUs it may run at once and an expiry date, all enforced by CloudGPU's servers. Revoke it at https://cloudgpu.app/api and it can no longer start anything.
143
149
  - **Read-only mode.** `CLOUDGPU_READ_ONLY=1` registers only the look-up tools.
144
150
 
145
151
  ## Configuration
146
152
 
147
153
  | Env | Default | |
148
154
  |---|---|---|
149
- | `CLOUDGPU_API_KEY` | (required) | From https://cloudgpu.app/api |
155
+ | `CLOUDGPU_API_KEY` | (or `connect_account`) | From https://cloudgpu.app/api. Without it, a key saved by `finish_connect` in `~/.config/cloudgpu/credentials.json` is used |
150
156
  | `CLOUDGPU_MAX_SPEND_USD` | `50` | Highest budget the agent may set for one instance |
151
157
  | `CLOUDGPU_MAX_HOURS` | `24` | Longest time limit the agent may set |
152
158
  | `CLOUDGPU_READ_ONLY` | off | `1` = look-up tools only |
@@ -182,7 +188,7 @@ cloudgpu down <id> # destroys it and stops billing (asks first; --
182
188
  | `login` | Save an API key (input hidden, or piped on stdin); checked against the API first |
183
189
  | `offers [--template ID]` | GPU models, VRAM, live price per GPU-hour, availability |
184
190
  | `templates` | Ready-made images and the GPU each recommends |
185
- | `up --gpu MODEL [--template ID] [--count N] [--max-minutes N] [--max-spend USD] [--idle-minutes N] [--wait]` | Rent an instance; `--wait` polls until it is running or failed, then prints the SSH command and URL |
191
+ | `up --gpu MODEL [--template ID] [--count N] [--max-minutes N] [--max-spend USD] [--idle-minutes N] [--setup FILE] [--wait]` | Rent an instance; `--setup` runs a bash script once as root after hand-over (log in `/root/cloudgpu-setup.log`); `--wait` polls until it is running or failed, then prints the SSH command and URL |
186
192
  | `ls` / `status <id>` | Instances with status, minutes run and cost so far |
187
193
  | `ssh <id> [-- ARGS]` | Run `ssh` with the instance's host, port and user; `--show-password` prints the password if there is one |
188
194
  | `down <id> [--yes]` | Destroy the instance; its disk is erased, so download results first |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cloudgpu-mcp",
3
- "version": "0.2.0",
3
+ "version": "0.4.0",
4
4
  "mcpName": "io.github.mrhy7176/cloudgpu-mcp",
5
5
  "description": "MCP server and command-line tool for cloudgpu.app: let Claude Code, Cursor, Cline, opencode, goose and other MCP clients (or you, from a terminal) rent a GPU per minute, run a job, fetch the results and shut it down, with spending limits the platform enforces.",
6
6
  "type": "module",
package/rules/cloudgpu.md CHANGED
@@ -32,6 +32,19 @@ Copy this file into your project as `AGENTS.md`, `.cursor/rules/cloudgpu.md` or
32
32
  - **Do not** change the root password, edit the SSH configuration, change the firewall, or stop the platform's monitoring agent (`cgpu-*` processes). The platform must keep its access to the instance; if that access is lost, the platform shuts the instance down. The MCP server refuses such commands.
33
33
  - Never use the GPU for cryptocurrency mining or anything the [acceptable use policy](https://cloudgpu.app/aup) forbids. Instances that do so are shut down.
34
34
 
35
+ ## Jobs: one command, start to finish on CloudGPU
36
+
37
+ For a batch task that is one command (a training script, a render, a batch of inference), `run_job` is simpler than renting an instance: CloudGPU starts the GPU, runs the command, and destroys the GPU when it finishes, even if you disconnect.
38
+
39
+ - Get the user's yes on the GPU, the budget and the time limit first, as for renting.
40
+ - The GPU's disk is erased when the job ends. The command must upload its results itself (for example to the user's own S3 bucket, with credentials the user gave for that) or print them. `get_job` returns the last ~4 KB of output.
41
+ - If `run_job` times out or the connection drops, call it again with the same `idempotency_key`. You get the same job back; a second GPU is not started.
42
+ - Check progress with `get_job` every minute or so. `needs_attention` means CloudGPU stopped the job to check something by hand; tell the user and do not resubmit it.
43
+
44
+ ## No API key?
45
+
46
+ Call `connect_account` with a name for yourself and the spending limit the user wants. Show the user the link; they sign in and approve. Then call `finish_connect`. The key is saved on this computer and never shown in the chat. The user can revoke it at https://cloudgpu.app/api.
47
+
35
48
  ## Finishing (always)
36
49
 
37
50
  1. Download every result: model weights, adapters, checkpoints, logs, metrics. Destroying an instance erases its disk, and CloudGPU has no persistent storage.
package/src/api.js CHANGED
@@ -18,8 +18,11 @@ export class CloudGpuApi {
18
18
  this.userAgent = userAgent;
19
19
  }
20
20
 
21
- async request(method, path, body) {
22
- if (!this.apiKey) {
21
+ // opts.idempotencyKey: sent as Idempotency-Key; such a POST is safe to retry because the server returns the
22
+ // same job for the same key instead of starting a second GPU.
23
+ // opts.noAuth: endpoints used before there is a key (agent connect).
24
+ async request(method, path, body, opts = {}) {
25
+ if (!this.apiKey && !opts.noAuth) {
23
26
  throw new ApiError(
24
27
  401,
25
28
  "missing_api_key",
@@ -27,14 +30,17 @@ export class CloudGpuApi {
27
30
  );
28
31
  }
29
32
  let lastErr;
30
- // Retry only on network errors and 502/503/504; never on 4xx (a create must not run twice).
31
- const attempts = method === "GET" ? 3 : 1;
33
+ // Retry only on network errors and 502/503/504; never on 4xx. A POST is retried only when it carries an
34
+ // Idempotency-Key, because only then can it not start a second GPU.
35
+ const retryable = method === "GET" || Boolean(opts.idempotencyKey);
36
+ const attempts = retryable ? 3 : 1;
32
37
  for (let i = 0; i < attempts; i++) {
33
38
  try {
34
39
  const res = await this.fetch(this.baseUrl + path, {
35
40
  method,
36
41
  headers: {
37
- Authorization: `Bearer ${this.apiKey}`,
42
+ ...(this.apiKey && !opts.noAuth ? { Authorization: `Bearer ${this.apiKey}` } : {}),
43
+ ...(opts.idempotencyKey ? { "Idempotency-Key": opts.idempotencyKey } : {}),
38
44
  "Content-Type": "application/json",
39
45
  "User-Agent": this.userAgent,
40
46
  },
@@ -50,7 +56,7 @@ export class CloudGpuApi {
50
56
  if (!res.ok) {
51
57
  const e = json && json.error ? json.error : {};
52
58
  const err = new ApiError(res.status, e.code || `http_${res.status}`, e.message || `HTTP ${res.status}`);
53
- if (method === "GET" && res.status >= 502 && res.status <= 504 && i < attempts - 1) {
59
+ if (retryable && res.status >= 502 && res.status <= 504 && i < attempts - 1) {
54
60
  lastErr = err;
55
61
  await sleep(1000 * (i + 1));
56
62
  continue;
@@ -94,6 +100,35 @@ export class CloudGpuApi {
94
100
  models() {
95
101
  return this.request("GET", "/v1/models").then((r) => r.data || []);
96
102
  }
103
+
104
+ // ── jobs: start a GPU, run one command, destroy the GPU (server-side) ──
105
+ createJob(body, idempotencyKey) {
106
+ if (!idempotencyKey) throw new Error("createJob needs an idempotency key");
107
+ return this.request("POST", "/v1/jobs", body, { idempotencyKey });
108
+ }
109
+ job(id) {
110
+ return this.request("GET", `/v1/jobs/${encodeURIComponent(id)}`);
111
+ }
112
+ jobs(limit = 20) {
113
+ return this.request("GET", `/v1/jobs?limit=${encodeURIComponent(limit)}`).then((r) => r.data || []);
114
+ }
115
+ jobLogs(id) {
116
+ return this.request("GET", `/v1/jobs/${encodeURIComponent(id)}/logs`);
117
+ }
118
+ jobEvents(id) {
119
+ return this.request("GET", `/v1/jobs/${encodeURIComponent(id)}/events`).then((r) => r.data || []);
120
+ }
121
+ cancelJob(id) {
122
+ return this.request("POST", `/v1/jobs/${encodeURIComponent(id)}/cancel`, {});
123
+ }
124
+
125
+ // ── agent connect: get a key with a budget, approved by the account owner in the browser ──
126
+ connectStart(body) {
127
+ return this.request("POST", "/v1/agent/connect", body, { noAuth: true });
128
+ }
129
+ connectToken(deviceCode) {
130
+ return this.request("POST", "/v1/agent/connect/token", { device_code: deviceCode }, { noAuth: true });
131
+ }
97
132
  }
98
133
 
99
134
  export function sleep(ms) {
package/src/cli-core.js CHANGED
@@ -66,7 +66,7 @@ const COMMANDS = {
66
66
  up: {
67
67
  summary: "Rent a GPU instance",
68
68
  usage:
69
- 'cloudgpu up --gpu "RTX 4090" [--template <id>] [--count N] [--max-minutes N] [--max-spend USD] [--idle-minutes N] [--wait] [--json]',
69
+ 'cloudgpu up --gpu "RTX 4090" [--template <id>] [--count N] [--max-minutes N] [--max-spend USD] [--idle-minutes N] [--setup FILE] [--wait] [--json]',
70
70
  details: [
71
71
  "--gpu <model> GPU model as `cloudgpu offers` lists it (required)",
72
72
  "--template <id> template id from `cloudgpu templates`; omit for a plain GPU with Python and CUDA",
@@ -74,6 +74,8 @@ const COMMANDS = {
74
74
  "--max-minutes N destroy the instance N minutes after it starts (enforced by the server)",
75
75
  "--max-spend USD destroy the instance before it costs more than this (enforced by the server)",
76
76
  "--idle-minutes N destroy after the GPU is idle this long; 0 = off, otherwise 10-1440",
77
+ "--setup FILE bash script run once as root after the instance is handed over (up to 16 KB);",
78
+ " output in /root/cloudgpu-setup.log on the instance",
77
79
  "--wait poll until the instance is running or failed, then print SSH and URLs",
78
80
  "--show-password with --wait, also print the SSH password if the API returns one",
79
81
  "Costs money: billing is per minute from your prepaid balance until the instance is destroyed.",
@@ -87,6 +89,7 @@ const COMMANDS = {
87
89
  "max-minutes": { type: "string" },
88
90
  "max-spend": { type: "string" },
89
91
  "idle-minutes": { type: "string" },
92
+ setup: { type: "string" },
90
93
  wait: { type: "boolean" },
91
94
  },
92
95
  args: [],
@@ -209,6 +212,8 @@ function intOpt(values, name, min, max) {
209
212
  return Number(v);
210
213
  }
211
214
 
215
+ export const SETUP_MAX_CHARS = 16384;
216
+
212
217
  /** 把 up 的选项变成 POST /v1/gpu/instances 的请求体(gpu_model 稍后用 offers 校正大小写)。 */
213
218
  export function buildCreateBody(values) {
214
219
  if (!values.gpu || !values.gpu.trim()) throw new UsageError('--gpu is required, e.g. --gpu "RTX 4090" (see `cloudgpu offers`)', "up");
@@ -228,6 +233,19 @@ export function buildCreateBody(values) {
228
233
  if (idle > 0 && idle < 10) throw new UsageError("--idle-minutes must be 0 (off) or from 10 to 1440", "up");
229
234
  body.idle_minutes = idle;
230
235
  }
236
+ if (values.setup !== undefined) {
237
+ // 启动脚本从文件读,服务器上限 16 KB(按字符算),这里先挡一道
238
+ let script;
239
+ try {
240
+ script = fs.readFileSync(values.setup, "utf8");
241
+ } catch (e) {
242
+ throw new UsageError(`--setup: cannot read ${values.setup} (${e.code || e.message})`, "up");
243
+ }
244
+ script = script.replace(/\r\n/g, "\n").trim();
245
+ if (!script) throw new UsageError(`--setup: ${values.setup} is empty`, "up");
246
+ if (script.length > SETUP_MAX_CHARS) throw new UsageError(`--setup: script is ${script.length} characters; the limit is ${SETUP_MAX_CHARS}`, "up");
247
+ body.setup_script = script;
248
+ }
231
249
  return body;
232
250
  }
233
251
 
@@ -0,0 +1,34 @@
1
+ // Where a key obtained through "connect_account" is kept, so the user does not have to paste it anywhere.
2
+ // File: ~/.config/cloudgpu/credentials.json (or $CLOUDGPU_CONFIG_DIR), readable only by the user.
3
+ // CLOUDGPU_API_KEY in the environment always wins over the file.
4
+ import fs from "node:fs";
5
+ import os from "node:os";
6
+ import path from "node:path";
7
+
8
+ export function configDir(env = process.env) {
9
+ return env.CLOUDGPU_CONFIG_DIR || path.join(os.homedir(), ".config", "cloudgpu");
10
+ }
11
+
12
+ export function loadStoredKey(env = process.env) {
13
+ try {
14
+ const j = JSON.parse(fs.readFileSync(path.join(configDir(env), "credentials.json"), "utf8"));
15
+ if (j && typeof j.api_key === "string" && j.api_key.trim()) {
16
+ if (j.expires_at && Number(j.expires_at) * 1000 < Date.now()) return null;
17
+ return j;
18
+ }
19
+ } catch {
20
+ // no file or unreadable: no stored key
21
+ }
22
+ return null;
23
+ }
24
+
25
+ export function saveStoredKey(cred, env = process.env) {
26
+ const dir = configDir(env);
27
+ fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
28
+ const file = path.join(dir, "credentials.json");
29
+ const tmp = file + ".tmp";
30
+ fs.writeFileSync(tmp, JSON.stringify(cred, null, 2), { mode: 0o600 });
31
+ fs.renameSync(tmp, file);
32
+ fs.chmodSync(file, 0o600);
33
+ return file;
34
+ }
package/src/index.js CHANGED
@@ -16,6 +16,8 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
16
16
  import { z } from "zod";
17
17
  import { CloudGpuApi, ApiError } from "./api.js";
18
18
  import { SshPool, exec, upload, download, writeFile } from "./ssh.js";
19
+ import { loadStoredKey, saveStoredKey } from "./credentials.js";
20
+ import crypto from "node:crypto";
19
21
  import {
20
22
  checkCommand,
21
23
  sensitiveReason,
@@ -27,12 +29,14 @@ import {
27
29
  shq,
28
30
  } from "./guards.js";
29
31
 
30
- const VERSION = "0.2.0";
32
+ const VERSION = "0.4.0";
31
33
  const HERE = path.dirname(fileURLToPath(import.meta.url));
32
34
  const RULES = fs.readFileSync(path.join(HERE, "..", "rules", "cloudgpu.md"), "utf8");
33
35
 
36
+ // A key from connect_account (saved on this computer) is used when CLOUDGPU_API_KEY is not set.
37
+ const stored = loadStoredKey();
34
38
  const cfg = {
35
- apiKey: (process.env.CLOUDGPU_API_KEY || "").trim(),
39
+ apiKey: (process.env.CLOUDGPU_API_KEY || "").trim() || (stored ? stored.api_key : ""),
36
40
  baseUrl: process.env.CLOUDGPU_BASE_URL || "https://cloudgpu.app",
37
41
  maxSpend: num(process.env.CLOUDGPU_MAX_SPEND_USD, 50),
38
42
  maxHours: num(process.env.CLOUDGPU_MAX_HOURS, 24),
@@ -53,6 +57,8 @@ const session = new Map();
53
57
  const INSTRUCTIONS = `CloudGPU (cloudgpu.app) rents GPUs billed per minute from a prepaid balance.
54
58
  Workflow: get_account and list_gpus -> estimate_cost -> show the quote to the user and get an explicit yes -> create_instance -> get_status until running -> upload -> run_command (background for long jobs) -> tail_logs -> download results -> stop_instance -> report the actual cost.
55
59
  Rules: never rent without the user's yes on a quote; always set a budget and time limit (the platform shuts the instance down when either is hit); download results before stop_instance because destroying an instance erases its disk; never change passwords, SSH config, the firewall or the platform's monitoring agent on the instance; if anything fails, download what exists and stop the instance rather than leaving it running.
60
+ Jobs: for a batch task (one command that writes its results somewhere), run_job does the whole thing on CloudGPU's servers: start a GPU, run the command, destroy the GPU, with the same per-job budget and time limit. Check it with get_job. The GPU's disk is erased when the job ends, so the command must upload its results itself (for example to the user's own S3 bucket) or print them; get_job returns the last ~4 KB of output.
61
+ No API key yet? connect_account gives the user a link to approve this assistant with a spending limit; then finish_connect stores the key on this computer.
56
62
  The same API key also works for the OpenAI-compatible model API at ${cfg.baseUrl}/v1 (see list_models).`;
57
63
 
58
64
  const server = new McpServer({ name: "cloudgpu", version: VERSION }, { instructions: INSTRUCTIONS });
@@ -248,6 +254,118 @@ server.registerTool(
248
254
  }),
249
255
  );
250
256
 
257
+ // ── connect (get a key with a budget, approved in the browser) ──────────────
258
+
259
+ let pendingConnect = null;
260
+
261
+ server.registerTool(
262
+ "connect_account",
263
+ {
264
+ title: "Connect this assistant to a CloudGPU account",
265
+ description:
266
+ "Use when there is no API key. Starts an approval request and returns a link. The user opens it, signs in to cloudgpu.app and approves this assistant " +
267
+ "with a spending limit and a maximum number of GPUs at once; CloudGPU's servers enforce both. Then call finish_connect. No money is spent.",
268
+ inputSchema: {
269
+ agent_name: z.string().min(1).max(64).describe("How the user will recognise this assistant, e.g. 'Claude Code on Yang's laptop'"),
270
+ spend_limit_usd: z.number().min(1).max(10000).describe("Total this key may ever spend, in USD; ask the user"),
271
+ max_concurrent: z.number().int().min(1).max(10).default(1).describe("GPUs or jobs this key may run at once"),
272
+ expires_in_days: z.number().int().min(1).max(90).default(30),
273
+ },
274
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
275
+ },
276
+ wrap(async ({ agent_name, spend_limit_usd, max_concurrent = 1, expires_in_days = 30 }) => {
277
+ const r = await api.connectStart({ agent_name, spend_limit_usd, max_concurrent, expires_in_days });
278
+ pendingConnect = { device_code: r.device_code, until: Date.now() + Number(r.expires_in || 600) * 1000, interval: Number(r.interval || 5) };
279
+ return ok({
280
+ link: r.verification_uri_complete,
281
+ code: r.user_code,
282
+ expires_in_seconds: r.expires_in,
283
+ next: "Show the link to the user and ask them to open it, sign in and approve. Then call finish_connect.",
284
+ });
285
+ }),
286
+ );
287
+
288
+ server.registerTool(
289
+ "finish_connect",
290
+ {
291
+ title: "Finish connecting",
292
+ description:
293
+ "After the user approved the link from connect_account: waits up to about a minute for the approval, then stores the new key on this computer " +
294
+ "(~/.config/cloudgpu/credentials.json, readable only by the user) and uses it from now on. The key itself is never shown.",
295
+ inputSchema: {},
296
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
297
+ },
298
+ wrap(async () => {
299
+ if (!pendingConnect) return fail("No approval is pending. Call connect_account first.");
300
+ const deadline = Math.min(Date.now() + 60_000, pendingConnect.until);
301
+ for (;;) {
302
+ try {
303
+ const cred = await api.connectToken(pendingConnect.device_code);
304
+ const file = saveStoredKey({
305
+ api_key: cred.api_key,
306
+ key_id: cred.key_id,
307
+ agent_name: cred.agent_name,
308
+ spend_limit_usd: cred.spend_limit_usd,
309
+ max_concurrent: cred.max_concurrent,
310
+ expires_at: cred.expires_at,
311
+ base_url: cfg.baseUrl,
312
+ });
313
+ cfg.apiKey = cred.api_key;
314
+ api.apiKey = cred.api_key;
315
+ pendingConnect = null;
316
+ return ok({
317
+ connected: true,
318
+ agent_name: cred.agent_name,
319
+ spend_limit_usd: cred.spend_limit_usd,
320
+ max_concurrent: cred.max_concurrent,
321
+ expires_at: cred.expires_at,
322
+ saved_to: file,
323
+ note: "The account owner can revoke this key at any time at https://cloudgpu.app/api.",
324
+ });
325
+ } catch (err) {
326
+ if (err instanceof ApiError && err.code === "authorization_pending" && Date.now() + pendingConnect.interval * 1000 < deadline) {
327
+ await new Promise((r) => setTimeout(r, pendingConnect.interval * 1000));
328
+ continue;
329
+ }
330
+ if (err instanceof ApiError && err.code === "authorization_pending") {
331
+ return fail("Not approved yet. Ask the user to open the link and approve, then call finish_connect again.");
332
+ }
333
+ if (err instanceof ApiError && (err.code === "access_denied" || err.code === "expired_token")) pendingConnect = null;
334
+ throw err;
335
+ }
336
+ }
337
+ }),
338
+ );
339
+
340
+ // ── jobs (read) ───────────────────────────────────────────────────────────
341
+
342
+ server.registerTool(
343
+ "get_job",
344
+ {
345
+ title: "Job status",
346
+ description:
347
+ "Status of a job (queued / provisioning / running / stopping / succeeded / failed / cancelled / needs_attention), exit code, cost so far, " +
348
+ "the last ~4 KB of the command's output and the job's event history.",
349
+ inputSchema: { job_id: z.string() },
350
+ annotations: { readOnlyHint: true, openWorldHint: true },
351
+ },
352
+ wrap(async ({ job_id }) => {
353
+ const [job, logs, events] = await Promise.all([api.job(job_id), api.jobLogs(job_id).catch(() => null), api.jobEvents(job_id).catch(() => [])]);
354
+ return ok({ ...job, output_tail: logs ? logs.tail : null, events });
355
+ }),
356
+ );
357
+
358
+ server.registerTool(
359
+ "list_jobs",
360
+ {
361
+ title: "List jobs",
362
+ description: "Recent jobs on this account with status and cost.",
363
+ inputSchema: { limit: z.number().int().min(1).max(100).default(20) },
364
+ annotations: { readOnlyHint: true, openWorldHint: true },
365
+ },
366
+ wrap(async ({ limit = 20 }) => ok({ jobs: await api.jobs(limit) })),
367
+ );
368
+
251
369
  // ── instances (read) ─────────────────────────────────────────────────────
252
370
 
253
371
  server.registerTool(
@@ -283,7 +401,8 @@ if (!cfg.readOnly) {
283
401
  description:
284
402
  "Rents the GPU from a quote. Costs money. Requires a quote_id from estimate_cost that the user has approved. " +
285
403
  "max_spend_usd and max_hours are enforced by CloudGPU's servers: the instance is destroyed when either is reached, even if this assistant has disconnected. " +
286
- "idle_minutes destroys it after the GPU sits idle that long (installing packages and downloading data count as idle, so allow for setup).",
404
+ "idle_minutes destroys it after the GPU sits idle that long (installing packages and downloading data count as idle, so allow for setup). " +
405
+ "setup_script (optional bash) runs once as root after the instance is handed over; its output is in /root/cloudgpu-setup.log.",
287
406
  inputSchema: {
288
407
  quote_id: z.string(),
289
408
  user_confirmed: z.boolean().describe("true only if the user explicitly approved this quote in the conversation"),
@@ -296,10 +415,15 @@ if (!cfg.readOnly) {
296
415
  .max(1440)
297
416
  .default(60)
298
417
  .describe("Destroy after the GPU has been idle this long; 0 turns it off; otherwise at least 10"),
418
+ setup_script: z
419
+ .string()
420
+ .max(16384)
421
+ .optional()
422
+ .describe("Optional bash script run once as root in the background after the instance is handed over; output in /root/cloudgpu-setup.log"),
299
423
  },
300
424
  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
301
425
  },
302
- wrap(async ({ quote_id, user_confirmed, max_spend_usd, max_hours, idle_minutes = 60 }) => {
426
+ wrap(async ({ quote_id, user_confirmed, max_spend_usd, max_hours, idle_minutes = 60, setup_script }) => {
303
427
  if (user_confirmed !== true) {
304
428
  return fail("Not rented: show the quote to the user and wait for an explicit yes, then call again with user_confirmed=true.");
305
429
  }
@@ -330,6 +454,7 @@ if (!cfg.readOnly) {
330
454
  idle_minutes,
331
455
  };
332
456
  if (quote.template) body.template = quote.template;
457
+ if (setup_script && setup_script.trim()) body.setup_script = setup_script;
333
458
  const inst = await api.create(body);
334
459
  track(inst.id);
335
460
  return ok({
@@ -339,6 +464,66 @@ if (!cfg.readOnly) {
339
464
  }),
340
465
  );
341
466
 
467
+ server.registerTool(
468
+ "run_job",
469
+ {
470
+ title: "Run a job on a GPU",
471
+ description:
472
+ "Costs money. CloudGPU starts a GPU, runs one bash command on it, then destroys the GPU, all on its servers, so it finishes even if this assistant disconnects. " +
473
+ "max_spend_usd and max_hours are enforced by the servers. Retrying with the same idempotency_key never starts a second GPU; this tool generates one if you leave it out and returns it. " +
474
+ "The disk is erased when the job ends: the command must upload its own results (for example to the user's storage) or print them. " +
475
+ "Requires the user's explicit yes on the GPU, budget and time limit.",
476
+ inputSchema: {
477
+ command: z.string().min(1).max(32768).describe("bash command or script to run on the GPU"),
478
+ gpu_model: z.string().optional().describe("GPU model exactly as list_gpus returns it"),
479
+ template: z.string().optional().describe("Template id from list_templates"),
480
+ gpu_count: z.number().int().min(1).max(8).default(1),
481
+ disk_gb: z.number().int().optional().describe("Larger system disk: 100, 200 or 500; omit for the standard disk"),
482
+ max_spend_usd: z.number().positive().describe(`Budget for this job in USD (at most ${cfg.maxSpend})`),
483
+ max_hours: z.number().positive().describe(`Hard time limit in hours (at most ${cfg.maxHours})`),
484
+ user_confirmed: z.boolean().describe("true only if the user explicitly approved the GPU, budget and time limit"),
485
+ idempotency_key: z.string().max(128).optional().describe("Reuse the same value when retrying the same job"),
486
+ },
487
+ annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
488
+ },
489
+ wrap(async ({ command, gpu_model, template, gpu_count = 1, disk_gb, max_spend_usd, max_hours, user_confirmed, idempotency_key }) => {
490
+ if (user_confirmed !== true) {
491
+ return fail("Not started: tell the user the GPU, budget and time limit, wait for an explicit yes, then call again with user_confirmed=true.");
492
+ }
493
+ if (!gpu_model && !template) return fail("Give gpu_model or template.");
494
+ if (max_spend_usd > cfg.maxSpend) {
495
+ return fail(`max_spend_usd ${max_spend_usd} is above this server's cap of ${cfg.maxSpend} (CLOUDGPU_MAX_SPEND_USD).`);
496
+ }
497
+ if (max_hours > cfg.maxHours) {
498
+ return fail(`max_hours ${max_hours} is above this server's cap of ${cfg.maxHours} (CLOUDGPU_MAX_HOURS).`);
499
+ }
500
+ const refused = checkCommand(command);
501
+ if (refused) return fail(refused);
502
+ const key = idempotency_key || crypto.randomUUID();
503
+ const body = { command, gpu_count, max_minutes: Math.ceil(max_hours * 60), max_spend_usd };
504
+ if (gpu_model) body.gpu_model = gpu_model;
505
+ if (template) body.template = template;
506
+ if (disk_gb) body.disk_gb = disk_gb;
507
+ const job = await api.createJob(body, key);
508
+ return ok({
509
+ ...job,
510
+ idempotency_key: key,
511
+ next: "Call get_job at intervals (every minute or so, not in a tight loop) until status is succeeded, failed or cancelled, then report the cost.",
512
+ });
513
+ }),
514
+ );
515
+
516
+ server.registerTool(
517
+ "cancel_job",
518
+ {
519
+ title: "Cancel a job",
520
+ description: "Stops a job: if a GPU was started it is destroyed and billing stops. Output not yet uploaded by the command is lost.",
521
+ inputSchema: { job_id: z.string() },
522
+ annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
523
+ },
524
+ wrap(async ({ job_id }) => ok(await api.cancelJob(job_id))),
525
+ );
526
+
342
527
  server.registerTool(
343
528
  "run_command",
344
529
  {