GPU instances

These methods rent GPU machines on Vast.ai using the Vast key connected in Alfe. The agent never receives that key, because Alfe makes the provider calls for it. They’re what the alfe gpu command uses, and most agents should use that command instead.

Read Rent GPUs with Vast.ai first for setup, limits, and the rules that apply to every instance. All examples use the @alfe.ai/agent-api-client.

Search offers

gpu.ts

const offers = await client.searchGpuOffers({
  gpuName: "RTX 4090",
  numGpus: 1,          // 1 to 16
  maxHourlyUsd: 1,     // up to 1000
  minGpuRamGb: 24,     // up to 1024
  datacenterOnly: true, // the default
  region: "US",        // 2-letter country code
  limit: 10,           // default 10, max 50
});
// POST /agent/gpu/offers/search

Every filter is optional. Each offer has offerId, gpuName, numGpus, gpuRamGb, hourlyUsd, location, reliability (0 to 1), and datacenter.

Launch an instance

const instance = await client.launchGpuInstance({
  offerId: offers[0].offerId,
  image: "pytorch/pytorch:latest",
  maxRuntimeHours: 2,        // above 0, at most 24
  sshPublicKey: publicKey,   // the key you'll connect with
  startCommand: "python /root/train.py", // optional
  env: { WANDB_MODE: "offline" },        // optional, up to 64
  diskGb: 64,                // optional, 8 to 2048, default 32
});
// POST /agent/gpu/instances

An offer found with datacenterOnly: false needs datacenterOnly: false on the launch too. If the agent can see more than one Vast connection, pass connectionId.

A lost response can hide a running instance

The client never retries a launch. If a launch times out or fails with a 5xx, it may still have created an instance that’s billing your Vast account. Call listGpuInstances() before launching again. A 503 is the exception: nothing was created, so it’s safe to retry.

List and inspect instances

const instances = await client.listGpuInstances();
// GET /agent/gpu/instances

const current = await client.getGpuInstance(instance.instanceId);
// GET /agent/gpu/instances/{instanceId}

Poll getGpuInstance until status is running. That call also finishes attaching your SSH key if the launch ran out of time, so read ssh from it rather than from the launch response.

Field	Meaning
instanceId	The ID to use with these methods.
status	starting, running, cleanup_pending, ended, or orphaned. See Instance statuses.
ssh	{ host, port, user } once it’s running. user is always root.
hourlyUsd	The current hourly price at Vast.
spentUsd	Tracked spend so far, excluding data transfer.
deadlineAt	When Alfe destroys it.
endedAt, terminationReason	Set once it has ended, for example deadline or usage_limit.

Read logs

const { logs, pending } = await client.getGpuInstanceLogs(instance.instanceId, {
  tail: 100, // default 200, max 1000
});
// GET /agent/gpu/instances/{instanceId}/logs

pending: true means the provider has no logs yet, so ask again shortly. That’s different from empty logs. The client doesn’t retry this call.

Destroy an instance

const ended = await client.destroyGpuInstance(instance.instanceId);
// DELETE /agent/gpu/instances/{instanceId}

This deletes everything on the instance. It’s safe to call again, and an ended instance returns its record. If the result’s status is cleanup_pending, Alfe is still confirming the machine is gone.

Errors

Thrown errors carry a status and a machine-readable code.

code	Status	Meaning
vast_not_connected	409	No Vast connection is available to this agent.
vast_key_invalid	409	Vast rejected the connected key.
usage_limit_exceeded	429	The launch would go over a GPU usage limit.
max_runtime_exceeded	400	maxRuntimeHours is above 24.
offer_unavailable	409	The offer is gone, or it doesn’t match datacenterOnly.
vast_insufficient_credit	402	The Vast account needs credit.
instance_not_found	404	No such instance on this agent.
instance_limit_reached	409	The agent has 5 instances that haven’t ended.
rate_limited	429	Too many requests. Limits are per agent per minute.
capability_unavailable	404	New launches aren’t available yet.
gpu_pricing_unavailable	502	Launches are refused until this is fixed on Alfe’s side.
launch_in_progress	409	The launch is still running. Retry the destroy after retryAfterSeconds.

Related resources

• Rent GPUs with Vast.ai — setup, limits, and the alfe gpu command.
• Connected accounts — credentials for other providers.