Skip to content
alfe.aiDocs

Rent GPUs with Vast.ai

Connect your Vast.ai account and your agent can rent a GPU when a task needs one: it finds an offer, launches a container, works over SSH, copies the results back, and destroys the machine.

You bring the key, and Vast.ai bills your Vast account directly. Nothing is charged to your Alfe credits. Your Vast API key stays in Alfe and never reaches the agent.

Before you start

Section titled “Before you start”

You need:

  • A Vast.ai account with credit, and an API key that can manage instances.
  • An agent with a shell. The agent uses the alfe gpu command, which needs ssh, scp, and ssh-keygen.
  • A recent Alfe CLI. Alfe holds the capability back until the agent’s CLI is new enough. See alfe doctor and upgrades.

Set up GPU access

Section titled “Set up GPU access”
  1. In the dashboard, open Connections and select Add new connection.
  2. Select Vast.ai, paste your API key, and save. Alfe checks the key with Vast before storing it. You can scope the connection to the organization, a team, a project, or one agent.
  3. Open Billing, select the Limits tab, and add a usage limit for GPU spend.

The capability then activates on agents in that connection’s scope. Agents on OpenClaw, Claude Code, Codex, Gemini CLI, and Grok Build also get a skill that teaches the workflow. A Hermes agent gets the CLI without the skill.

How limits apply

Section titled “How limits apply”

GPU usage limits are checked before a launch and while instances run:

  • At launch. Alfe adds the hourly price of your organization’s live instances, including this one, multiplied by the requested runtime, to what you’ve already spent. If that total goes over a limit, the launch is refused.
  • While running. When a limit is reached, Alfe destroys the instance. Its data is lost.

This check is deliberately conservative, so a narrow limit can refuse a launch it technically had room for.

Only limits set for GPU spend apply. An “all services” limit doesn’t count GPU spend, and your AI usage can’t block a GPU launch. Tracked spend covers compute and disk at Vast’s price. Vast bills data transfer separately, so your Vast invoice can be higher than the figure Alfe shows. See usage and top-ups for limits in general.

What an agent does

Section titled “What an agent does”

These are the commands your agent runs. You can run them yourself on the agent’s machine.

Terminal
# Find an offer. Cheapest first, datacenter hosts unless you pass --any-host.
alfe gpu search --gpu "RTX 4090" --max-price <USD_PER_HOUR>


# Launch it with a hard runtime cap.
alfe gpu launch --offer <OFFER_ID> --image pytorch/pytorch:latest --max-hours 2


# Poll until it's running. This prints the ssh and scp commands to use.
alfe gpu show <INSTANCE_ID>


# Read the container's output.
alfe gpu logs <INSTANCE_ID> --tail 100


# Destroy it once the results are copied back.
alfe gpu destroy <INSTANCE_ID>

alfe gpu ls lists the agent’s instances. Add --json to search, launch, ls, show, or destroy for machine-readable output.

Launch options

Section titled “Launch options”
Flag Purpose
--offer <id> Required. The offer from alfe gpu search.
--image <image> Required. A Docker image.
--max-hours <hours> Required. Above 0 and at most 24.
--cmd <command> A command to run when the container starts.
--env <KEY=VALUE> An environment variable. Repeatable, up to 64. The host can read these values, and names starting VAST_ or CONTAINER_ are reserved.
--disk <gb> Disk size, 8 to 2,048 GB. Defaults to 32.
--connection <id> Which Vast connection to use, if the agent can see more than one.
--any-host Required if the offer came from alfe gpu search --any-host.

Search filters

Section titled “Search filters”

alfe gpu search takes --gpu, --num-gpus (up to 16), --max-price, --min-vram, --region (a 2-letter country code), --any-host, and --limit (up to 50, default 10). Datacenter hosts are the default. Community hosts run by individuals need --any-host, so don’t send them sensitive data.

Rules that protect you

Section titled “Rules that protect you”
  • Every instance has a deadline. --max-hours is a hard cap of at most 24 hours. Alfe destroys the instance at that time, and the instance also carries its own self-destruct timer as a backstop. Everything on it is lost, so copy results off first.
  • Each agent has a cap. An agent can have at most 5 instances that haven’t ended.
  • Instances are per agent. An agent can only see and manage its own instances.
  • Deleting an agent destroys its instances.
  • SSH keys are per agent. The first launch creates ~/.ssh/alfe_gpu_ed25519 on the agent’s machine, used only for GPU instances.

Stop an instance yourself

Section titled “Stop an instance yourself”

There’s no GPU page in the dashboard. To stop an instance, ask the agent to run alfe gpu destroy, destroy it in the Vast console, or delete the agent.

Instance statuses

Section titled “Instance statuses”
Status Meaning
starting Launching. SSH isn’t ready yet.
running Ready. alfe gpu show prints the ssh and scp commands.
cleanup_pending A launch didn’t complete, and Alfe is confirming the machine is destroyed. It isn’t usable.
orphaned Alfe lost access to the connection. The agent can’t use or destroy it.
ended Finished. The output says why, for example it reached --max-hours or a limit.

Common errors

Section titled “Common errors”
Message What to do
No Vast.ai account is connected Add your key under Connections.
Vast.ai rejected the API key Replace the key under Connections.
This would go over a GPU usage limit Pick a cheaper offer or fewer hours, or raise the limit in Billing.
That offer is no longer available Search again. Offers disappear quickly.
The connected account doesn’t have enough credit Add credit at Vast.ai.
The launch may have gone through Run alfe gpu ls before launching again, because the launch may have created an instance.
GPU instances are not available on this Alfe environment yet Retrying won’t help. Contact support.
Section titled “Related resources”