Verlex documentation

Grab your API key from the dashboard.

Install with pip install verlex (see Installation for details), then run your code on a cloud GPU:

import verlex

# Define your function
def train_model():
    import torch
    model = torch.nn.Linear(100, 10)
    # Your training code here...
    return {"accuracy": 0.95}

# Run it on a cloud GPU - that's it!
result = verlex.cloud(train_model, gpu="A100", api_key="gw_your_key")
print(result)

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 can run until your credits are exhausted, with a hard backstop of 7 days per job. The 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 four serverless container lanes (Beam, Northflank, Novita, Cerebrium), 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")

If a launch fails or a region is out of stock, Verlex fails over automatically: nearby regions first, then other providers, then substitute GPUs, always cheapest first. Your job does not fail because one cloud ran out of capacity.

Pinning a single 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.

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.

Pass local file or folder paths as arguments, and Verlex automatically uploads them and makes them available in the cloud as temporary files. No manual upload step needed.

import verlex

def train_on_csv(data_path):
    import pandas as pd
    df = pd.read_csv(data_path)
    # ... train model on df
    return {"rows": len(df), "columns": list(df.columns)}

# Local file path is detected, uploaded, and available in the cloud
result = verlex.cloud(train_on_csv, "./data/training.csv", api_key="gw_your_key")

# Folders work too: automatically zipped, uploaded, and extracted
def process_images(image_dir):
    from PIL import Image
    import os, tempfile
    out = tempfile.mkdtemp()
    for f in os.listdir(image_dir):
        img = Image.open(os.path.join(image_dir, f))
        img = img.resize((224, 224))
        img.save(os.path.join(out, f))
    return f"Processed {len(os.listdir(out))} images"

result = verlex.cloud(process_images, "./dataset/images", api_key="gw_your_key")

File and folder paths must exist locally. Verlex reads and uploads them before execution. Large arguments (over 50 MB) are automatically offloaded regardless of type. Upload blobs are cached for reuse and expire automatically after a period of non-use.

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, or 3.12
)

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

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]'

Run cloud GPU jobs from GitHub Actions without storing API keys as secrets. Verlex supports GitHub's OIDC tokens for short-lived, keyless authentication.

# .github/workflows/train.yml
name: Train Model
on: [push]

permissions:
  id-token: write   # Required for OIDC

jobs:
  train:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Get Verlex token
        id: auth
        run: |
          OIDC_TOKEN=$(curl -s -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
            "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=verlex" | jq -r '.value')
          RESPONSE=$(curl -s -X POST https://api.verlex.dev/v1/auth/github-oidc \
            -H "Content-Type: application/json" \
            -d "{\"token\": \"$OIDC_TOKEN\"}")
          echo "api_key=$(echo $RESPONSE | jq -r '.access_token')" >> $GITHUB_OUTPUT

      - name: Run training
        env:
          VERLEX_API_KEY: ${{ steps.auth.outputs.api_key }}
        run: |
          pip install verlex
          verlex run train.py --gpu A100

OIDC tokens are scoped to your repository, and the Verlex API key minted from them expires after 24 hours. No long-lived secrets needed.

Note: GitHub OIDC must be enabled per account. Ask your Verlex operator to allowlist your repository (or owner) before using this flow, otherwise the call returns 403.

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, either as a spec value (verlex.cloud(fn, [x], "H100")) or with the gpu keyword. Verlex finds the cheapest available instance across 10 clouds, including AWS, GCP, Azure, Verda, RunPod, Vast.ai, JarvisLabs, Hyperstack, TensorDock, and Lyceum, plus serverless lanes on Beam, Northflank, Novita, and Cerebrium.

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.

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.

Verlex also ships a CLI for managing jobs from the terminal:

# Login
verlex login

# Run a script
verlex run train.py

# Run with specific GPU
verlex run train.py --gpu A100

# List recent jobs
verlex jobs

# Check a specific job
verlex status <job_id>

# Stream job logs
verlex logs <job_id> --follow

# Cancel a running job
verlex cancel <job_id>

# View account info
verlex whoami

# Show version
verlex version