Verlex documentation

One flag controls your price-speed tradeoff:

# Performance mode, immediate execution
result = verlex.cloud(my_function, api_key="gw_your_key", fast=True)

# Standard mode (default), wait for the lowest price
result = verlex.cloud(my_function, api_key="gw_your_key")

Performance mode (fast=True) requires the Performance plan ($10/mo). Standard mode (fast=False) is available on every plan.

Two parts: a monthly plan, then a per-job cost. Verlex passes the provider's live hardware price through at cost and adds a fixed service fee per GPU-hour, prorated per second. There is no percentage markup on the hardware. The Standard plan is free forever ($0/month); the Performance plan ($10/month) unlocks fast mode and 300 GB of storage.

The service-fee tier is derived from the hardware's FP16 tensor performance (TFLOPS):

The service fee is charged per GPU-hour. There is no cold-start surcharge; a cold machine and a warm one cost the same.

• Per-second billing, 1 second minimum: you pay only for the time your job actually runs. Both the provider cost and the service fee are prorated to the second.
• Prepaid credits: buy credits in the dashboard (minimum top-up $10). Each job places a hold and settles the exact amount when it finishes.
• Auto top-up (opt-in): adds credits automatically with your saved card when the balance runs low (default: $50 added when it drops below $10).
• Funds-based execution: a job runs until your credits are exhausted, it stops making progress (idle CPU/GPU with no output for a sustained period), or it finishes, with a hard 7-day backstop. The optional timeout argument is a client-side wait bound; when it expires, the client cancels the remote job.

Every job is priced across 10 clouds (AWS, GCP, Azure, Verda, RunPod, Vast.ai, JarvisLabs, Hyperstack, TensorDock, Lyceum) plus serverless container lanes for small jobs, and routed to the cheapest machine that fits.

import verlex

# Default: priced across 10 clouds, routed to the cheapest machine that fits
result = verlex.cloud(train_model, gpu="A100", api_key="gw_your_key")

# Provider list: cost comparison and failover stay inside your subset
result = verlex.cloud(
    train_model,
    gpu="A100",
    provider=["runpod", "gcp", "verda"],
    api_key="gw_your_key",
)

# Hard pin: one provider, no cross-provider failover if it is out of stock
result = verlex.cloud(train_model, gpu="A100", provider="aws", api_key="gw_your_key")

Failover: if a launch fails or a region is out of stock, Verlex fails over automatically, always cheapest first:

1. 01Cheapest provider, primary region
2. 02Nearby regions on the same provider
3. 03Next cheapest cloud
4. 04Substitute GPU (unless pinned)

Your job does not fail because one cloud ran out of capacity.

Pinning: a single pinned provider disables cross-provider failover: if that cloud has no capacity, the job fails instead of moving. Prefer a provider list, which keeps cost comparison and failover inside your chosen subset.

Serverless: small jobs are routed to serverless container lanes (billed per second) when that is cheaper than a VM, or faster within budget on the Performance plan. This happens automatically; nothing to configure.

Send local files up to the VM before your job runs and bring generated files back when it finishes. Pass a Workspace to any cloud call. Auto mode mirrors your project root (respecting .gitignore) and returns whatever your code creates or changes; or list explicit Upload and Output specs when you want full control over what goes up and what comes back.

import verlex
from verlex import Workspace

def train():
    from pathlib import Path
    Path("runs").mkdir(exist_ok=True)
    Path("runs/loss.json").write_text('{"loss": 0.42}')
    Path("model.pt").write_text("weights")
    return {"status": "done"}

# Auto mode mirrors your project root (respecting .gitignore) up to the VM,
# then returns new and changed files to the same paths locally
result = verlex.cloud(train, workspace=Workspace(), gpu="A100", api_key="gw_your_key")

# ./runs/loss.json and ./model.pt now exist locally

import verlex
from verlex import Workspace, Upload, Output

def finetune():
    import json
    from pathlib import Path
    cfg = json.load(open("config.json"))  # uploaded and renamed below
    Path("runs").mkdir(exist_ok=True)
    Path("runs/epoch1.ckpt").write_text("weights")  # trained on ./dataset
    Path("model.pt").write_text("final weights")
    return cfg["name"]

ws = Workspace(
    root=None,  # implied once uploads are listed; spelled out here for clarity
    uploads=[
        Upload("./configs/run.json", to="config.json"),  # rename into the workspace
        Upload("./dataset"),  # whole folder, hierarchy kept
    ],
    outputs=[
        Output(path="model.pt"),  # bring a single file back
        Output(pattern="runs/*.ckpt"),  # plus files matched by glob
    ],
)

result = verlex.cloud(finetune, workspace=ws, gpu="A100", api_key="gw_your_key")

Your function runs inside the synced workspace, so relative paths like open('data/train.csv') work unchanged. Listing explicit Upload specs replaces the auto mirror — you get exactly the files you named, and nothing else; pass root='auto' if you want the project mirror alongside them. Explicit Output specs never affect what goes up. There is no hard size limit by default: Verlex warns once the workspace passes 100 MB, so set a ceiling with Workspace(max_size_bytes=...) if you need one. Import Workspace, Upload, and Output from the top-level verlex package.

Verlex scans your function's source, pins the versions of imported packages installed locally, and bundles local .py modules automatically. When you need certainty, pass pip_packages=: those packages are authoritative, always installed, and a failed install fails the job loudly instead of continuing silently.

import verlex

def train():
    import numpy as np
    import torch
    from my_helpers import preprocess  # local .py modules are bundled automatically
    # ... your training code ...
    return {"loss": 0.03}

# Auto-detect: imported packages are pinned to your local versions
result = verlex.cloud(train, api_key="gw_your_key")

# Authoritative installs: always installed, a failed install fails the job
result = verlex.cloud(
    train,
    api_key="gw_your_key",
    pip_packages=["torch==2.3.1", "numpy==1.26.4"],
    python_version="3.11",  # 3.10, 3.11, 3.12, or 3.13
)

python_version controls the interpreter on the cloud side: supported values are 3.10, 3.11, 3.12, and 3.13. By default Verlex matches your local interpreter.

Kill the cold start before it happens. Call verlex.prewarm(your_function) and Verlex analyzes it, boots the right hardware, and hands you back a handle once the machine is ready (pass wait=False to get the handle immediately and let it boot in the background while your code runs). Calling the handle runs your function on that machine with no provisioning wait, and the machine stays attached to the handle between calls, so every call is warm. Release it with handle.release() or a with block when you are done; unreleased handles release themselves when your program exits, and a hard kill is covered by the server-side idle timeout.

New in 0.13.0: prewarm() replaces the old repo-scanning pre_warm(), which was removed.

import verlex

def train(batch):
    import torch
    ...

wf = verlex.prewarm(train, gpu="A100", api_key="gw_your_key")  # A100 starts booting NOW

data = load_and_clean()      # local preprocessing runs meanwhile

result = wf(data)            # runs train(data) on the warm machine
more = wf(other_data)        # still warm, the VM stays attached

# Define inputs/outputs with a Workspace, just like verlex.cloud —
# it's a per-call argument on the warm handle:
from verlex import Workspace, Upload, Output
out = wf(data, workspace=Workspace(
    uploads=[Upload("./configs/run.json", to="config.json")],  # sync inputs up
    outputs=[Output(pattern="checkpoints/*.ckpt")],            # bring results back
))

wf.release()                 # recommended, not required: frees the machine now.
                             # If you skip it, the handle auto-releases when your
                             # program exits (atexit). A hard kill that skips atexit
                             # is covered by the server-side idle timeout instead.

# Or auto-release with a context manager:
with verlex.prewarm(train, "A100") as wf:
    result = wf(data)

# Scope mode: prewarm() with no function sizes hardware from THIS file's
# code and binds no function. You pass the function to run as the first
# argument on every call (workspace= stays a keyword, so it comes last):
wf = verlex.prewarm(gpu="A10")          # no function -> scope mode
result = wf(train, data)                # function is the first call arg
out = wf(train, data, workspace=Workspace())  # same, with a Workspace
wf.release()

There are two ways to call prewarm, and they change how you invoke the handle:

• workspace= works the same as on any other cloud call: it syncs inputs up before the function runs and brings generated outputs back. Because it is a keyword, its position never changes, and it is per-call, so different calls on the same warm VM can carry different Workspaces.
• Multi-GPU cluster jobs, spot jobs, and workloads that resolve to the serverless lane skip pre-warming; they are already routed optimally.
• If the warm session expires before you call, the handle still works and simply provisions normally.

Billing: you pay only for the time the warm machine actually exists at the real instance rate, never for analysis time, failed warm-ups, or skipped sessions. Idle time between calls is billed in segments; job runtime is billed as a normal job.

The machine is released by whichever of these comes first:

Don't want to manage when code runs in the cloud? Let Verlex decide automatically. When your system's CPU, memory, or GPU usage exceeds the threshold, heavy functions are transparently offloaded to the cheapest cloud provider.

import verlex

# Pass your API key directly
verlex.overflow(api_key="gw_your_key")

# Your code runs normally.
# When CPU, memory, or GPU exceeds 85%, functions go to the cloud.
data = load_data()
result = train_model(data)   # system overloaded? → cloud
evaluate(result)             # resources free → runs locally

Parameters

Defaults: With just an API key, overflow monitors CPU, memory, and GPU. If any of them exceeds 85% usage, functions are automatically offloaded to the cloud in standard mode.

Note: GPU monitoring uses pynvml (included with the base install) and needs an NVIDIA GPU. Without one, overflow gracefully falls back to CPU and memory monitoring only.

CPU and memory monitoring need psutil. Install with: pip install 'verlex[overflow]'

Connect Claude, Codex, Gemini CLI — or any MCP-compatible assistant — to your Verlex account and drive it in plain language: "run this fine-tune on an A100, show me the log as it goes, and kill it if the loss blows up".

Install

pip install "verlex[mcp]>=0.17.0"

# Storing your key once here means the configs below
# can carry no secret at all.
verlex login

Connect your assistant

Claude Code

claude mcp add verlex -- verlex-mcp

# View only: no submitting, cancelling or spending
claude mcp add verlex -- verlex-mcp --read-only

Claude Desktop

Add this to claude_desktop_config.json — %APPDATA%\Claude\ on Windows, ~/Library/Application Support/Claude/ on macOS, ~/.config/Claude/ on Linux.

{
  "mcpServers": {
    "verlex": {
      "command": "verlex-mcp",
      "env": { "VERLEX_MCP_MAX_SPEND": "25" }
    }
  }
}

Codex

[mcp_servers.verlex]
command = "verlex-mcp"
env = { VERLEX_MCP_MAX_SPEND = "25" }

Gemini CLI

{
  "mcpServers": {
    "verlex": {
      "command": "verlex-mcp",
      "timeout": 60000
    }
  }
}

Keep any client request timeout at 60 seconds or more: log tailing holds a request open for up to 25 seconds while it waits for new output.

What you can ask

Once connected, your assistant can do all of this on its own:

• →"What GPUs can I get, and what would an A100 cost me for two hours?"
• →"Run this script on an A100 and show me the output as it goes."
• →"Cancel that job if you see the loss go to NaN."
• →"List my last 10 jobs and what each one cost."
• →"How much have I spent this month, and how much credit is left?"

Safety

The connector is a thin client holding your own API key, so it can only ever see and do what you can. There is no database access and no shared credential. On top of that:

• Anything that spends money or cancels work needs an explicit confirmation step, so it always surfaces as a visible action rather than a silent side effect.
• Every submission is priced first, and the estimate comes back with the job so you see the cost up front.
• A per-session spend cap (default $25), a one-GPU limit and a 60-minute duration limit are enforced before any request is sent.
• Job output is fenced and labelled as untrusted data, so instructions hidden inside a log cannot redirect your assistant.

Verlex raises specific exceptions so you can handle failures gracefully:

from verlex.errors import (
    VerlexError,              # Base class for all Verlex errors
    AuthenticationError,      # Invalid or missing credentials
    InsufficientCreditsError, # Not enough credits to run the job
    ProviderMaintenanceError, # Pinned provider is under maintenance
    JobFailedError,           # Job execution failed in the cloud
    JobTimeoutError,          # Job exceeded its timeout
    SerializationError,       # Function could not be serialized
    NetworkError,             # Connection to Verlex API failed
    RateLimitError,           # Too many requests
)

import verlex

try:
    result = verlex.cloud(train_model, api_key="gw_your_key", gpu="A100")
except InsufficientCreditsError as e:
    print(f"Need more credits: {e.required} required, {e.available} available")
except JobFailedError as e:
    print(f"Job {e.job_id} failed in the cloud. Logs:\n{e.logs}")
except ProviderMaintenanceError:
    print("That provider is under maintenance. Pick another or drop the pin")
except JobTimeoutError:
    print("Job took too long. Increase timeout or optimize your code")
except VerlexError as e:
    print(f"Something went wrong: {e}")

Request a GPU by name with gpu="H100", or as Hardware(gpu="H100"). Verlex finds the cheapest available instance across 10 clouds, including AWS, GCP, Azure, Verda, RunPod, Vast.ai, JarvisLabs, Hyperstack, TensorDock, and Lyceum, plus serverless container lanes for small jobs.

If you don't specify a GPU, Verlex auto-detects your code's needs and picks the best option. Availability and pricing vary by provider. Verlex always routes to the cheapest option.

Job inputs, outputs, workspace files, and checkpoints live in Verlex object storage and count against your plan's storage quota:

Workspace upload blobs are stored by content hash and expire automatically after a period of non-use, so re-uploads of unchanged files are fast.

Spot capacity is 60-80% cheaper than on-demand, but the provider can reclaim it at any time. Verlex handles the recovery: anything your job writes into the checkpoint directory is synced to object storage while it runs (every 60 seconds, every 20 seconds on short-notice providers, and immediately when a preemption notice arrives).

When a spot instance is reclaimed, the job is automatically re-enqueued on the next cheapest spot capacity (a different provider whenever one is stocked), the checkpoint directory is restored before your code runs again, and the reclaimed time is not billed. If spot keeps getting reclaimed, or no spot capacity fits the requested hardware anywhere, the job finishes on on-demand capacity so it always completes.

Write checkpoints, resume on restart

import os, pickle

def train():
    # Set inside every Verlex job; synced to object storage while you run.
    ckpt_dir = os.environ.get("GATEWAY_CHECKPOINT_DIR", "./ckpt")
    state_file = os.path.join(ckpt_dir, "state.pkl")

    start = 0
    if os.path.exists(state_file):
        with open(state_file, "rb") as f:
            start = pickle.load(f)["epoch"]

    for epoch in range(start, 100):
        run_one_epoch()
        tmp = state_file + ".tmp"
        with open(tmp, "wb") as f:
            pickle.dump({"epoch": epoch + 1}, f)
        os.replace(tmp, state_file)  # atomic: never syncs a torn file

The same restore also runs when an on-demand instance dies and the job is retried on fresh hardware. On providers with no advance reclaim notice, progress since the last periodic sync (at most the sync interval) can be lost.

Corporate accounts get organization-backed teams: a shared org credit pool, email invitations, and roles (owner, admin, member).

Admins allocate credits from the pool to members and can claw back unused allocations; members can also contribute personal credits to the pool. Everything is managed from the dashboard.

Set daily or monthly spending caps from your dashboard to prevent unexpected charges. When a limit is reached, Verlex can block new jobs, warn you, or send a notification.

Configure spending limits in your dashboard settings. You can also enable auto top-up to automatically add credits when your balance gets low.