Machines

A machine is a rented GPU computer running one program: one of our ready programs or one of your own capabilities. The API calls a machine a pod; each one has a unique pod_id such as my-worker-3f9a1c.

Every machine runs a program. To rent a plain machine for interactive work, make a capability whose start keeps running (for example sleep infinity) and rent that; see Capabilities.

Units everywhere: sizes in gigabytes, prices in US dollars per hour.

#Search for machines

POST /v1/offers/search

Searches every provider at once and returns every machine that fits, cheapest first. Searching is free and rents nothing.

You can describe the hardware directly, or send a capability_id and the requirements are read from that capability. Anything you send explicitly wins over the capability.

#Request fields

curl -s "https://api.gpuforge.io/v1/offers/search" \
  -H "Authorization: Bearer $GF_KEY" -H "Content-Type: application/json" \
  -d '{"min_vram_gb": 80, "disk_gb": 100, "min_gpu_family": "hopper", "limit": 5}'

#Response

Each offer has offer_id, provider, gpu (name, family, count, vram_gb_per_gpu, vram_gb_total), host (cpu_cores, ram_gb, disk_available_gb, cuda_version), location (country_code), price, availability, secure_cloud, reliability, inet_down_mbps and interruptible.

Price: price.customer_usd_hr is what you pay per hour for that machine, locked when you rent it. When it is null, you pay price.total_usd_hr. Your max_price_per_hour is compared with the price you pay.

A null field means the provider does not publish that value, not that it is zero.

#Rent the cheapest machine for a capability

POST /v1/capabilities/{capability_id}/deploy

The capability already says what it needs and what it is worth per hour, so no body is needed. GPU Forge first wakes a parked machine of this program if one is free (seconds). Otherwise it searches every provider and rents the cheapest machine that fits under the price limit, moving to the next cheapest if a provider refuses.

curl -s -X POST "https://api.gpuforge.io/v1/capabilities/cap_ab12cd34/deploy" -H "Authorization: Bearer $GF_KEY"

{
  "pod_id": "hello-gpu-3f9a1c",
  "capability_id": "cap_ab12cd34",
  "provider": "vast",
  "price_usd_hr": 0.48,
  "gpu_name": "RTX 4090",
  "country_code": "DE",
  "offers_considered": 37,
  "attempts": [ ... ],
  "note": "..."
}

The answer comes as soon as the machine is rented, not when it is ready. If the capability has a surge_price_per_hour and every machine under its normal limit refused, the deploy tries once more up to the surge price.

#Run N machines

POST /v1/capabilities/{capability_id}/scale

desired_pods is a target, not an increment: asking for 3 when 1 is running starts 2; asking again starts nothing. Parked machines are woken first, and only the rest is rented.

The answer has running_before, newly_rented, running_now, short_by (how many the providers could not supply), pods (each new machine), woken and woken_pods.

scale never ends machines: a target below what is running rents nothing and ends nothing, because a machine in the middle of a request is not GPU Forge's to stop. Machines leave on their idle limit, or when you release or destroy them. A short fill is normal when providers run out: send the same target again later and it fills in. Only one scale or deploy per capability runs at a time; a second one at the same moment answers 409 (try again in a moment).

#Rent an offer you picked

POST /v1/deploy

The answer has pod_id, provider, instance_id, price_usd_hr, image and notes on what still has to happen.

#Watch your machines

GET /v1/fleet
GET /v1/fleet/{pod_id}

GET /v1/fleet lists everything that could be costing you money right now, newest first: running, starting, stopping and parked machines. Filters: capability_id, state, provider. ?include=all also returns ended machines; ?include=telemetry adds each machine's last heartbeat (combine with a comma).

GET /v1/fleet/{pod_id} returns one machine with its last heartbeat in full (beat: GPU use, temperature, disks and more).

#Fields you will use most

What each machine costs you right now is also in GET /v1/billing → machines[].cost_usd_hr.

#Waiting for ready

Poll GET /v1/fleet/{pod_id} every 10 seconds until capability_state is ready, and pass status on to your user while you wait.

• A machine that already holds the program: usually 1–3 minutes. A woken parked machine: about 20–60 seconds plus the program's start.
• A fresh machine: download and install time, up to 15–20 minutes for large programs. Wait at least 20 minutes before giving up.
• ready is re-checked on every heartbeat: a program that exits later moves to failed.
• If capability_state is failed or the machine is gone (destroyed_at set), read the logs, then deploy again.

#Logs and output

GET /v1/fleet/{pod_id}/logs

Returns last_seen_at, events, error and startup (recent output of your program, separate from downloads). It is the last report the machine sent, readable even after the machine has ended; it is not a live stream.

GET /v1/fleet/{pod_id}/output?since={time}&limit={n}

For machines running our ready programs: everything the program printed, kept 30 days. Returns pieces (at, run, text) and next (the since value for the next page).

#Stop, park, wake

Send these as POST with an empty JSON body {}. Destroy is POST /v1/fleet/{pod_id}/destroy, not DELETE.

#Park

curl -s "https://api.gpuforge.io/v1/fleet/<pod_id>/stop-choices" -H "Authorization: Bearer $GF_KEY"

{
  "pod_id": "hello-gpu-3f9a1c",
  "park": {"allowed": true, "refusal": null, "usd_hr": 0.012, "usd_day": 0.288, "released_after_unused_days": 3},
  "release": {"usd_day": 0.0, "note": "The machine and its disk end now; the next start rents a fresh one."}
}

curl -s -X POST "https://api.gpuforge.io/v1/fleet/<pod_id>/park" -H "Authorization: Bearer $GF_KEY" \
  -H "Content-Type: application/json" -d '{}'

• Parking is possible on Vast.ai, Jarvis Labs and Nebius, when the program is switched on and the machine runs the program's current version and disk size. Otherwise it answers 409 with the reason.
• Parking by hand raises the program's dormant_pods by one if there was no free slot.
• The provider can take up to a minute to finish stopping the machine.
• A parked machine unused for 3 days is released; you are notified a day before.

#Wake

curl -s -X POST "https://api.gpuforge.io/v1/fleet/<pod_id>/wake" -H "Authorization: Bearer $GF_KEY" \
  -H "Content-Type: application/json" -d '{}'

You rarely need this: deploy and scale wake parked machines first. A wake that produces no heartbeat within 240 seconds is parked again; after two failed wakes the machine is ended. Read capability_url again after every wake.

#Destroy

curl -s -X POST "https://api.gpuforge.io/v1/fleet/<pod_id>/destroy" -H "Authorization: Bearer $GF_KEY" \
  -H "Content-Type: application/json" -d '{}'

GPU Forge asks the provider to end the machine and records it gone only once the provider confirms. Until then the answer is 502, the request is retried automatically, and the machine stays visible in your fleet, because it may still be billing. Copy anything you need off the disk first.

#Idle shutdown and keepalive

Every machine has an idle limit (idle_ttl_seconds, default 600 seconds). After that long without activity it parks (if its program keeps parked machines and the provider can park) or ends.

• Activity is network traffic or GPU use, measured on the machine. With the capability setting idle_by: "gpu", only GPU use counts, so an open SSH session alone does not keep a machine running.
• The clock starts only when your program is up.
• The limit cannot be switched off; a value of 0 is stored as at least one hour.

To keep one running machine longer, or restart its countdown:

curl -s -X POST "https://api.gpuforge.io/v1/fleet/<pod_id>/keepalive" \
  -H "Authorization: Bearer $GF_KEY" -H "Content-Type: application/json" \
  -d '{"idle_ttl_seconds": 3600, "reason": "long training run"}'

{"pod_id": "hello-gpu-3f9a1c", "idle_ttl_seconds": 3600, "previous_idle_ttl_seconds": 600, "idle_reset_at": "...", "note": "..."}

The machine keeps billing for as long as it runs. Changing a capability's idle limit affects new and woken machines, not running ones; keepalive is how you change a running one. Answers 409 if the machine is already being shut down or is stopped.

#Fix or update a running machine

These keep the same rental, price and disk. Each order is picked up on the machine's next heartbeat (a few seconds), so they work only on a machine that is still reporting.

Your own capabilities only; machines of our ready programs are updated by GPU Forge.

#SSH access

SSH is available for your own capabilities on Vast.ai, RunPod and Nebius. It is not available on machines of our ready programs.

1. Rent with your public key. Put it in the capability's ssh_public_keys, or send ssh_public_keys on deploy, scale or POST /v1/deploy. Never send a private key. A machine rented without keys has no managed SSH port.

2. Read the connection details:

   ShellCopy

   curl -s "https://api.gpuforge.io/v1/fleet/<pod_id>/ssh" -H "Authorization: Bearer $GF_KEY"

   JSONCopy

   {
    "pod_id": "hello-gpu-3f9a1c",
    "state": "configured",
    "host": "203.0.113.10",
    "port": 41022,
    "username": "root",
    "command": "ssh -p 41022 root@203.0.113.10",
    "host_public_key": "ssh-ed25519 AAAA...",
    "host_key_fingerprint": "SHA256:...",
    "keys": [{"key_id": "<64 hex characters>", "public_key": "ssh-ed25519 AAAA... you@laptop"}],
    "generation": "...",
    "note": "Key changes affect new connections; already-open SSH sessions remain open. ..."
   }

   state is disabled (rented without keys), pending (being applied; poll again), configured, error or unavailable (the machine is stopped, ended or silent). Pin host_public_key in your known_hosts to verify the machine.

3. Add or remove keys on a running machine:

   ShellCopy

   curl -s -X POST "https://api.gpuforge.io/v1/fleet/<pod_id>/ssh/keys" \
    -H "Authorization: Bearer $GF_KEY" -H "Content-Type: application/json" \
    -d '{"public_key": "ssh-ed25519 AAAA... teammate@laptop"}'
   
   curl -s -X DELETE "https://api.gpuforge.io/v1/fleet/<pod_id>/ssh/keys/<key_id>" -H "Authorization: Bearer $GF_KEY"

   Changes apply to new connections once state is configured again. Sessions already open stay open.

The CLI does all of this with gpuforge ssh <pod_id>.

#What survives what

Keep your own copy of anything that matters. Machines are rented from GPU marketplaces and can fail or be reclaimed.

#GPU families

GET /v1/gpu-families

Lists the supported generations (ada_lovelace, hopper, blackwell), the minimum CUDA compute capability of each, and which generations satisfy each minimum. The order is a policy line, not a speed ranking.

#Several GPUs and clusters

• Up to 8 GPUs on one machine: set gpu_count (1–8) on the capability, or cluster_size on a search. It is exact, not a minimum, and max_price_per_hour is for the whole machine. Prefer this to a cluster.
• Multi-node clusters (training across machines, RunPod): GET /v1/clusters/options lists cards available for a cluster now with an estimated price. POST /v1/clusters with capability_id, gpu_type, nodes (2–8), gpus_per_node (1–8) and max_price_per_hour (for the whole cluster) rents all nodes at once. Each node runs the capability's start with NODE_RANK, NUM_NODES, MASTER_ADDR, MASTER_PORT and WORLD_SIZE set, and appears in your fleet as <cluster_id>-n<rank>. GET /v1/clusters and GET /v1/clusters/{cluster_id} show them; DELETE /v1/clusters/{cluster_id} ends every node. A cluster also ends once every node has been idle past its idle limit.

This page as Markdown, for tools and agents: /docs/machines.md