cloudgpu-mcp 0.3.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 |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cloudgpu-mcp",
3
- "version": "0.3.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) {
@@ -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.3.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(
@@ -346,6 +464,66 @@ if (!cfg.readOnly) {
346
464
  }),
347
465
  );
348
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
+
349
527
  server.registerTool(
350
528
  "run_command",
351
529
  {