Capabilities (your own programs)

A capability describes your software once: what hardware it needs, which files to download, how to install and start it, and what you are willing to pay. After that, renting a machine for it, or fifty, is one call with its id, on whichever provider has the cheapest machine that fits.

GPU Forge never interprets your commands or files. They run as root on your own machine.

#Create a capability

POST /v1/capabilities

curl -s "https://api.gpuforge.io/v1/capabilities" \
  -H "Authorization: Bearer $GF_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "my-inference-server",
    "user_id": "usr_...",
    "spec": {
      "version": "1.0.0",
      "min_vram_gb": 48,
      "min_gpu_family": "ada_lovelace",
      "disk_gb": 100,
      "assets": [
        {"url": "https://my-bucket.example.com/server-1.0.0.tar.zst", "dest": "/opt/app", "unpack": true,
         "sha256": "9f2c..."},
        {"url": "https://my-bucket.example.com/weights.safetensors", "dest": "/opt/app/weights.safetensors",
         "sha256": "41ab..."}
      ],
      "install": "cd /opt/app && ./install.sh",
      "start": "cd /opt/app && exec ./serve --port 8000",
      "port": 8000,
      "ready_check": {"path": "/health/ready", "timeout_seconds": 900},
      "max_price_per_hour": 1.5,
      "idle_ttl_seconds": 900
    }
  }'

201 returns the capability with its capability_id (cap_...). Nothing is rented yet.

#The spec

Required fields: min_vram_gb, disk_gb, min_gpu_family, start, port. To rent with deploy or scale, the spec also needs max_price_per_hour.

#Hardware

#Price and spending

#Software

#Idle and access

#Files: assets

Files are downloaded in parallel. Several medium-sized files are easier to cache and republish than one huge file.

#Files: origins and files

One file list, served from a bucket per region. The machine's country picks the origin at rent time.

{
  "origins": [
    {"name": "eu", "zones": ["europe"], "base_url": "https://eu-bucket.example.com/app/"},
    {"name": "us", "zones": ["north_america", "south_america", "any"], "base_url": "https://us-bucket.example.com/app/"}
  ],
  "files": [
    {"path": "server-1.0.0.tar.zst", "dest": "/opt/app", "unpack": true, "sha256": "9f2c..."}
  ]
}

Zones: north_america, south_america, europe, asia (including South-East Asia and Oceania), and any (the fallback). Each zone may appear in one origin only; a machine in a zone no origin covers is skipped unless one origin is any. base_url must end with /; a file's path must not start with /.

#ready_check

#Images

Leave image unset unless you need your own. The provider defaults (a Vast.ai base image and a RunPod PyTorch image) currently provide Ubuntu 24.04, CUDA 13 and Python 3.12, but they are not identical, so bring everything your program needs as files and treat the image as a floor. The one thing you cannot ship is the CUDA driver: use min_cuda_version for that.

On RunPod, GPU Forge's start-up replaces a custom image's own start command, so a custom image's entrypoint does not run unless your start runs it.

#What your program is told

These environment variables are set for install and start:

#Secrets

Secrets are kept beside the spec, never inside it. They are stored encrypted, never returned by any API call (a read shows only their names), and reach only your own machines.

How the bucket credential works: when a machine asks for its files, GPU Forge turns each file URL into a signed link valid for expires_seconds (default one hour; size it to your download). The credential itself never leaves GPU Forge. Give a read-only credential scoped to the one bucket. Prefer a permanent key: a temporary one (with session_token) expires, and then new machines cannot download their files.

Without asset_auth, a private bucket answers 403 to every download, after the machine is already rented and billing. A capability whose secrets cannot be read is refused before anything is rented.

Changing secrets:

• Leave secrets out of a PATCH and they stay as they are; a spec change never touches them.
• Sending env replaces all of env and keeps asset_auth, and the other way round.
• {} clears all secrets. Clearing is refused while machines depend on them.
• Running machines read secrets fresh: POST /v1/fleet/{pod_id}/restart-capability applies a rotated secret to a running machine.

A read returns a summary only:

"secrets": {"set": true, "env_keys": ["HF_TOKEN"], "asset_auth": "s3", "asset_auth_temporary": false}

#Change a capability

PATCH /v1/capabilities/{capability_id}

Send only what you want to change:

curl -s -X PATCH "https://api.gpuforge.io/v1/capabilities/cap_ab12cd34" \
  -H "Authorization: Bearer $GF_KEY" -H "Content-Type: application/json" \
  -d '{"settings": {"idle_ttl_seconds": 1200, "max_price_per_hour": 2.5}}'

Running machines are not changed. A change applies to the next machine rented (and, for idle limits, to woken ones). To move a running machine onto your new spec, use POST /v1/fleet/{pod_id}/update-capability; to change one machine's idle limit, use keepalive. See Machines.

A change while a rental for the same capability is in progress answers 409; try again in a moment.

#Delete a capability

DELETE /v1/capabilities/{capability_id}

Refused (409) while any machine runs it: destroy those first. There is no undo.

#Add a ready program to your account

POST /v1/catalog/{program_id}/add

Makes your copy of one of our ready programs: a capability on your account that runs our built program, starts from machines that already hold it, and bills your balance like any capability of yours.

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

201:

Adding the same program twice answers 409 with your existing copy's id.

How a copy differs from your own capability:

• You choose its settings (price limits, daily budget, idle limit, GPUs, interruptible, price reduction), active and dormant_pods. Its files, commands and environment stay ours; a full spec you send keeps them as they are.
• The only secret you can set is the program key, {"secrets": {"env": {"GF_API_KEY": "..."}}}. Machines started after the change use the new key.
• New versions of the program reach your copy by themselves, keeping your settings. Parked machines take the new version at their next wake.
• A new copy keeps no parked machines (dormant_pods: 0): an idle machine is let go. Parking is your choice (POST /v1/fleet/{pod_id}/park).
• Parked machines of a ready program are shared between customers, and each start or wake empties the working folder. See How GPU Forge behaves.
• There is no SSH; use the program's own API.

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