Search the Vast.ai GPU marketplace for rentable machine offers.

The body is sent as-is to POST /bundles/. Top-level keys commonly include type ("ondemand" | "bid"), limit, and filter objects. Each filter maps a field name to an operator object: {eq, neq, gt, lt, gte, lte, in, notin}.

Examples: search_offers({"gpu_name": {"in": ["RTX 4090"]}, "num_gpus": {"gte": 1}, "reliability": {"gte": 0.99}, "verified": {"eq": True}, "rentable": {"eq": True}, "type": "ondemand", "limit": 5}) search_offers({"type": "bid", "gpu_ram": {"gte": 24000}, "order": [["dph_total", "asc"]], "limit": 10})

Retrieve all GPU benchmark records (GET /benchmarks/).

Returns a list of benchmark entries with gpu_name, value, type, etc.

Examples: search_benchmarks()

Search user and public templates (GET /template/).

The endpoint always requires a select_filters body (pass {} for "all"). This tool defaults to {} when called without arguments.

Examples: search_templates() search_templates(select_filters={"tag": {"eq": "pytorch"}})

Current snapshot of supply, demand, and pricing across GPU types (GET /metrics/gpu/current/).

Examples: get_gpu_metrics() get_gpu_metrics(gpu_name=["RTX 4090", "A100"], verified=True)

Time-series of GPU supply/demand/pricing (GET /metrics/gpu/history/).

Returns ~20 sampled data points over the window by default.

Examples: get_gpu_trends() get_gpu_trends(gpu_names=["RTX 4090"], window_hours=168)

List the authenticated user's instances (GET /instances/).

Examples: list_instances() list_instances(label="vllm-inference")

Retrieve details of a specific instance (GET /instances/{id}/).

Examples: get_instance(instance_id=12345)

Rent a GPU by accepting offer_id (PUT /asks/{offer_id}/).

Either image or template_hash_id must be provided. Use price to create an interruptible (spot) instance; omit it for on-demand.

env is a flat dict: regular vars as key/value pairs, port mappings as {"-p 8000:8000": "1"}. Use onstart to launch your app on SSH/Jupyter runtypes (their entrypoint is replaced by Vast's).

Examples: create_instance(offer_id=12345678, image="ubuntu:22.04", disk=16, runtype="ssh_direct") create_instance(offer_id=12345678, image="vllm/vllm-openai:latest", disk=50, runtype="ssh_direct", env={"MODEL_ID": "deepseek-ai/DeepSeek-R1-Distill-Llama-8B", "-p 8000:8000": "1"}, onstart="vllm serve $MODEL_ID --port 8000") create_instance(offer_id=12345678, template_hash_id="4e17788f74f075dd9aab7d0d4427968f", disk=100) create_instance(offer_id=12345678, image="ubuntu:22.04", disk=16, runtype="ssh_direct", price=0.20)

Control instance state: start/stop/label/reboot/recycle.

• start/stop/label: PUT /instances/{id}/ with state or label.

• reboot: PUT /instances/reboot/{id}/ (stops and starts, preserves GPU priority).

• recycle: PUT /instances/recycle/{id}/ (destroys and recreates from fresh image pull).

For action="label", the label argument is required.

Examples: manage_instance(instance_id=12345, action="stop") manage_instance(instance_id=12345, action="start") manage_instance(instance_id=12345, action="label", label="my-server") manage_instance(instance_id=12345, action="reboot")

Permanently destroy an instance and all its data (DELETE /instances/{id}/).

Irreversible. Call carefully.

Examples: destroy_instance(instance_id=12345)

Change the bid price of an interruptible instance (PUT /instances/bid_price/{id}/).

Examples: change_bid(instance_id=12345, price=0.25)

Request instance logs (PUT /instances/request_logs/{id}). Logs are uploaded to S3; the response contains a URL to fetch them.

Examples: show_instance_logs(instance_id=12345) show_instance_logs(instance_id=12345, tail=5000)

Execute a constrained remote command on a STOPPED instance (PUT /instances/command/{id}/).

Only works on instances whose actual_status is stopped (transient launch commands like downloading an image on first start). For running instances, the API rejects this with: "Execute command only avail on stopped instances. Use ssh to run commands on running instances." — use ssh_exec instead.

The API additionally enforces a command whitelist — unknown commands return 400 "Invalid command given". ls-style inspection commands are accepted; nvidia-smi, whoami, arbitrary binaries are not. For arbitrary commands on a running instance, use ssh_exec.

Examples: execute_command(instance_id=12345, command="ls /workspace")

Retrieve the authenticated user's account info and credit balance (GET /users/current/).

Examples: get_current_user()

Escape hatch for any Vast.ai REST endpoint not covered by other tools.

path is appended to https://console.vast.ai/api/v0 (include the leading slash, e.g. "/volumes/").

Examples: raw_request(method="GET", path="/volumes/") raw_request(method="POST", path="/ssh/", body={"ssh_key": "ssh-rsa AAA..."})

Register a local SSH public key on the Vast.ai account (POST /ssh/).

The key is applied automatically to all current instances and any new instances created afterwards. Reads the .pub file from disk — never uploads your private key.

Examples: register_ssh_key(name="laptop", public_key_path="C:/Users/me/.ssh/id_ed25519.pub") register_ssh_key(name="ci", public_key_path="/home/runner/.ssh/id_ed25519.pub")

List SSH keys registered on the Vast.ai account (GET /ssh/).

Examples: list_ssh_keys()

Resolve an instance's direct SSH endpoint (host, port) and return a ready-to-run ssh command. Requires actual_status == "running" and a ssh_direct or jupyter_direct runtype.

Examples: get_instance_ssh_info(instance_id=12345)

Execute a command on a running instance over SSH (paramiko).

Resolves the instance's ssh_host/ssh_port automatically. The private key stays local — never sent to the Vast.ai API.

key_path defaults to the VASTAI_MCP_SSH_KEY_PATH env var if set.

Examples: ssh_exec(instance_id=12345, command="nvidia-smi") ssh_exec(instance_id=12345, command="ls /workspace", key_path="/home/me/.ssh/id_ed25519") ssh_exec(instance_id=12345, command="python train.py", user="root", timeout=300)

Transfer a single file between the local machine and an instance over SFTP.

• upload: local file -> instance path

• download: instance path -> local file

Directories are not supported — call once per file. Resolves the instance's ssh_host/ssh_port automatically. The private key stays local.

key_path defaults to the VASTAI_MCP_SSH_KEY_PATH env var if set.

Examples: ssh_transfer(direction="upload", instance_id=12345, local_path="./train.py", remote_path="/workspace/train.py") ssh_transfer(direction="download", instance_id=12345, local_path="./results.tar", remote_path="/workspace/results.tar")