How to reuse a running GPU over remote MCP

An MCP client should look for a compatible running rental before requesting a new quote, and reuse that same instance_id only while it is running and the next work stays inside the original max_spend_usd, max_hours, and idle_minutes. A stopped record, a Workspace version, or a previous Job id is not a running GPU. If reuse is not valid, get a fresh quote and owner approval rather than starting a second machine blindly.

Cap fields and enforcement are in How to set GPU budget caps over remote MCP. Keeping files is in How to save GPU results over remote MCP. The pricing page is the billing source.

Preconditions

The owner authorizes the MCP connection first. Remote Streamable HTTP is https://cloudgpu.app/mcp. Local stdio is the published cloudgpu-mcp 0.16.3 package. Setup is in the MCP guide. After authorization, read the tool list that session returns. Local and remote tool sets differ. Remote orchestration does not read local files or provide local SSH transfers. If a name below is missing, skip it.

On 2026-11-15, GET /v1/public/compute-capabilities reported full_disk_restore false, apply_workspace true, workspaces true, job_rerun true, storage true, and automatic_output_collection true. Read that document again before relying on Workspace or Job output collection.

Find a reusable rental

Call get_account and list_instances first. Both take no parameters in cloudgpu-mcp 0.16.3. get_account reports the balance, how many instances the account may run at once, and how many are running now. list_instances returns running instances, starting instances, and stopped records from the last 7 days, with cost. Then call get_status on a candidate:

{
  "instance_id": "<id from list_instances>"
}

get_status reports status (creating, running, stopped, or failed), minutes run, cost so far, whether SSH is ready, api_url when the template has one, and the auto-shutdown limits. The OpenAPI instance limits object has max_minutes, max_spend_usd, idle_minutes, expires_at, and stopped_by. expires_at is the Unix time when max_minutes ends the instance. stopped_by is max_minutes, max_spend, or idle when one of those limits ended the instance, and null otherwise. The 0.16.3 local client passes that object through, returns ssh_ready, and removes the SSH host, user, and password before the model sees the object. There is no remaining-budget field. Compare the next work with those original limits and with cost so far and minutes run.

Reuse only a row whose get_status status is running and that already has the needed software or files. A stopped record from that 7-day list is not a persistent disk. stop_instance erases the disk. A listed GPU, or a past Job id, is not proof that the next task fits the remaining caps.

Continue work on that instance

run_command is a local stdio tool in cloudgpu-mcp 0.16.3. It opens an SSH session from the computer running that process. tail_logs, upload, and download are the same kind of tool: tail_logs uses that SSH session, and upload / download use SFTP with a path on that computer. The published remote descriptor excludes local filesystem and SSH tools. Do not call run_command over remote MCP. The 0.16.3 schema has no remote MCP tool that runs a shell on an existing instance_id.

On local stdio, when run_command is listed, continue on that same instance_id. Do not send gpu_model. gpu_model is an input for a new create_instance or run_job, not for an existing rental.

{
  "instance_id": "<running instance id>",
  "command": "<the command the owner approved>",
  "background": false,
  "timeout_sec": 600,
  "workdir": "~"
}

background defaults to false. timeout_sec applies to a foreground command, defaults to 600, and accepts 5 through 3600. workdir defaults to ~. For a long command, set background to true and follow it with tail_logs. The agent rules say to check ownership, readiness, and whether the instance still has memory and disk for that command. Do not keep an idle GPU running only to consume time that was already authorized.

On remote MCP, continue on that rental only with a tool the session actually lists that does not need a local path. When apply_workspace is listed, it copies a saved Workspace version onto the running GPU. It does not run a command. When the get_status result includes api_url, that value is the template’s public HTTPS endpoint while status is running. Use the endpoint from that response. The ComfyUI HTTP path is How to run ComfyUI over remote MCP. A missing run_command is a reason to skip the shell, not a reason to invent one.

Workspace, the running rental, and a new Job

Workspace reuses selected project files. It does not reuse the operating system, installed packages, or custom nodes. With full_disk_restore false, a version is not a disk image.

save_workspace takes local_dir on the computer running local stdio, not a path on the rented GPU. A remote session must not pass an instance path to save_workspace or upload_artifact. When the documented path is a client file, download the outputs locally first. Parameters are in the save-results guide.

When apply_workspace is listed, and the live capability is true, call it only after the owner confirms:

{
  "version_id": "<saved workspace version id>",
  "instance_id": "<running instance id>",
  "user_confirmed": true
}

That call restores the version into a new private directory. Rental billing continues. It does not replace the instance, install dependencies, execute code, or overwrite existing files. Then call get_workspace_application with the same version_id and instance_id. Documented states are not_started, applying, applied, failed, busy, conflict, and needs_attention. applied includes the project path. The status is not available after the instance ends, and it is not billing or release evidence. list_workspace_instances lists running GPUs this key can access. A budgeted agent key can apply only to instances that same key created. An uncertain application is inspected, not retried, and it is not permission to stop the instance.

run_job and prepare_job_rerun provision separately. run_job does not take instance_id. prepare_job_rerun takes only job_id:

{
  "job_id": "<id of a successful Job>"
}

It reads the original command, pinned model references, and Workspace from that successful Job. It does not start a GPU. It does not reuse the old quote or the old idempotency key. A new Job needs a fresh quote and a new approval. Quote clocks and cap fields stay in the budget-caps guide. Project-file reuse across tasks is the project reuse example.

When not to reuse

Get a new quote and wait for approval when any of these is true:

• get_status is stopped, failed, or still creating. A Job whose status is needs_attention, or a Workspace application in needs_attention, is not a running GPU. The agent guide says a needs_attention Job is not retried automatically.
• The original max_spend_usd, max_minutes / expires_at, and idle_minutes, read against cost so far and minutes run, will not cover download, setup, and the next command.
• The needed software or files are not on that disk.
• The caps have to change. cloudgpu-mcp 0.16.3 has no tool that changes max_spend_usd, max_hours, or idle_minutes on a running rental.

create_instance is not idempotent. Do not retry an uncertain allocation blindly. If a create call’s result is unknown, call list_instances and look for an instance already created before calling create_instance again. The quote clocks are in the budget-caps guide.

Save and release

Stopping the GPU is separate from keeping files. stop_instance erases the disk. A Job releases its GPU when the command ends. Confirm saved files, or Job output_collection status succeeded, before stop_instance and before treating a finished Job as saved. The parameter walkthrough is the save-results guide.

A lost response or an ambiguous state does not authorize another allocation. Keep the original instance id or Job id and poll that id. stopping on a Job, and needs_attention, are not a confirmed release and are not permission to allocate again.

Exceptions

Local stdio and remote MCP do not expose the same tools. run_command stays on local stdio. Stopped rows in list_instances are records from the last 7 days, not disks. Workspace is not a full-disk restore while full_disk_restore is false. prepare_job_rerun is a new provision. Caps on a running rental stay at the original values. Collection can fail and the GPU can still be released. That failure does not authorize another allocation.

Related

Rent, reuse, and release boundaries are in the rent-and-reuse guide. Quotes and Jobs are in GPU Jobs for AI agents and the quote and reuse note. Tool rules are in AGENTS.md. Connection wording is in the MCP guide and the agent guide.

Questions and answers

Can a stopped instance be reused as a disk?

No. list_instances includes running instances, starting instances, and stopped records from the last 7 days. get_status status values are creating, running, stopped, and failed. Reuse only status running. stop_instance erases the instance disk. A stopped record is not a persistent disk, and a Workspace version is not that disk.

Does Workspace restore installed packages?

No. On 2026-11-15, GET /v1/public/compute-capabilities reported full_disk_restore false. save_workspace stores selected regular project files. apply_workspace, when listed, restores that version into a new private directory on a running GPU. It does not install dependencies, restore the operating system, or restore custom nodes. Rental billing continues, and the call does not replace the instance.

Do run_job and prepare_job_rerun reuse the same GPU?

No. run_job starts a GPU, runs one command, and releases that GPU when the command ends. It does not take the existing instance_id. prepare_job_rerun reads parameters from a successful Job and does not start a GPU. It does not reuse the old quote or the old idempotency key. A new Job needs a fresh quote and a new approval.

Can the agent raise caps to keep a running rental?

No. cloudgpu-mcp 0.16.3 has no tool that changes max_spend_usd, max_hours, or idle_minutes on a running instance. Reuse that instance_id only while get_status shows it running and the next work stays inside the original caps. A higher limit on this rental is a new quote and a new owner approval for a new allocation. A higher key limit does not change the caps already set on the running rental. Do not keep an idle GPU running only to consume time that was already authorized.