Docs

Quickstart

runmesh is one marketplace for GPU machines across providers. People use the website; programs and agents use the REST API or the MCP server. All three see the same live offers and prices.

Launching is invite-only for now

Searching the market is public. Launching works for invited accounts with credit; everyone else gets not_allowlisted. Card top-ups open soon.

Keys

Programs and agents authenticate with an agent key — create one under Console → Keys. Each key has its own lifetime budget and hourly cap and can be read-only. Send it as Authorization: Bearer bk_live_…. Keys can’t add credit, create keys or use admin endpoints.

REST API

Base URL https://runmesh.ai/api/v1. JSON in and out; errors follow RFC 7807 with a machine-readable code.

Search offers — public, no key

curl "https://runmesh.ai/api/v1/offers?gpu=RTX%204090&min_gpus=2&max_price_per_gpu=0.6&sort=price"

Returns offers[], total and facets (counts per GPU model, region and host tier, computed over everything except the facet's own filter). Prices are per hour for a 40 GB disk.

Launch a machine

K="Authorization: Bearer $RUNMESH_KEY"

# 1. your SSH public key (once)
curl -X POST https://runmesh.ai/api/v1/ssh-keys -H "$K" \
  -d "{\"name\":\"laptop\",\"public_key\":\"$(cat ~/.ssh/id_ed25519.pub)\"}"

# 2. hold the price for 120 s — disk is part of the price
curl -X POST https://runmesh.ai/api/v1/quotes -H "$K" -d '{"offer_id":"m_4be1c09a7f3d21e6b8a0","disk_gb":40}'

# 3. launch (retry with the same Idempotency-Key is safe)
curl -X POST https://runmesh.ai/api/v1/leases -H "$K" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"quote_id":"q_…","image":"ubuntu:22.04","ssh_key_ids":["key_…"],"ttl_hours":2,"max_spend_usd":5}'

# 4. poll until "state":"running", then use "ssh.command"
curl https://runmesh.ai/api/v1/leases/ls_… -H "$K"

# 5. stop (billing stops now)
curl -X DELETE https://runmesh.ai/api/v1/leases/ls_… -H "$K"

Also: GET /leases, POST /leases/{id}/extend {"hours":2}, GET /account, GET /account/ledger, GET /images/templates.

Error codes: insufficient_funds, budget_exceeded, cap_exceeded, offer_gone, quote_expired, quote_mismatch, image_invalid, no_ssh_key, not_allowlisted, key_cannot_launch, kill_switch, rate_limited.

Offer filters

gpu	Comma list of exact models, e.g. RTX 4090,H100 SXM
min_gpus / max_gpus	GPUs per machine
min_vram	GB per GPU
max_price · max_price_per_gpu	USD per hour
region · country	NA, EU, AS, OC, SA, AF · ISO-2 codes
host_tier	community, secure, datacenter
min_reliability · min_inet_down · min_cuda	0–1 · Mbps · e.g. 12.4
q	Free text over model, country, CPU
sort	price, price_per_gpu, vram, gpus, reliability, perf_per_dollar, inet_down — prefix - for descending
limit · offset	Default 100, max 500

MCP

Streamable-HTTP MCP server at https://runmesh.ai/mcp, authenticated with an agent key. In Claude Code:

claude mcp add --transport http runmesh https://runmesh.ai/mcp \
  --header "Authorization: Bearer bk_live_…"

Any other MCP client:

{
  "mcpServers": {
    "runmesh": {
      "type": "http",
      "url": "https://runmesh.ai/mcp",
      "headers": { "Authorization": "Bearer bk_live_…" }
    }
  }
}

Tools: gpu_search_offers, gpu_get_offer, gpu_list_images, gpu_quote, gpu_launch, gpu_get_lease, gpu_list_leases, gpu_extend, gpu_stop, gpu_balance, gpu_topup_link. See For agents.

Billing model

Prepaid USD credit via Stripe. No post-paid usage.
Launching places a hold of about an hour plus boot time; it refills while you run and is released when you stop.
Metering is per second from provider allocation to termination. Machines that never start are refunded.
The hourly price is locked at launch.