CloudGPU for AI agents: integration guide

Q: Is the quote a price guarantee?

No. It is an estimate valid for 5 minutes. Pass quote_id when you start the instance: if the price went up or the GPU is gone, the call fails instead of starting a dearer GPU.

Q: Why can a task be within budget but not startable?

within_budget compares the estimated cost with your budget. Starting also needs required_starting_balance in your account, because one hour is pre-authorised. Send your API key with the quote to get can_start_with_balance.

Q: Can a job start two GPUs if my request is sent twice?

No, as long as both requests carry the same Idempotency-Key: the second returns the first job. If CloudGPU's service restarts while it is starting the GPU, it checks for that GPU before trying again and stops the job as needs_attention when it cannot tell, rather than start another.

This guide is for agents and the people who build them. It covers a public GPU catalog, a quote API, connect links that give an agent its own key with a budget, the Jobs API, and the GPU instances API. The MCP server uses the same endpoints. The machine-readable description of every endpoint is at openapi.json.

Base URL: https://cloudgpu.app. Errors always look like {"error": {"type", "code", "message"}}.

Owner flow: one link to connect, no key pasted into chat

Start from the Agent page, copy the public integration instructions and give them to your tool-enabled agent. An installed MCP client can call connect_account and finish_connect; an HTTPS agent can use the REST connect flow below. The owner opens the session-specific link and checks its limits. The approval page does not display the resulting secret key. A static /connect link alone does not connect an arbitrary agent session.

Keep the spending proposal separate and explicit. Within an approved task, the agent can manage the execution; it must not treat connection approval as permission for unrelated paid work. Discovery is public; persistent storage and execution still enforce account eligibility and key scope.

Reuse a saved project

The person uploading files uses Workspace: upload files, select them, create a project and save a version. Renting in the web UI can carry that version to the instance page; the owner confirms application after the GPU is ready. This is an explicit file restore, not automatic disk backup or dependency installation. Billing continues during transfer; check the returned project directory before running code.

An agent uses save_workspace / list_workspace_versions, then run_job(workspace_version_id=...) for a new batch Job, or apply_workspace for an existing running instance it is allowed to access. Do not destroy a user’s running instance because file application fails. Source version expiry must not hide the status or directory of an application that already started.

Pinned public model references and successful-Job rerun preparation are available. Read /v1/public/compute-capabilities: do not submit model_references unless that capability is explicitly true. MCP 0.9.0 provides the matching model/rerun tools; inspect the installed tool list before using them. There is no separate Agent Job web console; use REST/MCP and report status, results and cost to the owner.

1. Discover: the public GPU catalog

GET /v1/public/gpu-catalog. No key needed.

curl -s https://cloudgpu.app/v1/public/gpu-catalog

Field	Meaning
`gpus[]`	`model`, `vram_gb`, `price_per_gpu_hour_usd`, `min_gpu_count`, `availability` (`available`, `limited`, `unavailable`), `tier`
`billing`	`increment_seconds`, `minimum_seconds`, `preauthorized_seconds`, `description`
`disk_options[]`	`disk_gb` and `addon_per_hour_usd` for each system disk size you can request; `0` is the standard disk
`templates[]`	Ready templates with `id`, `recommended_gpu` and `min_vram_gb`
`generated_at`, `cache_ttl_seconds`	When the data was read, and how long you may cache it

Prices and availability change during the day. Read the catalog, or request a quote, right before you start an instance.

2. Quote: estimate a task

POST /v1/quotes. No key needed. Send a key to also learn whether your balance can start each candidate.

curl -s https://cloudgpu.app/v1/quotes \
  -H 'Content-Type: application/json' \
  -d '{
    "requirements": {"min_vram_gb": 24, "gpu_count": 1},
    "estimated_duration_seconds": 1800,
    "max_budget_usd": "1.00",
    "sort_by": "estimated_total_cost"
  }'

requirements can also carry gpu_model, template and disk_gb. Each entry in candidates[] has:

Field	Meaning
`estimated_total_cost`	USD the task is expected to use: billed minutes × the instance’s hourly price
`required_starting_balance`	USD your balance needs to start the instance. One hour is pre-authorised at start, so this is often higher than the estimate for short tasks
`within_budget`	Whether `estimated_total_cost` is within `max_budget_usd`. It does not mean you can start now
`can_start_with_balance`	Only set when you send an API key: whether that account’s balance covers `required_starting_balance`. `null` without a key
`instance_price_per_hour_usd`, `billed_minutes`, `availability`	The inputs to the estimate
`supports_jobs`	Whether this GPU can run a job with `POST /v1/jobs` right now. Some GPUs can only be rented as instances

A quote has an id and an expires_at 5 minutes later. It is an estimate (price_guarantee: "estimate"), not a reservation.

3. Connect: get a key with a budget

An agent without a key asks the account owner for one. Nothing is charged.

curl -s https://cloudgpu.app/v1/agent/connect \
  -H 'Content-Type: application/json' \
  -d '{"agent_name":"Build agent on ci-runner-3","spend_limit_usd":20,"max_concurrent":1,"expires_in_days":30}'

The response has a device_code (keep it secret, in the agent), a user_code such as ABCD-EFGH and a verification_uri_complete link. Show the link to the account owner. They sign in, check the agent’s name and limits, may lower them, and approve or decline.

Meanwhile call POST /v1/agent/connect/token with {"device_code": "..."} every interval seconds. It returns 400 authorization_pending until the owner approves, 403 access_denied if they decline, and 400 expired_token after 10 minutes. On approval it returns api_key once, with spend_limit_usd, max_concurrent and expires_at.

That key is refused, on CloudGPU’s servers, when:

a job or instance would take its total spend over spend_limit_usd (403 key_budget_exceeded). Unfinished jobs and instances count at their max_spend_usd, finished ones at what they cost, so every request with this key must set max_spend_usd;
it already runs max_concurrent jobs or instances (429 key_concurrency_exceeded);
it has expired or the owner revoked it on the API page (401). A revoked key cannot start anything, and a job it queued that has not started a GPU yet is stopped.

4. Run a job

POST /v1/jobs runs one bash command on a GPU from start to finish: CloudGPU starts the GPU, runs the command, and destroys the GPU when the command exits, on its servers. Needs a key and an Idempotency-Key header.

curl -s https://cloudgpu.app/v1/jobs \
  -H "Authorization: Bearer $CLOUDGPU_API_KEY" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 6f1c0a2e-6e0b-4b3a-9a59-2d9c3f1c7e11' \
  -d '{
    "gpu_model": "RTX 4090",
    "command": "python train.py && rclone copy out/ mystorage:run1",
    "max_minutes": 60,
    "max_spend_usd": 2.00
  }'

Field	Meaning
`command`	Bash, run once. The GPU’s disk is erased when the job ends: upload results from the command itself, or print them
`gpu_model`, `template`, `gpu_count`, `disk_gb`, `quote_id`	As for instances below. `quote_id` binds the job to a quote
`max_minutes`, `max_spend_usd`	Required. Limits for the whole job, enforced by CloudGPU’s servers

Idempotency. Use a new Idempotency-Key (a UUID) for each new job, and the same one when you retry. The same key with the same request returns the existing job (200, header Idempotent-Replayed: true) and never starts a second GPU, so it is safe to retry after a timeout. The same key with different parameters returns 409 idempotency_key_reused.

The call returns 202 with the job. Read it with GET /v1/jobs/{id}:

`status`	Meaning
`queued`	Accepted, no GPU yet
`provisioning`	Starting the GPU
`running`	The command is running
`stopping`	The command finished, or a limit or a cancel was hit; the GPU is being destroyed
`succeeded`	The command exited with code 0 and the GPU is destroyed
`failed`	See `error.code`: `command_failed` (non-zero `exit_code`), `time_limit_reached`, `spend_limit_reached`, `insufficient_balance`, `provisioning_failed`, `credential_revoked` and others
`cancelled`	Cancelled with `POST /v1/jobs/{id}/cancel`
`needs_attention`	CloudGPU stopped the job because it could not confirm the state of its GPU after an error. It is not retried automatically and the team is alerted. Do not resubmit it with a new key; contact support if it stays there

A job also has exit_code, cost_usd, instance_id, and timestamps. GET /v1/jobs/{id}/logs returns the last ~4 KB of the command’s output and GET /v1/jobs/{id}/events its history. A job keeps running if your session ends, and stops at its limits.

5. Or rent an instance

POST /v1/gpu/instances. Needs Authorization: Bearer <api key>; keys start with cgw-sk- and are created at cloudgpu.app/api.

curl -s https://cloudgpu.app/v1/gpu/instances \
  -H "Authorization: Bearer $CLOUDGPU_API_KEY" -H 'Content-Type: application/json' \
  -d '{
    "quote_id": "quote_...",
    "max_minutes": 40,
    "max_spend_usd": 1.00,
    "idle_minutes": 20
  }'

Field	Meaning
`gpu_model` or `template`	What to start. With `quote_id` and no `gpu_model`, the quote’s first candidate is used
`quote_id`	Optional. Binds the start to the quote: `gpu_count`, `template` and `disk_gb` you leave out are taken from the quote, and ones you send must match it. Fails with `409` and starts nothing if the quote expired, the configuration differs, the GPU is gone or its price went up (see the error table)
`max_minutes`, `max_spend_usd`, `idle_minutes`	Limits that CloudGPU’s servers enforce. The instance is destroyed when one is reached, even if your session has ended
`setup_script`	Optional bash script run as root after the instance is handed over
`disk_gb`	Optional larger system disk, one of the catalog’s `disk_options`. Charged per hour on top of the GPU price

The call returns 202 with status: "creating". Poll GET /v1/gpu/instances/{id} until status is running; the response then carries SSH details and, for templates with a web service, an api_url.

Do not retry an instance create blindly. Unlike jobs, POST /v1/gpu/instances takes no idempotency key: the same request sent twice can start two machines. If it times out, list your instances with GET /v1/gpu/instances and look for one created in the last few minutes with the same GPU model before you try again; when in doubt, destroy the extra one. For work that fits one command, use a job instead.

6. Run and collect results

Use the SSH details from the instance, or the MCP server’s upload, run_command, tail_logs and download tools. Copy results off before you destroy the instance: destroying it erases its disk.

7. Stop

POST /v1/gpu/instances/{id}/destroy. Billing stops when the instance is destroyed. If you set max_minutes or max_spend_usd, the instance is also destroyed when the limit is reached.

Billing

Per minute, rounded up, with a 1-minute minimum. One hour is pre-authorised while an instance runs, and unused minutes go back to your balance when you destroy the instance. There is no subscription and no minimum term.

Limits and errors

HTTP	`code`	What the agent should do
409	`quote_expired`	Request a new quote
409	`gpu_unavailable`	Choose another GPU from a new quote
409	`price_changed`	Request a new quote and check it against the budget again
409	`quote_mismatch`	Fix `gpu_count`, `template` or `disk_gb` to match the quote, or request a quote for the new configuration
402	`insufficient_balance`	Ask the user to top up; do not retry until the balance covers `required_starting_balance`
401	`missing_authorization`, `invalid_api_key`	Ask the user for a valid API key
429	`too_many_instances`	Destroy an instance you no longer need, or wait
429	rate limit	Wait and retry later. The catalog and quote endpoints are limited per IP, the GPU API per key
400	`invalid_request`	Fix the field named in the message
400	`idempotency_key_required`	Send an `Idempotency-Key` header with the job
409	`idempotency_key_reused`	That key belongs to a different job. Use a new key, or resend the original request unchanged to get that job
400	`max_spend_required`	This key has a spending limit; set `max_spend_usd`
403	`key_budget_exceeded`	Lower `max_spend_usd`, or ask the owner to connect the agent again with a higher limit
429	`key_concurrency_exceeded`	Wait for a job or instance of this key to finish, or cancel one
401	`credential_revoked`	The key was revoked or expired; connect again

Safety rules for agents

Show the user the quote, including required_starting_balance, and get their approval before starting a paid instance.
Always set max_minutes and max_spend_usd.
Reuse the same Idempotency-Key when you retry a job, and a new one for a new job.
Never print or log the API key.
Download results before destroying an instance.
If anything fails, destroy the instance rather than leave it running.

A ready-made skill for agents that load skill files is at /skills/cloudgpu-compute/SKILL.md.

What CloudGPU does not do

A Job’s or an instance’s local disk is erased when it ends. Files explicitly saved to Workspace are stored independently, subject to account eligibility, quota and retention rules. Unsaved results must be saved to persistent storage or downloaded before destruction. A Job runs exactly one command; for interactive work, rent an instance.

Optional persistence API (feature-gated)

Check GET /v1/public/compute-capabilities before using persistence. A missing endpoint or storage: false means it is unavailable; keep using your own storage. These APIs require an account quota and explicitly enabled storage. They do not promise free storage or a retention period.

When enabled, /v1/files provides persistent files for project code, datasets, models and artifacts. Create a reservation with name, purpose and size_bytes, upload each exact-size part using /v1/files/{id}/parts/{part}, then call /complete. The service verifies the parts before a file becomes ready. /download returns a short-lived URL; treat it as a credential.

Create a named /v1/workspaces, then a /v1/workspaces/{id}/versions manifest mapping relative project paths to your ready file_ids. Pass the immutable version as workspace_version_id to /v1/jobs: its files are restored into a fresh project directory before your command runs. Referenced files cannot be deleted until the version is removed, and an active job pins its version.

This restores project files, not a boot disk or GPU drivers. It does not automatically save project changes. For Jobs, check automatic_output_collection: when true, pass outputs with explicit file paths under $CLOUDGPU_OUTPUT_DIR and inspect output_collection. Existing quota, retention and storage fees apply; a GPU budget does not authorize paid storage. Cancellation, budget exhaustion or storage failure can prevent collection; GPU release still proceeds without an automatic rerun. Model caching and full-disk restore remain unavailable.

FAQ

Is the quote a price guarantee?

No. It is an estimate valid for 5 minutes. Pass quote_id when you start the instance: if the price went up or the GPU is gone, the call fails instead of starting a dearer GPU.

Why can a task be within budget but not startable?

within_budget compares the estimated cost with your budget. Starting also needs required_starting_balance in your account, because one hour is pre-authorised. Send your API key with the quote to get can_start_with_balance.

Can a job start two GPUs if my request is sent twice?

No, as long as both requests carry the same Idempotency-Key: the second returns the first job. If CloudGPU’s service restarts while it is starting the GPU, it checks for that GPU before trying again and stops the job as needs_attention when it cannot tell, rather than start another.

Can an agent use CloudGPU without MCP?

Yes. Every step is a plain HTTPS request, described in the OpenAPI file.

What happens if the agent’s session ends while an instance or job runs?

It keeps running until it finishes, is destroyed, or reaches a limit. Set max_minutes and max_spend_usd so CloudGPU’s servers shut it down.

Storage retention and separate charges

Read authenticated GET /v1/storage for the current included allowance, total quota, price and retention policy. Storage charges are separate from max_spend_usd on a GPU Job. An upload exceeding the included allowance requires accept_storage_charges: true after the user agrees to the account price. Budget-limited Agent keys cannot enable paid storage; normal unrestricted keys can after explicit agreement.

Completed files expose expires_at. Downloads do not renew retention; versions containing expired files become unavailable. Files referenced by active Jobs are deleted only after those Jobs finish. Workspace persistence saves project files, not an instance image, and Job outputs must be saved explicitly.

Personal and team account context

Before approving an Agent link, check which account is active. In a team context, keys, resources and charges belong to that team’s shared wallet. Personal credit is separate and is not automatically transferred. Team role checks remain server-side; per-member budget allocation is not currently available. A connect-link key’s budget does not create a per-member limit for unrelated web or API activity.

Continue your project through an agent

Tell your agent: “Continue my saved CloudGPU Workspace. Check the saved version and available files, then show me a fresh quote before starting.” The agent can reuse project files without requiring a separate task console. Every new task still needs a quote and your approval; saved files have their own quota and expiry.

Use the project reuse example with an HTTPS-capable agent or configured MCP client. It explains first-run authorization, Workspace reuse, result handling and safe recovery. Read live capabilities and the installed tool list before using optional features; a copied prompt does not install tools or start a GPU. Models and installed dependencies are not automatically preserved with project files.

For a first task, ask your Agent to use MCP list_task_templates / prepare_task_template, review the read-only draft, then quote and approve budget/time before running. No separate web console is needed. Prefer local execution for CPU-only work.

Get an API key OpenAPI description