diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 00000000..47a43e58
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,112 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - master
+      - main
+  pull_request:
+    branches:
+      - master
+      - main
+
+jobs:
+  lint:
+    name: Lint (Ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install Ruff
+        run: pip install ruff
+
+      - name: Run Ruff check
+        run: ruff check . --output-format=github
+
+      - name: Run Ruff format check
+        run: ruff format --check .
+
+  type-check:
+    name: Type Check (mypy)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run mypy
+        run: mypy vastai/
+
+  test:
+    name: Test (${{ matrix.os }} / Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run pytest with coverage
+        run: pytest --cov=vastai --cov-report=xml
+
+      - name: Upload coverage to Codecov
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  smoke-standalone:
+    name: Smoke Test Standalone (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install minimal dependencies (standalone mode)
+        run: pip install requests python-dateutil
+
+      - name: Test vast.py --help
+        run: python vast.py --help
+
+      - name: Test vast.py search offers --help
+        run: python vast.py search offers --help
+
+      - name: Test vast.py show instances --help
+        run: python vast.py show instances --help
diff --git a/.gitignore b/.gitignore
index a3df4740..28390020 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,4 +3,17 @@ passed_machines.txt
 failed_machines.txt
 Pass_testresults.log
 dist/
+build/
 __pycache__/
+*.egg-info/
+*.egg
+.eggs/
+*.pyc
+*.pyo
+
+# Test artifacts
+.coverage
+.pytest_cache/
+
+# MkDocs build output
+site/
diff --git a/__init__.py b/__init__.py
index 426f99d8..f2428881 100644
--- a/__init__.py
+++ b/__init__.py
@@ -1 +1,4 @@
-from .vastai_sdk import VastAI
\ No newline at end of file
+try:
+    from .vastai_sdk import VastAI
+except ImportError:
+    pass
diff --git a/benchmarks/docker-compose.yml b/benchmarks/docker-compose.yml
new file mode 100644
index 00000000..fce6c817
--- /dev/null
+++ b/benchmarks/docker-compose.yml
@@ -0,0 +1,31 @@
+version: "3.8"
+
+services:
+  prometheus:
+    image: prom/prometheus:latest
+    container_name: prometheus
+    restart: unless-stopped
+    ports:
+      - "9090:9090"
+    volumes:
+      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
+    command:
+      - "--config.file=/etc/prometheus/prometheus.yml"
+
+  grafana:
+    image: grafana/grafana:latest
+    container_name: grafana
+    restart: unless-stopped
+    ports:
+      - "3000:3000"
+    environment:
+      - GF_SECURITY_ADMIN_USER=admin
+      - GF_SECURITY_ADMIN_PASSWORD=admin
+      - GF_USERS_ALLOW_SIGN_UP=false
+    depends_on:
+      - prometheus
+    volumes:
+      - grafana-storage:/var/lib/grafana
+
+volumes:
+  grafana-storage:
diff --git a/benchmarks/llm_prom_metrics.py b/benchmarks/llm_prom_metrics.py
new file mode 100644
index 00000000..6ada242a
--- /dev/null
+++ b/benchmarks/llm_prom_metrics.py
@@ -0,0 +1,260 @@
+import asyncio
+from vastai import Serverless
+import os
+import random
+import collections
+import time
+import uuid
+from prometheus_client import start_http_server, Gauge, Histogram
+from typing import Dict, Any
+import nltk
+
+API_KEY = os.environ.get("VAST_API_KEY")
+
+
+nltk.download("words")
+WORD_LIST = nltk.corpus.words.words()
+# Generate unique run ID for this session
+RUN_ID = time.strftime("vLLM_%Y%m%d_%H%M%S") + "_" + str(uuid.uuid4())[:8]
+
+# Prometheus metrics
+REQUEST_STATUS = Gauge(
+    "vast_request_status_current",
+    "Current number of requests by status",
+    ["status", "run_id"]
+)
+LATENCY = Histogram(
+    "vast_request_latency_seconds",
+    "Latency of responses (seconds)",
+    ["run_id"]
+)
+
+LATENCY_AVG = Gauge(
+    "vast_request_latency_avg_seconds",
+    "Rolling average latency (seconds) over recent responses",
+    ["run_id"]
+)
+
+CURRENT_LOAD = Gauge(
+    "vast_current_load",
+    "Current request load (tokens per second or arbitrary units)",
+    ["run_id"]
+)
+
+WORKER_STATUS = Gauge(
+    "vast_workers_status_current",
+    "Current number of workers by status",
+    ["status", "run_id"]
+)
+
+WORKERS_TOTAL = Gauge(
+    "vast_workers_total",
+    "Total number of workers returned by get_endpoint_workers",
+    ["run_id"]
+)
+
+WORKER_CUR_LOAD_TOTAL = Gauge(
+    "vast_workers_cur_load_total",
+    "Sum of current load across workers",
+    ["run_id"]
+)
+
+WORKER_NEW_LOAD_TOTAL = Gauge(
+    "vast_workers_new_load_total",
+    "Sum of new load across workers",
+    ["run_id"]
+)
+
+WORKER_REQS_WORKING_TOTAL = Gauge(
+    "vast_workers_requests_working_total",
+    "Sum of requests_working across workers",
+    ["run_id"]
+)
+
+# Averages
+WORKERS_AVG_CUR_PERF = Gauge("vast_workers_avg_cur_perf", "Average cur_perf", ["run_id"])
+WORKERS_AVG_PERF = Gauge("vast_workers_avg_perf", "Average perf", ["run_id"])
+WORKERS_AVG_MEASURED_PERF = Gauge("vast_workers_avg_measured_perf", "Average measured_perf", ["run_id"])
+WORKERS_AVG_DLPERF = Gauge("vast_workers_avg_dlperf", "Average dlperf", ["run_id"])
+WORKERS_AVG_RELIABILITY = Gauge("vast_workers_avg_reliability", "Average reliability", ["run_id"])
+WORKERS_AVG_CUR_LOAD_ROLLING = Gauge("vast_workers_avg_cur_load_rolling", "Average cur_load_rolling_avg", ["run_id"])
+WORKERS_AVG_DISK_USAGE = Gauge("vast_workers_avg_disk_usage", "Average disk_usage", ["run_id"])
+
+# Per-worker gauges (also labeled with worker_id)
+WORKER_MEASURED_PERF = Gauge(
+    "vast_worker_measured_perf",
+    "Measured perf per worker",
+    ["worker_id", "run_id"]
+)
+WORKER_CUR_LOAD = Gauge(
+    "vast_worker_cur_load",
+    "Current load per worker",
+    ["worker_id", "run_id"]
+)
+WORKER_REQS_WORKING = Gauge(
+    "vast_worker_requests_working",
+    "Current requests_working per worker",
+    ["worker_id", "run_id"]
+)
+WORKER_STATUS_LIVE = Gauge(
+    "vast_worker_status_current",
+    "Status (1 for present) per worker; useful for per-worker dashboards",
+    ["worker_id", "status", "run_id"]
+)
+
+
+latencies = collections.deque(maxlen=50)
+
+def export_to_prom(agg: dict, run_id: str) -> None:
+    """
+    Push aggregate + per-worker metrics with run_id label.
+    Call this after aggregate_workers(workers).
+    """
+
+    # --- status counts: clear existing for this run_id, then set ---
+    # (Same internal reset pattern you used.)
+    for (label_status, label_run_id) in list(WORKER_STATUS._metrics.keys()):
+        if label_run_id == run_id:
+            WORKER_STATUS.labels(status=label_status, run_id=run_id).set(0)
+
+    for status, count in agg["status_counts"].items():
+        WORKER_STATUS.labels(status=status, run_id=run_id).set(count)
+
+    # --- totals / averages ---
+    WORKERS_TOTAL.labels(run_id=run_id).set(agg["total_workers"])
+    WORKER_CUR_LOAD_TOTAL.labels(run_id=run_id).set(agg["total_cur_load"])
+    WORKER_NEW_LOAD_TOTAL.labels(run_id=run_id).set(agg["total_new_load"])
+    WORKER_REQS_WORKING_TOTAL.labels(run_id=run_id).set(agg["total_reqs_working"])
+
+    WORKERS_AVG_CUR_PERF.labels(run_id=run_id).set(agg["avg_cur_perf"])
+    WORKERS_AVG_PERF.labels(run_id=run_id).set(agg["avg_perf"])
+    WORKERS_AVG_MEASURED_PERF.labels(run_id=run_id).set(agg["avg_measured_perf"])
+    WORKERS_AVG_DLPERF.labels(run_id=run_id).set(agg["avg_dlperf"])
+    WORKERS_AVG_RELIABILITY.labels(run_id=run_id).set(agg["avg_reliability"])
+    WORKERS_AVG_CUR_LOAD_ROLLING.labels(run_id=run_id).set(agg["avg_cur_load_rolling"])
+    WORKERS_AVG_DISK_USAGE.labels(run_id=run_id).set(agg["avg_disk_usage"])
+
+    # --- per-worker: set gauges keyed by worker_id + run_id ---
+    # First, clear any old per-worker status rows for this run_id
+    for (wid, status, label_run_id) in list(WORKER_STATUS_LIVE._metrics.keys()):
+        if label_run_id == run_id:
+            WORKER_STATUS_LIVE.labels(worker_id=wid, status=status, run_id=run_id).set(0)
+
+    for row in agg["per_worker"]:
+        wid = str(row["id"])
+        WORKER_MEASURED_PERF.labels(worker_id=wid, run_id=run_id).set(row["measured_perf"])
+        WORKER_CUR_LOAD.labels(worker_id=wid, run_id=run_id).set(row["cur_load"])
+        WORKER_REQS_WORKING.labels(worker_id=wid, run_id=run_id).set(row["reqs_working"])
+        # Mark this worker present in its current status (value=1)
+        WORKER_STATUS_LIVE.labels(worker_id=wid, status=row["status"], run_id=run_id).set(1)
+
+async def status_reporter(client, endpoint, responses, latencies, window_size=50):
+    """Continuously updates gauges to reflect live status counts."""
+    while True:
+        status_counts = collections.Counter()
+
+        for r in responses:
+            try:
+                status = getattr(r, "status", None)
+                if callable(status):
+                    status = status()
+                if status is None:
+                    status = "unknown"
+                status_counts[status] += 1
+            except Exception:
+                status_counts["error"] += 1
+
+        # Reset gauges before updating
+        for label_tuple in list(REQUEST_STATUS._metrics.keys()):
+            label_status, label_run_id = label_tuple
+            if label_run_id == RUN_ID:
+                REQUEST_STATUS.labels(status=label_status, run_id=RUN_ID).set(0)
+
+        # Update gauges to reflect current counts
+        for status, count in status_counts.items():
+            REQUEST_STATUS.labels(status=status, run_id=RUN_ID).set(count)
+
+        # Compute rolling latency average
+        avg_latency = sum(latencies) / len(latencies) if latencies else 0.0
+
+        # Record it in Prometheus
+        LATENCY_AVG.labels(run_id=RUN_ID).set(avg_latency)
+
+        #workers = await endpoint.get_workers()
+        #aggregate = client.aggregate_workers(workers)
+        #export_to_prom(aggregate)
+
+        # Console display
+        print("\n=== Live Response Status ===")
+        for status, count in status_counts.items():
+            print(f"{status:>12}: {count}")
+        print(f"Rolling Avg Latency (last {len(latencies)}): {avg_latency:.2f} s")
+        print("=============================\n")
+
+        await asyncio.sleep(1)
+
+
+def latency_callback(response):
+    latency = response.get("latency")
+    if latency is not None:
+        latencies.append(latency)
+        LATENCY.labels(run_id=RUN_ID).observe(latency)
+
+
+def cur_load(start_time, ramp_time, min_load, max_load, backwards=False):
+    # progress clamped to [0,1]
+    t = max(0.0, min((time.time() - start_time) / ramp_time, 1.0))
+    e = t * t  # quadratic ease-in; keep as-is for reverse too
+    a, b = (max_load, min_load) if backwards else (min_load, max_load)
+    return a + (b - a) * e
+
+async def main():
+    async with Serverless() as client:
+        endpoint = await client.get_endpoint(name="big")
+
+        system_prompt = """
+        You are Qwen.
+        You are to only speak in English.
+        You are to use the <stop> token when you are done generating tokens. Do *not* use the <stop> token unless you intend to stop responding.
+        Your task is to return Yes or No to the following question:
+        Does the document contain the word "establish"?
+        """
+
+
+        user_prompt = """
+        Who is your favorite character from late 2000's Disney/Nickelodeon?
+        """
+        responses = []
+
+        asyncio.create_task(status_reporter(client, endpoint, responses, latencies))
+
+        LOAD_PER_REQUEST = 10
+        MAX_LOAD = 10000
+        MIN_LOAD = 500
+        RAMP_TIME = 15 * 60 # seconds
+        BACKWARDS = False
+        start_time = time.time()
+
+        while True:
+            user_prompt = " ".join(random.choices(WORD_LIST, k=int(random.randint(300,1500))))
+            payload = {
+                "input" : {
+                    "model": "Qwen/Qwen2-72B",
+                    "prompt" : f"Random_Hash: {random.randint(1, 10000)}\nSystem: {system_prompt}\n<document>\n{user_prompt}</document>\nAssistant: ",
+                    "max_tokens" : 500,
+                    "temperature" : 0.7,
+                    "stop" : ["<stop>"]
+
+                }
+            }
+            CUR_LOAD = cur_load(start_time, RAMP_TIME, MIN_LOAD, MAX_LOAD, backwards=BACKWARDS)
+            CUR_LOAD = 1000 # Hardcode a set load
+            CURRENT_LOAD.labels(run_id=RUN_ID).set(CUR_LOAD)
+            request = endpoint.request("/v1/completions", payload, cost=LOAD_PER_REQUEST).then(latency_callback)
+            responses.append(request)
+            await asyncio.sleep(LOAD_PER_REQUEST / CUR_LOAD)
+
+
+if __name__ == "__main__":
+    start_http_server(8000)
+    asyncio.run(main())
diff --git a/benchmarks/prometheus/prometheus.yml b/benchmarks/prometheus/prometheus.yml
new file mode 100644
index 00000000..9eb43719
--- /dev/null
+++ b/benchmarks/prometheus/prometheus.yml
@@ -0,0 +1,8 @@
+global:
+  scrape_interval: 2s
+
+scrape_configs:
+  - job_name: "vast_metrics"
+    static_configs:
+    - targets: ["172.17.0.1:8000"]
+
diff --git a/benchmarks/prometheus_metrics.py b/benchmarks/prometheus_metrics.py
new file mode 100644
index 00000000..2b6d072e
--- /dev/null
+++ b/benchmarks/prometheus_metrics.py
@@ -0,0 +1,134 @@
+import asyncio
+from vastai import Serverless
+import os
+import random
+import collections
+import time
+import uuid
+from prometheus_client import start_http_server, Gauge, Histogram
+
+API_KEY = os.environ.get("VAST_API_KEY")
+
+# Generate unique run ID for this session
+RUN_ID = time.strftime("ComfyUI_Image_%Y%m%d_%H%M%S") + "_" + str(uuid.uuid4())[:8]
+
+# Prometheus metrics
+REQUEST_STATUS = Gauge(
+    "vast_request_status_current",
+    "Current number of requests by status",
+    ["status", "run_id"]
+)
+LATENCY = Histogram(
+    "vast_request_latency_seconds",
+    "Latency of responses (seconds)",
+    ["run_id"]
+)
+
+LATENCY_AVG = Gauge(
+    "vast_request_latency_avg_seconds",
+    "Rolling average latency (seconds) over recent responses",
+    ["run_id"]
+)
+
+
+latencies = collections.deque(maxlen=50)
+
+
+async def status_reporter(responses, latencies, window_size=50):
+    """Continuously updates gauges to reflect live status counts."""
+    while True:
+        status_counts = collections.Counter()
+
+        for r in responses:
+            try:
+                status = getattr(r, "status", None)
+                if callable(status):
+                    status = status()
+                if status is None:
+                    status = "unknown"
+                status_counts[status] += 1
+            except Exception:
+                status_counts["error"] += 1
+
+        # Reset gauges before updating
+        for label_tuple in list(REQUEST_STATUS._metrics.keys()):
+            label_status, label_run_id = label_tuple
+            if label_run_id == RUN_ID:
+                REQUEST_STATUS.labels(status=label_status, run_id=RUN_ID).set(0)
+
+        # Update gauges to reflect current counts
+        for status, count in status_counts.items():
+            REQUEST_STATUS.labels(status=status, run_id=RUN_ID).set(count)
+
+        # Compute rolling latency average
+        avg_latency = sum(latencies) / len(latencies) if latencies else 0.0
+
+        # Record it in Prometheus
+        LATENCY_AVG.labels(run_id=RUN_ID).set(avg_latency)
+
+        # Console display
+        print("\n=== Live Response Status ===")
+        for status, count in status_counts.items():
+            print(f"{status:>12}: {count}")
+        print(f"Rolling Avg Latency (last {len(latencies)}): {avg_latency:.2f} s")
+        print("=============================\n")
+
+        await asyncio.sleep(1)
+
+
+def latency_callback(response):
+    latency = response.get("latency")
+    if latency is not None:
+        latencies.append(latency)
+        LATENCY.labels(run_id=RUN_ID).observe(latency)
+
+
+def cur_load(start_time, ramp_time, min_load, max_load, backwards=False):
+    # progress clamped to [0,1]
+    t = max(0.0, min((time.time() - start_time) / ramp_time, 1.0))
+    e = t * t  # quadratic ease-in; keep as-is for reverse too
+    a, b = (max_load, min_load) if backwards else (min_load, max_load)
+    return a + (b - a) * e
+
+async def main():
+    client = Serverless()
+    endpoint = await client.get_endpoint(name="comfy")
+
+    prompts = [
+        "a page from a peanuts comic strip",
+    ]
+
+    responses = []
+
+    asyncio.create_task(status_reporter(responses, latencies))
+
+    LOAD_PER_REQUEST = 100
+    MAX_LOAD = 1000
+    MIN_LOAD = 50
+    RAMP_TIME = 15 * 60 # seconds
+    BACKWARDS = False
+    start_time = time.time()
+
+    while True:
+        payload = {
+            "input": {
+                "modifier": "Text2Image",
+                "modifications": {
+                    "prompt": random.choice(prompts),
+                    "width": 512,
+                    "height": 512,
+                    "steps": 10,
+                    "seed": random.randint(1, 10000)
+                }
+            }
+        }
+        CUR_LOAD = cur_load(start_time, RAMP_TIME, MIN_LOAD, MAX_LOAD, backwards=BACKWARDS)
+        CUR_LOAD = 1000 # Hardcode a set load
+        request = endpoint.request("/generate/sync", payload, cost=LOAD_PER_REQUEST).then(latency_callback)
+        responses.append(request)
+        await asyncio.sleep(LOAD_PER_REQUEST / CUR_LOAD)
+
+
+if __name__ == "__main__":
+    start_http_server(8000)
+    asyncio.run(main())
diff --git a/conftest.py b/conftest.py
new file mode 100644
index 00000000..ecd3474f
--- /dev/null
+++ b/conftest.py
@@ -0,0 +1 @@
+collect_ignore = ["__init__.py", "vast.py", "vast_pdf.py", "vast_config.py"]
diff --git a/examples/client/ace_example.py b/examples/client/ace_example.py
new file mode 100644
index 00000000..4f6f5777
--- /dev/null
+++ b/examples/client/ace_example.py
@@ -0,0 +1,149 @@
+from vastai import Serverless
+import asyncio
+
+
+async def main():
+    async with Serverless() as client:
+        endpoint = await client.get_endpoint(name="my-ace-endpoint")
+
+        # ComfyUI API compatible json workflow for ACE Step
+        workflow = {
+          "14": {
+            "inputs": {
+              "tags": "funk, pop, soul, rock, melodic, guitar, drums, bass, keyboard, percussion, 105 BPM, energetic, upbeat, groovy, vibrant, dynamic",
+              "lyrics": "[verse]\nNeon lights they flicker bright\nCity hums in dead of night\nRhythms pulse through concrete veins\nLost in echoes of refrains\n\n[verse]\nBassline groovin in my chest\nHeartbeats match the citys zest\nElectric whispers fill the air\nSynthesized dreams everywhere\n\n[chorus]\nTurn it up and let it flow\nFeel the fire let it grow\nIn this rhythm we belong\nHear the night sing out our song",
+              "lyrics_strength": 0.99,
+              "clip": ["40", 1]
+            },
+            "class_type": "TextEncodeAceStepAudio",
+            "_meta": {
+              "title": "TextEncodeAceStepAudio"
+            }
+          },
+          "17": {
+            "inputs": {
+              "seconds": 180,
+              "batch_size": 1
+            },
+            "class_type": "EmptyAceStepLatentAudio",
+            "_meta": {
+              "title": "EmptyAceStepLatentAudio"
+            }
+          },
+          "18": {
+            "inputs": {
+              "samples": ["52", 0],
+              "vae": ["40", 2]
+            },
+            "class_type": "VAEDecodeAudio",
+            "_meta": {
+              "title": "VAE Decode Audio"
+            }
+          },
+          "40": {
+            "inputs": {
+              "ckpt_name": "ace_step_v1_3.5b.safetensors"
+            },
+            "class_type": "CheckpointLoaderSimple",
+            "_meta": {
+              "title": "Load Checkpoint"
+            }
+          },
+          "44": {
+            "inputs": {
+              "conditioning": ["14", 0]
+            },
+            "class_type": "ConditioningZeroOut",
+            "_meta": {
+              "title": "ConditioningZeroOut"
+            }
+          },
+          "49": {
+            "inputs": {
+              "model": ["51", 0],
+              "operation": ["50", 0]
+            },
+            "class_type": "LatentApplyOperationCFG",
+            "_meta": {
+              "title": "LatentApplyOperationCFG"
+            }
+          },
+          "50": {
+            "inputs": {
+              "multiplier": 1.15
+            },
+            "class_type": "LatentOperationTonemapReinhard",
+            "_meta": {
+              "title": "LatentOperationTonemapReinhard"
+            }
+          },
+          "51": {
+            "inputs": {
+              "shift": 6,
+              "model": ["40", 0]
+            },
+            "class_type": "ModelSamplingSD3",
+            "_meta": {
+              "title": "ModelSamplingSD3"
+            }
+          },
+          "52": {
+            "inputs": {
+              "seed": "__RANDOM_INT__",
+              "steps": 65,
+              "cfg": 4,
+              "sampler_name": "er_sde",
+              "scheduler": "linear_quadratic",
+              "denoise": 1,
+              "model": ["49", 0],
+              "positive": ["14", 0],
+              "negative": ["44", 0],
+              "latent_image": ["17", 0]
+            },
+            "class_type": "KSampler",
+            "_meta": {
+              "title": "KSampler"
+            }
+          },
+          "59": {
+            "inputs": {
+              "filename_prefix": "audio/ComfyUI",
+              "quality": "V0",
+              "audioUI": "",
+              "audio": ["18", 0]
+            },
+            "class_type": "SaveAudioMP3",
+            "_meta": {
+              "title": "Save Audio (MP3)"
+            }
+          }
+        }
+
+        payload = {
+          "input": {
+            "request_id": "",
+            "workflow_json": workflow,
+            "s3": {
+              "access_key_id": "",
+              "secret_access_key": "",
+              "endpoint_url": "",
+              "bucket_name": "",
+              "region": ""
+            },
+            "webhook": {
+              "url": "",
+              "extra_params": {
+                "user_id": "12345",
+                "project_id": "abc-def"
+              }
+            }
+          }
+        }
+
+        response = await endpoint.request("/generate/sync", payload)
+
+        # Response contains status, output, and any errors
+        print(response["response"])
+
+if __name__ == "__main__":
+    asyncio.run(main())
\ No newline at end of file
diff --git a/examples/client/callback_example.py b/examples/client/callback_example.py
new file mode 100644
index 00000000..b9069e2c
--- /dev/null
+++ b/examples/client/callback_example.py
@@ -0,0 +1,32 @@
+import asyncio
+from vastai import Serverless, ServerlessRequest
+
+MAX_TOKENS = 128
+
+async def main():
+    async with Serverless() as client:
+        endpoint = await client.get_endpoint(name="my-vllm-endpoint")
+
+        payload = {
+            "input" : {
+                "model": "Qwen/Qwen3-8B",
+                "prompt" : "Who are you?",
+                "max_tokens" : MAX_TOKENS,
+                "temperature" : 0.7
+            }
+        }
+        
+        # Create a ServerlessRequest object to attach callbacks before submitting the request
+        req = ServerlessRequest()
+
+        # Attach a callback to run when the machine finished work on the request
+        def work_finished_callback(response):
+            print(f"Request finished. Got response of length {len(response["response"]["choices"][0]["text"])}")
+
+        req.then(work_finished_callback)
+
+        response = await endpoint.request(route="/v1/completions", payload=payload, serverless_request=req, cost=MAX_TOKENS)
+        print(response)
+
+if __name__ == "__main__":
+    asyncio.run(main())
\ No newline at end of file
diff --git a/examples/client/comfy_example.py b/examples/client/comfy_example.py
new file mode 100644
index 00000000..73147a5d
--- /dev/null
+++ b/examples/client/comfy_example.py
@@ -0,0 +1,29 @@
+import asyncio
+from vastai import Serverless
+import random
+
+async def main():
+    async with Serverless() as client:
+        endpoint = await client.get_endpoint(name="my-comfy-endpoint")
+
+        payload = {
+            "input": {
+                "modifier": "Text2Image",
+                "modifications": {
+                    "prompt": "Generate a page from a peanuts comic strip.",
+                    "width": 512,
+                    "height": 512,
+                    "steps": 10,
+                    "seed": random.randint(1, 1000)
+                }
+            }
+        }
+        
+        response = await endpoint.request("/generate/sync", payload)
+
+        # Get the file from the path on the local machine using SCP or SFTP
+        # or configure S3 to upload to cloud storage.
+        print(response["response"]["output"][0]["local_path"])
+
+if __name__ == "__main__":
+    asyncio.run(main())
\ No newline at end of file
diff --git a/examples/client/comfy_load_example.py b/examples/client/comfy_load_example.py
new file mode 100644
index 00000000..597bbdb8
--- /dev/null
+++ b/examples/client/comfy_load_example.py
@@ -0,0 +1,38 @@
+import asyncio
+from vastai import Serverless, ServerlessRequest
+import random
+
+COST_PER_REQUEST = 100
+
+async def main():
+    async with Serverless() as client:
+        endpoint = await client.get_endpoint(name="my-comfy-endpoint")
+
+        payload = {
+            "input": {
+                "modifier": "Text2Image",
+                "modifications": {
+                    "prompt": "Generate a page from a peanuts comic strip.",
+                    "width": 512,
+                    "height": 512,
+                    "steps": 10,
+                    "seed": random.randint(1, 1000)
+                }
+            }
+        }
+        
+        responses = []
+
+        CUR_LOAD = 300
+        while True:
+            # Create a ServerlessRequest object to attach callbacks before submitting the request
+            req = ServerlessRequest()
+            # Attach a callback to run when the machine finished work on the request
+            def work_finished_callback(response):
+                print(f"{len([x for x in responses if x.status != "Complete"])} in flight")    
+            req.then(work_finished_callback)
+            responses.append(endpoint.request(route="/generate/sync", payload=payload, serverless_request=req, cost=COST_PER_REQUEST))
+            await asyncio.sleep(COST_PER_REQUEST / CUR_LOAD)
+
+if __name__ == "__main__":
+    asyncio.run(main())
\ No newline at end of file
diff --git a/examples/client/tgi_simple_example.py b/examples/client/tgi_simple_example.py
new file mode 100644
index 00000000..45618baf
--- /dev/null
+++ b/examples/client/tgi_simple_example.py
@@ -0,0 +1,26 @@
+import asyncio
+from vastai import Serverless
+
+MAX_TOKENS = 128
+
+async def main():
+    async with Serverless() as client:
+        endpoint = await client.get_endpoint(name="my-tgi-endpoint")
+
+        prompt = "Who are you?"
+
+        payload = {
+            "inputs": prompt,
+            "parameters": {
+                "max_new_tokens": MAX_TOKENS,
+                "temperature": 0.7,
+                "return_full_text": False
+            }
+        }
+
+        resp = await endpoint.request("/generate", payload, cost=MAX_TOKENS)
+
+        print(resp["response"]["generated_text"])
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/client/tgi_stream_example.py b/examples/client/tgi_stream_example.py
new file mode 100644
index 00000000..5021485d
--- /dev/null
+++ b/examples/client/tgi_stream_example.py
@@ -0,0 +1,55 @@
+import asyncio
+from vastai import Serverless
+
+MAX_TOKENS = 1024
+
+def build_prompt(system_prompt: str, user_prompt: str) -> str:
+    return (
+        f"<<SYS>>\n{system_prompt.strip()}\n<</SYS>>\n\n"
+        f"User: {user_prompt.strip()}\n"
+        f"Assistant:"
+    )
+
+async def main():
+    async with Serverless() as client:
+        endpoint = await client.get_endpoint(name="my-tgi-endpoint")
+
+        system_prompt = (
+            "You are Qwen.\n"
+            "You are to only speak in English.\n"
+        )
+        user_prompt = """
+        Critically analyze the extent to which hotdogs are sandwiches.
+        """
+
+        prompt = build_prompt(system_prompt, user_prompt)
+
+        payload = {
+            "inputs": prompt,
+            "parameters": {
+                "max_new_tokens": MAX_TOKENS,
+                "temperature": 0.7,
+                "do_sample": True,
+                "return_full_text": False,
+            }
+        }
+
+        resp = await endpoint.request(
+            "/generate_stream",
+            payload,
+            cost=MAX_TOKENS,
+            stream=True,
+        )
+        stream = resp["response"]
+
+        printed_answer = False
+        async for event in stream:
+            tok = (event.get("token") or {}).get("text")
+            if tok:
+                if not printed_answer:
+                    printed_answer = True
+                    print("Answer:\n", end="", flush=True)
+                print(tok, end="", flush=True)
+
+if __name__ == "__main__":
+    asyncio.run(main())
\ No newline at end of file
diff --git a/examples/client/vllm_load_example.py b/examples/client/vllm_load_example.py
new file mode 100644
index 00000000..4ff103ce
--- /dev/null
+++ b/examples/client/vllm_load_example.py
@@ -0,0 +1,31 @@
+import asyncio
+from vastai import Serverless, ServerlessRequest
+
+MAX_TOKENS = 500
+
+async def main():
+    async with Serverless() as client:
+        endpoint = await client.get_endpoint(name="my-vllm-endpoint")
+
+        payload = {
+            "model": "Qwen/Qwen3-8B",
+            "prompt" : "Who are you?",
+            "max_tokens" : MAX_TOKENS,
+            "temperature" : 0.7
+        }
+        
+        responses = []
+
+        CUR_LOAD = 16000
+        while True:
+            # Create a ServerlessRequest object to attach callbacks before submitting the request
+            req = ServerlessRequest()
+            # Attach a callback to run when the machine finished work on the request
+            def work_finished_callback(response):
+                print(response["response"]["choices"][0]["text"])
+            req.then(work_finished_callback)
+            responses.append(endpoint.request(route="/v1/completions", payload=payload, serverless_request=req, cost=MAX_TOKENS))
+            await asyncio.sleep(MAX_TOKENS / CUR_LOAD)
+
+if __name__ == "__main__":
+    asyncio.run(main())
\ No newline at end of file
diff --git a/examples/client/vllm_simple_example.py b/examples/client/vllm_simple_example.py
new file mode 100644
index 00000000..9f527b30
--- /dev/null
+++ b/examples/client/vllm_simple_example.py
@@ -0,0 +1,21 @@
+import asyncio
+from vastai import Serverless
+
+MAX_TOKENS = 128
+
+async def main():
+    async with Serverless() as client:
+        endpoint = await client.get_endpoint(name="my-vllm-endpoint")
+
+        payload = {
+            "model": "Qwen/Qwen3-8B",
+            "prompt" : "Who are you?",
+            "max_tokens" : MAX_TOKENS,
+            "temperature" : 0.7
+        }
+        
+        response = await endpoint.request("/v1/completions", payload, cost=MAX_TOKENS)
+        print(response["response"]["choices"][0]["text"])
+
+if __name__ == "__main__":
+    asyncio.run(main())
\ No newline at end of file
diff --git a/examples/client/vllm_stream_convo_example.py b/examples/client/vllm_stream_convo_example.py
new file mode 100644
index 00000000..753219d9
--- /dev/null
+++ b/examples/client/vllm_stream_convo_example.py
@@ -0,0 +1,58 @@
+import asyncio
+from vastai import Serverless
+
+MAX_TOKENS = 1024
+
+async def main():
+    async with Serverless() as client:
+        endpoint = await client.get_endpoint(name="my-vllm-endpoint")
+
+        system_prompt = (
+            "You are Qwen.\n"
+            "You are to only speak in English.\n"
+        )
+
+        user_prompt = "What is the integral of 2x^2 from 0 to 5?"
+
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ]
+
+        payload = {
+            "model": "Qwen/Qwen3-8B",
+            "messages": messages,
+            "stream": True,
+            "max_tokens": MAX_TOKENS,
+            "temperature": 0.7,
+        }
+
+        response = await endpoint.request("/v1/chat/completions", payload, cost=MAX_TOKENS, stream=True)
+        stream = response["response"]
+
+        printed_reasoning = False
+        printed_answer = False
+
+        async for chunk in stream:
+            delta = chunk["choices"][0].get("delta", {})
+
+            rc = delta.get("reasoning_content", None)
+            if rc:
+                if not printed_reasoning:
+                    printed_reasoning = True
+                    print("Reasoning:\n", end="", flush=True)
+                print(rc, end="", flush=True)
+
+            content = delta.get("content", None)
+            if content:
+                if not printed_answer:
+                    printed_answer = True
+                    if printed_reasoning:
+                        print("\n\nAnswer:\n", end="", flush=True)
+                    else:
+                        print("Answer:\n", end="", flush=True)
+                print(content, end="", flush=True)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/client/vllm_streaming_example.py b/examples/client/vllm_streaming_example.py
new file mode 100644
index 00000000..b9f49a0e
--- /dev/null
+++ b/examples/client/vllm_streaming_example.py
@@ -0,0 +1,37 @@
+import asyncio
+from vastai import Serverless
+
+MAX_TOKENS = 1024
+
+async def main():
+    async with Serverless() as client:
+        endpoint = await client.get_endpoint(name="my-vllm-endpoint")
+
+        system_prompt = (
+            "You are Qwen, a helpful AI assistant.\n"
+            "You are to only speak in English.\n"
+            "Please answer the users response.\n"
+            "When you are done, use the <stop> token.\n"
+        )
+
+
+        user_prompt = """
+        What is the 118th element in the periodic table?
+        """
+
+        payload = {
+            "model": "Qwen/Qwen3-8B",
+            "prompt" : f"{system_prompt}\n{user_prompt}\n",
+            "max_tokens" : MAX_TOKENS,
+            "temperature" : 0.8,
+            "stop" : ["<stop>"],
+            "stream" : True,
+        }
+
+        response = await endpoint.request("/v1/completions", payload, cost=MAX_TOKENS, stream=True)
+        stream = response["response"]
+        async for event in stream:
+            print(event["choices"][0]["text"], end="", flush=True)
+
+if __name__ == "__main__":
+    asyncio.run(main())
\ No newline at end of file
diff --git a/examples/client/wan_example.py b/examples/client/wan_example.py
new file mode 100644
index 00000000..cfb708dc
--- /dev/null
+++ b/examples/client/wan_example.py
@@ -0,0 +1,205 @@
+from vastai import Serverless
+import asyncio
+
+async def main():
+    async with Serverless() as client:
+        endpoint = await client.get_endpoint(name="my-wan-endpoint")
+
+        # ComfyUI API compatible json workflow for Wan 2.2 T2V
+        workflow = {
+          "90": {
+            "inputs": {
+              "clip_name": "umt5_xxl_fp8_e4m3fn_scaled.safetensors",
+              "type": "wan",
+              "device": "default"
+            },
+            "class_type": "CLIPLoader",
+            "_meta": {
+              "title": "Load CLIP"
+            }
+          },
+          "91": {
+            "inputs": {
+              "text": "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走，裸露，NSFW",
+              "clip": ["90", 0]
+            },
+            "class_type": "CLIPTextEncode",
+            "_meta": {
+              "title": "CLIP Text Encode (Negative Prompt)"
+            }
+          },
+          "92": {
+            "inputs": {
+              "vae_name": "wan_2.1_vae.safetensors"
+            },
+            "class_type": "VAELoader",
+            "_meta": {
+              "title": "Load VAE"
+            }
+          },
+          "93": {
+            "inputs": {
+              "shift": 8.000000000000002,
+              "model": ["101", 0]
+            },
+            "class_type": "ModelSamplingSD3",
+            "_meta": {
+              "title": "ModelSamplingSD3"
+            }
+          },
+          "94": {
+            "inputs": {
+              "shift": 8,
+              "model": ["102", 0]
+            },
+            "class_type": "ModelSamplingSD3",
+            "_meta": {
+              "title": "ModelSamplingSD3"
+            }
+          },
+          "95": {
+            "inputs": {
+              "add_noise": "disable",
+              "noise_seed": 0,
+              "steps": 20,
+              "cfg": 3.5,
+              "sampler_name": "euler",
+              "scheduler": "simple",
+              "start_at_step": 10,
+              "end_at_step": 10000,
+              "return_with_leftover_noise": "disable",
+              "model": ["94", 0],
+              "positive": ["99", 0],
+              "negative": ["91", 0],
+              "latent_image": ["96", 0]
+            },
+            "class_type": "KSamplerAdvanced",
+            "_meta": {
+              "title": "KSampler (Advanced)"
+            }
+          },
+          "96": {
+            "inputs": {
+              "add_noise": "enable",
+              "noise_seed": "__RANDOM_INT__",
+              "steps": 20,
+              "cfg": 3.5,
+              "sampler_name": "euler",
+              "scheduler": "simple",
+              "start_at_step": 0,
+              "end_at_step": 10,
+              "return_with_leftover_noise": "enable",
+              "model": ["93", 0],
+              "positive": ["99", 0],
+              "negative": ["91", 0],
+              "latent_image": ["104", 0]
+            },
+            "class_type": "KSamplerAdvanced",
+            "_meta": {
+              "title": "KSampler (Advanced)"
+            }
+          },
+          "97": {
+            "inputs": {
+              "samples": ["95", 0],
+              "vae": ["92", 0]
+            },
+            "class_type": "VAEDecode",
+            "_meta": {
+              "title": "VAE Decode"
+            }
+          },
+          "98": {
+            "inputs": {
+              "filename_prefix": "video/ComfyUI",
+              "format": "auto",
+              "codec": "auto",
+              "video": ["100", 0]
+            },
+            "class_type": "SaveVideo",
+            "_meta": {
+              "title": "Save Video"
+            }
+          },
+          "99": {
+            "inputs": {
+              "text": "Beautiful young European woman with honey blonde hair gracefully turning her head back over shoulder, gentle smile, bright eyes looking at camera. Hair flowing in slow motion as she turns. Soft natural lighting, clean background, cinematic portrait.",
+              "clip": ["90", 0]
+            },
+            "class_type": "CLIPTextEncode",
+            "_meta": {
+              "title": "CLIP Text Encode (Positive Prompt)"
+            }
+          },
+          "100": {
+            "inputs": {
+              "fps": 16,
+              "images": ["97", 0]
+            },
+            "class_type": "CreateVideo",
+            "_meta": {
+              "title": "Create Video"
+            }
+          },
+          "101": {
+            "inputs": {
+              "unet_name": "wan2.2_t2v_high_noise_14B_fp8_scaled.safetensors",
+              "weight_dtype": "default"
+            },
+            "class_type": "UNETLoader",
+            "_meta": {
+              "title": "Load Diffusion Model"
+            }
+          },
+          "102": {
+            "inputs": {
+              "unet_name": "wan2.2_t2v_low_noise_14B_fp8_scaled.safetensors",
+              "weight_dtype": "default"
+            },
+            "class_type": "UNETLoader",
+            "_meta": {
+              "title": "Load Diffusion Model"
+            }
+          },
+          "104": {
+            "inputs": {
+              "width": 640,
+              "height": 640,
+              "length": 81,
+              "batch_size": 1
+            },
+            "class_type": "EmptyHunyuanLatentVideo",
+            "_meta": {
+              "title": "EmptyHunyuanLatentVideo"
+            }
+          }
+        }
+
+        payload = {
+          "input": {
+            "request_id": "",
+            "workflow_json": workflow,
+            "s3": {
+              "access_key_id": "",
+              "secret_access_key": "",
+              "endpoint_url": "",
+              "bucket_name": "",
+              "region": ""
+            },
+            "webhook": {
+              "url": "",
+              "extra_params": {
+                "user_id": "12345",
+                "project_id": "abc-def"
+              }
+            }
+          }
+        }
+
+        response = await endpoint.request("/generate/sync", payload)
+
+        # Response contains status, output, and any errors
+        print(response["response"])
+
+if __name__ == "__main__":
+    asyncio.run(main())
\ No newline at end of file
diff --git a/examples/server/ace_worker.py b/examples/server/ace_worker.py
new file mode 100644
index 00000000..11524a62
--- /dev/null
+++ b/examples/server/ace_worker.py
@@ -0,0 +1,184 @@
+import random
+import sys
+
+from vastai import Worker, WorkerConfig, HandlerConfig, LogActionConfig, BenchmarkConfig
+
+# ComyUI model configuration
+MODEL_SERVER_URL           = 'http://127.0.0.1'
+MODEL_SERVER_PORT          = 18288
+MODEL_LOG_FILE             = '/var/log/portal/comfyui.log'
+MODEL_HEALTHCHECK_ENDPOINT = "/health"
+
+# ComyUI-specific log messages
+MODEL_LOAD_LOG_MSG = [
+    "To see the GUI go to: "
+]
+
+MODEL_ERROR_LOG_MSGS = [
+    "MetadataIncompleteBuffer",
+    "Value not in list: ",
+    "[ERROR] Provisioning Script failed"
+]
+
+MODEL_INFO_LOG_MSGS = [
+    '"message":"Downloading'
+]
+
+benchmark_lyrics = [
+    "[verse]\nGuardian cloaked in twilight hue\nShadows melt where he breaks through\nEchoes swirl in mystic flight\nHooded hero owns the night\n\n[verse]\nThrough the chaos shapes arise\nFeral whispers, glowing eyes\nOrcs and creatures side by side\nMarch within the inky tide\n\n[chorus]\nRise above the fear and gloom\nLet your courage fully bloom\nIn the darkness stand your ground\nHear the night proclaim your sound",
+    "[verse]\nMorning sun on fields of gold\nGentle stories unfold\nEvery breeze a quiet song\nWhere the peaceful hearts belong\n\n[verse]\nLanterns glow at stable doors\nRustling leaves on orchard floors\nSimple joys in every hand\nLife grows soft in fertile land\n\n[chorus]\nLet the day drift slow and free\nRoot your soul where you can be\nIn this haven warm and bright\nFeel the earth breathe pure delight",
+    "[verse]\nLittle feet on dusty ground\nChasing dreams without a sound\nSoccer ball in morning light\nHopes take wing in youthful flight\n\n[verse]\nChrome reflections paint the day\nSwagger in the steps that play\nCopper tones in shining air\nChildhood gleaming everywhere\n\n[chorus]\nKick the world with boundless cheer\nHold the magic close and near\nIn each moment bold and true\nLet the sky belong to you",
+    "[verse]\nSunset bleeds across the street\nGilded calm in summer heat\nLow-rise towers rimmed with fire\nDreams ignite as lights climb higher\n\n[verse]\nFootsteps scatter through the haze\nFutures shimmer in the blaze\nEvery window tells a tale\nFloating through a tangerine veil\n\n[chorus]\nLet the neon softly glow\nLet your restless heartbeat slow\nIn this city forged in light\nCarry hope into the night",
+    "[verse]\nOcean breathes in rolling arcs\nSprays of diamond, glowing sparks\nWaves unfold a perfect line\nNature’s rhythm feels divine\n\n[verse]\nSun above in golden sweep\nPaints the rise of every deep\nShimmer drifting through the blue\nWorld reborn in every view\n\n[chorus]\nLet the tide pull you along\nHear the water’s ancient song\nIn the cresting waves you’ll find\nQuiet peace for heart and mind",
+    "[verse]\nGlass aglow with swirling light\nFruits and mints in colors bright\nIcy whispers clink and chime\nFlowing forms suspend in time\n\n[verse]\nCreamy spirals drift within\nGentle currents slowly spin\nWarm reflections lingering sweet\nMixing flavors at your feet\n\n[chorus]\nSip the glow and let it rise\nTaste the sunset in disguise\nIn this moment clear and true\nLet the warmth flow into you",
+    "[verse]\nEngines rumble down the lane\nCopper clouds of steam and rain\nOilpunk dreams in metal shine\nRider drifting down the line\n\n[verse]\nLeather jacket, steady glare\nStories sparking in the air\nMagazine lights frame his face\nKing of roads in timeless grace\n\n[chorus]\nThrottle up beyond the bend\nFeel the force of steel ascend\nRide the night and hold on tight\nClaim the world in streaks of light",
+    "[verse]\nCut-out shapes in swirling play\nTextures dance in bold array\nCats in denim, grinning wide\nStrut across the patterned tide\n\n[verse]\nPosters hum with neon glow\nSurreal scenes begin to grow\nColors crisp as folded art\nPatchwork beating like a heart\n\n[chorus]\nLet the collage come alive\nWatch the vibrant pieces thrive\nIn this joyful, crafted space\nEvery shape finds its own place",
+    "[verse]\nTiny world in crystal glass\nAncient tales behind the mass\nVillage lights in winter gleam\nFrozen in a mystic dream\n\n[verse]\nLantern beams in swirling air\nSoft enchantment everywhere\nShadows drift with gentle grace\nMagic sealed within the space\n\n[chorus]\nHold the sphere and you will see\nEchoes of a memory\nIn the glow of fragile light\nLives a realm of pure delight",
+    "[verse]\nArmor hums with power bright\nChopping sparks in jungle night\nMecha spirits shift and scream\nThrough the ferns like shattered beams\n\n[verse]\nAxes blaze in glowing arcs\nLighting up the shadowed marks\nNature roars in trembling air\nClash of steel and cosmic flare\n\n[chorus]\nRaise the fire, strike the ground\nLet your legend shake the sound\nIn the wild where echoes roam\nForge the fight and carve your home",
+    "[verse]\nCrowds ignite in vibrant flare\nBeats explode through smoky air\nDJ robes replaced with flame\nPope on decks in holy frame\n\n[verse]\nLeather gleams in blinding light\nTurntables spin with sacred might\nChoirs echo in the bass\nHeaven pulses through the place\n\n[chorus]\nLift the roof and shake the floor\nSacred rhythm evermore\nLet the music take control\nFeel the blessing in your soul",
+]
+
+benchmark_dataset = [
+    {
+        "input": {
+            "request_id": "",
+            "workflow_json": {
+                "14": {
+                "inputs": {
+                    "tags": "funk, pop, soul, rock, melodic, guitar, drums, bass, keyboard, percussion, 105 BPM, energetic, upbeat, groovy, vibrant, dynamic",
+                    "lyrics": lyrics,
+                    "lyrics_strength": 0.99,
+                    "clip": ["40", 1]
+                },
+                "class_type": "TextEncodeAceStepAudio",
+                "_meta": {
+                    "title": "TextEncodeAceStepAudio"
+                }
+                },
+                "17": {
+                "inputs": {
+                    "seconds": 180,
+                    "batch_size": 1
+                },
+                "class_type": "EmptyAceStepLatentAudio",
+                "_meta": {
+                    "title": "EmptyAceStepLatentAudio"
+                }
+                },
+                "18": {
+                "inputs": {
+                    "samples": ["52", 0],
+                    "vae": ["40", 2]
+                },
+                "class_type": "VAEDecodeAudio",
+                "_meta": {
+                    "title": "VAE Decode Audio"
+                }
+                },
+                "40": {
+                "inputs": {
+                    "ckpt_name": "ace_step_v1_3.5b.safetensors"
+                },
+                "class_type": "CheckpointLoaderSimple",
+                "_meta": {
+                    "title": "Load Checkpoint"
+                }
+                },
+                "44": {
+                "inputs": {
+                    "conditioning": ["14", 0]
+                },
+                "class_type": "ConditioningZeroOut",
+                "_meta": {
+                    "title": "ConditioningZeroOut"
+                }
+                },
+                "49": {
+                "inputs": {
+                    "model": ["51", 0],
+                    "operation": ["50", 0]
+                },
+                "class_type": "LatentApplyOperationCFG",
+                "_meta": {
+                    "title": "LatentApplyOperationCFG"
+                }
+                },
+                "50": {
+                "inputs": {
+                    "multiplier": 1.15
+                },
+                "class_type": "LatentOperationTonemapReinhard",
+                "_meta": {
+                    "title": "LatentOperationTonemapReinhard"
+                }
+                },
+                "51": {
+                "inputs": {
+                    "shift": 6,
+                    "model": ["40", 0]
+                },
+                "class_type": "ModelSamplingSD3",
+                "_meta": {
+                    "title": "ModelSamplingSD3"
+                }
+                },
+                "52": {
+                "inputs": {
+                    "seed": "__RANDOM_INT__",
+                    "steps": 65,
+                    "cfg": 4,
+                    "sampler_name": "er_sde",
+                    "scheduler": "linear_quadratic",
+                    "denoise": 1,
+                    "model": ["49", 0],
+                    "positive": ["14", 0],
+                    "negative": ["44", 0],
+                    "latent_image": ["17", 0]
+                },
+                "class_type": "KSampler",
+                "_meta": {
+                    "title": "KSampler"
+                }
+                },
+                "59": {
+                "inputs": {
+                    "filename_prefix": "audio/ComfyUI",
+                    "quality": "V0",
+                    "audioUI": "",
+                    "audio": ["18", 0]
+                },
+                "class_type": "SaveAudioMP3",
+                "_meta": {
+                    "title": "Save Audio (MP3)"
+                }
+                }
+            }
+        }
+    } for lyrics in benchmark_lyrics
+]
+
+worker_config = WorkerConfig(
+    model_server_url=MODEL_SERVER_URL,
+    model_server_port=MODEL_SERVER_PORT,
+    model_log_file=MODEL_LOG_FILE,
+    model_healthcheck_url=MODEL_HEALTHCHECK_ENDPOINT,
+    handlers=[
+        HandlerConfig(
+            route="/generate/sync",
+            allow_parallel_requests=False,
+            max_queue_time=10.0,
+            benchmark_config=BenchmarkConfig(
+                dataset=benchmark_dataset,
+                runs=1
+            ),
+            workload_calculator= lambda _ : 1000.0
+        )
+    ],
+    log_action_config=LogActionConfig(
+        on_load=MODEL_LOAD_LOG_MSG,
+        on_error=MODEL_ERROR_LOG_MSGS,
+        on_info=MODEL_INFO_LOG_MSGS
+    )
+)
+
+Worker(worker_config).run()
\ No newline at end of file
diff --git a/examples/server/comfy_worker.py b/examples/server/comfy_worker.py
new file mode 100644
index 00000000..ddb7da62
--- /dev/null
+++ b/examples/server/comfy_worker.py
@@ -0,0 +1,81 @@
+import random
+import sys
+
+from vastai import Worker, WorkerConfig, HandlerConfig, LogActionConfig, BenchmarkConfig
+
+# ComyUI model configuration
+MODEL_SERVER_URL           = 'http://127.0.0.1'
+MODEL_SERVER_PORT          = 18288
+MODEL_LOG_FILE             = '/var/log/portal/comfyui.log'
+MODEL_HEALTHCHECK_ENDPOINT = "/health"
+
+# ComyUI-specific log messages
+MODEL_LOAD_LOG_MSG = [
+    "To see the GUI go to: "
+]
+
+MODEL_ERROR_LOG_MSGS = [
+    "MetadataIncompleteBuffer",
+    "Value not in list: ",
+    "[ERROR] Provisioning Script failed"
+]
+
+MODEL_INFO_LOG_MSGS = [
+    '"message":"Downloading'
+]
+
+benchmark_prompts = [
+    "Cartoon hoodie hero; orc, anime cat, bunny; black goo; buff; vector on white.",
+    "Cozy farming-game scene with fine details.",
+    "2D vector child with soccer ball; airbrush chrome; swagger; antique copper.",
+    "Realistic futuristic downtown of low buildings at sunset.",
+    "Perfect wave front view; sunny seascape; ultra-detailed water; artful feel.",
+    "Clear cup with ice, fruit, mint; creamy swirls; fluid-sim CGI; warm glow.",
+    "Male biker with backpack on motorcycle; oilpunk; award-worthy magazine cover.",
+    "Collage for textile; surreal cartoon cat in cap/jeans before poster; crisp.",
+    "Medieval village inside glass sphere; volumetric light; macro focus.",
+    "Iron Man with glowing axe; mecha sci-fi; jungle scene; dynamic light.",
+    "Pope Francis DJ in leather jacket, mixing on giant console; dramatic.",
+]
+
+
+
+benchmark_dataset = [
+    {
+        "input": {
+            "request_id": f"test-{random.randint(1000, 99999)}",
+            "modifier": "Text2Image",
+            "modifications": {
+                "prompt": prompt,
+                "width": 512,
+                "height": 512,
+                "steps": 20,
+                "seed": random.randint(0, sys.maxsize)
+            }
+        }
+    } for prompt in benchmark_prompts
+]
+
+worker_config = WorkerConfig(
+    model_server_url=MODEL_SERVER_URL,
+    model_server_port=MODEL_SERVER_PORT,
+    model_log_file=MODEL_LOG_FILE,
+    model_healthcheck_url=MODEL_HEALTHCHECK_ENDPOINT,
+    handlers=[
+        HandlerConfig(
+            route="/generate/sync",
+            allow_parallel_requests=False,
+            max_queue_time=10.0,
+            benchmark_config=BenchmarkConfig(
+                dataset=benchmark_dataset,
+            )
+        )
+    ],
+    log_action_config=LogActionConfig(
+        on_load=MODEL_LOAD_LOG_MSG,
+        on_error=MODEL_ERROR_LOG_MSGS,
+        on_info=MODEL_INFO_LOG_MSGS
+    )
+)
+
+Worker(worker_config).run()
\ No newline at end of file
diff --git a/examples/server/tgi_worker.py b/examples/server/tgi_worker.py
new file mode 100644
index 00000000..f8084ab2
--- /dev/null
+++ b/examples/server/tgi_worker.py
@@ -0,0 +1,76 @@
+import nltk
+import random
+
+from vastai import Worker, WorkerConfig, HandlerConfig, LogActionConfig, BenchmarkConfig
+
+# TGI model configuration
+MODEL_SERVER_URL           = 'http://0.0.0.0'
+MODEL_SERVER_PORT          = 5001
+MODEL_LOG_FILE             = "/workspace/infer.log"
+MODEL_HEALTHCHECK_ENDPOINT = "/health"
+
+# TGI-specific log messages
+MODEL_LOAD_LOG_MSG = [
+    '"message":"Connected","target":"text_generation_router"',
+    '"message":"Connected","target":"text_generation_router::server"',
+]
+
+MODEL_ERROR_LOG_MSGS = [
+    "Error: WebserverFailed",
+    "Error: DownloadError",
+    "Error: ShardCannotStart",
+]
+
+MODEL_INFO_LOG_MSGS = [
+    '"message":"Download'
+]
+
+nltk.download("words")
+WORD_LIST = nltk.corpus.words.words()
+
+
+def benchmark_generator() -> dict:
+    prompt = " ".join(random.choices(WORD_LIST, k=int(250)))
+
+    benchmark_data = {
+        "inputs": prompt,
+        "parameters": {
+            "max_new_tokens": 128,
+            "temperature": 0.7,
+            "return_full_text": False
+        }
+    }
+
+    return benchmark_data
+
+worker_config = WorkerConfig(
+    model_server_url=MODEL_SERVER_URL,
+    model_server_port=MODEL_SERVER_PORT,
+    model_log_file=MODEL_LOG_FILE,
+    model_healthcheck_url=MODEL_HEALTHCHECK_ENDPOINT,
+    handlers=[
+        HandlerConfig(
+            route="/generate",
+            allow_parallel_requests=True,
+            max_queue_time=60.0,
+            benchmark_config=BenchmarkConfig(
+                generator=benchmark_generator,
+                concurrency=50
+            ),
+            workload_calculator= lambda x: x["parameters"]["max_new_tokens"]
+        ),
+        HandlerConfig(
+            route="/generate_stream",
+            allow_parallel_requests=True,
+            max_queue_time=60.0,
+            workload_calculator= lambda x: x["parameters"]["max_new_tokens"]
+        )
+    ],
+    log_action_config=LogActionConfig(
+        on_load=MODEL_LOAD_LOG_MSG,
+        on_error=MODEL_ERROR_LOG_MSGS,
+        on_info=MODEL_INFO_LOG_MSGS
+    )
+)
+
+Worker(worker_config).run()
\ No newline at end of file
diff --git a/examples/server/tutorial_worker.py b/examples/server/tutorial_worker.py
new file mode 100644
index 00000000..4cb86223
--- /dev/null
+++ b/examples/server/tutorial_worker.py
@@ -0,0 +1,92 @@
+from vastai import Worker, WorkerConfig, HandlerConfig, BenchmarkConfig, LogActionConfig
+
+# We define a WorkerConfig object to configure our PyWorker
+# Here, we can implement handlers for different routes our
+# endpoint may serve
+worker_config = WorkerConfig(
+    # --- Model Config ---
+    # The local URL of your model
+    model_server_url="http://127.0.0.1",
+    # The port your model is running on
+    model_server_port=18000,
+    # The file your model writes logs to
+    model_log_file="/var/model/out.log",
+    # If your model responds to a healthcheck, you can specify it here
+    model_healthcheck_url="/health",
+
+    # --- Handler Config ---
+    # Here, we define potentially multiple endpoint handlers for our endpoint,
+    # each of which services a different route on our endpoint
+    handlers=[
+        HandlerConfig(
+            # The route on our endpoint that we are handling
+            route="/my/route",
+            # Enable this if the model backend supports handling multiple requests at once
+            # If 'False', the worker will enforce one request at a time on the
+            # model backend with strict FIFO ordering.
+            allow_parallel_requests=False,
+            # --- Benchmark config ---
+            # One endpoint handler must implement a BenchmarkConfig
+            # The BenchmarkConfig defines sample payloads we use for
+            # measuring the performance of any given machine.
+            # This is essential for correct optimal autoscaling behavior.
+            benchmark_config=BenchmarkConfig(
+                # A list of possible request payloads to benchmark on
+                dataset=[
+                    { "prompt" : "some" },
+                    { "prompt" : "sample" },
+                    { "prompt" : "data" }
+                ],
+                # You may also implement a `generator` function, which
+                # returns a benchmark payload dictionary
+                # generator= lambda: { "prompt" : "a" * random.randint(60) }
+
+                # How many times you should run the benchmark
+                runs= 5,
+
+                # If `allow_parallel_requests` == True, how many concurrent payloads per run
+                concurrency=10 
+            ),
+            # A function that calculates the workload per request
+            # Example: the length of the input data
+            workload_calculator= lambda request: len(request["prompt"])
+        )
+    ],
+
+    # --- Log Config ---
+    # Here, we define various LogActions, which inform our worker
+    # of model start, model error, or useful model information.
+    # It's important that your model outputs logs to the file
+    # specified in `model_log_file`, so the worker knows the state
+    # of the model and can react accordingly.
+    log_action_config=LogActionConfig(
+        # A log line from our model that indicates
+        # the model has completed loading and is ready
+        # to recieve requests
+        on_load=[
+            "Application startup complete.",
+        ],
+        # The log lines from our model that indicate
+        # the model has suffered an irrecoverable error
+        # and our worker must be restarted
+        on_error=[
+            "INFO exited: vllm",
+            "RuntimeError: Engine",
+            "Traceback (most recent call last):"
+        ],
+        # A log line the model may emit
+        # containing relevant information
+        on_info=[
+            '"message":"Download'
+        ]
+    )
+)
+
+# --- Running the Worker ---
+# Run the worker synchronously
+Worker(worker_config).run()
+
+# Or, if you wish to continue executing Python from this entrypoint,
+# you can run your PyWorker in an asyncio background task
+# pyworker_task = asyncio.run(Worker(worker_config).run_async())
+# ... more python here ...
\ No newline at end of file
diff --git a/examples/server/vllm_worker.py b/examples/server/vllm_worker.py
new file mode 100644
index 00000000..6cf17f0e
--- /dev/null
+++ b/examples/server/vllm_worker.py
@@ -0,0 +1,78 @@
+import nltk
+import random
+import os
+
+from vastai import Worker, WorkerConfig, HandlerConfig, LogActionConfig, BenchmarkConfig
+
+# vLLM model configuration
+MODEL_SERVER_URL           = 'http://127.0.0.1'
+MODEL_SERVER_PORT          = 18000
+MODEL_LOG_FILE             = '/var/log/portal/vllm.log'
+MODEL_HEALTHCHECK_ENDPOINT = "/health"
+
+# vLLM-specific log messages
+MODEL_LOAD_LOG_MSG = [
+    "Application startup complete.",
+]
+
+MODEL_ERROR_LOG_MSGS = [
+    "INFO exited: vllm",
+    "RuntimeError: Engine",
+    "Traceback (most recent call last):"
+]
+
+MODEL_INFO_LOG_MSGS = [
+    '"message":"Download'
+]
+
+nltk.download("words")
+WORD_LIST = nltk.corpus.words.words()
+
+
+def completions_benchmark_generator() -> dict:
+    prompt = " ".join(random.choices(WORD_LIST, k=int(250)))
+    model = os.environ.get("MODEL_NAME")
+    if not model:
+        raise ValueError("MODEL_NAME environment variable not set")
+
+    benchmark_data = {
+        "model": model,
+        "prompt": prompt,
+        "temperature": 0.7,
+        "max_tokens": 500,
+    }
+
+    return benchmark_data
+
+worker_config = WorkerConfig(
+    model_server_url=MODEL_SERVER_URL,
+    model_server_port=MODEL_SERVER_PORT,
+    model_log_file=MODEL_LOG_FILE,
+    model_healthcheck_url=MODEL_HEALTHCHECK_ENDPOINT,
+    handlers=[
+        HandlerConfig(
+            route="/v1/completions",
+            workload_calculator= lambda data: data.get("max_tokens", 0),
+            allow_parallel_requests=True,
+            max_queue_time=60.0,
+            benchmark_config=BenchmarkConfig(
+                generator=completions_benchmark_generator,
+                concurrency=100,
+                runs=2
+            )
+        ),
+        HandlerConfig(
+            route="/v1/chat/completions",
+            workload_calculator= lambda data: data.get("max_tokens", 0),
+            allow_parallel_requests=True,
+            max_queue_time=60.0,
+        )
+    ],
+    log_action_config=LogActionConfig(
+        on_load=MODEL_LOAD_LOG_MSG,
+        on_error=MODEL_ERROR_LOG_MSGS,
+        on_info=MODEL_INFO_LOG_MSGS
+    )
+)
+
+Worker(worker_config).run()
\ No newline at end of file
diff --git a/examples/server/wan_example.py b/examples/server/wan_example.py
new file mode 100644
index 00000000..174b5f4f
--- /dev/null
+++ b/examples/server/wan_example.py
@@ -0,0 +1,288 @@
+import random
+import sys
+
+from vastai import Worker, WorkerConfig, HandlerConfig, LogActionConfig, BenchmarkConfig
+
+# ComyUI model configuration
+MODEL_SERVER_URL           = 'http://127.0.0.1'
+MODEL_SERVER_PORT          = 18288
+MODEL_LOG_FILE             = '/var/log/portal/comfyui.log'
+MODEL_HEALTHCHECK_ENDPOINT = "/health"
+
+# ComyUI-specific log messages
+MODEL_LOAD_LOG_MSG = [
+    "To see the GUI go to: "
+]
+
+MODEL_ERROR_LOG_MSGS = [
+    "MetadataIncompleteBuffer",
+    "Value not in list: ",
+    "[ERROR] Provisioning Script failed"
+]
+
+MODEL_INFO_LOG_MSGS = [
+    '"message":"Downloading'
+]
+
+benchmark_prompts = [
+    "Cartoon hoodie hero; orc, anime cat, bunny; black goo; buff; vector on white.",
+    "Cozy farming-game scene with fine details.",
+    "2D vector child with soccer ball; airbrush chrome; swagger; antique copper.",
+    "Realistic futuristic downtown of low buildings at sunset.",
+    "Perfect wave front view; sunny seascape; ultra-detailed water; artful feel.",
+    "Clear cup with ice, fruit, mint; creamy swirls; fluid-sim CGI; warm glow.",
+    "Male biker with backpack on motorcycle; oilpunk; award-worthy magazine cover.",
+    "Collage for textile; surreal cartoon cat in cap/jeans before poster; crisp.",
+    "Medieval village inside glass sphere; volumetric light; macro focus.",
+    "Iron Man with glowing axe; mecha sci-fi; jungle scene; dynamic light.",
+    "Pope Francis DJ in leather jacket, mixing on giant console; dramatic.",
+]
+
+benchmark_dataset = [
+    {
+        "input": {
+            "workflow_json": {
+                "90": {
+                    "inputs": {
+                    "clip_name": "umt5_xxl_fp8_e4m3fn_scaled.safetensors",
+                    "type": "wan",
+                    "device": "default"
+                    },
+                    "class_type": "CLIPLoader",
+                    "_meta": {
+                    "title": "Load CLIP"
+                    }
+                },
+                "91": {
+                    "inputs": {
+                    "text": "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走，裸露，NSFW",
+                    "clip": [
+                        "90",
+                        0
+                    ]
+                    },
+                    "class_type": "CLIPTextEncode",
+                    "_meta": {
+                    "title": "CLIP Text Encode (Negative Prompt)"
+                    }
+                },
+                "92": {
+                    "inputs": {
+                    "vae_name": "wan_2.1_vae.safetensors"
+                    },
+                    "class_type": "VAELoader",
+                    "_meta": {
+                    "title": "Load VAE"
+                    }
+                },
+                "93": {
+                    "inputs": {
+                    "shift": 8.000000000000002,
+                    "model": [
+                        "101",
+                        0
+                    ]
+                    },
+                    "class_type": "ModelSamplingSD3",
+                    "_meta": {
+                    "title": "ModelSamplingSD3"
+                    }
+                },
+                "94": {
+                    "inputs": {
+                    "shift": 8,
+                    "model": [
+                        "102",
+                        0
+                    ]
+                    },
+                    "class_type": "ModelSamplingSD3",
+                    "_meta": {
+                    "title": "ModelSamplingSD3"
+                    }
+                },
+                "95": {
+                    "inputs": {
+                    "add_noise": "disable",
+                    "noise_seed": 0,
+                    "steps": 20,
+                    "cfg": 3.5,
+                    "sampler_name": "euler",
+                    "scheduler": "simple",
+                    "start_at_step": 10,
+                    "end_at_step": 10000,
+                    "return_with_leftover_noise": "disable",
+                    "model": [
+                        "94",
+                        0
+                    ],
+                    "positive": [
+                        "99",
+                        0
+                    ],
+                    "negative": [
+                        "91",
+                        0
+                    ],
+                    "latent_image": [
+                        "96",
+                        0
+                    ]
+                    },
+                    "class_type": "KSamplerAdvanced",
+                    "_meta": {
+                    "title": "KSampler (Advanced)"
+                    }
+                },
+                "96": {
+                    "inputs": {
+                    "add_noise": "enable",
+                    "noise_seed": "__RANDOM_INT__",
+                    "steps": 20,
+                    "cfg": 3.5,
+                    "sampler_name": "euler",
+                    "scheduler": "simple",
+                    "start_at_step": 0,
+                    "end_at_step": 10,
+                    "return_with_leftover_noise": "enable",
+                    "model": [
+                        "93",
+                        0
+                    ],
+                    "positive": [
+                        "99",
+                        0
+                    ],
+                    "negative": [
+                        "91",
+                        0
+                    ],
+                    "latent_image": [
+                        "104",
+                        0
+                    ]
+                    },
+                    "class_type": "KSamplerAdvanced",
+                    "_meta": {
+                    "title": "KSampler (Advanced)"
+                    }
+                },
+                "97": {
+                    "inputs": {
+                    "samples": [
+                        "95",
+                        0
+                    ],
+                    "vae": [
+                        "92",
+                        0
+                    ]
+                    },
+                    "class_type": "VAEDecode",
+                    "_meta": {
+                    "title": "VAE Decode"
+                    }
+                },
+                "98": {
+                    "inputs": {
+                    "filename_prefix": "video/ComfyUI",
+                    "format": "auto",
+                    "codec": "auto",
+                    "video": [
+                        "100",
+                        0
+                    ]
+                    },
+                    "class_type": "SaveVideo",
+                    "_meta": {
+                    "title": "Save Video"
+                    }
+                },
+                "99": {
+                    "inputs": {
+                    "text":prompt,
+                    "clip": [
+                        "90",
+                        0
+                    ]
+                    },
+                    "class_type": "CLIPTextEncode",
+                    "_meta": {
+                    "title": "CLIP Text Encode (Positive Prompt)"
+                    }
+                },
+                "100": {
+                    "inputs": {
+                    "fps": 16,
+                    "images": [
+                        "97",
+                        0
+                    ]
+                    },
+                    "class_type": "CreateVideo",
+                    "_meta": {
+                    "title": "Create Video"
+                    }
+                },
+                "101": {
+                    "inputs": {
+                    "unet_name": "wan2.2_t2v_high_noise_14B_fp8_scaled.safetensors",
+                    "weight_dtype": "default"
+                    },
+                    "class_type": "UNETLoader",
+                    "_meta": {
+                    "title": "Load Diffusion Model"
+                    }
+                },
+                "102": {
+                    "inputs": {
+                    "unet_name": "wan2.2_t2v_low_noise_14B_fp8_scaled.safetensors",
+                    "weight_dtype": "default"
+                    },
+                    "class_type": "UNETLoader",
+                    "_meta": {
+                    "title": "Load Diffusion Model"
+                    }
+                },
+                "104": {
+                    "inputs": {
+                    "width": 640,
+                    "height": 640,
+                    "length": 81,
+                    "batch_size": 1
+                    },
+                    "class_type": "EmptyHunyuanLatentVideo",
+                    "_meta": {
+                    "title": "EmptyHunyuanLatentVideo"
+                    }
+                }
+            }
+        }
+    } for prompt in benchmark_prompts
+]
+
+worker_config = WorkerConfig(
+    model_server_url=MODEL_SERVER_URL,
+    model_server_port=MODEL_SERVER_PORT,
+    model_log_file=MODEL_LOG_FILE,
+    model_healthcheck_url=MODEL_HEALTHCHECK_ENDPOINT,
+    handlers=[
+        HandlerConfig(
+            route="/generate/sync",
+            allow_parallel_requests=False,
+            max_queue_time=10.0,
+            benchmark_config=BenchmarkConfig(
+                dataset=benchmark_dataset,
+                runs=1
+            ),
+            workload_calculator= lambda _ : 10000.0
+        )
+    ],
+    log_action_config=LogActionConfig(
+        on_load=MODEL_LOAD_LOG_MSG,
+        on_error=MODEL_ERROR_LOG_MSGS,
+        on_info=MODEL_INFO_LOG_MSGS
+    )
+)
+
+Worker(worker_config).run()
\ No newline at end of file
diff --git a/pyproject.toml b/pyproject.toml
index aeb35545..67bef6ad 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -21,26 +21,84 @@ requires-python = ">3.9.1, <4.0"
 license = { text = "MIT" }
 dynamic = ["version"]
 dependencies = [
+  # --- CLI core ---
   "xdg",
   "argcomplete==3.5.1",
-  "requests (>=2.32.4)",
-  "borb (==2.1.25)",
-  "python-dateutil==2.6.1",
+  "requests>=2.32.3",
+  "borb==2.1.25",
+  "python-dateutil>=2.6.1",
   "pytz",
   "urllib3>=2.6.3",
-  "poetry-dynamic-versioning (>=1.8.1,<2.0.0)",
-  "gitpython (>=3.1.44,<4.0.0)",
-  "toml (>=0.10.2,<0.11.0)",
-  "curlify (>=2.2.1,<3.0.0)",
+  "curlify>=2.2.1,<3.0.0",
   "setuptools",
-  "cryptography (>=44.0.2,<45.0.0)",
+  "cryptography>=44.0.2,<45.0.0",
   "rich",
   "fonttools>=4.60.2",
-  "qrcode"
+  "qrcode",
+  # --- SDK core (needed for vastai.sdk) ---
+  "pyparsing>=3.1,<4.0",
+]
+
+[project.optional-dependencies]
+# Serverless client + server dependencies
+serverless = [
+  "aiohttp>=3.10,<4.0",
+  "aiodns>=3.2.0",
+  "pycares>=4.4.0",
+  "anyio>=4.4,<5.0",
+  "psutil>=6.0,<7.0",
+  "pycryptodome>=3.20,<4.0",
+]
+# Everything: SDK + serverless
+all = [
+  "vastai[serverless]",
+]
+dev = [
+  "pytest>=8.0",
+  "pytest-cov>=4.0",
+  "mypy>=1.14",
+  "types-requests>=2.32",
+  "types-python-dateutil>=2.9",
+  "ruff>=0.9",
+  "pre-commit>=4.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = [
+  "--cov=vastai",
+  "--cov-report=term-missing",
+  "--cov-report=html:coverage_html",
+]
+
+[tool.coverage.run]
+branch = true
+source = ["vastai"]
+omit = [
+  "*/tests/*",
+  "*/.venv/*",
+  "*/site-packages/*",
+]
+
+[tool.coverage.report]
+precision = 2
+show_missing = true
+fail_under = 44
+exclude_lines = [
+  "pragma: no cover",
+  "if __name__ == .__main__.:",
+  "raise NotImplementedError",
+  "if TYPE_CHECKING:",
 ]
 
 [tool.poetry]
-packages = [{ include = "utils" }, { include = "vast.py" }]
+packages = [
+  { include = "vast.py" },
+  { include = "vast_config.py" },
+  { include = "utils" },
+  { include = "vastai" },
+  { include = "vastai_sdk" },
+]
 version = "0.0.0"
 
 [project.scripts]
@@ -58,3 +116,91 @@ style = "semver"
 
 [tool.poetry.requires-plugins]
 poetry-dynamic-versioning = { version = ">=1.0.0,<2.0.0", extras = ["plugin"] }
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+
+[[tool.mypy.overrides]]
+module = [
+    "borb.*",
+    "PIL.*",
+    "argcomplete.*",
+    "curlify.*",
+    "pyparsing.*",
+    "xdg.*",
+]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "vast"
+ignore_errors = true
+
+[[tool.mypy.overrides]]
+module = "vast_pdf"
+ignore_errors = true
+
+[[tool.mypy.overrides]]
+module = "vastai.vastai_base"
+ignore_errors = true
+
+[[tool.mypy.overrides]]
+module = "vastai.vastai_sdk"
+ignore_errors = true
+
+[[tool.mypy.overrides]]
+module = "vastai.serverless.*"
+ignore_errors = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+disallow_untyped_calls = false
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+exclude = [
+    ".git",
+    ".venv",
+    "__pycache__",
+    "build",
+    "dist",
+    ".eggs",
+    "*.egg-info",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "B",
+    "C4",
+    "UP",
+]
+ignore = [
+    "E501",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"vast.py" = ["T20", "A001", "A002", "E501", "B006", "F401", "F523", "F541", "F811", "F841", "E701", "E703", "E711", "E713", "E721", "E741"]
+"vast_pdf.py" = ["T20", "E501"]
+"tests/**/*.py" = ["F401", "S101"]
+"vastai/vastai_base.py" = ["B027"]
+"vastai/vastai_sdk.py" = ["E402", "F401"]
+"vastai/serverless/**/*.py" = ["F401", "F541", "F811", "F841", "E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["vastai", "vast"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
diff --git a/tests/__init__.py b/tests/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/conftest.py b/tests/conftest.py
new file mode 100644
index 00000000..efd75be9
--- /dev/null
+++ b/tests/conftest.py
@@ -0,0 +1,76 @@
+import json
+import os
+import pytest
+import argparse
+import requests
+from unittest.mock import MagicMock, patch
+
+
+@pytest.fixture
+def mock_args():
+    """Minimal argparse.Namespace for testing CLI functions."""
+    return argparse.Namespace(
+        api_key="test-key",
+        url="https://console.vast.ai",
+        retry=3,
+        raw=False,
+        explain=False,
+        quiet=False,
+        curl=False,
+        full=False,
+        no_color=True,
+        debugging=False,
+    )
+
+
+@pytest.fixture
+def mock_response():
+    """Mock HTTP response with configurable status and JSON body."""
+    response = MagicMock()
+    response.status_code = 200
+    response.json.return_value = {"success": True}
+    response.text = '{"success": true}'
+    response.content = b'{"success": true}'
+    response.headers = {"Content-Type": "application/json"}
+    response.raise_for_status = MagicMock()
+    return response
+
+
+@pytest.fixture
+def mock_api_response():
+    """Factory fixture for creating mock API responses with configurable status and data."""
+    def _make_response(status_code=200, json_data=None, text=None, headers=None):
+        response = MagicMock()
+        response.status_code = status_code
+        response.json.return_value = json_data if json_data is not None else {}
+        response.text = text if text is not None else json.dumps(json_data or {})
+        response.content = response.text.encode()
+        response.headers = headers if headers is not None else {"Content-Type": "application/json"}
+        if status_code >= 400:
+            response.raise_for_status.side_effect = requests.HTTPError(f"{status_code} Error")
+        else:
+            response.raise_for_status = MagicMock()
+        return response
+    return _make_response
+
+
+@pytest.fixture
+def mock_http_get(mock_api_response):
+    """Patch vast.http_get to return controlled responses."""
+    with patch('vast.http_get') as mock:
+        mock.return_value = mock_api_response(200, {"success": True})
+        yield mock
+
+
+@pytest.fixture
+def mock_http_post(mock_api_response):
+    """Patch vast.http_post to return controlled responses."""
+    with patch('vast.http_post') as mock:
+        mock.return_value = mock_api_response(200, {"success": True})
+        yield mock
+
+
+@pytest.fixture
+def vast_cli_path():
+    """Return path to vast.py for subprocess tests."""
+    return os.path.join(os.path.dirname(__file__), '..', 'vast.py')
diff --git a/tests/regression/__init__.py b/tests/regression/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/regression/test_bare_except.py b/tests/regression/test_bare_except.py
new file mode 100644
index 00000000..a2ac0ebb
--- /dev/null
+++ b/tests/regression/test_bare_except.py
@@ -0,0 +1,102 @@
+"""No bare except: clauses in vast.py.
+
+The bug: Bare except: catches SystemExit and KeyboardInterrupt, which can
+mask critical errors and make the program unresponsive to Ctrl+C. It also
+swallows programming errors (NameError, TypeError) that should crash loudly.
+
+The fix: Replace all bare except: with specific exception types appropriate
+to each try block's expected failure modes.
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+import re
+import pytest
+
+
+VAST_PY_PATH = os.path.join(os.path.dirname(__file__), '..', '..', 'vast.py')
+
+
+class TestNoBareExcept:
+    """Lint-style tests verifying no bare except: remains in vast.py."""
+
+    def test_no_bare_except(self):
+        """No bare except: clauses should exist in vast.py.
+
+        A bare except: catches everything including SystemExit and
+        KeyboardInterrupt, making Ctrl+C ineffective and masking bugs.
+        """
+        with open(VAST_PY_PATH, encoding='utf-8') as f:
+            content = f.read()
+        # Match "except:" but not "except SomeName:" or "except (A, B):"
+        bare_excepts = re.findall(r'^\s*except\s*:', content, re.MULTILINE)
+        assert len(bare_excepts) == 0, (
+            f"Found {len(bare_excepts)} bare except: clauses in vast.py. "
+            "Each except must catch specific exception types."
+        )
+
+    def test_except_clauses_have_types(self):
+        """Every except clause should specify at least one exception type."""
+        with open(VAST_PY_PATH, encoding='utf-8') as f:
+            content = f.read()
+        # Find all except lines
+        except_lines = re.findall(r'^\s*except\b.*:', content, re.MULTILINE)
+        for line in except_lines:
+            stripped = line.strip()
+            # Must be "except SomeType:" or "except (A, B) as e:" etc.
+            # NOT just "except:"
+            assert stripped != "except:", (
+                f"Found bare except: -- should catch specific types: {line!r}"
+            )
+
+
+class TestKeyboardInterruptPropagation:
+    """Verify KeyboardInterrupt is not swallowed by import handlers."""
+
+    def test_argcomplete_import_does_not_catch_keyboard_interrupt(self):
+        """The argcomplete import try/except should not catch KeyboardInterrupt.
+
+        Before the fix, bare except: would catch KeyboardInterrupt during
+        import, making Ctrl+C during startup silently ignored.
+        """
+        import importlib
+        import unittest.mock as mock
+
+        # Simulate argcomplete import raising KeyboardInterrupt
+        original_import = __builtins__.__import__ if hasattr(__builtins__, '__import__') else __import__
+
+        def mock_import(name, *args, **kwargs):
+            if name == 'argcomplete':
+                raise KeyboardInterrupt()
+            return original_import(name, *args, **kwargs)
+
+        # The except ImportError: handler should NOT catch KeyboardInterrupt
+        # so it should propagate
+        with pytest.raises(KeyboardInterrupt):
+            with mock.patch('builtins.__import__', side_effect=mock_import):
+                # Re-execute the import block logic
+                try:
+                    __import__('argcomplete')
+                except ImportError:
+                    pass  # This is what the fixed code does
+
+    def test_argcomplete_import_catches_import_error(self):
+        """The argcomplete import try/except should catch ImportError."""
+        import unittest.mock as mock
+
+        original_import = __builtins__.__import__ if hasattr(__builtins__, '__import__') else __import__
+
+        def mock_import(name, *args, **kwargs):
+            if name == 'argcomplete':
+                raise ImportError("No module named 'argcomplete'")
+            return original_import(name, *args, **kwargs)
+
+        # ImportError should be caught (not propagated)
+        caught = False
+        with mock.patch('builtins.__import__', side_effect=mock_import):
+            try:
+                __import__('argcomplete')
+            except ImportError:
+                caught = True
+        assert caught, "ImportError should be caught by except ImportError:"
diff --git a/tests/regression/test_direct_requests.py b/tests/regression/test_direct_requests.py
new file mode 100644
index 00000000..97be8800
--- /dev/null
+++ b/tests/regression/test_direct_requests.py
@@ -0,0 +1,146 @@
+"""No direct requests.get/post calls outside http_* helpers.
+
+The bug: Several functions used requests.get() or requests.post() directly,
+bypassing the centralized http_* helpers that provide timeout, retry, and
+error handling.
+
+The fix: Convert all direct requests.get/post calls in CLI command functions
+to use http_get/http_post. Only allowed exceptions are:
+  - get_project_data(): module-level PyPI check, no args available
+  - fetch_url_content(): utility function, no args available (dead code)
+  - _get_gpu_names(): module-level GPU cache, no args available
+  - http_request(): the low-level implementation that uses requests.Session
+  - import statements and commented-out code
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+import ast
+import re
+
+
+# Allowed locations for direct requests.get/post calls
+ALLOWED_FUNCTIONS = {
+    'get_project_data',   # Module-level PyPI check, no args
+    'fetch_url_content',  # Utility function, no args (dead code)
+    '_get_gpu_names',     # Module-level GPU cache, no args
+    'http_request',       # Low-level implementation
+}
+
+
+def _get_vast_source():
+    """Read the vast.py source file."""
+    vast_path = os.path.join(os.path.dirname(__file__), '..', '..', 'vast.py')
+    with open(vast_path, encoding='utf-8') as f:
+        return f.read()
+
+
+def test_no_direct_requests_get_in_command_functions():
+    """No requests.get() calls exist in CLI command functions (outside allowed exceptions)."""
+    source = _get_vast_source()
+    tree = ast.parse(source)
+
+    violations = []
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.FunctionDef):
+            func_name = node.name
+            if func_name in ALLOWED_FUNCTIONS:
+                continue
+
+            # Walk the function body looking for requests.get( or requests.post(
+            for child in ast.walk(node):
+                if isinstance(child, ast.Call):
+                    func = child.func
+                    # Match: requests.get(...) or requests.post(...)
+                    if (isinstance(func, ast.Attribute) and
+                            isinstance(func.value, ast.Name) and
+                            func.value.id == 'requests' and
+                            func.attr in ('get', 'post')):
+                        violations.append(
+                            f"  {func_name}() at line {child.lineno}: "
+                            f"requests.{func.attr}()"
+                        )
+
+    assert not violations, (
+        "Found direct requests.get/post calls in command functions "
+        "(should use http_get/http_post):\n" + "\n".join(violations)
+    )
+
+
+def test_no_direct_requests_get_via_grep():
+    """Grep-style check: no unprotected requests.get/post patterns in vast.py."""
+    source = _get_vast_source()
+    lines = source.split('\n')
+
+    violations = []
+    pattern = re.compile(r'(?<!#)\s*\w*\s*=?\s*requests\.(get|post)\(')
+
+    for i, line in enumerate(lines, 1):
+        stripped = line.strip()
+        # Skip comments
+        if stripped.startswith('#'):
+            continue
+        # Skip import lines
+        if 'import requests' in stripped:
+            continue
+
+        match = pattern.search(line)
+        if match:
+            # Check if this is in an allowed context
+            # We do a simple heuristic: look for function context
+            # by scanning backwards for the nearest 'def ' line
+            func_name = _find_enclosing_function(lines, i - 1)
+            if func_name in ALLOWED_FUNCTIONS:
+                continue
+            if func_name is None:
+                # Module level - check if it's in allowed module-level contexts
+                continue
+
+            violations.append(f"  Line {i} (in {func_name}): {stripped}")
+
+    assert not violations, (
+        "Found direct requests.get/post calls outside allowed functions:\n"
+        + "\n".join(violations)
+    )
+
+
+def _find_enclosing_function(lines, line_idx):
+    """Find the name of the outermost function containing the given line index.
+
+    Handles nested functions by tracking indentation: returns the function
+    definition with the smallest indentation (outermost enclosing function).
+    """
+    best_name = None
+    best_indent = float('inf')
+    for i in range(line_idx, -1, -1):
+        stripped = lines[i].lstrip()
+        if stripped.startswith('def '):
+            indent = len(lines[i]) - len(stripped)
+            match = re.match(r'def\s+(\w+)\s*\(', stripped)
+            if match and indent < best_indent:
+                best_name = match.group(1)
+                best_indent = indent
+                if indent == 0:
+                    break  # Top-level function, can't go higher
+    return best_name
+
+
+def test_allowed_exceptions_have_timeout():
+    """Allowed direct requests calls (get_project_data, _get_gpu_names) have timeout."""
+    source = _get_vast_source()
+    lines = source.split('\n')
+
+    # Find direct requests.get calls and verify they have timeout
+    for i, line in enumerate(lines, 1):
+        stripped = line.strip()
+        if stripped.startswith('#'):
+            continue
+        if 'requests.get(' in stripped and 'import' not in stripped:
+            func_name = _find_enclosing_function(lines, i - 1)
+            if func_name in ALLOWED_FUNCTIONS or func_name is None:
+                assert 'timeout' in stripped, (
+                    f"Line {i} (in {func_name or 'module-level'}): "
+                    f"direct requests.get() missing timeout parameter: {stripped}"
+                )
diff --git a/tests/regression/test_hardcoded_raw.py b/tests/regression/test_hardcoded_raw.py
new file mode 100644
index 00000000..4e499d5e
--- /dev/null
+++ b/tests/regression/test_hardcoded_raw.py
@@ -0,0 +1,61 @@
+"""Hardcoded `if True:` instead of `if args.raw:` in three functions.
+
+The bug: search__benchmarks, search__invoices, and search__templates have
+`if True: # args.raw:` which means they always return raw data / print JSON
+regardless of the --raw flag, bypassing display_table.
+
+The fix: Replace `if True:` with `if args.raw:`.
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+import argparse
+from unittest.mock import patch, MagicMock
+
+
+def _make_args(raw=False):
+    return argparse.Namespace(
+        api_key="test", url="https://console.vast.ai",
+        retry=3, raw=raw, explain=False, quiet=False,
+        curl=False, query=[],
+    )
+
+
+@patch('vast.display_table')
+@patch('vast.http_get')
+def test_search_benchmarks_respects_raw_flag(mock_http_get, mock_display):
+    """search__benchmarks calls display_table when raw=False."""
+    from vast import search__benchmarks
+
+    mock_resp = MagicMock()
+    mock_resp.status_code = 200
+    mock_resp.json.return_value = [{"id": 1, "score": 99}]
+    mock_resp.raise_for_status = MagicMock()
+    mock_http_get.return_value = mock_resp
+
+    args = _make_args(raw=False)
+    result = search__benchmarks(args)
+
+    # When raw=False, function should call display_table (not return data)
+    mock_display.assert_called_once()
+    # Return value should be None (display_table handles output)
+    assert result is None, f"Expected None when raw=False, got {result}"
+
+
+@patch('vast.http_get')
+def test_search_benchmarks_returns_data_when_raw(mock_http_get):
+    """search__benchmarks returns data when raw=True."""
+    from vast import search__benchmarks
+
+    mock_resp = MagicMock()
+    mock_resp.status_code = 200
+    mock_resp.json.return_value = [{"id": 1, "score": 99}]
+    mock_resp.raise_for_status = MagicMock()
+    mock_http_get.return_value = mock_resp
+
+    args = _make_args(raw=True)
+    result = search__benchmarks(args)
+
+    assert result is not None, "Expected data when raw=True"
+    assert isinstance(result, list)
diff --git a/tests/regression/test_http_exception.py b/tests/regression/test_http_exception.py
new file mode 100644
index 00000000..c94a5762
--- /dev/null
+++ b/tests/regression/test_http_exception.py
@@ -0,0 +1,72 @@
+"""Missing exception handling in http_request().
+
+The bug: session.send() has no try/except. Network errors (DNS failure,
+connection refused, timeout) crash with unhandled exceptions instead of
+being retried.
+
+The fix: Wrap session.send() in try/except RequestException. Retry on
+transient failures, re-raise on final attempt.
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+import argparse
+from unittest.mock import MagicMock, patch
+import pytest
+import requests.exceptions
+
+
+def _make_args(retry=3):
+    return argparse.Namespace(retry=retry, curl=False)
+
+
+@patch('vast.time.sleep')
+@patch('vast.requests.Session')
+def test_retries_on_connection_error(mock_session_cls, mock_sleep):
+    """http_request retries on ConnectionError before re-raising."""
+    from vast import http_request
+
+    mock_session = MagicMock()
+    mock_session_cls.return_value = mock_session
+
+    # First two calls raise ConnectionError, third succeeds
+    success_response = MagicMock()
+    success_response.status_code = 200
+    mock_session.send.side_effect = [
+        requests.exceptions.ConnectionError("connection refused"),
+        requests.exceptions.ConnectionError("connection refused"),
+        success_response,
+    ]
+    mock_session.prepare_request.return_value = MagicMock()
+
+    args = _make_args(retry=3)
+    # Patch ARGS global to avoid curl path
+    with patch('vast.ARGS', args):
+        result = http_request('GET', args, 'http://test.example.com')
+
+    assert result.status_code == 200
+    assert mock_session.send.call_count == 3
+    # Should have slept twice (after first two failures)
+    assert mock_sleep.call_count == 2
+
+
+@patch('vast.time.sleep')
+@patch('vast.requests.Session')
+def test_raises_on_final_retry(mock_session_cls, mock_sleep):
+    """http_request re-raises if all retries exhausted."""
+    from vast import http_request
+
+    mock_session = MagicMock()
+    mock_session_cls.return_value = mock_session
+
+    # All calls raise ConnectionError
+    mock_session.send.side_effect = requests.exceptions.ConnectionError("fail")
+    mock_session.prepare_request.return_value = MagicMock()
+
+    args = _make_args(retry=2)
+    with patch('vast.ARGS', args):
+        with pytest.raises(requests.exceptions.ConnectionError):
+            http_request('GET', args, 'http://test.example.com')
+
+    assert mock_session.send.call_count == 2
diff --git a/tests/regression/test_json_decode.py b/tests/regression/test_json_decode.py
new file mode 100644
index 00000000..f3a49d02
--- /dev/null
+++ b/tests/regression/test_json_decode.py
@@ -0,0 +1,128 @@
+"""JSONDecodeError handling in api_call().
+
+The bug: api_call() calls r.json() without protection. When the API returns
+non-JSON content (HTML error pages, empty responses, proxy errors), this
+raises JSONDecodeError and crashes the CLI.
+
+The fix: Wrap r.json() in try/except JSONDecodeError. On failure, return
+a fallback dict {"_raw_text": r.text} so callers can detect and handle
+the non-JSON response gracefully.
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+import argparse
+from unittest.mock import MagicMock, patch
+import pytest
+
+
+def _make_args(retry=1):
+    return argparse.Namespace(
+        retry=retry,
+        curl=False,
+        api_key="test-key",
+        url="https://console.vast.ai",
+        explain=False,
+        raw=False,
+    )
+
+
+@patch('vast.http_get')
+def test_api_call_returns_fallback_on_json_decode_error(mock_http_get):
+    """api_call() returns {"_raw_text": ...} when .json() raises JSONDecodeError."""
+    from vast import api_call, JSONDecodeError
+
+    mock_response = MagicMock()
+    mock_response.status_code = 200
+    mock_response.content = b"<html>Bad Gateway</html>"
+    mock_response.text = "<html>Bad Gateway</html>"
+    mock_response.json.side_effect = JSONDecodeError("msg", "doc", 0)
+    mock_response.raise_for_status.return_value = None
+    mock_http_get.return_value = mock_response
+
+    args = _make_args()
+    result = api_call(args, "GET", "/test/")
+
+    assert result is not None
+    assert "_raw_text" in result
+    assert result["_raw_text"] == "<html>Bad Gateway</html>"
+
+
+@patch('vast.http_get')
+def test_api_call_returns_json_on_valid_response(mock_http_get):
+    """api_call() returns parsed JSON normally when response is valid."""
+    from vast import api_call
+
+    mock_response = MagicMock()
+    mock_response.status_code = 200
+    mock_response.content = b'{"success": true}'
+    mock_response.json.return_value = {"success": True}
+    mock_response.raise_for_status.return_value = None
+    mock_http_get.return_value = mock_response
+
+    args = _make_args()
+    result = api_call(args, "GET", "/test/")
+
+    assert result == {"success": True}
+
+
+@patch('vast.http_get')
+def test_api_call_returns_none_for_empty_response(mock_http_get):
+    """api_call() returns None when response has no content."""
+    from vast import api_call
+
+    mock_response = MagicMock()
+    mock_response.status_code = 204
+    mock_response.content = b""
+    mock_response.raise_for_status.return_value = None
+    mock_http_get.return_value = mock_response
+
+    args = _make_args()
+    result = api_call(args, "GET", "/test/")
+
+    assert result is None
+
+
+@patch('vast.http_get')
+def test_api_call_no_exception_raised_on_html_response(mock_http_get):
+    """api_call() does NOT raise an exception when API returns HTML."""
+    from vast import api_call, JSONDecodeError
+
+    mock_response = MagicMock()
+    mock_response.status_code = 200
+    mock_response.content = b"<html><body>502 Bad Gateway</body></html>"
+    mock_response.text = "<html><body>502 Bad Gateway</body></html>"
+    mock_response.json.side_effect = JSONDecodeError("Expecting value", "<html>", 0)
+    mock_response.raise_for_status.return_value = None
+    mock_http_get.return_value = mock_response
+
+    args = _make_args()
+
+    # This should NOT raise - the whole point of the fix
+    try:
+        result = api_call(args, "GET", "/instances/")
+    except JSONDecodeError:
+        pytest.fail("api_call() should not raise JSONDecodeError")
+
+    assert "_raw_text" in result
+
+
+@patch('vast.http_post')
+def test_api_call_post_handles_json_decode_error(mock_http_post):
+    """api_call() handles JSONDecodeError for POST requests too."""
+    from vast import api_call, JSONDecodeError
+
+    mock_response = MagicMock()
+    mock_response.status_code = 200
+    mock_response.content = b"Internal Server Error"
+    mock_response.text = "Internal Server Error"
+    mock_response.json.side_effect = JSONDecodeError("msg", "doc", 0)
+    mock_response.raise_for_status.return_value = None
+    mock_http_post.return_value = mock_response
+
+    args = _make_args()
+    result = api_call(args, "POST", "/instances/", json_body={"test": True})
+
+    assert result is not None
+    assert result["_raw_text"] == "Internal Server Error"
diff --git a/tests/regression/test_main_error_handling.py b/tests/regression/test_main_error_handling.py
new file mode 100644
index 00000000..b5d4187b
--- /dev/null
+++ b/tests/regression/test_main_error_handling.py
@@ -0,0 +1,221 @@
+"""Regression tests for code quality fixes.
+
+- No Python builtins (id, sum) should be shadowed by local variables
+- strip('-') should not be used for prefix removal (use startswith + lstrip)
+- Error messages should reference correct field name
+- Unused variables should be removed
+"""
+import re
+import sys
+from pathlib import Path
+
+# Add vast-cli to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+
+class TestVariableShadowing:
+    """No Python builtins should be shadowed by local variable assignments."""
+
+    def test_no_id_shadowing(self):
+        """Local variable 'id' should not shadow builtin.
+
+        Note: keyword args in argparse.Namespace() like id=value are NOT shadowing.
+        """
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        content = vast_path.read_text(encoding='utf-8')
+
+        # Find all assignments to bare 'id' (not id= which is keyword arg)
+        # Pattern: whitespace + id + optional space + = + not = (not ==)
+        # This should NOT match lines like "id=ask_contract_id," in Namespace()
+        matches = re.findall(r'^\s+id\s+=[^=]', content, re.MULTILINE)
+
+        assert len(matches) == 0, (
+            f"Found {len(matches)} instances of 'id' shadowing builtin. "
+            f"These should be renamed to domain-specific names like instance_id, "
+            f"workergroup_id, etc. First few matches: {matches[:5]}"
+        )
+
+    def test_no_sum_function_shadowing(self):
+        """Function 'sum' should not shadow builtin.
+
+        The custom sum function should be renamed to sum_field or similar.
+        """
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        content = vast_path.read_text(encoding='utf-8')
+
+        # Check for def sum( function definition
+        matches = re.findall(r'^def sum\s*\(', content, re.MULTILINE)
+
+        assert len(matches) == 0, (
+            f"Found def sum() which shadows Python builtin. "
+            f"Should be renamed to sum_field() or similar."
+        )
+
+    def test_sum_field_function_exists(self):
+        """The renamed sum_field function should exist."""
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        content = vast_path.read_text(encoding='utf-8')
+
+        # Check for def sum_field( function definition
+        assert 'def sum_field(' in content, (
+            "Expected sum_field() function to exist after renaming from sum()"
+        )
+
+    def test_domain_specific_id_names_used(self):
+        """Verify domain-specific id names are used instead of bare 'id'."""
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        content = vast_path.read_text(encoding='utf-8')
+
+        expected_patterns = [
+            'workergroup_id = args.id',
+            'endpoint_id = args.id',
+            'volume_id = args.id',
+        ]
+
+        for pattern in expected_patterns:
+            assert pattern in content, (
+                f"Expected domain-specific name pattern '{pattern}' not found. "
+                f"Bare 'id' may not have been renamed properly."
+            )
+
+
+class TestStringMethodFixes:
+    """strip('-') should not be used for prefix removal."""
+
+    def test_no_strip_dash_for_direction(self):
+        """strip('-') removes from both ends - should use startswith + lstrip."""
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        content = vast_path.read_text(encoding='utf-8')
+
+        # .strip("-") or .strip('-') should not appear for direction parsing
+        matches = re.findall(r'name\.strip\(["\'][-+]["\']', content)
+
+        assert len(matches) == 0, (
+            f"Found {len(matches)} instances of name.strip('-') or name.strip('+'). "
+            f"These should use startswith() + lstrip() instead: {matches}"
+        )
+
+    def test_direction_parsing_uses_startswith(self):
+        """Sort direction parsing should use startswith, not strip comparison."""
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        content = vast_path.read_text(encoding='utf-8')
+
+        # Should find startswith("-") for direction checks
+        has_startswith_minus = 'name.startswith("-")' in content
+        has_startswith_plus = 'name.startswith("+")' in content
+
+        assert has_startswith_minus, (
+            "Expected name.startswith('-') for descending sort direction parsing"
+        )
+        assert has_startswith_plus, (
+            "Expected name.startswith('+') for ascending sort direction parsing"
+        )
+
+    def test_direction_parsing_uses_lstrip(self):
+        """After detecting prefix, should use lstrip to remove it."""
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        content = vast_path.read_text(encoding='utf-8')
+
+        # Should find lstrip("-") and lstrip("+")
+        has_lstrip_minus = 'name.lstrip("-")' in content
+        has_lstrip_plus = 'name.lstrip("+")' in content
+
+        assert has_lstrip_minus, (
+            "Expected name.lstrip('-') for removing descending prefix"
+        )
+        assert has_lstrip_plus, (
+            "Expected name.lstrip('+') for removing ascending prefix"
+        )
+
+    def test_elif_structure_for_direction_parsing(self):
+        """Direction parsing should use elif, not two separate if statements.
+
+        Using two separate if statements means a field like '-score' would first
+        match startswith('-') then incorrectly also check startswith('+').
+        """
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        content = vast_path.read_text(encoding='utf-8')
+
+        # Look for the correct pattern: if startswith("-") ... elif startswith("+")
+        # Not: if startswith("-") ... if startswith("+")
+        pattern = r'if name\.startswith\("-"\):.*?elif name\.startswith\("\+"\):'
+        matches = re.findall(pattern, content, re.DOTALL)
+
+        assert len(matches) >= 4, (
+            f"Expected at least 4 occurrences of correct if/elif pattern for "
+            f"direction parsing (in search__offers, search__instances, "
+            f"search__volumes, search__network_volumes), found {len(matches)}"
+        )
+
+
+class TestErrorMessages:
+    """Error messages should reference correct field."""
+
+    def test_start_date_error_message_correct(self):
+        """Error for start_date should say 'start date', not 'end date'."""
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        content = vast_path.read_text(encoding='utf-8')
+
+        # Should not have "start date" error saying "Ignoring end date"
+        bad_pattern = re.search(
+            r'Invalid start date.*Ignoring end date',
+            content,
+            re.IGNORECASE
+        )
+
+        assert bad_pattern is None, (
+            "Found misleading error message - start_date error mentions 'Ignoring end date'. "
+            "Should say 'Ignoring start date' instead."
+        )
+
+    def test_start_date_error_says_start_date(self):
+        """Start date errors should reference start date."""
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        content = vast_path.read_text(encoding='utf-8')
+
+        # Should find "Invalid start date" + "Ignoring start date" pattern
+        correct_pattern = re.search(
+            r'Invalid start date.*Ignoring start date',
+            content,
+            re.IGNORECASE
+        )
+
+        assert correct_pattern is not None, (
+            "Expected start_date error message to say 'Ignoring start date'"
+        )
+
+
+class TestUnusedVariables:
+    """Unused variables should be removed."""
+
+    def test_no_unused_date_txt_in_show_earnings(self):
+        """In show__earnings, date_txt variables should not be assigned if unused.
+
+        Note: date_txt variables ARE used in invoice functions, just not in show__earnings.
+        """
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        content = vast_path.read_text(encoding='utf-8')
+
+        # Find the show__earnings function
+        show_earnings_match = re.search(
+            r'def show__earnings\(args\):.*?(?=\ndef |$)',
+            content,
+            re.DOTALL
+        )
+
+        assert show_earnings_match is not None, "Could not find show__earnings function"
+
+        show_earnings_code = show_earnings_match.group(0)
+
+        # Check that end_date_txt and start_date_txt are not assigned in this function
+        has_end_date_txt = 'end_date_txt' in show_earnings_code
+        has_start_date_txt = 'start_date_txt' in show_earnings_code
+
+        assert not has_end_date_txt, (
+            "Found unused end_date_txt assignment in show__earnings. "
+            "This variable is assigned but never used in this function."
+        )
+        assert not has_start_date_txt, (
+            "Found unused start_date_txt assignment in show__earnings. "
+            "This variable is assigned but never used in this function."
+        )
diff --git a/tests/regression/test_main_raw_output.py b/tests/regression/test_main_raw_output.py
new file mode 100644
index 00000000..7e9df44f
--- /dev/null
+++ b/tests/regression/test_main_raw_output.py
@@ -0,0 +1,199 @@
+"""Regression tests for API request and raw output fixes."""
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+
+class TestApiKeyHandling:
+    """API key should be in headers, not JSON body."""
+
+    def test_no_api_key_in_json_blob(self):
+        """api_key should not appear in json_blob assignments."""
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        content = vast_path.read_text(encoding='utf-8')
+
+        # Look for json_blob containing api_key (but not in comments)
+        lines = content.split('\n')
+        violations = []
+        for i, line in enumerate(lines, 1):
+            # Skip comments
+            if line.strip().startswith('#'):
+                continue
+            # Check for api_key in json dict literal on same line as json_blob
+            if 'json_blob' in line and 'api_key' in line and '=' in line:
+                violations.append(f"Line {i}: {line.strip()}")
+
+        assert len(violations) == 0, f"Found api_key in json_blob: {violations}"
+
+    def test_get_endpt_logs_no_api_key_in_body(self):
+        """get__endpt_logs should not have api_key in JSON."""
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        content = vast_path.read_text(encoding='utf-8')
+
+        # Find function and check its body
+        pattern = r'def get__endpt_logs\(.*?(?=\ndef |\Z)'
+        match = re.search(pattern, content, re.DOTALL)
+        assert match, "get__endpt_logs function not found"
+
+        func_body = match.group(0)
+        # Should not have api_key in any dict literal
+        json_lines = [l for l in func_body.split('\n')
+                     if 'json_blob' in l and 'api_key' in l and '=' in l
+                     and not l.strip().startswith('#')]
+        assert len(json_lines) == 0, f"get__endpt_logs has api_key in json_blob: {json_lines}"
+
+    def test_get_wrkgrp_logs_no_api_key_in_body(self):
+        """get__wrkgrp_logs should not have api_key in JSON."""
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        content = vast_path.read_text(encoding='utf-8')
+
+        pattern = r'def get__wrkgrp_logs\(.*?(?=\ndef |\Z)'
+        match = re.search(pattern, content, re.DOTALL)
+        assert match, "get__wrkgrp_logs function not found"
+
+        func_body = match.group(0)
+        json_lines = [l for l in func_body.split('\n')
+                     if 'json_blob' in l and 'api_key' in l and '=' in l
+                     and not l.strip().startswith('#')]
+        assert len(json_lines) == 0, f"get__wrkgrp_logs has api_key in json_blob: {json_lines}"
+
+    def test_show_workergroups_no_api_key_in_body(self):
+        """show__workergroups should not have api_key in JSON."""
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        content = vast_path.read_text(encoding='utf-8')
+
+        pattern = r'def show__workergroups\(.*?(?=\ndef |\Z)'
+        match = re.search(pattern, content, re.DOTALL)
+        assert match, "show__workergroups function not found"
+
+        func_body = match.group(0)
+        json_lines = [l for l in func_body.split('\n')
+                     if 'json_blob' in l and 'api_key' in l and '=' in l
+                     and not l.strip().startswith('#')]
+        assert len(json_lines) == 0, f"show__workergroups has api_key in json_blob: {json_lines}"
+
+    def test_show_endpoints_no_api_key_in_body(self):
+        """show__endpoints should not have api_key in JSON."""
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        content = vast_path.read_text(encoding='utf-8')
+
+        pattern = r'def show__endpoints\(.*?(?=\ndef |\Z)'
+        match = re.search(pattern, content, re.DOTALL)
+        assert match, "show__endpoints function not found"
+
+        func_body = match.group(0)
+        json_lines = [l for l in func_body.split('\n')
+                     if 'json_blob' in l and 'api_key' in l and '=' in l
+                     and not l.strip().startswith('#')]
+        assert len(json_lines) == 0, f"show__endpoints has api_key in json_blob: {json_lines}"
+
+
+class TestSafeIteration:
+    """next() calls should have default to prevent StopIteration."""
+
+    def test_next_calls_have_default(self):
+        """All next() calls with generators should have a default parameter."""
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        content = vast_path.read_text(encoding='utf-8')
+
+        # Find next() calls without default
+        # Pattern: next(something for something) without a comma before closing
+        lines = content.split('\n')
+        risky_calls = []
+        for i, line in enumerate(lines, 1):
+            if 'next(' in line and not line.strip().startswith('#'):
+                # Simple heuristic: if line has next( with 'for' inside but no comma
+                # This catches: next(x for x in y) but not next((x for x in y), None)
+                match = re.search(r'next\(\s*[^,)]+\s+for\s+[^,)]+\)', line)
+                if match:
+                    risky_calls.append(f"Line {i}: {line.strip()}")
+
+        assert len(risky_calls) == 0, f"Found next() without default: {risky_calls}"
+
+    def test_show_clusters_next_has_default(self):
+        """show__clusters manager_node lookup should have default."""
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        content = vast_path.read_text(encoding='utf-8')
+
+        pattern = r'def show__clusters\(.*?(?=\ndef |\Z)'
+        match = re.search(pattern, content, re.DOTALL)
+        assert match, "show__clusters function not found"
+
+        func_body = match.group(0)
+
+        # Should have next(..., None) pattern - may be multiline with nested parens
+        assert 'next(' in func_body, "show__clusters should use next()"
+        # Check for manager_node = next(..., None) with multiline and nested parens
+        # The pattern has: next(\n(generator),\nNone\n)
+        has_none_default = re.search(r'manager_node\s*=\s*next\s*\(.*?,\s*None\s*\)', func_body, re.DOTALL)
+        assert has_none_default, "show__clusters next() should have None default"
+
+    def test_show_clusters_handles_missing_manager(self):
+        """show__clusters should handle case when no manager node exists."""
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        content = vast_path.read_text(encoding='utf-8')
+
+        pattern = r'def show__clusters\(.*?(?=\ndef |\Z)'
+        match = re.search(pattern, content, re.DOTALL)
+        assert match, "show__clusters function not found"
+
+        func_body = match.group(0)
+
+        # Should check for None manager_node
+        assert 'manager_node is None' in func_body or 'if manager_node is None' in func_body, \
+            "show__clusters should check for None manager_node"
+
+
+class TestTransferCredit:
+    """--transfer_credit should be implemented or removed from docs."""
+
+    def test_transfer_credit_not_in_create_team_epilog(self):
+        """create team epilog should not mention --transfer_credit."""
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        content = vast_path.read_text(encoding='utf-8')
+
+        # Find create__team function and its decorator
+        pattern = r'@parser\.command\([^)]*argument\([^)]*team_name[^)]*\)[^)]*\)[^@]*def create__team'
+        match = re.search(pattern, content, re.DOTALL)
+        if match:
+            decorator_and_func = match.group(0)
+            # Should not mention --transfer_credit as a flag
+            assert '--transfer_credit' not in decorator_and_func, \
+                "create team should not document --transfer_credit as a flag"
+
+    def test_transfer_credit_consistency(self):
+        """If --transfer_credit is mentioned, it should be documented correctly."""
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        content = vast_path.read_text(encoding='utf-8')
+
+        # Find create__team decorator/epilog section
+        pattern = r'@parser\.command\(\s*argument\("--team_name".*?def create__team'
+        match = re.search(pattern, content, re.DOTALL)
+
+        if match:
+            section = match.group(0)
+            # If transfer_credit is mentioned at all, it should NOT be as --transfer_credit flag
+            if 'transfer_credit' in section.lower():
+                # Should be pointing to the separate command, not documenting a flag
+                assert 'vastai transfer credit' in section or '--transfer_credit' not in section, \
+                    "transfer_credit should point to 'vastai transfer credit' command, not a flag"
+
+    def test_transfer_credit_command_exists(self):
+        """The transfer__credit command should exist as separate command."""
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        content = vast_path.read_text(encoding='utf-8')
+
+        # transfer__credit should exist as its own command
+        assert 'def transfer__credit' in content, \
+            "transfer__credit should exist as a separate command"
+
+        # It should have proper argument decorators - multiline decorator
+        # Look for recipient and amount in argument() calls before def transfer__credit
+        pattern = r'@parser\.command\(.*?def transfer__credit'
+        match = re.search(pattern, content, re.DOTALL)
+        assert match, "transfer__credit should have @parser.command decorator"
+        decorator_section = match.group(0)
+        assert 'recipient' in decorator_section, "transfer__credit should have recipient argument"
+        assert 'amount' in decorator_section, "transfer__credit should have amount argument"
diff --git a/tests/regression/test_mutable_defaults.py b/tests/regression/test_mutable_defaults.py
new file mode 100644
index 00000000..777c2b72
--- /dev/null
+++ b/tests/regression/test_mutable_defaults.py
@@ -0,0 +1,54 @@
+"""Mutable default arguments in http_put, http_post, http_del.
+
+The bug: Using json={} as a default argument means all calls share the same
+dict object. If any caller mutates the dict, subsequent calls see the mutation.
+
+The fix: Use json=None and initialize to {} at runtime.
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+from unittest.mock import MagicMock, patch
+import argparse
+
+
+def _make_args():
+    return argparse.Namespace(retry=1, curl=False)
+
+
+def _mock_http_request(verb, args, req_url, headers, json, **kwargs):
+    """Capture the json arg and return a mock response."""
+    r = MagicMock()
+    r.status_code = 200
+    # Store reference to the json dict that was passed
+    r._captured_json = json
+    return r
+
+
+@patch('vast.http_request', side_effect=_mock_http_request)
+def test_http_put_no_shared_default(mock_req):
+    from vast import http_put
+    args = _make_args()
+    r1 = http_put(args, "http://test1", headers=None)
+    r2 = http_put(args, "http://test2", headers=None)
+    # Each call must get its own dict, not share the mutable default
+    assert r1._captured_json is not r2._captured_json
+
+
+@patch('vast.http_request', side_effect=_mock_http_request)
+def test_http_post_no_shared_default(mock_req):
+    from vast import http_post
+    args = _make_args()
+    r1 = http_post(args, "http://test1", headers=None)
+    r2 = http_post(args, "http://test2", headers=None)
+    assert r1._captured_json is not r2._captured_json
+
+
+@patch('vast.http_request', side_effect=_mock_http_request)
+def test_http_del_no_shared_default(mock_req):
+    from vast import http_del
+    args = _make_args()
+    r1 = http_del(args, "http://test1", headers=None)
+    r2 = http_del(args, "http://test2", headers=None)
+    assert r1._captured_json is not r2._captured_json
diff --git a/tests/regression/test_namespace_typo.py b/tests/regression/test_namespace_typo.py
new file mode 100644
index 00000000..2aa8a79b
--- /dev/null
+++ b/tests/regression/test_namespace_typo.py
@@ -0,0 +1,23 @@
+"""Typo 'debbuging' in Namespace construction.
+
+The bug: destroy_args = argparse.Namespace(..., debbuging=args.debugging, ...)
+creates an attribute 'debbuging' instead of 'debugging'. Any code accessing
+destroy_args.debugging gets AttributeError.
+
+The fix: Change 'debbuging' to 'debugging'.
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+
+def test_no_debbuging_typo_in_source():
+    """Verify the typo 'debbuging' does not appear in vast.py source."""
+    vast_path = os.path.join(os.path.dirname(__file__), '..', '..', 'vast.py')
+    with open(vast_path, 'r', encoding='utf-8', errors='replace') as f:
+        source = f.read()
+
+    assert 'debbuging' not in source, (
+        "Found 'debbuging' typo in vast.py. "
+        "Should be 'debugging' in the Namespace construction."
+    )
diff --git a/tests/regression/test_parse_query.py b/tests/regression/test_parse_query.py
new file mode 100644
index 00000000..9d6bfaac
--- /dev/null
+++ b/tests/regression/test_parse_query.py
@@ -0,0 +1,59 @@
+"""parse_query() field alias bug -- v references dict after pop.
+
+The bug: `v = res.setdefault(field, {})` gets a reference to a dict at the
+original field name. Then `res.pop(field)` removes it from res. Writing to v
+modifies an orphaned dict that's no longer in res.
+
+Fields affected: cuda_vers->cuda_max_good, dph->dph_total, dlperf_usd->dlperf_per_dphtotal
+
+The fix: Resolve alias before calling setdefault.
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+
+def test_field_alias_cuda_vers():
+    """parse_query correctly aliases cuda_vers to cuda_max_good."""
+    from vast import parse_query, offers_fields, offers_alias
+
+    result = parse_query("cuda_vers >= 12.0", {}, offers_fields, offers_alias)
+    # The result should have cuda_max_good, NOT cuda_vers
+    assert 'cuda_max_good' in result, (
+        f"Expected 'cuda_max_good' in result, got keys: {list(result.keys())}. "
+        f"Field alias not applied correctly."
+    )
+    assert 'cuda_vers' not in result, "Old field name 'cuda_vers' should not be in result"
+    assert 'gte' in result['cuda_max_good'], (
+        f"Expected 'gte' operator in cuda_max_good, got: {result['cuda_max_good']}"
+    )
+
+
+def test_field_alias_dph():
+    """parse_query correctly aliases dph to dph_total."""
+    from vast import parse_query, offers_fields, offers_alias, offers_mult
+
+    result = parse_query("dph <= 1.5", {}, offers_fields, offers_alias, offers_mult)
+    assert 'dph_total' in result, f"Expected 'dph_total', got keys: {list(result.keys())}"
+    assert 'dph' not in result
+    assert 'lte' in result['dph_total']
+
+
+def test_field_alias_value_preserved():
+    """After alias resolution, the operator value is correctly stored."""
+    from vast import parse_query, offers_fields, offers_alias
+
+    result = parse_query("cuda_vers >= 12.0", {}, offers_fields, offers_alias)
+    assert result['cuda_max_good']['gte'] == '12.0', (
+        f"Expected value '12.0', got: {result['cuda_max_good'].get('gte')}"
+    )
+
+
+def test_non_aliased_field_unaffected():
+    """Fields without aliases work normally."""
+    from vast import parse_query, offers_fields, offers_alias
+
+    result = parse_query("num_gpus >= 2", {}, offers_fields, offers_alias)
+    assert 'num_gpus' in result
+    assert 'gte' in result['num_gpus']
+    assert result['num_gpus']['gte'] == '2'
diff --git a/tests/regression/test_raw_completeness.py b/tests/regression/test_raw_completeness.py
new file mode 100644
index 00000000..a798c9dd
--- /dev/null
+++ b/tests/regression/test_raw_completeness.py
@@ -0,0 +1,176 @@
+"""
+Regression Tests: Raw Mode Completeness
+
+Verifies that command functions have consistent --raw handling.
+"""
+import re
+import sys
+from pathlib import Path
+
+# Add vast-cli to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+
+class TestRawModeCompleteness:
+    """Tests that command functions have raw mode handling."""
+
+    def setup_method(self):
+        """Load vast.py source code once per test."""
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        self.source = vast_path.read_text(encoding="utf-8")
+
+    def test_minimum_raw_handlers(self):
+        """Verify at least 90 raw mode handlers exist."""
+        raw_count = len(re.findall(r"if args\.raw:", self.source))
+        assert raw_count >= 90, f"Expected at least 90 raw handlers, found {raw_count}"
+
+    def test_command_functions_have_raw_handling(self):
+        """Check that common command functions have if args.raw: patterns."""
+        # Key command functions that should have raw handling
+        expected_functions = [
+            "attach__ssh",
+            "cancel__copy",
+            "cancel__sync",
+            "change__bid",
+            "create__api_key",
+            "create__env_var",
+            "create__ssh_key",
+            "create__workergroup",
+            "create__endpoint",
+            "create__subaccount",
+            "create__team",
+            "create__team_role",
+            "create__template",
+            "delete__api_key",
+            "delete__ssh_key",
+            "delete__scheduled_job",
+            "delete__workergroup",
+            "delete__endpoint",
+            "delete__env_var",
+            "delete__template",
+            "destroy__team",
+            "detach__ssh",
+            "invite__member",
+            "label__instance",
+            "prepay__instance",
+            "reboot__instance",
+            "recycle__instance",
+            "remove__member",
+            "remove__team_role",
+            "reports",
+            "reset__api_key",
+            "transfer__credit",
+        ]
+
+        for func_name in expected_functions:
+            # Find the function definition
+            func_pattern = rf"^def {func_name}\(args"
+            match = re.search(func_pattern, self.source, re.MULTILINE)
+            assert match, f"Function {func_name} not found"
+
+            # Get function body (rough approximation - from def to next def or EOF)
+            start = match.start()
+            next_def = re.search(r"^def \w+\(", self.source[start + 10:], re.MULTILINE)
+            end = start + 10 + next_def.start() if next_def else len(self.source)
+            func_body = self.source[start:end]
+
+            # Check for raw handling
+            has_raw = "if args.raw:" in func_body
+            assert has_raw, f"Function {func_name} missing 'if args.raw:' handling"
+
+    def test_no_orphan_print_without_raw_check(self):
+        """
+        Verify that functions returning JSON data have raw checks before prints.
+
+        This is a sampling test - check a few critical functions.
+        """
+        # Functions that should have raw handling before their main output
+        critical_patterns = [
+            # (function_name, expected_pattern_after_raw_check)
+            ("create__team", r"if args\.raw:.*?return.*?print\(result\)"),
+            ("delete__api_key", r"if args\.raw:.*?return.*?print\(result\)"),
+        ]
+
+        for func_name, _ in critical_patterns:
+            func_pattern = rf"^def {func_name}\(args"
+            match = re.search(func_pattern, self.source, re.MULTILINE)
+            assert match, f"Function {func_name} not found"
+
+            start = match.start()
+            next_def = re.search(r"^def \w+\(", self.source[start + 10:], re.MULTILINE)
+            end = start + 10 + next_def.start() if next_def else len(self.source)
+            func_body = self.source[start:end]
+
+            # Verify raw check exists
+            assert "if args.raw:" in func_body, f"{func_name} should have raw check"
+
+
+class TestRawModeReturnsData:
+    """Tests that raw mode handlers return data, not None."""
+
+    def setup_method(self):
+        """Load vast.py source code once per test."""
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        self.source = vast_path.read_text(encoding="utf-8")
+
+    def test_raw_handlers_have_return_statements(self):
+        """Verify raw mode handlers include return statements."""
+        # Find all if args.raw: blocks
+        raw_pattern = r"if args\.raw:\s*\n\s+return"
+        matches = re.findall(raw_pattern, self.source)
+        # Should have many return statements following raw checks
+        assert len(matches) >= 80, f"Expected 80+ 'if args.raw: return' patterns, found {len(matches)}"
+
+    def test_no_empty_raw_blocks(self):
+        """Verify no raw blocks that just pass or do nothing."""
+        # Pattern for raw checks that just pass
+        empty_raw_pattern = r"if args\.raw:\s*\n\s+pass\s*\n"
+        matches = re.findall(empty_raw_pattern, self.source)
+        assert len(matches) == 0, f"Found {len(matches)} empty 'if args.raw: pass' blocks"
+
+
+class TestRawModeConsistency:
+    """Tests for consistent raw mode patterns across the codebase."""
+
+    def setup_method(self):
+        """Load vast.py source code once per test."""
+        vast_path = Path(__file__).parent.parent.parent / "vast.py"
+        self.source = vast_path.read_text(encoding="utf-8")
+
+    def test_consistent_raw_return_pattern(self):
+        """
+        Verify raw mode uses consistent return patterns.
+
+        Expected patterns:
+        - if args.raw: return rj
+        - if args.raw: return result
+        - if args.raw: return rows
+        - if args.raw: return data
+        """
+        # Find all raw return patterns
+        raw_return_pattern = r"if args\.raw:\s*\n\s+return\s+(\w+)"
+        matches = re.findall(raw_return_pattern, self.source)
+
+        # Common return variable names
+        valid_names = {"rj", "result", "rows", "data", "processed", "user_blob",
+                       "response_data", "instances", "volumes", "machines", "offers"}
+
+        for var_name in matches:
+            # Allow any reasonable variable name (not just the common ones)
+            # This is a sanity check - variables should be short identifiers
+            assert len(var_name) < 30, f"Suspicious return variable: {var_name}"
+
+    def test_output_result_handles_raw(self):
+        """Verify output_result function exists and handles raw mode."""
+        # Check that output_result is defined
+        assert "def output_result(" in self.source, "output_result function not found"
+
+        # Check that output_result checks args.raw
+        output_result_match = re.search(
+            r"def output_result\(.*?\n(.*?)(?=^def |\Z)",
+            self.source,
+            re.MULTILINE | re.DOTALL
+        )
+        assert output_result_match, "Could not extract output_result function body"
+        func_body = output_result_match.group(1)
+        assert "args.raw" in func_body, "output_result should check args.raw"
diff --git a/tests/regression/test_raw_errors.py b/tests/regression/test_raw_errors.py
new file mode 100644
index 00000000..b30b54b7
--- /dev/null
+++ b/tests/regression/test_raw_errors.py
@@ -0,0 +1,188 @@
+"""Error messages in --raw mode must be valid JSON.
+
+The bug: When --raw mode is active and an HTTPError or ValueError occurs,
+the error handler prints plain text (e.g., "failed with error 500: ...").
+Scripts and automation tools parsing JSON output get broken by mixed
+text/JSON output.
+
+The fix: Check args.raw in the HTTPError and ValueError exception handlers
+in main(), and output a JSON object with error/status_code/msg fields.
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+import json
+import argparse
+import pytest
+from unittest import mock
+from io import StringIO
+
+import requests
+
+
+class TestHTTPErrorRawMode:
+    """Verify HTTPError in --raw mode produces valid JSON."""
+
+    def _make_mock_response(self, status_code, json_body=None):
+        """Create a mock response for HTTPError."""
+        resp = mock.MagicMock()
+        resp.status_code = status_code
+        if json_body is not None:
+            resp.json.return_value = json_body
+        else:
+            resp.json.side_effect = json.JSONDecodeError("No JSON", "", 0)
+        return resp
+
+    def _run_main_with_error(self, args):
+        """Run vast.main() with proper mocking, return captured stdout."""
+        import vast
+
+        captured = StringIO()
+        with mock.patch.object(vast, 'ARGS', args):
+            with mock.patch('vast.parser') as mock_parser:
+                mock_parser.parse_args.return_value = args
+                mock_parser.add_argument = mock.MagicMock()
+                mock_parser.parser = mock.MagicMock()
+                with mock.patch('vast.should_check_for_update', False):
+                    with mock.patch('vast.TABCOMPLETE', False):
+                        with mock.patch('vast.api_key_guard', 'GUARD'):
+                            with mock.patch('sys.stdout', captured):
+                                try:
+                                    vast.main()
+                                except SystemExit:
+                                    pass
+        return captured.getvalue().strip()
+
+    def test_http_error_raw_mode_produces_json(self):
+        """HTTPError with --raw should output valid JSON with error/status_code/msg."""
+        mock_resp = self._make_mock_response(500, {"msg": "Internal server error"})
+        http_error = requests.exceptions.HTTPError(response=mock_resp)
+
+        args = argparse.Namespace(
+            raw=True, func=mock.MagicMock(side_effect=http_error),
+            api_key="test", url="https://test.com", explain=False,
+            retry=3, full=False, curl=False, no_color=False,
+        )
+
+        output = self._run_main_with_error(args)
+        parsed = json.loads(output)
+        assert parsed["error"] is True
+        assert parsed["status_code"] == 500
+        assert parsed["msg"] == "Internal server error"
+
+    def test_http_error_raw_mode_401_produces_json(self):
+        """HTTPError 401 with --raw should output JSON with login message."""
+        mock_resp = self._make_mock_response(401, json_body=None)
+        http_error = requests.exceptions.HTTPError(response=mock_resp)
+
+        args = argparse.Namespace(
+            raw=True, func=mock.MagicMock(side_effect=http_error),
+            api_key="test", url="https://test.com", explain=False,
+            retry=3, full=False, curl=False, no_color=False,
+        )
+
+        output = self._run_main_with_error(args)
+        parsed = json.loads(output)
+        assert parsed["error"] is True
+        assert parsed["status_code"] == 401
+        assert "log in" in parsed["msg"].lower() or "sign up" in parsed["msg"].lower()
+
+    def test_http_error_non_raw_mode_produces_text(self):
+        """HTTPError without --raw should output human-readable text."""
+        mock_resp = self._make_mock_response(500, {"msg": "Server error"})
+        http_error = requests.exceptions.HTTPError(response=mock_resp)
+
+        args = argparse.Namespace(
+            raw=False, func=mock.MagicMock(side_effect=http_error),
+            api_key="test", url="https://test.com", explain=False,
+            retry=3, full=False, curl=False, no_color=False,
+        )
+
+        output = self._run_main_with_error(args)
+        # Non-raw should NOT be valid JSON with error key
+        assert "failed with error" in output.lower()
+
+
+class TestValueErrorRawMode:
+    """Verify ValueError in --raw mode produces valid JSON."""
+
+    def _run_main_with_error(self, args):
+        """Run vast.main() with proper mocking, return captured stdout."""
+        import vast
+
+        captured = StringIO()
+        with mock.patch.object(vast, 'ARGS', args):
+            with mock.patch('vast.parser') as mock_parser:
+                mock_parser.parse_args.return_value = args
+                mock_parser.add_argument = mock.MagicMock()
+                mock_parser.parser = mock.MagicMock()
+                with mock.patch('vast.should_check_for_update', False):
+                    with mock.patch('vast.TABCOMPLETE', False):
+                        with mock.patch('vast.api_key_guard', 'GUARD'):
+                            with mock.patch('sys.stdout', captured):
+                                try:
+                                    vast.main()
+                                except SystemExit:
+                                    pass
+        return captured.getvalue().strip()
+
+    def test_value_error_raw_mode_produces_json(self):
+        """ValueError with --raw should output valid JSON with error/msg."""
+        args = argparse.Namespace(
+            raw=True, func=mock.MagicMock(side_effect=ValueError("bad value")),
+            api_key="test", url="https://test.com", explain=False,
+            retry=3, full=False, curl=False, no_color=False,
+        )
+
+        output = self._run_main_with_error(args)
+        parsed = json.loads(output)
+        assert parsed["error"] is True
+        assert parsed["msg"] == "bad value"
+
+    def test_value_error_non_raw_mode_produces_text(self):
+        """ValueError without --raw should print the error message as text."""
+        args = argparse.Namespace(
+            raw=False, func=mock.MagicMock(side_effect=ValueError("bad value")),
+            api_key="test", url="https://test.com", explain=False,
+            retry=3, full=False, curl=False, no_color=False,
+        )
+
+        output = self._run_main_with_error(args)
+        assert output == "bad value"
+
+
+class TestRawErrorHandlerLintChecks:
+    """Lint-style tests to verify raw error handling exists in main()."""
+
+    def test_httperror_handler_checks_args_raw(self):
+        """The HTTPError handler in main() must check args.raw."""
+        VAST_PY_PATH = os.path.join(os.path.dirname(__file__), '..', '..', 'vast.py')
+        with open(VAST_PY_PATH, encoding='utf-8') as f:
+            content = f.read()
+
+        # Find the HTTPError handler section
+        assert 'HTTPError' in content, "HTTPError handler must exist"
+        # Find args.raw in the context of error handling
+        import re
+        # Look for args.raw near HTTPError handling
+        http_error_section = content[content.index('HTTPError'):]
+        # Limit to the next except or end of function
+        next_section = http_error_section[:http_error_section.index('except ValueError')]
+        assert 'args.raw' in next_section, (
+            "HTTPError handler must check args.raw for JSON output"
+        )
+
+    def test_valueerror_handler_checks_args_raw(self):
+        """The ValueError handler in main() must check args.raw."""
+        VAST_PY_PATH = os.path.join(os.path.dirname(__file__), '..', '..', 'vast.py')
+        with open(VAST_PY_PATH, encoding='utf-8') as f:
+            content = f.read()
+
+        # Find the ValueError handler in main() - the one near end of file
+        # Look for the last 'except ValueError' which is in main()
+        last_ve_idx = content.rindex('except ValueError')
+        ve_section = content[last_ve_idx:last_ve_idx + 300]
+        assert 'args.raw' in ve_section, (
+            "ValueError handler in main() must check args.raw for JSON output"
+        )
diff --git a/tests/regression/test_retry.py b/tests/regression/test_retry.py
new file mode 100644
index 00000000..ab1822a5
--- /dev/null
+++ b/tests/regression/test_retry.py
@@ -0,0 +1,233 @@
+"""Incomplete retry logic -- only retries on HTTP 429.
+
+The bug: http_request() only retries when the server returns 429 (rate limit).
+Transient 5xx errors (502, 503, 504) and connection failures cause immediate
+command failure instead of being retried.
+
+The fix: Expand retry to cover {429, 502, 503, 504} status codes and split
+exception handling so ConnectionError/Timeout are retried while other
+RequestException subclasses are raised immediately.
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+import argparse
+from unittest.mock import MagicMock, patch
+import pytest
+import requests.exceptions
+
+
+def _make_args(retry=3):
+    return argparse.Namespace(retry=retry, curl=False)
+
+
+@patch('vast.time.sleep')
+@patch('vast.requests.Session')
+def test_retry_on_502(mock_session_cls, mock_sleep):
+    """http_request retries on 502 Bad Gateway and recovers."""
+    from vast import http_request
+
+    mock_session = MagicMock()
+    mock_session_cls.return_value = mock_session
+
+    response_502 = MagicMock()
+    response_502.status_code = 502
+    response_200 = MagicMock()
+    response_200.status_code = 200
+
+    mock_session.send.side_effect = [response_502, response_200]
+    mock_session.prepare_request.return_value = MagicMock()
+
+    args = _make_args(retry=3)
+    with patch('vast.ARGS', args):
+        result = http_request('GET', args, 'http://example.com/test')
+
+    assert result.status_code == 200
+    assert mock_session.send.call_count == 2
+
+
+@patch('vast.time.sleep')
+@patch('vast.requests.Session')
+def test_retry_on_503(mock_session_cls, mock_sleep):
+    """http_request retries on 503 Service Unavailable."""
+    from vast import http_request
+
+    mock_session = MagicMock()
+    mock_session_cls.return_value = mock_session
+
+    response_503 = MagicMock()
+    response_503.status_code = 503
+    response_200 = MagicMock()
+    response_200.status_code = 200
+
+    mock_session.send.side_effect = [response_503, response_200]
+    mock_session.prepare_request.return_value = MagicMock()
+
+    args = _make_args(retry=3)
+    with patch('vast.ARGS', args):
+        result = http_request('GET', args, 'http://example.com/test')
+
+    assert result.status_code == 200
+    assert mock_session.send.call_count == 2
+
+
+@patch('vast.time.sleep')
+@patch('vast.requests.Session')
+def test_retry_on_504(mock_session_cls, mock_sleep):
+    """http_request retries on 504 Gateway Timeout."""
+    from vast import http_request
+
+    mock_session = MagicMock()
+    mock_session_cls.return_value = mock_session
+
+    response_504 = MagicMock()
+    response_504.status_code = 504
+    response_200 = MagicMock()
+    response_200.status_code = 200
+
+    mock_session.send.side_effect = [response_504, response_200]
+    mock_session.prepare_request.return_value = MagicMock()
+
+    args = _make_args(retry=3)
+    with patch('vast.ARGS', args):
+        result = http_request('GET', args, 'http://example.com/test')
+
+    assert result.status_code == 200
+    assert mock_session.send.call_count == 2
+
+
+@patch('vast.time.sleep')
+@patch('vast.requests.Session')
+def test_retry_on_429_still_works(mock_session_cls, mock_sleep):
+    """Original 429 retry behavior is preserved."""
+    from vast import http_request
+
+    mock_session = MagicMock()
+    mock_session_cls.return_value = mock_session
+
+    response_429 = MagicMock()
+    response_429.status_code = 429
+    response_200 = MagicMock()
+    response_200.status_code = 200
+
+    mock_session.send.side_effect = [response_429, response_200]
+    mock_session.prepare_request.return_value = MagicMock()
+
+    args = _make_args(retry=3)
+    with patch('vast.ARGS', args):
+        result = http_request('GET', args, 'http://example.com/test')
+
+    assert result.status_code == 200
+    assert mock_session.send.call_count == 2
+    # Should have slept once (after the 429)
+    assert mock_sleep.call_count == 1
+
+
+@patch('vast.time.sleep')
+@patch('vast.requests.Session')
+def test_retry_on_connection_error(mock_session_cls, mock_sleep):
+    """http_request retries on ConnectionError and recovers."""
+    from vast import http_request
+
+    mock_session = MagicMock()
+    mock_session_cls.return_value = mock_session
+
+    response_200 = MagicMock()
+    response_200.status_code = 200
+
+    mock_session.send.side_effect = [
+        requests.exceptions.ConnectionError("connection refused"),
+        response_200,
+    ]
+    mock_session.prepare_request.return_value = MagicMock()
+
+    args = _make_args(retry=3)
+    with patch('vast.ARGS', args):
+        result = http_request('GET', args, 'http://example.com/test')
+
+    assert result.status_code == 200
+    assert mock_session.send.call_count == 2
+
+
+@patch('vast.time.sleep')
+@patch('vast.requests.Session')
+def test_retry_on_timeout_exception(mock_session_cls, mock_sleep):
+    """http_request retries on Timeout exception and recovers."""
+    from vast import http_request
+
+    mock_session = MagicMock()
+    mock_session_cls.return_value = mock_session
+
+    response_200 = MagicMock()
+    response_200.status_code = 200
+
+    mock_session.send.side_effect = [
+        requests.exceptions.Timeout("read timed out"),
+        response_200,
+    ]
+    mock_session.prepare_request.return_value = MagicMock()
+
+    args = _make_args(retry=3)
+    with patch('vast.ARGS', args):
+        result = http_request('GET', args, 'http://example.com/test')
+
+    assert result.status_code == 200
+    assert mock_session.send.call_count == 2
+
+
+@patch('vast.time.sleep')
+@patch('vast.requests.Session')
+def test_no_retry_on_non_retryable_exception(mock_session_cls, mock_sleep):
+    """Non-retryable RequestException subclasses are raised immediately."""
+    from vast import http_request
+
+    mock_session = MagicMock()
+    mock_session_cls.return_value = mock_session
+
+    # InvalidURL is a non-retryable error
+    mock_session.send.side_effect = requests.exceptions.InvalidURL("bad url")
+    mock_session.prepare_request.return_value = MagicMock()
+
+    args = _make_args(retry=3)
+    with patch('vast.ARGS', args):
+        with pytest.raises(requests.exceptions.InvalidURL):
+            http_request('GET', args, 'http://example.com/test')
+
+    # Should NOT have retried -- only 1 call
+    assert mock_session.send.call_count == 1
+    # Should NOT have slept
+    assert mock_sleep.call_count == 0
+
+
+@patch('vast.time.sleep')
+@patch('vast.requests.Session')
+def test_no_retry_on_non_retryable_status(mock_session_cls, mock_sleep):
+    """Non-retryable status codes (e.g., 400, 404, 500) break out immediately."""
+    from vast import http_request
+
+    mock_session = MagicMock()
+    mock_session_cls.return_value = mock_session
+
+    response_400 = MagicMock()
+    response_400.status_code = 400
+
+    mock_session.send.return_value = response_400
+    mock_session.prepare_request.return_value = MagicMock()
+
+    args = _make_args(retry=3)
+    with patch('vast.ARGS', args):
+        result = http_request('GET', args, 'http://example.com/test')
+
+    # Should return on first call without retrying
+    assert result.status_code == 400
+    assert mock_session.send.call_count == 1
+
+
+@patch('vast.time.sleep')
+@patch('vast.requests.Session')
+def test_retryable_status_codes_constant(mock_session_cls, mock_sleep):
+    """RETRYABLE_STATUS_CODES contains exactly {429, 502, 503, 504}."""
+    from vast import RETRYABLE_STATUS_CODES
+
+    assert RETRYABLE_STATUS_CODES == {429, 502, 503, 504}
diff --git a/tests/regression/test_return_response.py b/tests/regression/test_return_response.py
new file mode 100644
index 00000000..c97d9ca1
--- /dev/null
+++ b/tests/regression/test_return_response.py
@@ -0,0 +1,58 @@
+"""22 functions return Response object instead of parsed JSON.
+
+The bug: Functions using http_* directly return `r` (Response object) in raw
+mode. Response objects are not JSON-serializable, causing json.dumps to fail.
+The bare except: in main() masks this by calling res.json() as a fallback.
+
+The fix: Change `return r` to `return r.json()` in all 22 functions.
+Also: Remove bare except in main() since all returns are now serializable.
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+import re
+
+
+def test_no_bare_return_r_in_functions():
+    """No function (except http_request) returns bare `r` (Response object)."""
+    vast_path = os.path.join(os.path.dirname(__file__), '..', '..', 'vast.py')
+    with open(vast_path, 'r', encoding='utf-8', errors='replace') as f:
+        lines = f.readlines()
+
+    # Find all 'return r' lines outside http_request
+    in_http_request = False
+    violations = []
+    for i, line in enumerate(lines, 1):
+        stripped = line.strip()
+        if stripped.startswith('def http_request('):
+            in_http_request = True
+        elif stripped.startswith('def ') and in_http_request:
+            in_http_request = False
+
+        if in_http_request:
+            continue
+
+        # Match 'return r' but not 'return rows', 'return r.json()', etc.
+        if re.match(r'\s+return r\s*$', line):
+            violations.append(f"Line {i}: {stripped}")
+
+    assert not violations, (
+        f"Found {len(violations)} function(s) still returning bare Response object:\n"
+        + "\n".join(violations)
+    )
+
+
+def test_no_bare_except_in_main():
+    """main() should not have a bare except: clause for raw output."""
+    vast_path = os.path.join(os.path.dirname(__file__), '..', '..', 'vast.py')
+    with open(vast_path, 'r', encoding='utf-8', errors='replace') as f:
+        source = f.read()
+
+    # Check that res.json() fallback is gone from main's raw handler
+    # The old pattern was: try: json.dumps(res) except: json.dumps(res.json())
+    # After fix: just json.dumps(res) with no try/except
+    assert 'res.json()' not in source, (
+        "Found res.json() fallback in main(). "
+        "All returns are JSON-serializable and the fallback is dead code."
+    )
diff --git a/tests/regression/test_safe_dict_access.py b/tests/regression/test_safe_dict_access.py
new file mode 100644
index 00000000..fc285a5e
--- /dev/null
+++ b/tests/regression/test_safe_dict_access.py
@@ -0,0 +1,237 @@
+"""Safe dict access on API response dicts.
+
+The bug: 60+ locations accessed API response dicts with rj["key"],
+r.json()["key"], or result["key"] which raises KeyError if the API
+response format changes or an endpoint returns unexpected data.
+
+The fix: Convert all API response dict accesses to .get() with
+appropriate defaults:
+  - Boolean checks: rj.get("success") -- None is falsy
+  - Messages: rj.get("msg", "Unknown error") -- fallback text
+  - Iterable data: rj.get("offers", []) -- empty list for iteration
+  - Required fields: rj.get("result_url") with explicit error check
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+import re
+import argparse
+import pytest
+from unittest.mock import MagicMock, patch
+
+VAST_PY_PATH = os.path.join(os.path.dirname(__file__), '..', '..', 'vast.py')
+
+
+# --------------------------------------------------------------------------- #
+# Lint-style tests #
+# --------------------------------------------------------------------------- #
+
+class TestMinimalRawDictAccess:
+    """Ensure almost no raw rj['key'] access patterns remain on API data."""
+
+    def test_minimal_rj_bracket_access(self):
+        """Count rj["..."] patterns -- should be zero after the fix."""
+        with open(VAST_PY_PATH, encoding='utf-8') as f:
+            content = f.read()
+        raw_accesses = re.findall(r'rj\["[^"]+"\]', content)
+        assert len(raw_accesses) == 0, (
+            f"Found {len(raw_accesses)} raw rj[\"key\"] accesses; "
+            f"expected 0. Convert to rj.get('key', default). "
+            f"Matches: {raw_accesses[:5]}"
+        )
+
+    def test_minimal_rj_single_quote_access(self):
+        """Count rj['...'] patterns -- should be zero after the fix."""
+        with open(VAST_PY_PATH, encoding='utf-8') as f:
+            content = f.read()
+        raw_accesses = re.findall(r"rj\['[^']+'\]", content)
+        assert len(raw_accesses) == 0, (
+            f"Found {len(raw_accesses)} raw rj['key'] accesses; "
+            f"expected 0. Convert to rj.get('key', default). "
+            f"Matches: {raw_accesses[:5]}"
+        )
+
+    def test_minimal_r_json_bracket_access(self):
+        """Count r.json()["..."] patterns (excluding comments)."""
+        with open(VAST_PY_PATH, encoding='utf-8') as f:
+            lines = f.readlines()
+        raw_accesses = []
+        for i, line in enumerate(lines, 1):
+            stripped = line.lstrip()
+            if stripped.startswith('#'):
+                continue
+            matches = re.findall(r'\.json\(\)\["[^"]+"\]', line)
+            for m in matches:
+                raw_accesses.append(f"line {i}: {m}")
+        assert len(raw_accesses) == 0, (
+            f"Found {len(raw_accesses)} raw .json()[\"key\"] accesses in "
+            f"non-comment lines; expected 0. Matches: {raw_accesses[:5]}"
+        )
+
+    def test_high_safe_access_count(self):
+        """Verify a high number of .get() patterns exist."""
+        with open(VAST_PY_PATH, encoding='utf-8') as f:
+            content = f.read()
+        rj_gets = len(re.findall(r'rj\.get\(', content))
+        json_gets = len(re.findall(r'\.json\(\)\.get\(', content))
+        result_gets = len(re.findall(r'result\.get\(', content))
+        total = rj_gets + json_gets + result_gets
+        assert total >= 60, (
+            f"Found only {total} safe .get() accesses on API response dicts "
+            f"(rj.get: {rj_gets}, .json().get: {json_gets}, result.get: {result_gets}); "
+            f"expected >= 60 after safe dict access conversion."
+        )
+
+
+# --------------------------------------------------------------------------- #
+# Functional tests: missing "success" key #
+# --------------------------------------------------------------------------- #
+
+class TestMissingSuccessKey:
+    """Verify functions handle missing 'success' key without KeyError."""
+
+    @patch('vast.http_put')
+    def test_prepay_instance_no_success_key(self, mock_put, capsys):
+        """prepay__instance should not crash if 'success' key is missing."""
+        import vast
+
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.raise_for_status = MagicMock()
+        # API returns dict WITHOUT 'success' key
+        mock_response.json.return_value = {"some_other_field": 123}
+        mock_put.return_value = mock_response
+
+        args = argparse.Namespace(
+            api_key="test-key", url="https://console.vast.ai",
+            retry=3, raw=False, explain=False,
+            id=12345, amount=10.0
+        )
+
+        # Should not raise KeyError
+        vast.prepay__instance(args)
+
+        captured = capsys.readouterr()
+        # Since success is missing (falsy), it should print the error branch
+        assert "Unknown error" in captured.out
+
+    @patch('vast.api_call')
+    def test_label_instance_no_success_key(self, mock_api_call, capsys):
+        """label__instance should not crash if 'success' key is missing."""
+        import vast
+
+        # api_call returns a dict without 'success' key
+        mock_api_call.return_value = {"some_other_field": 123}
+
+        args = argparse.Namespace(
+            api_key="test-key", url="https://console.vast.ai",
+            retry=3, raw=False, explain=False,
+            id=12345, label="test-label"
+        )
+
+        # Should not raise KeyError
+        vast.label__instance(args)
+
+        captured = capsys.readouterr()
+        # Since success is missing (falsy), it should print the error branch
+        assert "Unknown error" in captured.out
+
+
+# --------------------------------------------------------------------------- #
+# Functional tests: missing "msg" key #
+# --------------------------------------------------------------------------- #
+
+class TestMissingMsgKey:
+    """Verify functions handle missing 'msg' key by printing fallback."""
+
+    @patch('vast.http_put')
+    def test_prepay_failure_no_msg(self, mock_put, capsys):
+        """When API returns success=False without msg, print 'Unknown error'."""
+        import vast
+
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.raise_for_status = MagicMock()
+        mock_response.json.return_value = {"success": False}
+        mock_put.return_value = mock_response
+
+        args = argparse.Namespace(
+            api_key="test-key", url="https://console.vast.ai",
+            retry=3, raw=False, explain=False,
+            id=999, amount=5.0
+        )
+
+        vast.prepay__instance(args)
+
+        captured = capsys.readouterr()
+        assert "Unknown error" in captured.out
+
+    @patch('vast.http_post')
+    def test_create_overlay_no_msg(self, mock_post, capsys):
+        """create__overlay should print 'Unknown error' when msg key missing."""
+        import vast
+
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.raise_for_status = MagicMock()
+        mock_response.json.return_value = {"status": "ok"}  # no "msg" key
+        mock_post.return_value = mock_response
+
+        args = argparse.Namespace(
+            api_key="test-key", url="https://console.vast.ai",
+            retry=3, raw=False, explain=False,
+            name="test-overlay", cluster_id=123
+        )
+
+        vast.create__overlay(args)
+
+        captured = capsys.readouterr()
+        assert "Unknown error" in captured.out
+
+
+# --------------------------------------------------------------------------- #
+# Functional tests: missing data extraction keys #
+# --------------------------------------------------------------------------- #
+
+class TestMissingDataKeys:
+    """Verify functions handle missing data keys gracefully."""
+
+    @patch('vast.http_get')
+    def test_show_instances_missing_instances_key(self, mock_get, capsys):
+        """show__instances should handle missing 'instances' key without crash."""
+        import vast
+
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.raise_for_status = MagicMock()
+        mock_response.json.return_value = {"success": True}  # no "instances"
+        mock_get.return_value = mock_response
+
+        args = argparse.Namespace(
+            api_key="test-key", url="https://console.vast.ai",
+            retry=3, raw=True, explain=False,
+            quiet=False
+        )
+
+        # Should return empty list, not KeyError
+        result = vast.show__instances(args)
+        assert result == []
+
+    @patch('vast.api_call')
+    def test_show_volumes_missing_volumes_key(self, mock_api_call, capsys):
+        """show__volumes should handle missing 'volumes' key without crash."""
+        import vast
+
+        # api_call returns a dict without 'volumes' key
+        mock_api_call.return_value = {"success": True}
+
+        args = argparse.Namespace(
+            api_key="test-key", url="https://console.vast.ai",
+            retry=3, raw=True, explain=False,
+            quiet=False, type="all"
+        )
+
+        # Should return empty list, not KeyError
+        result = vast.show__volumes(args)
+        assert result == [] or result is None
diff --git a/tests/regression/test_sdk_exception_handling.py b/tests/regression/test_sdk_exception_handling.py
new file mode 100644
index 00000000..03af6887
--- /dev/null
+++ b/tests/regression/test_sdk_exception_handling.py
@@ -0,0 +1,59 @@
+"""Regression test: SDK wrapper must not use bare `except: pass`.
+
+The bug: The SDK wrapper at sdk.py has `except: pass` which catches
+SystemExit (preventing CLI functions from exiting), KeyboardInterrupt
+(preventing Ctrl+C), and all errors (returning empty string '').
+
+The fix: Catch SystemExit separately (capture exit code), catch Exception
+with logging, let KeyboardInterrupt propagate.
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+import re
+
+
+def test_no_bare_except_in_sdk():
+    """sdk.py should not contain bare `except:` clauses."""
+    sdk_path = os.path.join(os.path.dirname(__file__), '..', '..', 'vastai', 'sdk.py')
+    with open(sdk_path, 'r') as f:
+        lines = f.readlines()
+
+    bare_excepts = []
+    for i, line in enumerate(lines, 1):
+        stripped = line.strip()
+        # Match `except:` but not `except SomeException:` or `except (A, B):`
+        if re.match(r'^except\s*:\s*$', stripped):
+            bare_excepts.append(f"Line {i}: {stripped}")
+
+    assert not bare_excepts, (
+        f"Found {len(bare_excepts)} bare except: clause(s) in sdk.py:\n"
+        + "\n".join(bare_excepts)
+        + "\nUse specific exception types instead."
+    )
+
+
+def test_sdk_catches_system_exit():
+    """sdk.py catches SystemExit separately from other exceptions."""
+    sdk_path = os.path.join(os.path.dirname(__file__), '..', '..', 'vastai', 'sdk.py')
+    with open(sdk_path, 'r') as f:
+        source = f.read()
+
+    assert 'except SystemExit' in source, (
+        "sdk.py should catch SystemExit separately to handle CLI sys.exit() calls. "
+        "Expected: `except SystemExit as e:`"
+    )
+
+
+def test_sdk_does_not_catch_keyboard_interrupt():
+    """sdk.py should NOT catch KeyboardInterrupt (Ctrl+C must work)."""
+    sdk_path = os.path.join(os.path.dirname(__file__), '..', '..', 'vastai', 'sdk.py')
+    with open(sdk_path, 'r') as f:
+        source = f.read()
+
+    # If it catches BaseException, that would include KeyboardInterrupt
+    assert 'except BaseException' not in source, (
+        "sdk.py catches BaseException which includes KeyboardInterrupt. "
+        "Use `except Exception` instead to allow Ctrl+C to work."
+    )
diff --git a/tests/regression/test_sdk_integration.py b/tests/regression/test_sdk_integration.py
new file mode 100644
index 00000000..7354d8a4
--- /dev/null
+++ b/tests/regression/test_sdk_integration.py
@@ -0,0 +1,456 @@
+"""
+Regression tests for SDK integration.
+
+These tests verify the SDK wrapper integrates correctly with the live vast module
+and supports all documented features, including method resolution, argument passing,
+and output capture.
+"""
+import sys
+import warnings
+from io import StringIO
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+# Add vast-cli to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+
+class TestSDKLiveModuleImport:
+    """SDK must import from live vast module, not frozen copy."""
+
+    def test_sentinel_attribute_visible(self):
+        """Adding sentinel to vast module should be visible through SDK."""
+        import vast
+
+        # Add sentinel attribute
+        vast._SDK_TEST_SENTINEL = "phase6_integration_test"
+
+        # Import SDK internals
+        from vastai import sdk
+
+        # Verify SDK's imported vast module sees the sentinel
+        assert hasattr(sdk._vast, '_SDK_TEST_SENTINEL'), \
+            "SDK's vast module should see runtime-added attributes"
+        assert sdk._vast._SDK_TEST_SENTINEL == "phase6_integration_test", \
+            "Sentinel value should match"
+
+        # Cleanup
+        del vast._SDK_TEST_SENTINEL
+
+    def test_parser_from_vast_module(self):
+        """Parser should be imported from vast module."""
+        import vast
+        from vastai import sdk
+
+        # The parser used by SDK should be the same object as vast.parser
+        assert sdk.parser is vast.parser, \
+            "SDK parser should be the same object as vast.parser"
+
+    def test_apikey_file_from_vast_module(self):
+        """APIKEY_FILE should be imported from vast module."""
+        import vast
+        from vastai import sdk
+
+        # APIKEY_FILE should match
+        assert sdk.APIKEY_FILE == vast.APIKEY_FILE, \
+            "SDK APIKEY_FILE should match vast.APIKEY_FILE"
+
+
+class TestSDKFeatureCompleteness:
+    """VastAI class must support all documented features."""
+
+    def test_instantiation_with_api_key(self):
+        """VastAI can be instantiated with api_key parameter."""
+        from vastai import VastAI
+
+        sdk = VastAI(api_key="test_key_12345")
+
+        assert sdk.api_key == "test_key_12345"
+        assert sdk._creds == "CODE"  # API key provided in code
+
+    def test_raw_mode_default(self):
+        """VastAI defaults to raw=True for SDK usage."""
+        from vastai import VastAI
+
+        sdk = VastAI(api_key="test_key")
+
+        assert sdk.raw is True, "SDK should default to raw=True"
+
+    def test_raw_mode_toggle(self):
+        """VastAI raw mode can be toggled."""
+        from vastai import VastAI
+
+        sdk_raw = VastAI(api_key="test_key", raw=True)
+        sdk_human = VastAI(api_key="test_key", raw=False)
+
+        assert sdk_raw.raw is True
+        assert sdk_human.raw is False
+
+    def test_server_url_parameter(self):
+        """VastAI accepts server_url parameter."""
+        from vastai import VastAI
+
+        sdk = VastAI(api_key="test_key", server_url="https://custom.vast.ai")
+
+        assert sdk.server_url == "https://custom.vast.ai"
+
+    def test_retry_parameter(self):
+        """VastAI accepts retry parameter."""
+        from vastai import VastAI
+
+        sdk = VastAI(api_key="test_key", retry=5)
+
+        assert sdk.retry == 5
+
+    def test_explain_parameter(self):
+        """VastAI accepts explain parameter."""
+        from vastai import VastAI
+
+        sdk = VastAI(api_key="test_key", explain=True)
+
+        assert sdk.explain is True
+
+    def test_quiet_parameter(self):
+        """VastAI accepts quiet parameter."""
+        from vastai import VastAI
+
+        sdk = VastAI(api_key="test_key", quiet=True)
+
+        assert sdk.quiet is True
+
+    def test_imported_methods_populated(self):
+        """VastAI should have imported_methods dict populated."""
+        from vastai import VastAI
+
+        sdk = VastAI(api_key="test_key")
+
+        assert hasattr(sdk, 'imported_methods')
+        assert isinstance(sdk.imported_methods, dict)
+        # Should have many methods (vast.py has 115+ commands)
+        assert len(sdk.imported_methods) > 50, \
+            f"Expected 50+ methods, got {len(sdk.imported_methods)}"
+
+    def test_dynamic_method_binding(self):
+        """VastAI should have methods dynamically bound from vast.py."""
+        from vastai import VastAI
+
+        sdk = VastAI(api_key="test_key")
+
+        # Check some well-known methods exist
+        assert hasattr(sdk, 'search_offers'), "search_offers should be bound"
+        assert hasattr(sdk, 'show_instances'), "show_instances should be bound"
+        assert hasattr(sdk, 'show_machines'), "show_machines should be bound"
+        assert callable(sdk.search_offers), "search_offers should be callable"
+
+    def test_workergroup_and_autoscaler_aliases(self):
+        """Both workergroup and autoscaler/autogroup aliases should work."""
+        from vastai import VastAI
+
+        sdk = VastAI(api_key="test_key")
+
+        # Workergroup naming (primary method names from CLI)
+        assert hasattr(sdk, 'create_workergroup') or 'create_workergroup' in sdk.imported_methods, \
+            "create_workergroup should exist"
+        assert hasattr(sdk, 'show_workergroups') or 'show_workergroups' in sdk.imported_methods, \
+            "show_workergroups should exist"
+        assert hasattr(sdk, 'delete_workergroup') or 'delete_workergroup' in sdk.imported_methods, \
+            "delete_workergroup should exist"
+        assert hasattr(sdk, 'update_workergroup') or 'update_workergroup' in sdk.imported_methods, \
+            "update_workergroup should exist"
+
+        # Autoscaler/autogroup backwards compatibility aliases
+        # Base class provides aliases: create_autogroup, delete_autoscaler, show_autoscalers, update_autoscaler
+        assert hasattr(sdk, 'create_autogroup'), \
+            "create_autogroup alias should exist"
+        assert hasattr(sdk, 'show_autoscalers'), \
+            "show_autoscalers alias should exist"
+        assert hasattr(sdk, 'delete_autoscaler'), \
+            "delete_autoscaler alias should exist"
+        assert hasattr(sdk, 'update_autoscaler'), \
+            "update_autoscaler alias should exist"
+
+
+class TestSDKMethodCoverage:
+    """Verify SDK method coverage against CLI commands."""
+
+    def test_method_count_matches_cli_commands(self):
+        """SDK should have methods for most CLI commands."""
+        from vastai import VastAI
+        import vast
+
+        sdk = VastAI(api_key="test_key")
+
+        # Count CLI commands (functions with double underscore)
+        cli_commands = [
+            name for name in dir(vast)
+            if callable(getattr(vast, name))
+            and '__' in name
+            and not name.startswith('_')
+        ]
+
+        # SDK should have at least 80% coverage
+        # (some commands like 'help' are excluded)
+        min_expected = int(len(cli_commands) * 0.80)
+        actual_count = len(sdk.imported_methods)
+
+        assert actual_count >= min_expected, \
+            f"SDK has {actual_count} methods but CLI has {len(cli_commands)} commands. " \
+            f"Expected at least {min_expected} methods."
+
+    def test_all_critical_methods_exist(self):
+        """SDK must have all commonly-used methods."""
+        from vastai import VastAI
+
+        sdk = VastAI(api_key="test_key")
+
+        critical_methods = [
+            'search_offers',
+            'create_instance',
+            'destroy_instance',
+            'show_instances',
+            'start_instance',
+            'stop_instance',
+            'show_machines',
+            'logs',
+            'execute',
+            'copy',
+            'show_user',
+        ]
+
+        for method in critical_methods:
+            assert hasattr(sdk, method) or method in sdk.imported_methods, \
+                f"Critical method '{method}' missing from SDK"
+
+
+class TestSDKMethodExecution:
+    """Verify SDK methods execute through the vast module correctly."""
+
+    def test_show_instances_method_exists_and_callable(self):
+        """show_instances method should exist and be callable."""
+        from vastai import VastAI
+
+        sdk = VastAI(api_key="test_key")
+
+        # Method should exist as callable
+        assert hasattr(sdk, 'show_instances'), "show_instances should be bound"
+        assert callable(sdk.show_instances), "show_instances should be callable"
+
+    def test_search_offers_method_exists_and_callable(self):
+        """search_offers method should exist and be callable."""
+        from vastai import VastAI
+
+        sdk = VastAI(api_key="test_key")
+
+        assert hasattr(sdk, 'search_offers'), "search_offers should be bound"
+        assert callable(sdk.search_offers), "search_offers should be callable"
+
+    def test_method_binding_uses_vast_functions(self):
+        """SDK methods should be bound from vast module functions."""
+        from vastai import VastAI
+        import vast
+
+        sdk = VastAI(api_key="test_key")
+
+        # The method should be in imported_methods and callable
+        if 'show_instances' in sdk.imported_methods:
+            # The bound method comes from vast.show__instances
+            vast_func_name = 'show__instances'
+            assert hasattr(vast, vast_func_name), \
+                f"vast.{vast_func_name} should exist for SDK to bind"
+
+    def test_method_returns_callable_not_none(self):
+        """SDK methods should return callable functions, not None."""
+        from vastai import VastAI
+
+        sdk = VastAI(api_key="test_key")
+
+        # Check several methods to ensure they're properly bound
+        methods_to_check = ['search_offers', 'show_instances', 'show_machines', 'show_user']
+
+        for method_name in methods_to_check:
+            method = getattr(sdk, method_name, None)
+            assert method is not None, f"{method_name} should not be None"
+            assert callable(method), f"{method_name} should be callable"
+
+
+class TestSdkMethodResolution:
+    """SDK wrapper method resolution tests."""
+
+    def test_search_offers_method_exists(self):
+        """SDK has search_offers method."""
+        from vastai import VastAI
+        sdk = VastAI(api_key="test-key")
+        assert hasattr(sdk, 'search_offers')
+        assert callable(sdk.search_offers)
+
+    def test_show_instances_method_exists(self):
+        """SDK has show_instances method."""
+        from vastai import VastAI
+        sdk = VastAI(api_key="test-key")
+        assert hasattr(sdk, 'show_instances')
+        assert callable(sdk.show_instances)
+
+    def test_create_instance_method_exists(self):
+        """SDK has create_instance method."""
+        from vastai import VastAI
+        sdk = VastAI(api_key="test-key")
+        assert hasattr(sdk, 'create_instance')
+        assert callable(sdk.create_instance)
+
+    def test_destroy_instance_method_exists(self):
+        """SDK has destroy_instance method."""
+        from vastai import VastAI
+        sdk = VastAI(api_key="test-key")
+        assert hasattr(sdk, 'destroy_instance')
+        assert callable(sdk.destroy_instance)
+
+    def test_method_resolution_is_consistent(self):
+        """Same method should resolve identically across multiple SDK instances."""
+        from vastai import VastAI
+        sdk1 = VastAI(api_key="test-key-1")
+        sdk2 = VastAI(api_key="test-key-2")
+
+        # Both instances should have same method names in imported_methods
+        assert sdk1.imported_methods.keys() == sdk2.imported_methods.keys()
+
+
+class TestSdkArgumentPassing:
+    """SDK wrapper argument passing tests."""
+
+    def test_api_key_stored_in_instance(self):
+        """SDK stores api_key in instance for use in requests."""
+        from vastai import VastAI
+
+        sdk = VastAI(api_key="test-api-key-12345")
+
+        # API key should be accessible
+        assert sdk.api_key == "test-api-key-12345"
+
+    def test_retry_parameter_passed(self):
+        """SDK retry parameter is stored and accessible."""
+        from vastai import VastAI
+
+        sdk = VastAI(api_key="test-key", retry=10)
+        assert sdk.retry == 10
+
+    def test_server_url_parameter_passed(self):
+        """SDK server_url parameter is stored and accessible."""
+        from vastai import VastAI
+
+        sdk = VastAI(api_key="test-key", server_url="https://custom.vast.ai")
+        assert sdk.server_url == "https://custom.vast.ai"
+
+    def test_explain_parameter_passed(self):
+        """SDK explain parameter is stored and accessible."""
+        from vastai import VastAI
+
+        sdk = VastAI(api_key="test-key", explain=True)
+        assert sdk.explain is True
+
+    def test_quiet_parameter_passed(self):
+        """SDK quiet parameter is stored and accessible."""
+        from vastai import VastAI
+
+        sdk = VastAI(api_key="test-key", quiet=True)
+        assert sdk.quiet is True
+
+
+class TestSdkOutputCapture:
+    """SDK wrapper output capture tests."""
+
+    def test_sdk_instance_has_output_capture_mechanism(self):
+        """SDK should have mechanism for capturing output."""
+        from vastai import VastAI
+
+        sdk = VastAI(api_key="test-key", raw=True)
+
+        # SDK uses raw=True by default to return data instead of printing
+        # This verifies the mechanism exists
+        assert sdk.raw is True
+
+    def test_sdk_raw_mode_returns_data_type(self):
+        """SDK in raw mode should be configured to return data."""
+        from vastai import VastAI
+
+        sdk = VastAI(api_key="test-key", raw=True)
+
+        # Verify the SDK is configured correctly for raw output
+        assert hasattr(sdk, 'raw')
+        assert sdk.raw is True
+        # Raw mode means CLI functions return data instead of printing
+
+    def test_sdk_non_raw_mode_available(self):
+        """SDK can be set to non-raw mode for human-readable output."""
+        from vastai import VastAI
+
+        sdk = VastAI(api_key="test-key", raw=False)
+        assert sdk.raw is False
+
+
+class TestSdkBackwardsCompatibility:
+    """SDK backwards compatibility tests."""
+
+    def test_autogroup_alias_exists(self):
+        """SDK has autogroup alias methods for backwards compatibility."""
+        from vastai import VastAI
+        sdk = VastAI(api_key="test-key")
+
+        # Both workergroup and autogroup/autoscaler names should work
+        if hasattr(sdk, 'show_workergroups') or 'show_workergroups' in sdk.imported_methods:
+            # Autoscaler aliases from base class
+            assert hasattr(sdk, 'show_autoscalers'), "show_autoscalers alias should exist"
+
+    def test_autoscaler_crud_aliases_exist(self):
+        """SDK has all autoscaler CRUD aliases for backwards compatibility."""
+        from vastai import VastAI
+        sdk = VastAI(api_key="test-key")
+
+        # These aliases are defined in vastai_base.py
+        assert hasattr(sdk, 'create_autogroup'), "create_autogroup alias should exist"
+        assert hasattr(sdk, 'show_autoscalers'), "show_autoscalers alias should exist"
+        assert hasattr(sdk, 'delete_autoscaler'), "delete_autoscaler alias should exist"
+        assert hasattr(sdk, 'update_autoscaler'), "update_autoscaler alias should exist"
+
+    def test_old_import_path_warning(self):
+        """Importing from vastai_sdk works (with or without deprecation warning)."""
+        # The vastai_sdk module may or may not emit a deprecation warning
+        # depending on implementation. Either behavior is acceptable.
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            try:
+                from vastai_sdk import VastAI as OldVastAI
+                # Import succeeded - either with warning or without
+                # Both are acceptable for backwards compatibility
+                assert OldVastAI is not None
+            except ImportError:
+                # If vastai_sdk shim doesn't exist, that's also acceptable
+                # as long as the main vastai import works
+                from vastai import VastAI
+                assert VastAI is not None
+
+    def test_primary_import_path_works(self):
+        """Primary import path 'from vastai import VastAI' works."""
+        from vastai import VastAI
+        sdk = VastAI(api_key="test-key")
+        assert sdk is not None
+        assert hasattr(sdk, 'api_key')
+
+
+class TestSdkMethodDocstrings:
+    """SDK methods have docstrings for IDE autocomplete."""
+
+    def test_sdk_methods_have_docstrings(self):
+        """SDK methods should have docstrings for IDE support."""
+        from vastai import VastAI
+        sdk = VastAI(api_key="test-key")
+
+        # Check some key methods have docstrings
+        methods_to_check = ['search_offers', 'show_instances', 'create_instance']
+
+        for method_name in methods_to_check:
+            if hasattr(sdk, method_name):
+                method = getattr(sdk, method_name)
+                # Method should be callable and have docstring
+                assert callable(method), f"{method_name} should be callable"
+                # Docstring may come from vast.py function or be added by SDK
+                # Either is acceptable as long as method works
diff --git a/tests/regression/test_sdk_naming_and_async.py b/tests/regression/test_sdk_naming_and_async.py
new file mode 100644
index 00000000..35fc6baa
--- /dev/null
+++ b/tests/regression/test_sdk_naming_and_async.py
@@ -0,0 +1,232 @@
+"""Regression tests for SDK naming consistency, typo fixes, and async migration."""
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+
+class TestNamingConsistency:
+    """Both workergroup and autogroup names should exist."""
+
+    def test_workergroup_methods_exist(self):
+        """SDK should have workergroup method names."""
+        base_path = Path(__file__).parent.parent.parent / "vastai" / "vastai_base.py"
+        content = base_path.read_text()
+
+        # Should have workergroup methods
+        workergroup_methods = re.findall(r'def\s+\w*workergroup\w*\s*\(', content, re.IGNORECASE)
+        assert len(workergroup_methods) > 0, "Should have workergroup methods"
+
+    def test_autogroup_aliases_exist(self):
+        """SDK should have autogroup aliases for backwards compatibility."""
+        base_path = Path(__file__).parent.parent.parent / "vastai" / "vastai_base.py"
+        content = base_path.read_text()
+
+        # Should have autogroup names (either as primary or alias)
+        has_autogroup = "autogroup" in content.lower()
+        assert has_autogroup, "Should have autogroup names for backwards compatibility"
+
+    def test_sdk_has_both_names(self):
+        """VastAI instance should have both naming conventions."""
+        try:
+            from vastai import VastAI
+            v = VastAI(api_key="test")
+
+            # Check for at least one workergroup and autogroup method
+            methods = dir(v)
+            has_workergroup = any("workergroup" in m.lower() for m in methods)
+            has_autogroup = any("autogroup" in m.lower() for m in methods)
+
+            # At least one should exist (may not have full set in base)
+            assert has_workergroup or has_autogroup, "Should have group-related methods"
+        except ImportError:
+            # If import fails, just check file content
+            pass
+
+    def test_all_workergroup_methods_have_aliases(self):
+        """Each workergroup method should have an autogroup alias."""
+        base_path = Path(__file__).parent.parent.parent / "vastai" / "vastai_base.py"
+        content = base_path.read_text()
+
+        # Find all workergroup method definitions
+        workergroup_defs = re.findall(r'def\s+(\w*workergroup\w*)\s*\(', content, re.IGNORECASE)
+
+        # Each should have a corresponding alias comment or assignment
+        for method in workergroup_defs:
+            # Check for alias assignment pattern: xxx_autogroup = xxx_workergroup or xxx_autoscaler = xxx_workergroup
+            alias_patterns = [
+                method.lower().replace("workergroup", "autogroup"),
+                method.lower().replace("workergroup", "autoscaler"),
+            ]
+            has_alias = any(p in content.lower() for p in alias_patterns)
+            assert has_alias, f"Method {method} should have a backwards compatibility alias"
+
+    def test_naming_matches_cli(self):
+        """SDK method names should match CLI command naming."""
+        # CLI uses: create__workergroup, delete__workergroup, show__workergroups, update__workergroup
+        # SDK should have: create_workergroup, delete_workergroup, show_workergroups, update_workergroup
+        base_path = Path(__file__).parent.parent.parent / "vastai" / "vastai_base.py"
+        content = base_path.read_text()
+
+        expected_methods = [
+            "create_workergroup",
+            "delete_workergroup",
+            "show_workergroups",
+            "update_workergroup",
+        ]
+
+        for method in expected_methods:
+            pattern = rf'def\s+{method}\s*\('
+            match = re.search(pattern, content)
+            assert match, f"Should have method {method} matching CLI command"
+
+
+class TestTypoFixes:
+    """Response dict should have correct spelling."""
+
+    def test_no_reuqest_typo(self):
+        """Should not have 'reuqest' typo anywhere."""
+        client_path = Path(__file__).parent.parent.parent / "vastai" / "serverless" / "client" / "client.py"
+
+        if client_path.exists():
+            content = client_path.read_text()
+            assert "reuqest" not in content, "Found 'reuqest' typo - should be 'request'"
+
+    def test_request_idx_correct(self):
+        """Should have 'request_idx' with correct spelling."""
+        client_path = Path(__file__).parent.parent.parent / "vastai" / "serverless" / "client" / "client.py"
+
+        if client_path.exists():
+            content = client_path.read_text()
+            # If request_idx is used, it should be spelled correctly
+            if "request_idx" in content or "reuqest_idx" in content:
+                assert "request_idx" in content, "Should have correctly spelled request_idx"
+                assert "reuqest_idx" not in content, "Should not have reuqest_idx typo"
+
+    def test_response_dict_keys_spelled_correctly(self):
+        """Response dict keys should all be spelled correctly."""
+        client_path = Path(__file__).parent.parent.parent / "vastai" / "serverless" / "client" / "client.py"
+
+        if client_path.exists():
+            content = client_path.read_text()
+            # Find the response dict assignment
+            if '"request_idx"' in content:
+                # Should have correct key
+                assert '"request_idx"' in content, "Response dict should have request_idx key"
+
+
+class TestAsyncMigration:
+    """_fetch_pubkey should use proper HTTP, not subprocess curl."""
+
+    def test_no_subprocess_curl(self):
+        """Should not use subprocess to call curl."""
+        backend_path = Path(__file__).parent.parent.parent / "vastai" / "serverless" / "server" / "lib" / "backend.py"
+
+        if backend_path.exists():
+            content = backend_path.read_text()
+
+            # Should not have subprocess curl pattern
+            has_subprocess_curl = "subprocess.check_output" in content and "curl" in content
+            assert not has_subprocess_curl, "Should not use subprocess curl - use requests or aiohttp"
+
+    def test_no_subprocess_import(self):
+        """Should not import subprocess (no longer needed)."""
+        backend_path = Path(__file__).parent.parent.parent / "vastai" / "serverless" / "server" / "lib" / "backend.py"
+
+        if backend_path.exists():
+            content = backend_path.read_text()
+
+            # Check for subprocess import at module level
+            import_pattern = r'^import subprocess\s*$'
+            has_import = re.search(import_pattern, content, re.MULTILINE)
+            assert not has_import, "Should not import subprocess - no longer needed"
+
+    def test_uses_requests_or_aiohttp(self):
+        """_fetch_pubkey should use requests or aiohttp."""
+        backend_path = Path(__file__).parent.parent.parent / "vastai" / "serverless" / "server" / "lib" / "backend.py"
+
+        if backend_path.exists():
+            content = backend_path.read_text()
+
+            # Should use requests (for sync) or aiohttp (for async)
+            uses_requests = "requests.get" in content
+            uses_aiohttp = "ClientSession" in content and "aiohttp" in content
+
+            # _fetch_pubkey should use proper HTTP library
+            if "_fetch_pubkey" in content:
+                assert uses_requests or uses_aiohttp, "Should use requests or aiohttp for _fetch_pubkey"
+
+    def test_has_async_variant(self):
+        """Should have async variant of _fetch_pubkey using aiohttp."""
+        backend_path = Path(__file__).parent.parent.parent / "vastai" / "serverless" / "server" / "lib" / "backend.py"
+
+        if backend_path.exists():
+            content = backend_path.read_text()
+
+            # Should have async version for use in async contexts
+            has_async = "async def _fetch_pubkey_async" in content
+            assert has_async, "Should have async variant _fetch_pubkey_async using aiohttp"
+
+    def test_fetch_pubkey_has_timeout(self):
+        """_fetch_pubkey should have timeout to prevent hanging."""
+        backend_path = Path(__file__).parent.parent.parent / "vastai" / "serverless" / "server" / "lib" / "backend.py"
+
+        if backend_path.exists():
+            content = backend_path.read_text()
+
+            # Both sync and async versions should have timeout
+            assert "timeout" in content, "Should have timeout in HTTP requests"
+
+
+class TestServerlessImports:
+    """Basic serverless module tests."""
+
+    def test_serverless_client_importable(self):
+        """Serverless client should be importable without aiohttp at vastai level."""
+        # This tests that lazy imports work
+        try:
+            # Just import vastai - should not fail even without aiohttp
+            import vastai
+            assert vastai is not None
+        except ImportError as e:
+            if "aiohttp" in str(e):
+                # This is expected if aiohttp not installed
+                pass
+            else:
+                raise
+
+    def test_vastai_base_importable(self):
+        """VastAIBase should be importable."""
+        from vastai.vastai_base import VastAIBase
+        assert VastAIBase is not None
+
+    def test_base_class_has_workergroup_methods(self):
+        """VastAIBase should define workergroup methods."""
+        from vastai.vastai_base import VastAIBase
+
+        # Check class attributes
+        assert hasattr(VastAIBase, "create_workergroup"), "Should have create_workergroup"
+        assert hasattr(VastAIBase, "delete_workergroup"), "Should have delete_workergroup"
+        assert hasattr(VastAIBase, "show_workergroups"), "Should have show_workergroups"
+        assert hasattr(VastAIBase, "update_workergroup"), "Should have update_workergroup"
+
+    def test_base_class_has_autogroup_aliases(self):
+        """VastAIBase should have autogroup/autoscaler aliases for backwards compatibility."""
+        from vastai.vastai_base import VastAIBase
+
+        # Check aliases exist
+        assert hasattr(VastAIBase, "create_autogroup"), "Should have create_autogroup alias"
+        assert hasattr(VastAIBase, "delete_autoscaler"), "Should have delete_autoscaler alias"
+        assert hasattr(VastAIBase, "show_autoscalers"), "Should have show_autoscalers alias"
+        assert hasattr(VastAIBase, "update_autoscaler"), "Should have update_autoscaler alias"
+
+    def test_aliases_point_to_same_method(self):
+        """Aliases should point to the same underlying method."""
+        from vastai.vastai_base import VastAIBase
+
+        # Aliases should be the same function
+        assert VastAIBase.create_autogroup is VastAIBase.create_workergroup
+        assert VastAIBase.delete_autoscaler is VastAIBase.delete_workergroup
+        assert VastAIBase.show_autoscalers is VastAIBase.show_workergroups
+        assert VastAIBase.update_autoscaler is VastAIBase.update_workergroup
diff --git a/tests/regression/test_sdk_timezone_import.py b/tests/regression/test_sdk_timezone_import.py
new file mode 100644
index 00000000..41ee4af7
--- /dev/null
+++ b/tests/regression/test_sdk_timezone_import.py
@@ -0,0 +1,56 @@
+"""Regression test: SDK copy must import timezone from datetime.
+
+The bug: vastai/vast.py imports date, datetime, timedelta but NOT
+timezone. Any code using datetime.timezone.utc or timezone(...) fails with
+NameError or ImportError.
+
+The fix: Add timezone to the import statement.
+"""
+import sys
+import os
+
+import pytest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+_SDK_VAST_PATH = os.path.join(
+    os.path.dirname(__file__), '..', '..', '..', 'vast-sdk', 'vastai', 'vast.py'
+)
+
+
+@pytest.mark.skipif(
+    not os.path.isfile(_SDK_VAST_PATH),
+    reason="vast-sdk sibling directory not present"
+)
+def test_frozen_sdk_has_timezone_import():
+    """The frozen SDK copy imports timezone from datetime."""
+    # Read the frozen SDK file directly
+    with open(_SDK_VAST_PATH, 'r', encoding='utf-8', errors='replace') as f:
+        source = f.read()
+
+    assert 'timezone' in source, (
+        "vast-sdk/vastai/vast.py does not import 'timezone' from datetime. "
+        "Add it: from datetime import date, datetime, timedelta, timezone"
+    )
+
+    # Also verify the import line specifically
+    import_found = False
+    for line in source.split('\n'):
+        if line.startswith('from datetime import') and 'timezone' in line:
+            import_found = True
+            break
+
+    assert import_found, (
+        "Could not find 'from datetime import ... timezone ...' in vast-sdk/vastai/vast.py"
+    )
+
+
+def test_live_vast_has_timezone_import():
+    """The live vast.py already has the timezone import (sanity check)."""
+    vast_path = os.path.join(os.path.dirname(__file__), '..', '..', 'vast.py')
+    with open(vast_path, 'r') as f:
+        for line in f:
+            if line.startswith('from datetime import') and 'timezone' in line:
+                return  # Found it, test passes
+
+    assert False, "Live vast.py missing timezone import"
diff --git a/tests/regression/test_sdk_wrapper_safety.py b/tests/regression/test_sdk_wrapper_safety.py
new file mode 100644
index 00000000..e1949fa6
--- /dev/null
+++ b/tests/regression/test_sdk_wrapper_safety.py
@@ -0,0 +1,189 @@
+"""Regression tests for SDK wrapper safety.
+
+- stdout capture must use finally block for guaranteed restoration
+- sys.exit() from CLI functions should return exit code, not crash SDK
+- Exception handling should use specific types, not bare except
+"""
+import io
+import re
+import sys
+from pathlib import Path
+from unittest.mock import patch, MagicMock
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+
+class TestStdoutCapture:
+    """stdout capture must use finally block."""
+
+    def test_finally_block_exists(self):
+        """SDK wrapper should have finally block for stdout restoration."""
+        sdk_path = Path(__file__).parent.parent.parent / "vastai" / "sdk.py"
+        content = sdk_path.read_text()
+
+        # Should have finally: followed by stdout restoration
+        assert "finally:" in content, "SDK should have finally block"
+
+        # The finally block should restore stdout
+        finally_pattern = re.search(r'finally:.*?sys\.stdout\s*=', content, re.DOTALL)
+        assert finally_pattern is not None, "finally block should restore sys.stdout"
+
+    def test_stdout_restoration_guaranteed(self):
+        """Verify stdout restoration code is in finally block, not outside."""
+        sdk_path = Path(__file__).parent.parent.parent / "vastai" / "sdk.py"
+        content = sdk_path.read_text()
+
+        # Check that stdout restoration is inside finally
+        finally_match = re.search(
+            r'finally:\s*\n\s*#.*restore stdout.*\n\s*if out_o is not None.*:\s*\n\s*sys\.stdout = out_o',
+            content,
+            re.IGNORECASE
+        )
+        assert finally_match is not None, "stdout restoration should be inside finally block"
+
+    def test_stdout_restored_after_sdk_init(self):
+        """sys.stdout should be the original after SDK operations."""
+        from vastai import VastAI
+
+        original_stdout = sys.stdout
+
+        # Create SDK instance
+        v = VastAI(api_key="test_key_12345")
+
+        # stdout should still be the original
+        assert sys.stdout is original_stdout, "stdout was corrupted after SDK init"
+
+
+class TestSysExitHandling:
+    """sys.exit() should be caught and converted."""
+
+    def test_systemexit_caught_separately(self):
+        """SystemExit should have its own except block."""
+        sdk_path = Path(__file__).parent.parent.parent / "vastai" / "sdk.py"
+        content = sdk_path.read_text()
+
+        # Should catch SystemExit separately
+        assert "except SystemExit" in content, "Should catch SystemExit separately"
+
+    def test_exit_code_extracted(self):
+        """sys.exit() code should be extracted, not re-raised."""
+        sdk_path = Path(__file__).parent.parent.parent / "vastai" / "sdk.py"
+        content = sdk_path.read_text()
+
+        # Should access e.code
+        assert "e.code" in content, "Should extract exit code from SystemExit"
+
+    def test_systemexit_before_general_exception(self):
+        """SystemExit should be caught before general Exception."""
+        sdk_path = Path(__file__).parent.parent.parent / "vastai" / "sdk.py"
+        content = sdk_path.read_text()
+
+        # Find positions of both except blocks
+        systemexit_pos = content.find("except SystemExit")
+        exception_pos = content.find("except Exception")
+
+        assert systemexit_pos != -1, "SystemExit handler not found"
+        assert exception_pos != -1, "Exception handler not found"
+        assert systemexit_pos < exception_pos, "SystemExit should be caught before general Exception"
+
+
+class TestExceptionSpecificity:
+    """Exception handling should be specific, not broad."""
+
+    def test_no_bare_except(self):
+        """Should not have bare 'except:' without exception type."""
+        sdk_path = Path(__file__).parent.parent.parent / "vastai" / "sdk.py"
+        content = sdk_path.read_text()
+
+        # Find bare except: (not except Something:)
+        lines = content.split('\n')
+        bare_excepts = []
+        for i, line in enumerate(lines, 1):
+            stripped = line.strip()
+            # Match "except:" but not "except Something:" or "except (A, B):"
+            if stripped == "except:" or stripped.startswith("except: "):
+                bare_excepts.append(f"Line {i}: {line}")
+
+        assert len(bare_excepts) == 0, f"Found bare except: {bare_excepts}"
+
+    def test_exception_handlers_have_types(self):
+        """except blocks should specify exception types."""
+        sdk_path = Path(__file__).parent.parent.parent / "vastai" / "sdk.py"
+        content = sdk_path.read_text()
+
+        # Find all except statements
+        except_lines = re.findall(r'^\s*except\s+.*:', content, re.MULTILINE)
+
+        # All should have a type (not bare except:)
+        for line in except_lines:
+            stripped = line.strip()
+            # Allow "except Type:" or "except (A, B):" or "except Type as e:"
+            assert stripped != "except:", f"Found bare except: {line}"
+            # Verify it has some type specification
+            type_match = re.match(r'except\s+[\w\(\),\s]+', stripped)
+            assert type_match, f"Exception handler should have type: {line}"
+
+    def test_specific_exceptions_in_queryformatter(self):
+        """queryFormatter should use specific exceptions (KeyError, TypeError)."""
+        sdk_path = Path(__file__).parent.parent.parent / "vastai" / "sdk.py"
+        content = sdk_path.read_text()
+
+        # The queryFormatter function should have specific exceptions
+        assert "except (KeyError, TypeError):" in content, \
+            "queryFormatter should catch specific KeyError and TypeError"
+
+
+class TestSDKImport:
+    """Basic SDK import and instantiation tests."""
+
+    def test_import_vastai(self):
+        """from vastai import VastAI should work."""
+        from vastai import VastAI
+        assert VastAI is not None
+
+    def test_instantiate_with_api_key(self):
+        """VastAI(api_key='test') should not raise."""
+        from vastai import VastAI
+        v = VastAI(api_key="test_key_12345")
+        assert v is not None
+        assert hasattr(v, "api_key")
+
+    def test_sdk_has_expected_attributes(self):
+        """SDK instance should have standard attributes."""
+        from vastai import VastAI
+        v = VastAI(api_key="test_key_12345")
+
+        # Core attributes
+        assert hasattr(v, "api_key")
+        assert hasattr(v, "server_url")
+        assert hasattr(v, "retry")
+        assert hasattr(v, "raw")
+        assert hasattr(v, "last_output")
+
+    def test_sdk_last_output_initialized(self):
+        """SDK should initialize last_output to None."""
+        from vastai import VastAI
+        v = VastAI(api_key="test_key_12345")
+        assert v.last_output is None
+
+
+class TestStdoutCaptureIntegration:
+    """Integration tests for stdout capture behavior."""
+
+    def test_stdout_not_leaked_on_multiple_operations(self):
+        """Multiple SDK operations should not leak stdout state."""
+        from vastai import VastAI
+
+        original_stdout = sys.stdout
+        v = VastAI(api_key="test_key_12345")
+
+        # Perform multiple operations (even if they fail due to no network)
+        for _ in range(3):
+            try:
+                # These may fail due to no API key/network, but stdout should be safe
+                v.show_user()
+            except Exception:
+                pass
+
+            # Check stdout is still original
+            assert sys.stdout is original_stdout, "stdout leaked after SDK operation"
diff --git a/tests/regression/test_serverless_lazy_import.py b/tests/regression/test_serverless_lazy_import.py
new file mode 100644
index 00000000..dc17499a
--- /dev/null
+++ b/tests/regression/test_serverless_lazy_import.py
@@ -0,0 +1,225 @@
+"""
+Regression tests for serverless lazy imports.
+
+These tests verify that serverless classes don't load heavy dependencies
+until they are actually accessed.
+"""
+import sys
+from pathlib import Path
+
+# Add vast-cli to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+
+class TestLazyImportConfiguration:
+    """Verify lazy import mechanism is configured correctly."""
+
+    def test_lazy_imports_dict_exists(self):
+        """vastai/__init__.py should have _LAZY_IMPORTS dict."""
+        import vastai
+
+        assert hasattr(vastai, '_LAZY_IMPORTS'), \
+            "vastai/__init__.py should have _LAZY_IMPORTS dict"
+        assert isinstance(vastai._LAZY_IMPORTS, dict), \
+            "_LAZY_IMPORTS should be a dict"
+
+    def test_lazy_imports_contains_serverless_classes(self):
+        """_LAZY_IMPORTS should map serverless class names to modules."""
+        import vastai
+
+        expected_classes = [
+            'Serverless',
+            'ServerlessRequest',
+            'Endpoint',
+            'Worker',
+            'WorkerConfig',
+            'HandlerConfig',
+        ]
+
+        for cls_name in expected_classes:
+            assert cls_name in vastai._LAZY_IMPORTS, \
+                f"'{cls_name}' should be in _LAZY_IMPORTS"
+
+    def test_getattr_function_exists(self):
+        """vastai/__init__.py should have __getattr__ for PEP 562."""
+        import vastai
+
+        # PEP 562: Module-level __getattr__ is exposed in the module namespace
+        assert hasattr(vastai, '__getattr__'), \
+            "vastai/__init__.py should have __getattr__ function"
+        assert callable(vastai.__getattr__), \
+            "__getattr__ should be callable"
+
+    def test_getattr_raises_for_unknown_attribute(self):
+        """__getattr__ should raise AttributeError for unknown names."""
+        import vastai
+
+        try:
+            _ = vastai.NonExistentClass
+            assert False, "Should have raised AttributeError"
+        except AttributeError as e:
+            assert "NonExistentClass" in str(e)
+
+
+class TestBasicVastAIImport:
+    """Basic vastai import should work without serverless deps."""
+
+    def test_vastai_import_succeeds(self):
+        """Basic import vastai should succeed."""
+        import vastai
+
+        assert vastai is not None
+
+    def test_vastai_class_available(self):
+        """VastAI class should be directly importable."""
+        from vastai import VastAI
+
+        assert VastAI is not None
+
+    def test_vastai_instantiation_works(self):
+        """VastAI can be instantiated without serverless deps."""
+        from vastai import VastAI
+
+        sdk = VastAI(api_key="test_key")
+
+        assert sdk is not None
+        assert sdk.api_key == "test_key"
+
+    def test_all_exports_defined(self):
+        """__all__ should list all public exports."""
+        import vastai
+
+        assert hasattr(vastai, '__all__'), \
+            "vastai should have __all__ defined"
+        assert 'VastAI' in vastai.__all__, \
+            "VastAI should be in __all__"
+        assert 'Serverless' in vastai.__all__, \
+            "Serverless should be in __all__ (even if lazy)"
+
+
+class TestServerlessClassAccess:
+    """Test that serverless classes can be accessed when deps are available."""
+
+    def test_serverless_in_all(self):
+        """Serverless classes should be listed in __all__."""
+        import vastai
+
+        serverless_classes = [
+            'Serverless',
+            'ServerlessRequest',
+            'Endpoint',
+            'Worker',
+            'WorkerConfig',
+            'HandlerConfig',
+            'LogActionConfig',
+            'BenchmarkConfig',
+        ]
+
+        for cls_name in serverless_classes:
+            assert cls_name in vastai.__all__, \
+                f"'{cls_name}' should be in __all__"
+
+    def test_serverless_import_path_correct(self):
+        """Lazy import paths should point to correct modules."""
+        import vastai
+
+        # Serverless and ServerlessRequest should be in client.client
+        assert '.serverless.client.client' in vastai._LAZY_IMPORTS['Serverless'], \
+            "Serverless should be in serverless.client.client"
+
+        # Worker classes should be in server.worker
+        assert '.serverless.server.worker' in vastai._LAZY_IMPORTS['Worker'], \
+            "Worker should be in serverless.server.worker"
+
+
+class TestAiohttpFreeEnvironment:
+    """Test behavior in environment without aiohttp."""
+
+    def test_aiohttp_not_imported_on_basic_import(self):
+        """Importing vastai should not import aiohttp."""
+        # Clear any cached imports
+        import sys
+
+        # Note: This test documents expected behavior
+        # The actual lazy import only delays the import until class access
+        # So if aiohttp is installed, this test just verifies the mechanism
+
+        # Check that vast and vastai can be imported
+        if 'vastai' in sys.modules:
+            del sys.modules['vastai']
+        if 'vastai.sdk' in sys.modules:
+            del sys.modules['vastai.sdk']
+
+        # Record aiohttp import state before
+        aiohttp_before = 'aiohttp' in sys.modules
+
+        # Import vastai
+        import vastai
+        from vastai import VastAI
+
+        # Create SDK instance
+        sdk = VastAI(api_key="test")
+
+        # Note: We can't truly test aiohttp-free behavior if aiohttp is installed
+        # This test documents that the lazy import mechanism is in place
+        assert True, "Basic vastai import and VastAI instantiation succeeded"
+
+    def test_lazy_import_delays_module_load(self):
+        """Serverless modules should not be in sys.modules after basic import."""
+        import sys
+
+        # Clear caches
+        modules_to_clear = [
+            'vastai.serverless.client.client',
+            'vastai.serverless.server.worker',
+        ]
+        for mod in modules_to_clear:
+            if mod in sys.modules:
+                del sys.modules[mod]
+
+        # Import only VastAI
+        from vastai import VastAI
+
+        # Check serverless modules are not yet loaded
+        # (This may vary depending on test order, so we just document behavior)
+        sdk = VastAI(api_key="test")
+
+        # The SDK should work without serverless modules being loaded
+        assert sdk is not None
+
+
+class TestServerlessIntegration:
+    """Test serverless framework integration."""
+
+    def test_serverless_class_loadable(self):
+        """Serverless class should be loadable (when deps available)."""
+        try:
+            from vastai import Serverless
+
+            # If aiohttp is available, this should work
+            assert Serverless is not None
+        except ImportError as e:
+            # If aiohttp not available, should get ImportError from the module
+            assert 'aiohttp' in str(e).lower() or 'No module' in str(e), \
+                f"Unexpected import error: {e}"
+
+    def test_worker_class_loadable(self):
+        """Worker class should be loadable (when deps available)."""
+        try:
+            from vastai import Worker
+
+            assert Worker is not None
+        except ImportError as e:
+            # Expected if dependencies not available
+            assert 'aiohttp' in str(e).lower() or 'No module' in str(e), \
+                f"Unexpected import error: {e}"
+
+    def test_endpoint_class_loadable(self):
+        """Endpoint class should be loadable."""
+        try:
+            from vastai import Endpoint
+
+            assert Endpoint is not None
+        except ImportError as e:
+            # May fail if deps not available
+            pass  # Expected behavior
diff --git a/tests/regression/test_shell_injection.py b/tests/regression/test_shell_injection.py
new file mode 100644
index 00000000..40556aa0
--- /dev/null
+++ b/tests/regression/test_shell_injection.py
@@ -0,0 +1,116 @@
+"""No shell=True subprocess calls in vast.py.
+
+The bug: subprocess calls with shell=True are vulnerable to command injection
+(CWE-78). User-controlled data (paths, instance IDs, addresses) could be
+injected into shell commands. Additionally, subprocess.getoutput() implicitly
+uses shell=True.
+
+The fix: Convert all shell=True calls to argument lists. Replace
+subprocess.getoutput("echo $HOME") with os.path.expanduser("~"). Convert
+get_update_command() to return a list instead of a string.
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+import re
+import pytest
+
+
+VAST_PY_PATH = os.path.join(os.path.dirname(__file__), '..', '..', 'vast.py')
+
+
+class TestNoShellTrue:
+    """Lint-style tests verifying no shell=True remains in vast.py."""
+
+    def test_no_shell_true(self):
+        """No shell=True subprocess calls should exist in vast.py.
+
+        shell=True enables command injection when user-controlled data
+        is passed to subprocess calls.
+        """
+        with open(VAST_PY_PATH, encoding='utf-8') as f:
+            content = f.read()
+        assert 'shell=True' not in content, (
+            "Found shell=True in vast.py. All subprocess calls must use "
+            "argument lists instead of shell command strings."
+        )
+
+    def test_no_subprocess_getoutput(self):
+        """No subprocess.getoutput() calls should exist in vast.py.
+
+        subprocess.getoutput() implicitly uses shell=True and is
+        vulnerable to command injection.
+        """
+        with open(VAST_PY_PATH, encoding='utf-8') as f:
+            content = f.read()
+        assert 'subprocess.getoutput' not in content, (
+            "Found subprocess.getoutput in vast.py. Use os.path.expanduser "
+            "or subprocess.run with argument lists instead."
+        )
+
+
+class TestGetUpdateCommand:
+    """Verify get_update_command() returns a list, not a string."""
+
+    def test_returns_list_for_pip(self):
+        """get_update_command() should return a list when is_pip_package."""
+        import vast
+        from unittest.mock import patch
+
+        with patch.object(vast, 'is_pip_package', return_value=True):
+            result = vast.get_update_command("1.2.3")
+        assert isinstance(result, list), (
+            f"get_update_command() returned {type(result).__name__}, expected list"
+        )
+        assert all(isinstance(item, str) for item in result), (
+            "All elements of the command list must be strings"
+        )
+        assert "vastai==1.2.3" in result, (
+            "Command list should include version-pinned package name"
+        )
+
+    def test_returns_list_for_git(self):
+        """get_update_command() should return a list when not pip."""
+        import vast
+        from unittest.mock import patch
+
+        with patch.object(vast, 'is_pip_package', return_value=False):
+            result = vast.get_update_command("1.2.3")
+        assert isinstance(result, list), (
+            f"get_update_command() returned {type(result).__name__}, expected list"
+        )
+        assert all(isinstance(item, str) for item in result), (
+            "All elements of the command list must be strings"
+        )
+        assert "git" in result, "Git command list should contain 'git'"
+
+    def test_pip_command_has_no_shell_operators(self):
+        """The pip command list should not contain shell operators."""
+        import vast
+        from unittest.mock import patch
+
+        # Shell operators that indicate command chaining/injection
+        shell_operators = ['&&', '||', '|', ';', '>', '<', '$(', '`']
+        with patch.object(vast, 'is_pip_package', return_value=True):
+            result = vast.get_update_command("1.2.3")
+        combined = " ".join(result)
+        for op in shell_operators:
+            assert op not in combined, (
+                f"Shell operator {op!r} found in pip command: {combined!r}"
+            )
+
+    def test_git_command_has_no_shell_operators(self):
+        """The git command list should not contain && or | operators."""
+        import vast
+        from unittest.mock import patch
+
+        with patch.object(vast, 'is_pip_package', return_value=False):
+            result = vast.get_update_command("1.2.3")
+        combined = " ".join(result)
+        assert "&&" not in combined, (
+            "Git command should not contain '&&' -- use separate subprocess calls"
+        )
+        assert "|" not in combined, (
+            "Git command should not contain pipe operators"
+        )
diff --git a/tests/regression/test_show_instances.py b/tests/regression/test_show_instances.py
new file mode 100644
index 00000000..fad8df97
--- /dev/null
+++ b/tests/regression/test_show_instances.py
@@ -0,0 +1,90 @@
+"""show__instances() loop rebinds local variable without updating list.
+
+The bug: `for row in rows: row = {...}` rebinds the local `row` variable to a
+new dict, but the original dict in `rows` is unchanged. The stripped strings
+and computed duration are lost.
+
+The fix: Build a new list and reassign rows.
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+import argparse
+import time
+from unittest.mock import MagicMock, patch
+
+
+def test_rows_are_modified_after_loop():
+    """After show__instances processes rows, the returned rows have modified data."""
+    from vast import show__instances
+
+    mock_instances = [
+        {
+            "id": 12345,
+            "start_date": time.time() - 3600,  # started 1 hour ago
+            "extra_env": [["KEY1", "val1"], ["KEY2", "val2"]],
+            "status": "running",
+            "name": "  test  ",  # has leading/trailing spaces
+        }
+    ]
+
+    mock_response = MagicMock()
+    mock_response.json.return_value = {"instances": mock_instances}
+    mock_response.status_code = 200
+    mock_response.raise_for_status = MagicMock()
+
+    args = argparse.Namespace(
+        api_key="test", url="https://console.vast.ai",
+        retry=3, raw=True, explain=False, quiet=False,
+        curl=False, full=False,
+    )
+
+    with patch('vast.apiurl', return_value="https://console.vast.ai/api/v0/instances"), \
+         patch('vast.http_get', return_value=mock_response):
+        result = show__instances(args, extra={})
+
+    # In raw mode, show__instances returns rows
+    assert result is not None, "show__instances returned None in raw mode"
+    assert len(result) > 0, "show__instances returned empty list"
+    row = result[0]
+    # The row should have 'duration' field computed from the loop
+    assert 'duration' in row, "Row missing 'duration' -- loop rebinding bug still present"
+    assert row['duration'] > 0, f"Duration should be positive, got {row['duration']}"
+    # extra_env should be converted from list-of-pairs to dict
+    assert isinstance(row['extra_env'], dict), "extra_env not converted to dict"
+    assert row['extra_env'].get('KEY1') == 'val1'
+
+
+def test_rows_stripped_strings_preserved():
+    """Verify strip_strings is applied and preserved in the returned rows."""
+    from vast import show__instances
+
+    mock_instances = [
+        {
+            "id": 99,
+            "start_date": time.time() - 100,
+            "extra_env": [],
+            "status": "  running  ",
+        }
+    ]
+
+    mock_response = MagicMock()
+    mock_response.json.return_value = {"instances": mock_instances}
+    mock_response.status_code = 200
+    mock_response.raise_for_status = MagicMock()
+
+    args = argparse.Namespace(
+        api_key="test", url="https://console.vast.ai",
+        retry=3, raw=True, explain=False, quiet=False,
+        curl=False, full=False,
+    )
+
+    with patch('vast.apiurl', return_value="https://console.vast.ai/api/v0/instances"), \
+         patch('vast.http_get', return_value=mock_response):
+        result = show__instances(args, extra={})
+
+    assert result is not None
+    row = result[0]
+    # strip_strings should have trimmed the status value
+    assert row['status'] == 'running', f"Expected 'running', got '{row['status']}' -- strip not applied"
diff --git a/tests/regression/test_show_machine.py b/tests/regression/test_show_machine.py
new file mode 100644
index 00000000..f75d0b56
--- /dev/null
+++ b/tests/regression/test_show_machine.py
@@ -0,0 +1,58 @@
+"""show__machine() doesn't handle single dict response.
+
+The bug: api_call returns a dict for single-machine queries. The code
+iterates `for row in rows` which iterates over dict KEYS (strings like 'id',
+'gpu_name') instead of dicts. display_table also expects a list of dicts.
+
+The fix: Wrap single dict responses in a list.
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+import argparse
+from unittest.mock import patch, MagicMock
+
+
+def test_single_dict_response_handled():
+    """show__machine wraps a single dict response in a list."""
+    from vast import show__machine
+
+    single_machine = {
+        "id": 42,
+        "gpu_name": "RTX 4090",
+        "num_gpus": 1,
+    }
+
+    args = argparse.Namespace(
+        api_key="test", url="https://console.vast.ai",
+        retry=3, raw=True, explain=False, quiet=False,
+        curl=False, id=42,
+    )
+
+    with patch('vast.api_call', return_value=single_machine):
+        result = show__machine(args)
+
+    # In raw mode, should return a list (wrapped dict)
+    assert isinstance(result, list), f"Expected list, got {type(result)}"
+    assert len(result) == 1
+    assert result[0]['id'] == 42
+
+
+def test_list_response_unchanged():
+    """show__machine leaves list responses as-is."""
+    from vast import show__machine
+
+    machine_list = [{"id": 42, "gpu_name": "RTX 4090"}]
+
+    args = argparse.Namespace(
+        api_key="test", url="https://console.vast.ai",
+        retry=3, raw=True, explain=False, quiet=False,
+        curl=False, id=42,
+    )
+
+    with patch('vast.api_call', return_value=machine_list):
+        result = show__machine(args)
+
+    assert isinstance(result, list)
+    assert len(result) == 1
diff --git a/tests/regression/test_timeout.py b/tests/regression/test_timeout.py
new file mode 100644
index 00000000..330d994c
--- /dev/null
+++ b/tests/regression/test_timeout.py
@@ -0,0 +1,129 @@
+"""Missing timeout on HTTP requests.
+
+The bug: session.send() has no timeout parameter. Requests can hang
+indefinitely if the server never responds or the connection stalls.
+
+The fix: Add timeout=DEFAULT_TIMEOUT (30s) to http_request() and forward
+it to session.send(). All wrapper functions (http_get, http_post, http_put,
+http_del) accept and forward the timeout parameter.
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+import argparse
+from unittest.mock import MagicMock, patch, call
+import pytest
+
+
+def _make_args(retry=1):
+    return argparse.Namespace(retry=retry, curl=False)
+
+
+@patch('vast.time.sleep')
+@patch('vast.requests.Session')
+def test_default_timeout_forwarded(mock_session_cls, mock_sleep):
+    """http_request passes timeout=30 (DEFAULT_TIMEOUT) to session.send by default."""
+    from vast import http_request, DEFAULT_TIMEOUT
+
+    mock_session = MagicMock()
+    mock_session_cls.return_value = mock_session
+
+    success_response = MagicMock()
+    success_response.status_code = 200
+    mock_session.send.return_value = success_response
+    mock_session.prepare_request.return_value = MagicMock()
+
+    args = _make_args(retry=1)
+    with patch('vast.ARGS', args):
+        result = http_request('GET', args, 'http://example.com/test')
+
+    assert result.status_code == 200
+    # Verify timeout was passed to session.send
+    mock_session.send.assert_called_once()
+    _, kwargs = mock_session.send.call_args
+    assert kwargs.get('timeout') == DEFAULT_TIMEOUT
+    assert kwargs.get('timeout') == 30
+
+
+@patch('vast.time.sleep')
+@patch('vast.requests.Session')
+def test_custom_timeout_forwarded(mock_session_cls, mock_sleep):
+    """http_request forwards a custom timeout value to session.send."""
+    from vast import http_request
+
+    mock_session = MagicMock()
+    mock_session_cls.return_value = mock_session
+
+    success_response = MagicMock()
+    success_response.status_code = 200
+    mock_session.send.return_value = success_response
+    mock_session.prepare_request.return_value = MagicMock()
+
+    args = _make_args(retry=1)
+    with patch('vast.ARGS', args):
+        result = http_request('GET', args, 'http://example.com/test', timeout=120)
+
+    assert result.status_code == 200
+    _, kwargs = mock_session.send.call_args
+    assert kwargs.get('timeout') == 120
+
+
+@patch('vast.http_request')
+def test_http_get_forwards_timeout(mock_http_request):
+    """http_get forwards timeout parameter to http_request."""
+    from vast import http_get
+
+    mock_http_request.return_value = MagicMock(status_code=200)
+    args = _make_args()
+
+    http_get(args, 'http://example.com/test', timeout=60)
+
+    mock_http_request.assert_called_once()
+    _, kwargs = mock_http_request.call_args
+    assert kwargs.get('timeout') == 60
+
+
+@patch('vast.http_request')
+def test_http_post_forwards_timeout(mock_http_request):
+    """http_post forwards timeout parameter to http_request."""
+    from vast import http_post
+
+    mock_http_request.return_value = MagicMock(status_code=200)
+    args = _make_args()
+
+    http_post(args, 'http://example.com/test', timeout=90)
+
+    mock_http_request.assert_called_once()
+    _, kwargs = mock_http_request.call_args
+    assert kwargs.get('timeout') == 90
+
+
+@patch('vast.http_request')
+def test_http_put_forwards_timeout(mock_http_request):
+    """http_put forwards timeout parameter to http_request."""
+    from vast import http_put
+
+    mock_http_request.return_value = MagicMock(status_code=200)
+    args = _make_args()
+
+    http_put(args, 'http://example.com/test', timeout=45)
+
+    mock_http_request.assert_called_once()
+    _, kwargs = mock_http_request.call_args
+    assert kwargs.get('timeout') == 45
+
+
+@patch('vast.http_request')
+def test_http_del_forwards_timeout(mock_http_request):
+    """http_del forwards timeout parameter to http_request."""
+    from vast import http_del
+
+    mock_http_request.return_value = MagicMock(status_code=200)
+    args = _make_args()
+
+    http_del(args, 'http://example.com/test', timeout=15)
+
+    mock_http_request.assert_called_once()
+    _, kwargs = mock_http_request.call_args
+    assert kwargs.get('timeout') == 15
diff --git a/tests/regression/test_timezone_handling.py b/tests/regression/test_timezone_handling.py
new file mode 100644
index 00000000..2bddcad0
--- /dev/null
+++ b/tests/regression/test_timezone_handling.py
@@ -0,0 +1,41 @@
+"""Timezone handling uses time.mktime() which interprets as local time.
+
+The bug: time.mktime() converts a time tuple to epoch using the LOCAL timezone.
+For a user in PST (UTC-8), a date "01/15/2025" would produce an epoch value
+that's 8 hours later than UTC midnight, giving wrong results.
+
+The fix: Use calendar.timegm() which always interprets the time tuple as UTC.
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+import calendar
+
+
+def test_string_to_unix_epoch_utc():
+    """string_to_unix_epoch returns UTC timestamps regardless of local timezone."""
+    from vast import string_to_unix_epoch
+
+    # 01/15/2025 00:00:00 UTC = 1736899200
+    result = string_to_unix_epoch("01/15/2025")
+    expected = calendar.timegm((2025, 1, 15, 0, 0, 0, 0, 0, 0))
+    assert expected == 1736899200, f"Sanity check: expected 1736899200, got {expected}"
+    assert result == expected, (
+        f"string_to_unix_epoch('01/15/2025') returned {result}, expected {expected}. "
+        f"This likely means time.mktime() is still being used instead of calendar.timegm()."
+    )
+
+
+def test_string_to_unix_epoch_returns_float_passthrough():
+    """string_to_unix_epoch returns float values as-is."""
+    from vast import string_to_unix_epoch
+
+    assert string_to_unix_epoch("1736899200") == 1736899200.0
+
+
+def test_string_to_unix_epoch_none():
+    """string_to_unix_epoch returns None for None input."""
+    from vast import string_to_unix_epoch
+
+    assert string_to_unix_epoch(None) is None
diff --git a/tests/regression/test_unreachable_code.py b/tests/regression/test_unreachable_code.py
new file mode 100644
index 00000000..f70e3b93
--- /dev/null
+++ b/tests/regression/test_unreachable_code.py
@@ -0,0 +1,227 @@
+"""No unreachable code after raise_for_status().
+
+The bug: 19 functions had `if (r.status_code == 200):` guards immediately
+after `r.raise_for_status()`. Since raise_for_status() raises HTTPError for
+non-2xx responses, the status_code check was always True and the `else` branch
+(printing "failed with error {r.status_code}") was unreachable dead code.
+
+The fix: Remove the redundant status_code == 200 wrapper, de-indent the
+success path, and remove the unreachable else branches. API-level success
+checks (rj.get("success")) are preserved since those check the JSON body,
+not the HTTP status.
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+import re
+import argparse
+import pytest
+from unittest import mock
+from unittest.mock import MagicMock, patch
+from io import StringIO
+
+VAST_PY_PATH = os.path.join(os.path.dirname(__file__), '..', '..', 'vast.py')
+
+
+# --------------------------------------------------------------------------- #
+# Lint-style tests #
+# --------------------------------------------------------------------------- #
+
+class TestNoUnreachableStatusCheck:
+    """Ensure no status_code == 200 checks follow raise_for_status()."""
+
+    def test_no_status_check_after_raise_for_status(self):
+        """Pattern: raise_for_status() followed within 3 lines by status_code == 200."""
+        with open(VAST_PY_PATH, encoding='utf-8') as f:
+            content = f.read()
+        # Match raise_for_status() followed (within a few lines) by status_code == 200
+        pattern = r'raise_for_status\(\)\s*\n(?:\s*\n)*\s*if\s*\(?r\.status_code\s*==\s*200'
+        matches = re.findall(pattern, content)
+        assert len(matches) == 0, (
+            f"Found {len(matches)} unreachable status_code == 200 checks after "
+            f"raise_for_status(). These are unreachable and should be removed."
+        )
+
+    def test_no_status_check_after_raise_for_status_response_var(self):
+        """Same pattern but with 'response' variable name."""
+        with open(VAST_PY_PATH, encoding='utf-8') as f:
+            content = f.read()
+        pattern = r'raise_for_status\(\)\s*\n(?:\s*\n)*\s*if\s*\(?response\.status_code\s*==\s*200'
+        matches = re.findall(pattern, content)
+        assert len(matches) == 0, (
+            f"Found {len(matches)} unreachable status_code == 200 checks (response var) "
+            f"after raise_for_status()."
+        )
+
+    def test_no_unreachable_failed_with_error_after_unconditional_raise(self):
+        """The 'failed with error' message should not appear after an
+        *unconditional* raise_for_status() call (same indentation as function body).
+        Conditional raise_for_status() calls (inside if blocks) are excluded."""
+        with open(VAST_PY_PATH, encoding='utf-8') as f:
+            lines = f.readlines()
+
+        # Find unconditional raise_for_status lines (indented exactly 4 spaces,
+        # i.e., at function-body level, not nested inside an if/else)
+        rfs_indices = []
+        for i, line in enumerate(lines):
+            stripped = line.rstrip()
+            if 'raise_for_status()' in stripped and not stripped.lstrip().startswith('#'):
+                # Check indentation: unconditional means base function indent (4 spaces)
+                indent = len(line) - len(line.lstrip())
+                if indent == 4:
+                    rfs_indices.append(i)
+
+        for rfs_idx in rfs_indices:
+            # Check within 20 lines after raise_for_status for the dead pattern
+            for offset in range(1, 20):
+                check_idx = rfs_idx + offset
+                if check_idx >= len(lines):
+                    break
+                line = lines[check_idx]
+                # If we hit a new function def or decorator, stop scanning
+                if re.match(r'^def\s+', line) or re.match(r'^@', line):
+                    break
+                if 'failed with error {r.status_code}' in line:
+                    assert False, (
+                        f"Line {check_idx + 1}: Found unreachable 'failed with error' "
+                        f"message after unconditional raise_for_status() at line {rfs_idx + 1}"
+                    )
+
+
+# --------------------------------------------------------------------------- #
+# Functional tests #
+# --------------------------------------------------------------------------- #
+
+class TestStartInstanceBehavior:
+    """Verify start_instance works correctly after unreachable code removal."""
+
+    @patch('vast.http_put')
+    def test_success_prints_message(self, mock_put, capsys):
+        """When API returns 200 with success=True, print starting message."""
+        import vast
+
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.raise_for_status = MagicMock()
+        mock_response.json.return_value = {"success": True}
+        mock_put.return_value = mock_response
+
+        args = argparse.Namespace(
+            api_key="test-key", url="https://console.vast.ai",
+            retry=3, raw=False, explain=False
+        )
+
+        result = vast.start_instance(12345, args)
+
+        assert result is True
+        captured = capsys.readouterr()
+        assert "starting instance" in captured.out
+
+    @patch('vast.http_put')
+    def test_api_failure_prints_msg(self, mock_put, capsys):
+        """When API returns 200 with success=False, print the error msg."""
+        import vast
+
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.raise_for_status = MagicMock()
+        mock_response.json.return_value = {"success": False, "msg": "instance not found"}
+        mock_put.return_value = mock_response
+
+        args = argparse.Namespace(
+            api_key="test-key", url="https://console.vast.ai",
+            retry=3, raw=False, explain=False
+        )
+
+        result = vast.start_instance(12345, args)
+
+        assert result is True
+        captured = capsys.readouterr()
+        assert "instance not found" in captured.out
+
+    @patch('vast.http_put')
+    def test_http_error_raises(self, mock_put):
+        """When API returns 500, raise_for_status raises HTTPError."""
+        import vast
+        import requests
+
+        mock_response = MagicMock()
+        mock_response.status_code = 500
+        mock_response.raise_for_status.side_effect = requests.exceptions.HTTPError(
+            "500 Server Error"
+        )
+        mock_put.return_value = mock_response
+
+        args = argparse.Namespace(
+            api_key="test-key", url="https://console.vast.ai",
+            retry=3, raw=False, explain=False
+        )
+
+        with pytest.raises(requests.exceptions.HTTPError):
+            vast.start_instance(12345, args)
+
+    @patch('vast.http_put')
+    def test_missing_msg_uses_default(self, mock_put, capsys):
+        """When API returns success=False without msg, use default error."""
+        import vast
+
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.raise_for_status = MagicMock()
+        mock_response.json.return_value = {"success": False}
+        mock_put.return_value = mock_response
+
+        args = argparse.Namespace(
+            api_key="test-key", url="https://console.vast.ai",
+            retry=3, raw=False, explain=False
+        )
+
+        vast.start_instance(12345, args)
+
+        captured = capsys.readouterr()
+        assert "Unknown error" in captured.out
+
+
+class TestDestroyInstanceBehavior:
+    """Verify destroy_instance preserves raw mode path after refactor."""
+
+    @patch('vast.http_del')
+    def test_raw_mode_returns_json(self, mock_del):
+        """In raw mode, destroy_instance returns parsed JSON."""
+        import vast
+
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.raise_for_status = MagicMock()
+        mock_response.json.return_value = {"success": True}
+        mock_del.return_value = mock_response
+
+        args = argparse.Namespace(
+            api_key="test-key", url="https://console.vast.ai",
+            retry=3, raw=True, explain=False
+        )
+
+        result = vast.destroy_instance(12345, args)
+        assert result == {"success": True}
+
+    @patch('vast.http_del')
+    def test_non_raw_prints_destroying(self, mock_del, capsys):
+        """In non-raw mode, destroy_instance prints 'destroying instance'."""
+        import vast
+
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.raise_for_status = MagicMock()
+        mock_response.json.return_value = {"success": True}
+        mock_del.return_value = mock_response
+
+        args = argparse.Namespace(
+            api_key="test-key", url="https://console.vast.ai",
+            retry=3, raw=False, explain=False
+        )
+
+        vast.destroy_instance(12345, args)
+
+        captured = capsys.readouterr()
+        assert "destroying instance" in captured.out
diff --git a/tests/regression/test_utc_display.py b/tests/regression/test_utc_display.py
new file mode 100644
index 00000000..0d31ca32
--- /dev/null
+++ b/tests/regression/test_utc_display.py
@@ -0,0 +1,97 @@
+"""UTC-labeled timestamps must actually display UTC.
+
+The bug: datetime.fromtimestamp(ts) without tz= returns LOCAL time, but
+the columns are labeled "UTC" or the output is treated as UTC. Users in
+non-UTC timezones see wrong times.
+
+The fix: All fromtimestamp() calls that produce UTC-labeled output now
+pass tz=timezone.utc explicitly.
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+import re
+import pytest
+from datetime import datetime, timezone
+
+
+VAST_PY_PATH = os.path.join(os.path.dirname(__file__), '..', '..', 'vast.py')
+
+
+class TestUnixToReadableUTC:
+    """Verify unix_to_readable() produces UTC output."""
+
+    def test_known_epoch_returns_utc_midnight(self):
+        """1704067200 is 2024-01-01 00:00:00 UTC. Output must show 00:00:00."""
+        from vast import unix_to_readable
+        result = unix_to_readable(1704067200)
+        assert "00:00:00" in result, (
+            f"unix_to_readable(1704067200) should show 00:00:00 UTC, got: {result}"
+        )
+
+    def test_known_epoch_returns_correct_date(self):
+        """1704067200 is 2024-01-01 UTC. Output must contain Jan-01-2024."""
+        from vast import unix_to_readable
+        result = unix_to_readable(1704067200)
+        assert "Jan-01-2024" in result, (
+            f"unix_to_readable(1704067200) should contain Jan-01-2024, got: {result}"
+        )
+
+    def test_midday_epoch_shows_utc_time(self):
+        """1704110400 is 2024-01-01 12:00:00 UTC. Output must show 12:00:00."""
+        from vast import unix_to_readable
+        result = unix_to_readable(1704110400)
+        assert "12:00:00" in result, (
+            f"unix_to_readable(1704110400) should show 12:00:00 UTC, got: {result}"
+        )
+
+
+class TestFromtimestampCallsUseUTC:
+    """Lint-style test: every fromtimestamp() call must use tz=timezone.utc."""
+
+    def test_all_fromtimestamp_calls_have_tz_utc(self):
+        """Every fromtimestamp( call in vast.py should include tz=timezone.utc.
+
+        This prevents regressions where a new fromtimestamp() call is added
+        without the timezone parameter, silently producing local time.
+        """
+        with open(VAST_PY_PATH, encoding='utf-8') as f:
+            lines = f.readlines()
+
+        violations = []
+        for i, line in enumerate(lines, 1):
+            # Skip comments
+            stripped = line.strip()
+            if stripped.startswith('#'):
+                continue
+            # Find fromtimestamp( calls
+            if 'fromtimestamp(' in line and 'utcfromtimestamp' not in line:
+                if 'tz=timezone.utc' not in line:
+                    violations.append(f"Line {i}: {stripped}")
+
+        assert len(violations) == 0, (
+            f"Found {len(violations)} fromtimestamp() calls without tz=timezone.utc:\n"
+            + "\n".join(violations)
+        )
+
+
+class TestCacheAgeUsesAwareDatetimes:
+    """Verify cache age calculation uses timezone-aware datetimes on both sides."""
+
+    def test_cache_age_uses_tz_aware_now(self):
+        """datetime.now() in cache age must use tz=timezone.utc."""
+        with open(VAST_PY_PATH, encoding='utf-8') as f:
+            content = f.read()
+
+        # Find the cache_age line
+        match = re.search(r'cache_age\s*=\s*(.+)', content)
+        assert match is not None, "cache_age assignment not found in vast.py"
+
+        cache_age_line = match.group(1)
+        assert 'datetime.now(tz=timezone.utc)' in cache_age_line, (
+            f"cache_age should use datetime.now(tz=timezone.utc), got: {cache_age_line}"
+        )
+        assert 'fromtimestamp(' in cache_age_line and 'tz=timezone.utc' in cache_age_line, (
+            f"cache_age should use fromtimestamp with tz=timezone.utc, got: {cache_age_line}"
+        )
diff --git a/tests/regression/test_utcfromtimestamp.py b/tests/regression/test_utcfromtimestamp.py
new file mode 100644
index 00000000..4d5dd255
--- /dev/null
+++ b/tests/regression/test_utcfromtimestamp.py
@@ -0,0 +1,93 @@
+"""No deprecated utcfromtimestamp() calls in vast.py.
+
+The bug: datetime.utcfromtimestamp() is deprecated since Python 3.12 and
+will be removed in a future version. It also returns a naive datetime that
+is ambiguous about its timezone.
+
+The fix: Replace all utcfromtimestamp() calls with
+datetime.fromtimestamp(ts, tz=timezone.utc), which returns an aware
+datetime and is not deprecated.
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+import re
+import pytest
+from datetime import datetime, timezone
+
+
+VAST_PY_PATH = os.path.join(os.path.dirname(__file__), '..', '..', 'vast.py')
+
+
+class TestNoUtcfromtimestamp:
+    """Lint-style tests verifying utcfromtimestamp is not used anywhere."""
+
+    def test_no_utcfromtimestamp_in_source(self):
+        """utcfromtimestamp should not appear anywhere in vast.py.
+
+        This deprecated method returns naive datetimes and will be removed
+        in a future Python version. Use fromtimestamp(ts, tz=timezone.utc).
+        """
+        with open(VAST_PY_PATH, encoding='utf-8') as f:
+            content = f.read()
+
+        matches = re.findall(r'utcfromtimestamp', content)
+        assert len(matches) == 0, (
+            f"Found {len(matches)} occurrences of utcfromtimestamp in vast.py. "
+            "Use datetime.fromtimestamp(ts, tz=timezone.utc) instead."
+        )
+
+    def test_no_utcnow_in_source(self):
+        """utcnow() is also deprecated for the same reason as utcfromtimestamp.
+
+        Prevent regression by ensuring neither deprecated UTC method is used.
+        """
+        with open(VAST_PY_PATH, encoding='utf-8') as f:
+            content = f.read()
+
+        # Match utcnow() but not in comments
+        lines = content.split('\n')
+        violations = []
+        for i, line in enumerate(lines, 1):
+            stripped = line.strip()
+            if stripped.startswith('#'):
+                continue
+            if 'utcnow()' in line:
+                violations.append(f"Line {i}: {stripped}")
+
+        assert len(violations) == 0, (
+            f"Found {len(violations)} occurrences of utcnow() in vast.py. "
+            "Use datetime.now(tz=timezone.utc) instead.\n"
+            + "\n".join(violations)
+        )
+
+
+class TestReplacementProducesAwareDatetime:
+    """Verify the replacement fromtimestamp(ts, tz=timezone.utc) works correctly."""
+
+    def test_fromtimestamp_with_tz_returns_aware_datetime(self):
+        """datetime.fromtimestamp(ts, tz=timezone.utc) must return a tz-aware datetime."""
+        ts = 1704067200  # 2024-01-01 00:00:00 UTC
+        dt = datetime.fromtimestamp(ts, tz=timezone.utc)
+        assert dt.tzinfo is not None, "Result should be timezone-aware"
+        assert dt.tzinfo == timezone.utc, "Result timezone should be UTC"
+
+    def test_fromtimestamp_with_tz_correct_values(self):
+        """Verify the replacement produces correct year/month/day/hour."""
+        ts = 1704067200  # 2024-01-01 00:00:00 UTC
+        dt = datetime.fromtimestamp(ts, tz=timezone.utc)
+        assert dt.year == 2024
+        assert dt.month == 1
+        assert dt.day == 1
+        assert dt.hour == 0
+        assert dt.minute == 0
+        assert dt.second == 0
+
+    def test_fromtimestamp_with_tz_matches_expected_format(self):
+        """The replacement in schedule_maintenance should format correctly."""
+        ts = 1704067200  # 2024-01-01 00:00:00 UTC
+        dt = datetime.fromtimestamp(ts, tz=timezone.utc)
+        # The schedule_maintenance function uses str(dt) implicitly in f-string
+        dt_str = str(dt)
+        assert "2024-01-01" in dt_str, f"Expected 2024-01-01 in {dt_str}"
diff --git a/tests/smoke/__init__.py b/tests/smoke/__init__.py
new file mode 100644
index 00000000..157ea08b
--- /dev/null
+++ b/tests/smoke/__init__.py
@@ -0,0 +1 @@
+"""Smoke tests for CLI commands and standalone execution."""
diff --git a/tests/smoke/test_cli_commands.py b/tests/smoke/test_cli_commands.py
new file mode 100644
index 00000000..dab965bf
--- /dev/null
+++ b/tests/smoke/test_cli_commands.py
@@ -0,0 +1,429 @@
+"""Smoke tests for CLI commands.
+
+TEST-08: CLI smoke tests - major commands parse args and call correct endpoints.
+
+These tests verify that CLI commands:
+1. Parse their arguments correctly
+2. Call the expected API endpoints
+3. Handle mocked responses appropriately
+
+All HTTP is mocked - no network calls are made.
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+import argparse
+import json
+import pytest
+from unittest.mock import MagicMock, patch
+
+
+def _make_base_args(**overrides):
+    """Create base args namespace with common fields."""
+    args = argparse.Namespace(
+        api_key="test-key",
+        url="https://console.vast.ai",
+        retry=3,
+        raw=False,
+        explain=False,
+        quiet=False,
+        curl=False,
+        full=False,
+        no_color=True,
+        debugging=False,
+    )
+    for key, value in overrides.items():
+        setattr(args, key, value)
+    return args
+
+
+@pytest.fixture(autouse=True)
+def setup_vast_args():
+    """Set up vast.ARGS to prevent NoneType errors in http_request."""
+    import vast
+    old_args = vast.ARGS
+    vast.ARGS = _make_base_args()
+    yield
+    vast.ARGS = old_args
+
+
+class TestSearchOffers:
+    """Smoke tests for 'search offers' command."""
+
+    @patch('vast.http_post')
+    def test_search_offers_calls_bundles_endpoint(self, mock_http_post):
+        """search offers calls /api/v0/bundles/ endpoint via POST."""
+        import vast
+
+        mock_response = MagicMock()
+        mock_response.json.return_value = {"offers": []}
+        mock_response.status_code = 200
+        mock_response.headers = {"Content-Type": "application/json"}
+        mock_response.raise_for_status = MagicMock()
+        mock_http_post.return_value = mock_response
+
+        args = _make_base_args(
+            query=["gpu_ram>=8"],
+            type="bid",
+            raw=True,
+            no_default=False,
+            new=False,
+            limit=None,
+            disable_bundling=False,
+            storage=5.0,
+            order="score-",
+        )
+        vast.search__offers(args)
+
+        mock_http_post.assert_called_once()
+        call_url = mock_http_post.call_args[0][1]
+        assert "/api/v0/bundles" in call_url
+
+    @patch('vast.http_post')
+    def test_search_offers_with_gpu_name(self, mock_http_post):
+        """search offers parses gpu_name filter."""
+        import vast
+
+        mock_response = MagicMock()
+        mock_response.json.return_value = {"offers": []}
+        mock_response.status_code = 200
+        mock_response.headers = {"Content-Type": "application/json"}
+        mock_response.raise_for_status = MagicMock()
+        mock_http_post.return_value = mock_response
+
+        args = _make_base_args(
+            query=["gpu_name=RTX_4090"],
+            type="on-demand",
+            raw=True,
+            no_default=False,
+            new=False,
+            limit=None,
+            disable_bundling=False,
+            storage=5.0,
+            order="score-",
+        )
+        vast.search__offers(args)
+
+        mock_http_post.assert_called_once()
+
+
+class TestShowInstances:
+    """Smoke tests for 'show instances' command."""
+
+    @patch('vast.http_get')
+    def test_show_instances_calls_instances_endpoint(self, mock_http_get):
+        """show instances calls /api/v0/instances/ endpoint."""
+        import vast
+
+        mock_response = MagicMock()
+        mock_response.json.return_value = {"instances": []}
+        mock_response.status_code = 200
+        mock_response.raise_for_status = MagicMock()
+        mock_http_get.return_value = mock_response
+
+        args = _make_base_args(raw=True)
+        vast.show__instances(args)
+
+        mock_http_get.assert_called_once()
+        call_url = mock_http_get.call_args[0][1]
+        assert "/api/v0/instances" in call_url
+
+    @patch('vast.http_get')
+    def test_show_instances_returns_list(self, mock_http_get):
+        """show instances handles list response correctly."""
+        import vast
+
+        mock_response = MagicMock()
+        mock_response.json.return_value = {
+            "instances": [
+                {"id": 123, "status": "running", "start_date": 1700000000, "extra_env": []},
+                {"id": 456, "status": "stopped", "start_date": 1700000000, "extra_env": []}
+            ]
+        }
+        mock_response.status_code = 200
+        mock_response.raise_for_status = MagicMock()
+        mock_http_get.return_value = mock_response
+
+        args = _make_base_args(raw=True)
+        result = vast.show__instances(args)
+
+        # In raw mode, should return the data
+        assert result is not None or mock_http_get.called
+
+
+class TestShowMachines:
+    """Smoke tests for 'show machines' command."""
+
+    @patch('vast.api_call')
+    def test_show_machines_calls_machines_endpoint(self, mock_api_call):
+        """show machines calls /api/v0/machines/ endpoint."""
+        import vast
+
+        mock_api_call.return_value = {"machines": []}
+
+        args = _make_base_args(raw=True, quiet=True)
+        vast.show__machines(args)
+
+        mock_api_call.assert_called_once()
+        call_args = mock_api_call.call_args
+        assert call_args[0][1] == "GET"
+        assert "/machines" in call_args[0][2]
+
+
+class TestShowUser:
+    """Smoke tests for 'show user' command."""
+
+    @patch('vast.api_call')
+    def test_show_user_calls_users_endpoint(self, mock_api_call):
+        """show user calls /api/v0/users/current endpoint."""
+        import vast
+
+        mock_api_call.return_value = {"id": 12345, "username": "testuser", "api_key": "secret"}
+
+        args = _make_base_args(raw=True, quiet=True)
+        vast.show__user(args)
+
+        mock_api_call.assert_called_once()
+        call_args = mock_api_call.call_args
+        assert call_args[0][1] == "GET"
+        assert "/users/current" in call_args[0][2]
+
+
+class TestCreateInstance:
+    """Smoke tests for 'create instance' command."""
+
+    @patch('vast.http_put')
+    def test_create_instance_calls_asks_endpoint(self, mock_http_put):
+        """create instance calls /api/v0/asks/{id}/ endpoint."""
+        import vast
+
+        mock_response = MagicMock()
+        mock_response.json.return_value = {"success": True, "new_contract": 789}
+        mock_response.status_code = 200
+        mock_response.raise_for_status = MagicMock()
+        mock_http_put.return_value = mock_response
+
+        args = _make_base_args(
+            id=12345,
+            bid_price=None,
+            disk=20.0,
+            image="pytorch/pytorch:latest",
+            raw=True,
+            onstart=None,
+            onstart_cmd=None,
+            entrypoint=None,
+            env=None,
+            args=None,
+            label=None,
+            extra=None,
+            jupyter=False,
+            jupyter_dir=None,
+            jupyter_lab=False,
+            lang_utf8=False,
+            python_utf8=False,
+            ssh=False,
+            direct=False,
+            cancel_unavail=False,
+            force=False,
+            login=None,
+            template_hash=None,
+            user=None,
+            create_volume=None,
+            link_volume=None,
+        )
+        vast.create__instance(args)
+
+        mock_http_put.assert_called_once()
+        call_url = mock_http_put.call_args[0][1]
+        assert "/api/v0/asks" in call_url
+
+
+class TestDestroyInstance:
+    """Smoke tests for 'destroy instance' command."""
+
+    @patch('vast.http_del')
+    def test_destroy_instance_calls_instances_endpoint(self, mock_http_del):
+        """destroy instance calls DELETE /api/v0/instances/{id}/ endpoint."""
+        import vast
+
+        mock_response = MagicMock()
+        mock_response.json.return_value = {"success": True}
+        mock_response.status_code = 200
+        mock_response.raise_for_status = MagicMock()
+        mock_http_del.return_value = mock_response
+
+        args = _make_base_args(id=12345, raw=True)
+        vast.destroy__instance(args)
+
+        mock_http_del.assert_called_once()
+        call_url = mock_http_del.call_args[0][1]
+        assert "/api/v0/instances" in call_url
+        assert "12345" in call_url
+
+
+class TestLogsCommand:
+    """Smoke tests for 'logs' command."""
+
+    @patch('vast.http_get')
+    @patch('vast.http_put')
+    def test_logs_calls_instances_endpoint(self, mock_http_put, mock_http_get):
+        """logs command calls appropriate endpoint."""
+        import vast
+
+        # Mock the logs request
+        mock_put_response = MagicMock()
+        mock_put_response.json.return_value = {"result_url": "https://example.com/logs"}
+        mock_put_response.status_code = 200
+        mock_put_response.raise_for_status = MagicMock()
+        mock_http_put.return_value = mock_put_response
+
+        # Mock the log fetch
+        mock_get_response = MagicMock()
+        mock_get_response.status_code = 200
+        mock_get_response.text = "Log output here"
+        mock_http_get.return_value = mock_get_response
+
+        args = _make_base_args(
+            INSTANCE_ID=123,
+            raw=True,
+            tail=None,
+            filter=None,
+            daemon_logs=False,
+        )
+
+        # logs may print and not return in non-raw mode
+        vast.logs(args)
+
+        # Should have made HTTP calls
+        assert mock_http_put.called
+
+
+class TestSetApiKey:
+    """Smoke tests for 'set api-key' command."""
+
+    @patch('builtins.open', create=True)
+    @patch('os.path.exists')
+    def test_set_api_key_writes_file(self, mock_exists, mock_open):
+        """set api-key writes key to config file."""
+        import vast
+
+        mock_exists.return_value = False
+        mock_file = MagicMock()
+        mock_open.return_value.__enter__ = MagicMock(return_value=mock_file)
+        mock_open.return_value.__exit__ = MagicMock(return_value=False)
+
+        args = _make_base_args(new_api_key="sk-test-key-12345")
+        vast.set__api_key(args)
+
+        mock_open.assert_called()
+
+
+class TestShowApiKeys:
+    """Smoke tests for 'show api-keys' command."""
+
+    @patch('vast.http_get')
+    def test_show_api_keys_calls_auth_endpoint(self, mock_http_get):
+        """show api-keys calls /api/v0/auth/apikeys/ endpoint."""
+        import vast
+
+        mock_response = MagicMock()
+        mock_response.json.return_value = [{"id": 1, "name": "test-key"}]
+        mock_response.status_code = 200
+        mock_response.raise_for_status = MagicMock()
+        mock_http_get.return_value = mock_response
+
+        args = _make_base_args(raw=True)
+        result = vast.show__api_keys(args)
+
+        mock_http_get.assert_called_once()
+        call_url = mock_http_get.call_args[0][1]
+        assert "/api/v0/auth/apikeys" in call_url
+
+
+class TestParserStructure:
+    """Tests verifying the argparse parser structure."""
+
+    def test_parser_has_subcommands(self):
+        """Parser has expected subcommand structure."""
+        import vast
+
+        # Parser should exist
+        assert hasattr(vast, 'parser')
+
+        # Should be able to parse help
+        with pytest.raises(SystemExit) as exc_info:
+            vast.parser.parse_args(['--help'])
+        assert exc_info.value.code == 0
+
+    def test_search_offers_subcommand_exists(self):
+        """search offers subcommand is registered."""
+        import vast
+
+        # Should not raise - parse_args with --help raises SystemExit(0)
+        with pytest.raises(SystemExit) as exc_info:
+            vast.parser.parse_args(['search', 'offers', '--help'])
+        assert exc_info.value.code == 0
+
+    def test_show_instances_subcommand_exists(self):
+        """show instances subcommand is registered."""
+        import vast
+
+        # Parse minimal args (should work)
+        args = vast.parser.parse_args(['show', 'instances'])
+        assert args is not None
+
+    def test_create_instance_subcommand_exists(self):
+        """create instance subcommand is registered."""
+        import vast
+
+        # Should parse with required args
+        with pytest.raises(SystemExit) as exc_info:
+            vast.parser.parse_args(['create', 'instance', '--help'])
+        assert exc_info.value.code == 0
+
+    def test_destroy_instance_subcommand_exists(self):
+        """destroy instance subcommand is registered."""
+        import vast
+
+        # Should parse with required args
+        with pytest.raises(SystemExit) as exc_info:
+            vast.parser.parse_args(['destroy', 'instance', '--help'])
+        assert exc_info.value.code == 0
+
+    def test_show_user_subcommand_exists(self):
+        """show user subcommand is registered."""
+        import vast
+
+        args = vast.parser.parse_args(['show', 'user'])
+        assert args is not None
+
+    def test_show_machines_subcommand_exists(self):
+        """show machines subcommand is registered."""
+        import vast
+
+        args = vast.parser.parse_args(['show', 'machines'])
+        assert args is not None
+
+    def test_set_api_key_subcommand_exists(self):
+        """set api-key subcommand is registered."""
+        import vast
+
+        with pytest.raises(SystemExit) as exc_info:
+            vast.parser.parse_args(['set', 'api-key', '--help'])
+        assert exc_info.value.code == 0
+
+    def test_logs_subcommand_exists(self):
+        """logs subcommand is registered."""
+        import vast
+
+        with pytest.raises(SystemExit) as exc_info:
+            vast.parser.parse_args(['logs', '--help'])
+        assert exc_info.value.code == 0
+
+    def test_show_api_keys_subcommand_exists(self):
+        """show api-keys subcommand is registered."""
+        import vast
+
+        args = vast.parser.parse_args(['show', 'api-keys'])
+        assert args is not None
diff --git a/tests/smoke/test_standalone.py b/tests/smoke/test_standalone.py
new file mode 100644
index 00000000..918689cd
--- /dev/null
+++ b/tests/smoke/test_standalone.py
@@ -0,0 +1,275 @@
+"""Smoke tests for standalone vast.py execution.
+
+TEST-09: Standalone vast.py smoke test - python vast.py --help works without pip dependencies.
+
+This test verifies that vast.py can be executed as a standalone script
+with only the minimal dependencies (requests, python-dateutil) available.
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+import subprocess
+import pytest
+
+
+# Get the path to vast.py relative to this test file
+VAST_CLI_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))
+VAST_PY_PATH = os.path.join(VAST_CLI_DIR, 'vast.py')
+
+
+class TestStandaloneHelp:
+    """Tests for standalone vast.py --help execution."""
+
+    def test_vast_help_exits_zero(self):
+        """vast.py --help exits with code 0."""
+        result = subprocess.run(
+            [sys.executable, VAST_PY_PATH, '--help'],
+            capture_output=True,
+            text=True,
+            cwd=VAST_CLI_DIR,
+            timeout=30,
+        )
+
+        assert result.returncode == 0, f"Exit code was {result.returncode}, stderr: {result.stderr}"
+
+    def test_vast_help_contains_usage(self):
+        """vast.py --help output contains usage information."""
+        result = subprocess.run(
+            [sys.executable, VAST_PY_PATH, '--help'],
+            capture_output=True,
+            text=True,
+            cwd=VAST_CLI_DIR,
+            timeout=30,
+        )
+
+        assert 'usage' in result.stdout.lower() or 'vast' in result.stdout.lower(), \
+            f"Help output missing expected content: {result.stdout[:500]}"
+
+    def test_vast_help_contains_commands(self):
+        """vast.py --help output lists available commands."""
+        result = subprocess.run(
+            [sys.executable, VAST_PY_PATH, '--help'],
+            capture_output=True,
+            text=True,
+            cwd=VAST_CLI_DIR,
+            timeout=30,
+        )
+
+        # Should mention some key commands
+        output = result.stdout.lower()
+        assert 'search' in output or 'show' in output or 'create' in output, \
+            f"Help output missing command listings: {result.stdout[:500]}"
+
+
+class TestSubcommandHelp:
+    """Tests for subcommand help output."""
+
+    def test_search_offers_help(self):
+        """vast.py search offers --help works."""
+        result = subprocess.run(
+            [sys.executable, VAST_PY_PATH, 'search', 'offers', '--help'],
+            capture_output=True,
+            text=True,
+            cwd=VAST_CLI_DIR,
+            timeout=30,
+        )
+
+        assert result.returncode == 0, f"Exit code was {result.returncode}, stderr: {result.stderr}"
+        assert 'search' in result.stdout.lower() or 'offers' in result.stdout.lower()
+
+    def test_show_instances_help(self):
+        """vast.py show instances --help works."""
+        result = subprocess.run(
+            [sys.executable, VAST_PY_PATH, 'show', 'instances', '--help'],
+            capture_output=True,
+            text=True,
+            cwd=VAST_CLI_DIR,
+            timeout=30,
+        )
+
+        assert result.returncode == 0, f"Exit code was {result.returncode}, stderr: {result.stderr}"
+
+    def test_create_instance_help(self):
+        """vast.py create instance --help works."""
+        result = subprocess.run(
+            [sys.executable, VAST_PY_PATH, 'create', 'instance', '--help'],
+            capture_output=True,
+            text=True,
+            cwd=VAST_CLI_DIR,
+            timeout=30,
+        )
+
+        assert result.returncode == 0, f"Exit code was {result.returncode}, stderr: {result.stderr}"
+
+    def test_destroy_instance_help(self):
+        """vast.py destroy instance --help works."""
+        result = subprocess.run(
+            [sys.executable, VAST_PY_PATH, 'destroy', 'instance', '--help'],
+            capture_output=True,
+            text=True,
+            cwd=VAST_CLI_DIR,
+            timeout=30,
+        )
+
+        assert result.returncode == 0, f"Exit code was {result.returncode}, stderr: {result.stderr}"
+
+
+class TestVersionFlag:
+    """Tests for version flag if implemented."""
+
+    def test_vast_version_or_help(self):
+        """vast.py responds to --version or --help without error."""
+        # Try --version first
+        result = subprocess.run(
+            [sys.executable, VAST_PY_PATH, '--version'],
+            capture_output=True,
+            text=True,
+            cwd=VAST_CLI_DIR,
+            timeout=30,
+        )
+
+        # If --version isn't implemented, that's okay - just verify it doesn't crash
+        # (might return non-zero for unrecognized flag, but shouldn't hang or throw)
+        assert result.returncode in [0, 1, 2], \
+            f"Unexpected exit code {result.returncode}, stderr: {result.stderr}"
+
+
+class TestInvalidCommand:
+    """Tests for invalid command handling."""
+
+    def test_invalid_command_exits_nonzero(self):
+        """vast.py with invalid command exits with non-zero code."""
+        result = subprocess.run(
+            [sys.executable, VAST_PY_PATH, 'not_a_real_command'],
+            capture_output=True,
+            text=True,
+            cwd=VAST_CLI_DIR,
+            timeout=30,
+        )
+
+        # Should exit non-zero for invalid command
+        assert result.returncode != 0, "Invalid command should exit non-zero"
+
+    def test_invalid_command_prints_error(self):
+        """vast.py with invalid command prints error message."""
+        result = subprocess.run(
+            [sys.executable, VAST_PY_PATH, 'not_a_real_command'],
+            capture_output=True,
+            text=True,
+            cwd=VAST_CLI_DIR,
+            timeout=30,
+        )
+
+        # Should have some error output
+        combined_output = result.stdout + result.stderr
+        assert len(combined_output) > 0, "Should produce some output for invalid command"
+
+
+class TestImportOnly:
+    """Tests that verify vast.py can be imported without side effects."""
+
+    def test_vast_importable(self):
+        """vast.py is importable as a module."""
+        # This runs in the test process, verifying import works
+        import vast
+
+        assert hasattr(vast, 'parser')
+        assert hasattr(vast, 'main')
+
+    def test_vast_main_exists(self):
+        """vast.main() function exists."""
+        import vast
+
+        assert callable(vast.main)
+
+    def test_vast_has_core_functions(self):
+        """vast module has core CLI functions."""
+        import vast
+
+        # Check for key command functions
+        assert hasattr(vast, 'search__offers')
+        assert hasattr(vast, 'show__instances')
+        assert hasattr(vast, 'create__instance')
+        assert hasattr(vast, 'destroy__instance')
+
+    def test_vast_has_http_helpers(self):
+        """vast module has HTTP helper functions."""
+        import vast
+
+        assert hasattr(vast, 'http_get')
+        assert hasattr(vast, 'http_post')
+        assert hasattr(vast, 'http_put')
+        assert hasattr(vast, 'http_del')
+
+
+class TestMinimalDependencies:
+    """Tests verifying vast.py works with minimal dependencies."""
+
+    def test_import_only_requires_requests(self):
+        """vast.py import only requires requests (and python-dateutil)."""
+        # Run a subprocess that only has requests available
+        # This is tested implicitly by the fact that we can import vast
+        # without extra dependencies installed
+        result = subprocess.run(
+            [sys.executable, '-c', 'import vast; print("OK")'],
+            capture_output=True,
+            text=True,
+            cwd=VAST_CLI_DIR,
+            timeout=30,
+        )
+
+        assert result.returncode == 0, f"Import failed: {result.stderr}"
+        assert "OK" in result.stdout
+
+    def test_help_runs_without_optional_deps(self):
+        """vast.py --help works even if optional dependencies are missing."""
+        # argcomplete and curlify are optional
+        # This test verifies help still works
+        result = subprocess.run(
+            [sys.executable, VAST_PY_PATH, '--help'],
+            capture_output=True,
+            text=True,
+            cwd=VAST_CLI_DIR,
+            timeout=30,
+        )
+
+        assert result.returncode == 0
+
+
+class TestExitCodes:
+    """Tests for proper exit codes."""
+
+    def test_help_exits_zero(self):
+        """--help exits with code 0."""
+        result = subprocess.run(
+            [sys.executable, VAST_PY_PATH, '--help'],
+            capture_output=True,
+            text=True,
+            cwd=VAST_CLI_DIR,
+            timeout=30,
+        )
+        assert result.returncode == 0
+
+    def test_subcommand_help_exits_zero(self):
+        """Subcommand --help exits with code 0."""
+        result = subprocess.run(
+            [sys.executable, VAST_PY_PATH, 'show', 'instances', '--help'],
+            capture_output=True,
+            text=True,
+            cwd=VAST_CLI_DIR,
+            timeout=30,
+        )
+        assert result.returncode == 0
+
+    def test_missing_required_arg_exits_nonzero(self):
+        """Missing required argument exits with non-zero code."""
+        # create instance requires an ID
+        result = subprocess.run(
+            [sys.executable, VAST_PY_PATH, 'create', 'instance'],
+            capture_output=True,
+            text=True,
+            cwd=VAST_CLI_DIR,
+            timeout=30,
+        )
+        assert result.returncode != 0
diff --git a/tests/unit/__init__.py b/tests/unit/__init__.py
new file mode 100644
index 00000000..8ff8dac6
--- /dev/null
+++ b/tests/unit/__init__.py
@@ -0,0 +1 @@
+"""Unit tests for vast.py helper functions."""
diff --git a/tests/unit/test_http_helpers.py b/tests/unit/test_http_helpers.py
new file mode 100644
index 00000000..3441f628
--- /dev/null
+++ b/tests/unit/test_http_helpers.py
@@ -0,0 +1,267 @@
+"""Unit tests for HTTP helper functions (api_call, http_*, retry logic).
+
+TEST-02: Unit tests for HTTP helper functions with mocked responses.
+
+These tests verify the helper functions in isolation, complementing the
+regression tests that focus on specific bug fixes.
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+import argparse
+import json
+import pytest
+from unittest.mock import MagicMock, patch, call
+from requests.exceptions import ConnectionError, Timeout, HTTPError
+
+
+def _make_args(retry=3, raw=False, explain=False, curl=False):
+    """Create minimal args namespace for testing."""
+    return argparse.Namespace(
+        api_key="test-key",
+        url="https://console.vast.ai",
+        retry=retry,
+        raw=raw,
+        explain=explain,
+        quiet=False,
+        curl=curl,
+    )
+
+
+class TestApiCall:
+    """Tests for the api_call() helper function."""
+
+    @patch('vast.http_get')
+    def test_api_call_get_request(self, mock_http_get):
+        """api_call makes GET request and returns parsed JSON."""
+        from vast import api_call
+
+        mock_response = MagicMock()
+        mock_response.json.return_value = {"offers": [{"id": 1}]}
+        mock_http_get.return_value = mock_response
+
+        args = _make_args()
+        # api_call signature: api_call(args, method, path, *, json_body=None, query_args=None)
+        result = api_call(args, "GET", "/api/v0/bundles")
+
+        assert result == {"offers": [{"id": 1}]}
+        mock_http_get.assert_called_once()
+
+    @patch('vast.http_post')
+    def test_api_call_post_request(self, mock_http_post):
+        """api_call makes POST request with JSON body."""
+        from vast import api_call
+
+        mock_response = MagicMock()
+        mock_response.json.return_value = {"success": True}
+        mock_http_post.return_value = mock_response
+
+        args = _make_args()
+        # api_call signature: api_call(args, method, path, *, json_body=None, query_args=None)
+        result = api_call(args, "POST", "/api/v0/instances/123/", json_body={"action": "start"})
+
+        assert result == {"success": True}
+        mock_http_post.assert_called_once()
+
+    @patch('vast.http_get')
+    def test_api_call_handles_http_error(self, mock_http_get):
+        """api_call propagates HTTPError from response."""
+        from vast import api_call
+
+        mock_response = MagicMock()
+        mock_response.raise_for_status.side_effect = HTTPError("404 Not Found")
+        mock_http_get.return_value = mock_response
+
+        args = _make_args()
+        with pytest.raises(HTTPError):
+            # api_call signature: api_call(args, method, path, *, json_body=None, query_args=None)
+            api_call(args, "GET", "/api/v0/nonexistent")
+
+
+class TestHttpHelpers:
+    """Tests for http_get, http_post, http_put, http_del functions."""
+
+    @patch('vast.http_request')
+    def test_http_get_constructs_correct_request(self, mock_http_request):
+        """http_get passes correct method and URL to http_request."""
+        from vast import http_get
+
+        mock_http_request.return_value = MagicMock(status_code=200)
+        args = _make_args()
+
+        http_get(args, "https://example.com/api/test")
+
+        mock_http_request.assert_called_once()
+        call_args = mock_http_request.call_args
+        assert call_args[0][0] == "GET"  # method
+        assert call_args[0][2] == "https://example.com/api/test"  # url
+
+    @patch('vast.http_request')
+    def test_http_post_sends_json_body(self, mock_http_request):
+        """http_post includes JSON body in request."""
+        from vast import http_post
+
+        mock_http_request.return_value = MagicMock(status_code=200)
+        args = _make_args()
+        body = {"key": "value"}
+
+        # http_post signature: http_post(args, req_url, headers=None, json=None, timeout=DEFAULT_TIMEOUT)
+        http_post(args, "https://example.com/api/test", json=body)
+
+        # http_request is called as: http_request('POST', args, req_url, headers, json, timeout=timeout)
+        # json is passed as positional arg at index 4
+        call_args = mock_http_request.call_args[0]
+        assert call_args[4] == body  # json is 5th positional arg (index 4)
+
+    @patch('vast.http_request')
+    def test_http_put_sends_json_body(self, mock_http_request):
+        """http_put includes JSON body in request."""
+        from vast import http_put
+
+        mock_http_request.return_value = MagicMock(status_code=200)
+        args = _make_args()
+        body = {"update": "data"}
+
+        # http_put signature: http_put(args, req_url, headers=None, json=None, timeout=DEFAULT_TIMEOUT)
+        http_put(args, "https://example.com/api/test", json=body)
+
+        # http_request is called as: http_request('PUT', args, req_url, headers, json, timeout=timeout)
+        # json is passed as positional arg at index 4
+        call_args = mock_http_request.call_args[0]
+        assert call_args[4] == body  # json is 5th positional arg (index 4)
+
+    @patch('vast.http_request')
+    def test_http_del_makes_delete_request(self, mock_http_request):
+        """http_del uses DELETE method."""
+        from vast import http_del
+
+        mock_http_request.return_value = MagicMock(status_code=200)
+        args = _make_args()
+
+        http_del(args, "https://example.com/api/resource/123")
+
+        call_args = mock_http_request.call_args
+        assert call_args[0][0] == "DELETE"
+
+
+class TestHttpRequestRetry:
+    """Tests for retry logic in http_request."""
+
+    @patch('vast.time.sleep')
+    @patch('vast.requests.Session')
+    def test_retry_on_connection_error(self, mock_session_cls, mock_sleep):
+        """http_request retries on ConnectionError."""
+        from vast import http_request
+
+        mock_session = MagicMock()
+        mock_session_cls.return_value = mock_session
+
+        # First call fails, second succeeds
+        success_response = MagicMock(status_code=200)
+        mock_session.send.side_effect = [
+            ConnectionError("Connection refused"),
+            success_response
+        ]
+        mock_session.prepare_request.return_value = MagicMock()
+
+        args = _make_args(retry=3)
+        with patch('vast.ARGS', args):
+            result = http_request('GET', args, 'http://example.com/test')
+
+        assert result.status_code == 200
+        assert mock_session.send.call_count == 2
+
+    @patch('vast.time.sleep')
+    @patch('vast.requests.Session')
+    def test_retry_on_timeout(self, mock_session_cls, mock_sleep):
+        """http_request retries on Timeout."""
+        from vast import http_request
+
+        mock_session = MagicMock()
+        mock_session_cls.return_value = mock_session
+
+        success_response = MagicMock(status_code=200)
+        mock_session.send.side_effect = [
+            Timeout("Request timed out"),
+            success_response
+        ]
+        mock_session.prepare_request.return_value = MagicMock()
+
+        args = _make_args(retry=3)
+        with patch('vast.ARGS', args):
+            result = http_request('GET', args, 'http://example.com/test')
+
+        assert result.status_code == 200
+        assert mock_session.send.call_count == 2
+
+    @patch('vast.time.sleep')
+    @patch('vast.requests.Session')
+    def test_retry_on_503_status(self, mock_session_cls, mock_sleep):
+        """http_request retries on 503 Service Unavailable."""
+        from vast import http_request, RETRYABLE_STATUS_CODES
+
+        mock_session = MagicMock()
+        mock_session_cls.return_value = mock_session
+
+        error_response = MagicMock(status_code=503)
+        success_response = MagicMock(status_code=200)
+        mock_session.send.side_effect = [error_response, success_response]
+        mock_session.prepare_request.return_value = MagicMock()
+
+        assert 503 in RETRYABLE_STATUS_CODES
+
+        args = _make_args(retry=3)
+        with patch('vast.ARGS', args):
+            result = http_request('GET', args, 'http://example.com/test')
+
+        assert result.status_code == 200
+        assert mock_session.send.call_count == 2
+
+    @patch('vast.time.sleep')
+    @patch('vast.requests.Session')
+    def test_no_retry_on_400_status(self, mock_session_cls, mock_sleep):
+        """http_request does not retry on 400 Bad Request."""
+        from vast import http_request
+
+        mock_session = MagicMock()
+        mock_session_cls.return_value = mock_session
+
+        error_response = MagicMock(status_code=400)
+        mock_session.send.return_value = error_response
+        mock_session.prepare_request.return_value = MagicMock()
+
+        args = _make_args(retry=3)
+        with patch('vast.ARGS', args):
+            result = http_request('GET', args, 'http://example.com/test')
+
+        assert result.status_code == 400
+        assert mock_session.send.call_count == 1  # No retry
+
+
+class TestTimeoutConstants:
+    """Tests for timeout constant values."""
+
+    def test_default_timeout_defined(self):
+        """DEFAULT_TIMEOUT constant is defined and reasonable."""
+        from vast import DEFAULT_TIMEOUT
+
+        assert DEFAULT_TIMEOUT == 30
+        assert isinstance(DEFAULT_TIMEOUT, (int, float))
+
+    def test_long_timeout_defined(self):
+        """LONG_TIMEOUT constant is defined for file operations."""
+        from vast import LONG_TIMEOUT
+
+        assert LONG_TIMEOUT == 120
+        assert LONG_TIMEOUT > 30  # Should be longer than default
+
+    def test_retryable_status_codes_defined(self):
+        """RETRYABLE_STATUS_CODES contains expected HTTP statuses."""
+        from vast import RETRYABLE_STATUS_CODES
+
+        assert 429 in RETRYABLE_STATUS_CODES  # Too Many Requests
+        assert 502 in RETRYABLE_STATUS_CODES  # Bad Gateway
+        assert 503 in RETRYABLE_STATUS_CODES  # Service Unavailable
+        assert 504 in RETRYABLE_STATUS_CODES  # Gateway Timeout
+        assert 500 not in RETRYABLE_STATUS_CODES  # 500 not retried (may have side effects)
diff --git a/tests/unit/test_query_parser.py b/tests/unit/test_query_parser.py
new file mode 100644
index 00000000..2fe89948
--- /dev/null
+++ b/tests/unit/test_query_parser.py
@@ -0,0 +1,160 @@
+"""Unit tests for query parsing functions (parse_query, field aliases).
+
+TEST-04: Unit tests for query parsing.
+
+These tests verify the query parser handles field names, operators,
+aliases, and various query formats correctly.
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+import pytest
+
+
+class TestParseQuery:
+    """Tests for parse_query() function."""
+
+    def test_simple_equality(self):
+        """Simple equality operator parses correctly."""
+        from vast import parse_query, offers_fields, offers_alias
+
+        result = parse_query("gpu_ram=8", {}, offers_fields, offers_alias)
+
+        assert 'gpu_ram' in result
+        assert result['gpu_ram']['eq'] == '8'
+
+    def test_greater_than_or_equal(self):
+        """Greater-than-or-equal operator parses correctly."""
+        from vast import parse_query, offers_fields, offers_alias
+
+        result = parse_query("gpu_ram>=16", {}, offers_fields, offers_alias)
+
+        assert 'gpu_ram' in result
+        assert 'gte' in result['gpu_ram']
+        assert result['gpu_ram']['gte'] == '16'
+
+    def test_less_than_or_equal(self):
+        """Less-than-or-equal operator parses correctly."""
+        from vast import parse_query, offers_fields, offers_alias
+
+        result = parse_query("gpu_ram<=32", {}, offers_fields, offers_alias)
+
+        assert 'gpu_ram' in result
+        assert 'lte' in result['gpu_ram']
+        assert result['gpu_ram']['lte'] == '32'
+
+    def test_multiple_conditions(self):
+        """Multiple space-separated conditions parse correctly."""
+        from vast import parse_query, offers_fields, offers_alias
+
+        result = parse_query("gpu_ram>=8 num_gpus>=2", {}, offers_fields, offers_alias)
+
+        assert 'gpu_ram' in result
+        assert 'num_gpus' in result
+
+
+class TestFieldAliases:
+    """Tests for field alias handling in parse_query."""
+
+    def test_cuda_vers_alias(self):
+        """cuda_vers is aliased to cuda_max_good."""
+        from vast import parse_query, offers_fields, offers_alias
+
+        result = parse_query("cuda_vers>=12.0", {}, offers_fields, offers_alias)
+
+        # After alias resolution, cuda_vers should become cuda_max_good
+        assert 'cuda_max_good' in result
+        assert 'cuda_vers' not in result
+        assert 'gte' in result['cuda_max_good']
+
+    def test_alias_resolution_preserves_value(self):
+        """Alias resolution preserves the comparison value."""
+        from vast import parse_query, offers_fields, offers_alias
+
+        result = parse_query("cuda_vers>=11.8", {}, offers_fields, offers_alias)
+
+        assert result['cuda_max_good']['gte'] == '11.8'
+
+
+class TestOfferFieldsDefinition:
+    """Tests verifying offers_fields contains expected fields."""
+
+    def test_gpu_ram_field_exists(self):
+        """gpu_ram is a valid offer field."""
+        from vast import offers_fields
+
+        assert 'gpu_ram' in offers_fields
+
+    def test_num_gpus_field_exists(self):
+        """num_gpus is a valid offer field."""
+        from vast import offers_fields
+
+        assert 'num_gpus' in offers_fields
+
+    def test_cuda_max_good_field_exists(self):
+        """cuda_max_good is a valid offer field."""
+        from vast import offers_fields
+
+        assert 'cuda_max_good' in offers_fields
+
+    def test_dph_total_field_exists(self):
+        """dph_total (price) is a valid offer field."""
+        from vast import offers_fields
+
+        assert 'dph_total' in offers_fields
+
+
+class TestQueryEdgeCases:
+    """Tests for edge cases in query parsing."""
+
+    def test_empty_query(self):
+        """Empty query returns empty result."""
+        from vast import parse_query, offers_fields, offers_alias
+
+        result = parse_query("", {}, offers_fields, offers_alias)
+
+        assert result == {} or result is not None
+
+    def test_whitespace_handling(self):
+        """Whitespace around operators is handled."""
+        from vast import parse_query, offers_fields, offers_alias
+
+        # Query with extra whitespace should still parse
+        result = parse_query("gpu_ram >= 8", {}, offers_fields, offers_alias)
+
+        # Should have gpu_ram field with gte constraint
+        assert 'gpu_ram' in result
+
+    def test_decimal_values(self):
+        """Decimal values in queries parse correctly."""
+        from vast import parse_query, offers_fields, offers_alias
+
+        result = parse_query("dph_total<=0.5", {}, offers_fields, offers_alias)
+
+        assert 'dph_total' in result
+        assert result['dph_total']['lte'] == '0.5'
+
+
+class TestOfferAliasDefinition:
+    """Tests for offer field alias definitions."""
+
+    def test_offers_alias_is_dict(self):
+        """offers_alias is a dictionary."""
+        from vast import offers_alias
+
+        assert isinstance(offers_alias, dict)
+
+    def test_cuda_vers_alias_defined(self):
+        """cuda_vers -> cuda_max_good alias is defined."""
+        from vast import offers_alias
+
+        assert 'cuda_vers' in offers_alias
+        assert offers_alias['cuda_vers'] == 'cuda_max_good'
+
+    def test_dph_alias_defined(self):
+        """dph -> dph_total alias is defined."""
+        from vast import offers_alias
+
+        assert 'dph' in offers_alias
+        assert offers_alias['dph'] == 'dph_total'
diff --git a/tests/unit/test_serverless_client.py b/tests/unit/test_serverless_client.py
new file mode 100644
index 00000000..75c89051
--- /dev/null
+++ b/tests/unit/test_serverless_client.py
@@ -0,0 +1,257 @@
+"""Unit tests for vastai.serverless.client.client module.
+
+Tests for ServerlessRequest and Serverless class instantiation/configuration.
+These tests focus on synchronous initialization code that does NOT require
+actual network calls or async execution.
+"""
+
+import pytest
+import asyncio
+from unittest.mock import MagicMock, patch, PropertyMock
+import sys
+import time
+import logging
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from vastai.serverless.client.client import Serverless, ServerlessRequest
+
+
+@pytest.fixture
+def event_loop_for_request():
+    """Create an event loop for ServerlessRequest tests (Future requires event loop)."""
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    yield loop
+    loop.close()
+    asyncio.set_event_loop(None)
+
+
+class TestServerlessRequest:
+    """Tests for ServerlessRequest class."""
+
+    def test_init_defaults(self, event_loop_for_request):
+        """Test ServerlessRequest initializes with expected defaults."""
+        before_time = time.time()
+        req = ServerlessRequest()
+        after_time = time.time()
+
+        assert req.status == "New"
+        assert req.start_time is None
+        assert req.complete_time is None
+        assert req.req_idx == 0
+        # create_time should be between before and after test execution
+        assert before_time <= req.create_time <= after_time
+
+    def test_init_status_is_new(self, event_loop_for_request):
+        """Test that initial status is always 'New'."""
+        req = ServerlessRequest()
+        assert req.status == "New"
+
+    def test_then_returns_self(self, event_loop_for_request):
+        """Test that then() method returns self for chaining."""
+        req = ServerlessRequest()
+        callback = MagicMock()
+        result = req.then(callback)
+        assert result is req
+
+    def test_then_callback_called_on_result(self, event_loop_for_request):
+        """Test that callback is called when result is set."""
+        req = ServerlessRequest()
+        callback = MagicMock()
+        req.then(callback)
+
+        test_data = {"test": "data", "value": 123}
+        req.set_result(test_data)
+        # Run pending callbacks
+        event_loop_for_request.run_until_complete(asyncio.sleep(0))
+
+        callback.assert_called_once_with(test_data)
+
+    def test_then_callback_not_called_on_exception(self, event_loop_for_request):
+        """Test that callback is NOT called when exception is set."""
+        req = ServerlessRequest()
+        callback = MagicMock()
+        req.then(callback)
+
+        # Set exception instead of result
+        req.set_exception(ValueError("test error"))
+        # Run pending callbacks
+        event_loop_for_request.run_until_complete(asyncio.sleep(0))
+
+        # Callback should not be called for exceptions
+        callback.assert_not_called()
+
+    def test_multiple_then_callbacks(self, event_loop_for_request):
+        """Test that multiple callbacks can be chained."""
+        req = ServerlessRequest()
+        callback1 = MagicMock()
+        callback2 = MagicMock()
+
+        req.then(callback1).then(callback2)
+
+        test_data = {"result": "success"}
+        req.set_result(test_data)
+        # Run pending callbacks
+        event_loop_for_request.run_until_complete(asyncio.sleep(0))
+
+        callback1.assert_called_once_with(test_data)
+        callback2.assert_called_once_with(test_data)
+
+
+class TestServerlessInit:
+    """Tests for Serverless class __init__ method."""
+
+    def test_raises_on_none_api_key(self):
+        """Test that None api_key raises AttributeError."""
+        with pytest.raises(AttributeError, match="API key missing"):
+            Serverless(api_key=None)
+
+    def test_raises_on_empty_api_key(self):
+        """Test that empty string api_key raises AttributeError."""
+        with pytest.raises(AttributeError, match="API key missing"):
+            Serverless(api_key="")
+
+    def test_valid_api_key_stored(self):
+        """Test that valid api_key is stored correctly."""
+        client = Serverless(api_key="test_api_key_123")
+        assert client.api_key == "test_api_key_123"
+
+    def test_prod_instance_url(self):
+        """Test instance='prod' sets autoscaler_url to production URL."""
+        client = Serverless(api_key="test_key", instance="prod")
+        assert client.autoscaler_url == "https://run.vast.ai"
+
+    def test_alpha_instance_url(self):
+        """Test instance='alpha' sets autoscaler_url to alpha URL."""
+        client = Serverless(api_key="test_key", instance="alpha")
+        assert client.autoscaler_url == "https://run-alpha.vast.ai"
+
+    def test_local_instance_url(self):
+        """Test instance='local' sets autoscaler_url to localhost."""
+        client = Serverless(api_key="test_key", instance="local")
+        assert client.autoscaler_url == "http://localhost:8080"
+
+    def test_unknown_instance_defaults_to_prod(self):
+        """Test that unknown instance value defaults to production URL."""
+        client = Serverless(api_key="test_key", instance="unknown_value")
+        assert client.autoscaler_url == "https://run.vast.ai"
+
+    def test_connection_limit_stored(self):
+        """Test that connection_limit is stored correctly."""
+        client = Serverless(api_key="test_key", connection_limit=100)
+        assert client.connection_limit == 100
+
+    def test_default_connection_limit(self):
+        """Test default connection_limit value."""
+        client = Serverless(api_key="test_key")
+        assert client.connection_limit == 500
+
+    def test_default_request_timeout_stored_as_float(self):
+        """Test that default_request_timeout is stored as float."""
+        client = Serverless(api_key="test_key", default_request_timeout=120)
+        assert client.default_request_timeout == 120.0
+        assert isinstance(client.default_request_timeout, float)
+
+    def test_max_poll_interval_stored_as_float(self):
+        """Test that max_poll_interval is stored as float."""
+        client = Serverless(api_key="test_key", max_poll_interval=30)
+        assert client.max_poll_interval == 30.0
+        assert isinstance(client.max_poll_interval, float)
+
+    def test_debug_true_sets_logger_level(self):
+        """Test debug=True sets logger to DEBUG level."""
+        client = Serverless(api_key="test_key", debug=True)
+        assert client.logger.level == logging.DEBUG
+
+    def test_debug_false_uses_null_handler(self):
+        """Test debug=False adds NullHandler (no output)."""
+        client = Serverless(api_key="test_key", debug=False)
+        # Logger should have handlers, and at least one should be NullHandler
+        handlers = client.logger.handlers
+        assert any(isinstance(h, logging.NullHandler) for h in handlers)
+
+    def test_session_initially_none(self):
+        """Test that _session is None after initialization."""
+        client = Serverless(api_key="test_key")
+        assert client._session is None
+
+    def test_ssl_context_initially_none(self):
+        """Test that _ssl_context is None after initialization."""
+        client = Serverless(api_key="test_key")
+        assert client._ssl_context is None
+
+
+class TestServerlessIsOpen:
+    """Tests for Serverless.is_open() method."""
+
+    def test_returns_false_when_session_is_none(self):
+        """Test is_open() returns False when _session is None."""
+        client = Serverless(api_key="test_key")
+        assert client._session is None
+        assert client.is_open() is False
+
+    def test_returns_true_when_session_open(self):
+        """Test is_open() returns True when session exists and not closed."""
+        client = Serverless(api_key="test_key")
+
+        # Create a mock session that is not closed
+        mock_session = MagicMock()
+        mock_session.closed = False
+        client._session = mock_session
+
+        assert client.is_open() is True
+
+    def test_returns_false_when_session_closed(self):
+        """Test is_open() returns False when session is closed."""
+        client = Serverless(api_key="test_key")
+
+        # Create a mock session that IS closed
+        mock_session = MagicMock()
+        mock_session.closed = True
+        client._session = mock_session
+
+        assert client.is_open() is False
+
+
+class TestServerlessGetAvgRequestTime:
+    """Tests for Serverless.get_avg_request_time() method."""
+
+    def test_returns_60_hardcoded(self):
+        """Test get_avg_request_time() returns 60.0 (hardcoded value)."""
+        client = Serverless(api_key="test_key")
+        result = client.get_avg_request_time()
+        assert result == 60.0
+        assert isinstance(result, float)
+
+
+class TestServerlessConstants:
+    """Tests for Serverless class constants."""
+
+    def test_ssl_cert_url(self):
+        """Test SSL_CERT_URL constant value."""
+        assert Serverless.SSL_CERT_URL == "https://console.vast.ai/static/jvastai_root.cer"
+
+    def test_vast_web_url(self):
+        """Test VAST_WEB_URL constant value."""
+        assert Serverless.VAST_WEB_URL == "https://console.vast.ai"
+
+    def test_vast_serverless_url(self):
+        """Test VAST_SERVERLESS_URL constant value."""
+        assert Serverless.VAST_SERVERLESS_URL == "https://run.vast.ai"
+
+
+class TestServerlessLatencies:
+    """Tests for latencies deque initialization."""
+
+    def test_latencies_initialized_empty(self):
+        """Test that latencies deque is empty after init."""
+        client = Serverless(api_key="test_key")
+        assert len(client.latencies) == 0
+
+    def test_latencies_maxlen_is_50(self):
+        """Test that latencies deque has maxlen of 50."""
+        client = Serverless(api_key="test_key")
+        assert client.latencies.maxlen == 50
diff --git a/tests/unit/test_serverless_connection.py b/tests/unit/test_serverless_connection.py
new file mode 100644
index 00000000..9f3f34ab
--- /dev/null
+++ b/tests/unit/test_serverless_connection.py
@@ -0,0 +1,284 @@
+"""Unit tests for vastai.serverless.client.connection module helper functions.
+
+Tests cover:
+- _retryable: status code retry determination
+- _backoff_delay: exponential backoff with jitter calculation
+- _build_kwargs: HTTP request argument construction
+"""
+import pytest
+from unittest.mock import MagicMock, patch
+import sys
+from pathlib import Path
+
+# Add vast-cli to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from vastai.serverless.client.connection import (
+    _retryable,
+    _backoff_delay,
+    _build_kwargs,
+    _JITTER_CAP_SECONDS,
+)
+
+
+class TestRetryable:
+    """Tests for _retryable() function."""
+
+    def test_retryable_408_request_timeout(self):
+        """408 Request Timeout is retryable."""
+        assert _retryable(408) is True
+
+    def test_retryable_429_too_many_requests(self):
+        """429 Too Many Requests is retryable."""
+        assert _retryable(429) is True
+
+    def test_retryable_500_internal_server_error(self):
+        """500 Internal Server Error is retryable."""
+        assert _retryable(500) is True
+
+    def test_retryable_501_not_implemented(self):
+        """501 Not Implemented is retryable (5xx range)."""
+        assert _retryable(501) is True
+
+    def test_retryable_502_bad_gateway(self):
+        """502 Bad Gateway is retryable."""
+        assert _retryable(502) is True
+
+    def test_retryable_503_service_unavailable(self):
+        """503 Service Unavailable is retryable."""
+        assert _retryable(503) is True
+
+    def test_retryable_504_gateway_timeout(self):
+        """504 Gateway Timeout is retryable."""
+        assert _retryable(504) is True
+
+    def test_retryable_599_max_5xx(self):
+        """599 (max 5xx) is retryable."""
+        assert _retryable(599) is True
+
+    def test_not_retryable_200_ok(self):
+        """200 OK is not retryable."""
+        assert _retryable(200) is False
+
+    def test_not_retryable_201_created(self):
+        """201 Created is not retryable."""
+        assert _retryable(201) is False
+
+    def test_not_retryable_400_bad_request(self):
+        """400 Bad Request is not retryable."""
+        assert _retryable(400) is False
+
+    def test_not_retryable_401_unauthorized(self):
+        """401 Unauthorized is not retryable."""
+        assert _retryable(401) is False
+
+    def test_not_retryable_403_forbidden(self):
+        """403 Forbidden is not retryable."""
+        assert _retryable(403) is False
+
+    def test_not_retryable_404_not_found(self):
+        """404 Not Found is not retryable."""
+        assert _retryable(404) is False
+
+    def test_not_retryable_600_boundary(self):
+        """600 is not retryable (beyond 5xx range)."""
+        assert _retryable(600) is False
+
+
+class TestBackoffDelay:
+    """Tests for _backoff_delay() function."""
+
+    def test_backoff_attempt_1(self):
+        """Attempt 1 returns delay between 2.0 and 3.0."""
+        delay = _backoff_delay(1)
+        # 2^1 + random.uniform(0, 1) = 2.0 to 3.0
+        assert 2.0 <= delay <= 3.0
+
+    def test_backoff_attempt_2(self):
+        """Attempt 2 returns delay between 4.0 and 5.0."""
+        delay = _backoff_delay(2)
+        # 2^2 + random.uniform(0, 1) = 4.0 to 5.0 (capped at 5.0)
+        assert 4.0 <= delay <= 5.0
+
+    def test_backoff_capped_at_jitter_cap(self):
+        """Large attempts are capped at _JITTER_CAP_SECONDS (5.0)."""
+        delay = _backoff_delay(10)  # 2^10 = 1024 >> 5
+        assert delay <= _JITTER_CAP_SECONDS
+        assert delay <= 5.0
+
+    def test_backoff_attempt_0(self):
+        """Attempt 0 returns delay between 1.0 and 2.0."""
+        delay = _backoff_delay(0)
+        # 2^0 + random.uniform(0, 1) = 1.0 to 2.0
+        assert 1.0 <= delay <= 2.0
+
+    def test_backoff_always_positive(self):
+        """All backoff delays are positive."""
+        for attempt in range(10):
+            delay = _backoff_delay(attempt)
+            assert delay > 0
+
+    @patch('vastai.serverless.client.connection.random.uniform')
+    def test_backoff_uses_random_uniform(self, mock_uniform):
+        """_backoff_delay uses random.uniform for jitter."""
+        mock_uniform.return_value = 0.5
+        delay = _backoff_delay(1)
+        # 2^1 + 0.5 = 2.5 (not capped)
+        assert delay == 2.5
+        mock_uniform.assert_called_once_with(0, 1)
+
+
+class TestBuildKwargs:
+    """Tests for _build_kwargs() function."""
+
+    def test_includes_body_for_post(self):
+        """_build_kwargs includes json body for POST requests."""
+        result = _build_kwargs(
+            headers={"Authorization": "Bearer test"},
+            params={"key": "val"},
+            ssl_context=None,
+            timeout=30,
+            body={"data": "test"},
+            method="POST",
+            stream=False,
+        )
+        assert "json" in result
+        assert result["json"] == {"data": "test"}
+
+    def test_includes_body_for_put(self):
+        """_build_kwargs includes json body for PUT requests."""
+        result = _build_kwargs(
+            headers={},
+            params={},
+            ssl_context=None,
+            timeout=30,
+            body={"data": "update"},
+            method="PUT",
+            stream=False,
+        )
+        assert "json" in result
+        assert result["json"] == {"data": "update"}
+
+    def test_includes_body_for_delete(self):
+        """_build_kwargs includes json body for DELETE requests."""
+        result = _build_kwargs(
+            headers={},
+            params={},
+            ssl_context=None,
+            timeout=30,
+            body={"id": 123},
+            method="DELETE",
+            stream=False,
+        )
+        assert "json" in result
+        assert result["json"] == {"id": 123}
+
+    def test_excludes_body_for_get(self):
+        """_build_kwargs excludes body for GET requests."""
+        result = _build_kwargs(
+            headers={},
+            params={},
+            ssl_context=None,
+            timeout=30,
+            body={"data": "test"},
+            method="GET",
+            stream=False,
+        )
+        assert "json" not in result
+
+    def test_excludes_body_when_none(self):
+        """_build_kwargs excludes json when body is None."""
+        result = _build_kwargs(
+            headers={},
+            params={},
+            ssl_context=None,
+            timeout=30,
+            body=None,
+            method="POST",
+            stream=False,
+        )
+        assert "json" not in result
+
+    def test_includes_headers(self):
+        """_build_kwargs includes headers in result."""
+        headers = {"Authorization": "Bearer token", "Content-Type": "application/json"}
+        result = _build_kwargs(
+            headers=headers,
+            params={},
+            ssl_context=None,
+            timeout=30,
+            body=None,
+            method="GET",
+            stream=False,
+        )
+        assert result["headers"] == headers
+
+    def test_includes_params(self):
+        """_build_kwargs includes params in result."""
+        params = {"api_key": "abc123", "limit": "10"}
+        result = _build_kwargs(
+            headers={},
+            params=params,
+            ssl_context=None,
+            timeout=30,
+            body=None,
+            method="GET",
+            stream=False,
+        )
+        assert result["params"] == params
+
+    def test_includes_ssl_context(self):
+        """_build_kwargs includes ssl context in result."""
+        mock_ssl = MagicMock()
+        result = _build_kwargs(
+            headers={},
+            params={},
+            ssl_context=mock_ssl,
+            timeout=30,
+            body=None,
+            method="GET",
+            stream=False,
+        )
+        assert result["ssl"] == mock_ssl
+
+    def test_timeout_non_stream(self):
+        """_build_kwargs sets timeout for non-streaming requests."""
+        result = _build_kwargs(
+            headers={},
+            params={},
+            ssl_context=None,
+            timeout=30,
+            body=None,
+            method="GET",
+            stream=False,
+        )
+        assert result["timeout"].total == 30
+
+    def test_timeout_stream(self):
+        """_build_kwargs sets timeout to None for streaming requests."""
+        result = _build_kwargs(
+            headers={},
+            params={},
+            ssl_context=None,
+            timeout=30,
+            body=None,
+            method="GET",
+            stream=True,
+        )
+        assert result["timeout"].total is None
+
+    def test_all_keys_present(self):
+        """_build_kwargs always includes headers, params, ssl, timeout."""
+        result = _build_kwargs(
+            headers={},
+            params={},
+            ssl_context=None,
+            timeout=60,
+            body=None,
+            method="GET",
+            stream=False,
+        )
+        assert "headers" in result
+        assert "params" in result
+        assert "ssl" in result
+        assert "timeout" in result
diff --git a/tests/unit/test_serverless_data_types.py b/tests/unit/test_serverless_data_types.py
new file mode 100644
index 00000000..201f1957
--- /dev/null
+++ b/tests/unit/test_serverless_data_types.py
@@ -0,0 +1,450 @@
+"""Unit tests for vastai.serverless.server.lib.data_types module.
+
+Tests cover:
+- JsonDataException: message storage
+- AuthData: from_json_msg with valid/missing/extra fields
+- SystemMetrics: empty() factory, update_disk_usage(), reset()
+- RequestMetrics: dataclass instantiation
+- BenchmarkResult: is_successful property
+- ModelMetrics: empty() factory, properties, set_errored(), reset()
+- WorkerStatusData: dataclass instantiation
+- LogAction enum: value validation
+"""
+import pytest
+from unittest.mock import MagicMock, patch
+import sys
+import time
+from pathlib import Path
+
+# Add vast-cli to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from vastai.serverless.server.lib.data_types import (
+    JsonDataException,
+    AuthData,
+    SystemMetrics,
+    RequestMetrics,
+    BenchmarkResult,
+    ModelMetrics,
+    WorkerStatusData,
+    LogAction,
+)
+
+
+class TestJsonDataException:
+    """Tests for JsonDataException class."""
+
+    def test_stores_message_dict(self):
+        """JsonDataException stores the error message dict."""
+        error_msg = {"field": "missing parameter"}
+        exc = JsonDataException(error_msg)
+        assert exc.message == {"field": "missing parameter"}
+
+    def test_multiple_fields_in_message(self):
+        """JsonDataException can store multiple field errors."""
+        error_msg = {"cost": "missing parameter", "endpoint": "invalid format"}
+        exc = JsonDataException(error_msg)
+        assert exc.message == error_msg
+        assert "cost" in exc.message
+        assert "endpoint" in exc.message
+
+    def test_is_exception(self):
+        """JsonDataException is a proper Exception subclass."""
+        exc = JsonDataException({"error": "test"})
+        assert isinstance(exc, Exception)
+
+
+class TestAuthData:
+    """Tests for AuthData dataclass."""
+
+    def test_from_json_msg_valid(self):
+        """AuthData.from_json_msg creates instance with valid data."""
+        json_msg = {
+            "cost": "0.10",
+            "endpoint": "/api/test",
+            "reqnum": 1,
+            "request_idx": 0,
+            "signature": "abc123",
+            "url": "https://example.com",
+        }
+        auth = AuthData.from_json_msg(json_msg)
+        assert auth.cost == "0.10"
+        assert auth.endpoint == "/api/test"
+        assert auth.reqnum == 1
+        assert auth.request_idx == 0
+        assert auth.signature == "abc123"
+        assert auth.url == "https://example.com"
+
+    def test_from_json_msg_missing_field_raises(self):
+        """AuthData.from_json_msg raises JsonDataException for missing fields."""
+        json_msg = {
+            "cost": "0.10",
+            "endpoint": "/api/test",
+            # missing reqnum, request_idx, signature, url
+        }
+        with pytest.raises(JsonDataException) as exc_info:
+            AuthData.from_json_msg(json_msg)
+        assert "reqnum" in exc_info.value.message
+        assert "request_idx" in exc_info.value.message
+        assert "signature" in exc_info.value.message
+        assert "url" in exc_info.value.message
+
+    def test_from_json_msg_single_missing_field(self):
+        """AuthData.from_json_msg reports single missing field."""
+        json_msg = {
+            "cost": "0.10",
+            "endpoint": "/api/test",
+            "reqnum": 1,
+            "request_idx": 0,
+            "signature": "abc123",
+            # missing url
+        }
+        with pytest.raises(JsonDataException) as exc_info:
+            AuthData.from_json_msg(json_msg)
+        assert "url" in exc_info.value.message
+        assert exc_info.value.message["url"] == "missing parameter"
+
+    def test_from_json_msg_extra_fields_ignored(self):
+        """AuthData.from_json_msg ignores extra fields."""
+        json_msg = {
+            "cost": "0.10",
+            "endpoint": "/api/test",
+            "reqnum": 1,
+            "request_idx": 0,
+            "signature": "abc123",
+            "url": "https://example.com",
+            "extra_field": "should be ignored",
+            "another_extra": 12345,
+        }
+        auth = AuthData.from_json_msg(json_msg)
+        assert auth.cost == "0.10"
+        assert not hasattr(auth, "extra_field")
+        assert not hasattr(auth, "another_extra")
+
+
+class TestSystemMetrics:
+    """Tests for SystemMetrics dataclass."""
+
+    @patch("vastai.serverless.server.lib.data_types.psutil.disk_usage")
+    @patch("vastai.serverless.server.lib.data_types.time.time")
+    def test_empty_factory(self, mock_time, mock_disk_usage):
+        """SystemMetrics.empty() creates instance with default values."""
+        mock_time.return_value = 1000.0
+        mock_disk_usage.return_value = MagicMock(used=10 * (2**30))  # 10 GB
+
+        metrics = SystemMetrics.empty()
+
+        assert metrics.model_loading_start == 1000.0
+        assert metrics.model_loading_time is None
+        assert metrics.last_disk_usage == 10.0  # GB
+        assert metrics.additional_disk_usage == 0.0
+        assert metrics.model_is_loaded is False
+
+    @patch("vastai.serverless.server.lib.data_types.psutil.disk_usage")
+    def test_update_disk_usage(self, mock_disk_usage):
+        """SystemMetrics.update_disk_usage() updates disk usage stats."""
+        # Initial disk usage: 10 GB
+        metrics = SystemMetrics(
+            model_loading_start=0.0,
+            model_loading_time=None,
+            last_disk_usage=10.0,
+            additional_disk_usage=0.0,
+            model_is_loaded=False,
+        )
+
+        # After update: 15 GB used
+        mock_disk_usage.return_value = MagicMock(used=15 * (2**30))
+        metrics.update_disk_usage()
+
+        assert metrics.last_disk_usage == 15.0
+        assert metrics.additional_disk_usage == 5.0  # 15 - 10
+
+    def test_reset_clears_loading_time_when_expected(self):
+        """SystemMetrics.reset() clears model_loading_time when matching expected."""
+        metrics = SystemMetrics(
+            model_loading_start=0.0,
+            model_loading_time=5.0,
+            last_disk_usage=10.0,
+            additional_disk_usage=0.0,
+            model_is_loaded=True,
+        )
+
+        metrics.reset(expected=5.0)
+        assert metrics.model_loading_time is None
+
+    def test_reset_preserves_loading_time_when_different(self):
+        """SystemMetrics.reset() preserves model_loading_time when not matching expected."""
+        metrics = SystemMetrics(
+            model_loading_start=0.0,
+            model_loading_time=5.0,
+            last_disk_usage=10.0,
+            additional_disk_usage=0.0,
+            model_is_loaded=True,
+        )
+
+        metrics.reset(expected=10.0)  # Different from current value
+        assert metrics.model_loading_time == 5.0  # Preserved
+
+    def test_reset_with_none_expected(self):
+        """SystemMetrics.reset() with None expected clears None loading time."""
+        metrics = SystemMetrics(
+            model_loading_start=0.0,
+            model_loading_time=None,
+            last_disk_usage=10.0,
+            additional_disk_usage=0.0,
+            model_is_loaded=False,
+        )
+
+        metrics.reset(expected=None)
+        assert metrics.model_loading_time is None
+
+
+class TestRequestMetrics:
+    """Tests for RequestMetrics dataclass."""
+
+    def test_instantiation_required_fields(self):
+        """RequestMetrics can be instantiated with required fields."""
+        metrics = RequestMetrics(
+            request_idx=0,
+            reqnum=1,
+            workload=1.5,
+            status="processing",
+        )
+        assert metrics.request_idx == 0
+        assert metrics.reqnum == 1
+        assert metrics.workload == 1.5
+        assert metrics.status == "processing"
+        assert metrics.success is False  # default
+
+    def test_instantiation_with_success(self):
+        """RequestMetrics respects success parameter."""
+        metrics = RequestMetrics(
+            request_idx=1,
+            reqnum=2,
+            workload=2.0,
+            status="completed",
+            success=True,
+        )
+        assert metrics.success is True
+
+
+class TestBenchmarkResult:
+    """Tests for BenchmarkResult dataclass."""
+
+    def test_is_successful_true(self):
+        """BenchmarkResult.is_successful returns True for 200 response."""
+        mock_response = MagicMock()
+        mock_response.status = 200
+
+        mock_task = MagicMock()
+        result = BenchmarkResult(
+            request_idx=0,
+            workload=1.0,
+            task=mock_task,
+            response=mock_response,
+        )
+        assert result.is_successful is True
+
+    def test_is_successful_false_non_200(self):
+        """BenchmarkResult.is_successful returns False for non-200 response."""
+        mock_response = MagicMock()
+        mock_response.status = 500
+
+        mock_task = MagicMock()
+        result = BenchmarkResult(
+            request_idx=0,
+            workload=1.0,
+            task=mock_task,
+            response=mock_response,
+        )
+        assert result.is_successful is False
+
+    def test_is_successful_false_no_response(self):
+        """BenchmarkResult.is_successful returns False when response is None."""
+        mock_task = MagicMock()
+        result = BenchmarkResult(
+            request_idx=0,
+            workload=1.0,
+            task=mock_task,
+            response=None,  # No response yet
+        )
+        assert result.is_successful is False
+
+
+class TestModelMetrics:
+    """Tests for ModelMetrics dataclass."""
+
+    def test_empty_factory(self):
+        """ModelMetrics.empty() creates instance with zero values."""
+        metrics = ModelMetrics.empty()
+        assert metrics.workload_pending == 0.0
+        assert metrics.workload_served == 0.0
+        assert metrics.workload_cancelled == 0.0
+        assert metrics.workload_errored == 0.0
+        assert metrics.workload_rejected == 0.0
+        assert metrics.workload_received == 0.0
+        assert metrics.error_msg is None
+        assert metrics.max_throughput == 0.0
+
+    def test_workload_processing_property(self):
+        """ModelMetrics.workload_processing computes correctly."""
+        metrics = ModelMetrics.empty()
+        metrics.workload_received = 10.0
+        metrics.workload_cancelled = 3.0
+        assert metrics.workload_processing == 7.0  # 10 - 3
+
+    def test_workload_processing_never_negative(self):
+        """ModelMetrics.workload_processing is clamped to 0."""
+        metrics = ModelMetrics.empty()
+        metrics.workload_received = 5.0
+        metrics.workload_cancelled = 10.0  # More cancelled than received
+        assert metrics.workload_processing == 0.0
+
+    def test_wait_time_empty_requests(self):
+        """ModelMetrics.wait_time returns 0 when no requests working."""
+        metrics = ModelMetrics.empty()
+        assert metrics.wait_time == 0.0
+
+    def test_wait_time_calculation(self):
+        """ModelMetrics.wait_time computes workload/throughput."""
+        metrics = ModelMetrics.empty()
+        metrics.max_throughput = 10.0
+        metrics.requests_working = {
+            0: RequestMetrics(request_idx=0, reqnum=1, workload=5.0, status="working"),
+            1: RequestMetrics(request_idx=1, reqnum=2, workload=5.0, status="working"),
+        }
+        # wait_time = sum(workloads) / max_throughput = 10.0 / 10.0 = 1.0
+        assert metrics.wait_time == 1.0
+
+    def test_wait_time_near_zero_throughput(self):
+        """ModelMetrics.wait_time handles near-zero throughput gracefully."""
+        metrics = ModelMetrics.empty()
+        metrics.max_throughput = 0.0  # Will use 0.00001 denominator
+        metrics.requests_working = {
+            0: RequestMetrics(request_idx=0, reqnum=1, workload=1.0, status="working"),
+        }
+        # Should not raise ZeroDivisionError
+        result = metrics.wait_time
+        assert result == 1.0 / 0.00001  # Very large but finite
+
+    def test_cur_load_property(self):
+        """ModelMetrics.cur_load sums workload from working requests."""
+        metrics = ModelMetrics.empty()
+        metrics.requests_working = {
+            0: RequestMetrics(request_idx=0, reqnum=1, workload=2.0, status="working"),
+            1: RequestMetrics(request_idx=1, reqnum=2, workload=3.0, status="working"),
+        }
+        assert metrics.cur_load == 5.0
+
+    def test_cur_load_empty(self):
+        """ModelMetrics.cur_load returns 0 for no working requests."""
+        metrics = ModelMetrics.empty()
+        assert metrics.cur_load == 0.0
+
+    def test_working_request_idxs_property(self):
+        """ModelMetrics.working_request_idxs returns list of request indices."""
+        metrics = ModelMetrics.empty()
+        metrics.requests_working = {
+            0: RequestMetrics(request_idx=0, reqnum=1, workload=1.0, status="working"),
+            5: RequestMetrics(request_idx=5, reqnum=6, workload=1.0, status="working"),
+        }
+        idxs = metrics.working_request_idxs
+        assert 0 in idxs
+        assert 5 in idxs
+
+    def test_set_errored(self):
+        """ModelMetrics.set_errored resets metrics and sets error message."""
+        metrics = ModelMetrics.empty()
+        metrics.workload_served = 10.0
+        metrics.workload_received = 20.0
+
+        metrics.set_errored("Test error message")
+
+        assert metrics.error_msg == "Test error message"
+        assert metrics.workload_served == 0
+        assert metrics.workload_received == 0
+
+    def test_reset(self):
+        """ModelMetrics.reset clears workload counters."""
+        metrics = ModelMetrics.empty()
+        metrics.workload_served = 10.0
+        metrics.workload_received = 20.0
+        metrics.workload_cancelled = 5.0
+        metrics.workload_errored = 2.0
+        metrics.workload_rejected = 1.0
+
+        metrics.reset()
+
+        assert metrics.workload_served == 0
+        assert metrics.workload_received == 0
+        assert metrics.workload_cancelled == 0
+        assert metrics.workload_errored == 0
+        assert metrics.workload_rejected == 0
+
+
+class TestWorkerStatusData:
+    """Tests for WorkerStatusData dataclass."""
+
+    def test_instantiation_all_fields(self):
+        """WorkerStatusData can be instantiated with all fields."""
+        status = WorkerStatusData(
+            id=123,
+            mtoken="token-abc",
+            version="1.0.0",
+            loadtime=5.0,
+            cur_load=2.0,
+            rej_load=0.5,
+            new_load=1.5,
+            error_msg="",
+            max_perf=10.0,
+            cur_perf=8.0,
+            cur_capacity=100.0,
+            max_capacity=200.0,
+            num_requests_working=3,
+            num_requests_recieved=10,
+            additional_disk_usage=1.5,
+            working_request_idxs=[0, 1, 2],
+            url="https://worker.example.com",
+        )
+
+        assert status.id == 123
+        assert status.mtoken == "token-abc"
+        assert status.version == "1.0.0"
+        assert status.loadtime == 5.0
+        assert status.cur_load == 2.0
+        assert status.rej_load == 0.5
+        assert status.new_load == 1.5
+        assert status.error_msg == ""
+        assert status.max_perf == 10.0
+        assert status.cur_perf == 8.0
+        assert status.cur_capacity == 100.0
+        assert status.max_capacity == 200.0
+        assert status.num_requests_working == 3
+        assert status.num_requests_recieved == 10
+        assert status.additional_disk_usage == 1.5
+        assert status.working_request_idxs == [0, 1, 2]
+        assert status.url == "https://worker.example.com"
+
+
+class TestLogAction:
+    """Tests for LogAction enum."""
+
+    def test_model_loaded_value(self):
+        """LogAction.ModelLoaded has value 1."""
+        assert LogAction.ModelLoaded.value == 1
+
+    def test_model_error_value(self):
+        """LogAction.ModelError has value 2."""
+        assert LogAction.ModelError.value == 2
+
+    def test_info_value(self):
+        """LogAction.Info has value 3."""
+        assert LogAction.Info.value == 3
+
+    def test_all_members_exist(self):
+        """All expected LogAction members exist."""
+        members = list(LogAction)
+        assert len(members) == 3
+        assert LogAction.ModelLoaded in members
+        assert LogAction.ModelError in members
+        assert LogAction.Info in members
diff --git a/tests/unit/test_serverless_endpoint.py b/tests/unit/test_serverless_endpoint.py
new file mode 100644
index 00000000..596251b5
--- /dev/null
+++ b/tests/unit/test_serverless_endpoint.py
@@ -0,0 +1,247 @@
+"""Unit tests for vastai.serverless.client.endpoint module.
+
+Tests for Endpoint and RouteResponse classes.
+These tests focus on synchronous initialization and validation code.
+"""
+
+import pytest
+from unittest.mock import MagicMock
+import sys
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from vastai.serverless.client.endpoint import Endpoint, RouteResponse
+
+
+class TestEndpointInit:
+    """Tests for Endpoint class __init__ method."""
+
+    def test_raises_on_none_client(self):
+        """Test that None client raises ValueError."""
+        with pytest.raises(ValueError, match="cannot be created without client"):
+            Endpoint(client=None, name="test", id=1, api_key="key")
+
+    def test_raises_on_empty_name(self):
+        """Test that empty string name raises ValueError."""
+        mock_client = MagicMock()
+        with pytest.raises(ValueError, match="name cannot be empty"):
+            Endpoint(client=mock_client, name="", id=1, api_key="key")
+
+    def test_raises_on_falsy_name(self):
+        """Test that falsy name (None) raises ValueError."""
+        mock_client = MagicMock()
+        with pytest.raises(ValueError, match="name cannot be empty"):
+            Endpoint(client=mock_client, name=None, id=1, api_key="key")
+
+    def test_raises_on_none_id(self):
+        """Test that None id raises ValueError."""
+        mock_client = MagicMock()
+        with pytest.raises(ValueError, match="id cannot be empty"):
+            Endpoint(client=mock_client, name="test", id=None, api_key="key")
+
+    def test_valid_instantiation_stores_attributes(self):
+        """Test that valid instantiation stores all attributes correctly."""
+        mock_client = MagicMock()
+        endpoint = Endpoint(
+            client=mock_client,
+            name="my-endpoint",
+            id=123,
+            api_key="secret_api_key"
+        )
+        assert endpoint.client is mock_client
+        assert endpoint.name == "my-endpoint"
+        assert endpoint.id == 123
+        assert endpoint.api_key == "secret_api_key"
+
+    def test_zero_id_is_valid(self):
+        """Test that id=0 is valid (not None)."""
+        mock_client = MagicMock()
+        endpoint = Endpoint(client=mock_client, name="test", id=0, api_key="key")
+        assert endpoint.id == 0
+
+    def test_negative_id_is_valid(self):
+        """Test that negative id is stored (no validation against negative)."""
+        mock_client = MagicMock()
+        endpoint = Endpoint(client=mock_client, name="test", id=-5, api_key="key")
+        assert endpoint.id == -5
+
+
+class TestEndpointRepr:
+    """Tests for Endpoint __repr__ method."""
+
+    def test_repr_format(self):
+        """Test __repr__ returns expected string format."""
+        mock_client = MagicMock()
+        endpoint = Endpoint(client=mock_client, name="test-ep", id=42, api_key="key")
+        assert repr(endpoint) == "<Endpoint test-ep (id=42)>"
+
+    def test_repr_with_long_name(self):
+        """Test __repr__ handles long endpoint names."""
+        mock_client = MagicMock()
+        endpoint = Endpoint(
+            client=mock_client,
+            name="very-long-endpoint-name-for-testing",
+            id=999,
+            api_key="key"
+        )
+        assert repr(endpoint) == "<Endpoint very-long-endpoint-name-for-testing (id=999)>"
+
+    def test_repr_with_special_chars_in_name(self):
+        """Test __repr__ handles special characters in name."""
+        mock_client = MagicMock()
+        endpoint = Endpoint(client=mock_client, name="my_test.endpoint", id=1, api_key="key")
+        assert repr(endpoint) == "<Endpoint my_test.endpoint (id=1)>"
+
+
+class TestRouteResponseStatusReady:
+    """Tests for RouteResponse when URL is present (READY status)."""
+
+    def test_status_ready_when_url_present(self):
+        """Test that presence of 'url' in body sets status to READY."""
+        body = {"url": "https://worker.example.com", "request_idx": 5}
+        response = RouteResponse(body)
+        assert response.status == "READY"
+
+    def test_request_idx_extracted_when_present(self):
+        """Test request_idx is extracted from body when present."""
+        body = {"url": "https://worker.example.com", "request_idx": 42}
+        response = RouteResponse(body)
+        assert response.request_idx == 42
+
+    def test_body_stored_when_ready(self):
+        """Test that body dict is stored."""
+        body = {"url": "https://worker.example.com", "extra": "data"}
+        response = RouteResponse(body)
+        assert response.body == body
+
+
+class TestRouteResponseStatusWaiting:
+    """Tests for RouteResponse when URL is NOT present (WAITING status)."""
+
+    def test_status_waiting_when_no_url(self):
+        """Test that absence of 'url' in body sets status to WAITING."""
+        body = {"request_idx": 3}
+        response = RouteResponse(body)
+        assert response.status == "WAITING"
+
+    def test_request_idx_extracted_when_waiting(self):
+        """Test request_idx is extracted from body when in waiting status."""
+        body = {"request_idx": 7}
+        response = RouteResponse(body)
+        assert response.request_idx == 7
+
+    def test_body_stored_when_waiting(self):
+        """Test that body dict is stored when waiting."""
+        body = {"request_idx": 3, "other": "info"}
+        response = RouteResponse(body)
+        assert response.body == body
+
+
+class TestRouteResponseRequestIdx:
+    """Tests for RouteResponse request_idx handling."""
+
+    def test_request_idx_defaults_to_zero(self):
+        """Test request_idx defaults to 0 when not in body."""
+        body = {}
+        response = RouteResponse(body)
+        assert response.request_idx == 0
+
+    def test_request_idx_zero_when_explicit(self):
+        """Test request_idx=0 when explicitly set."""
+        body = {"request_idx": 0}
+        response = RouteResponse(body)
+        assert response.request_idx == 0
+
+    def test_request_idx_large_value(self):
+        """Test request_idx with large value."""
+        body = {"request_idx": 999999}
+        response = RouteResponse(body)
+        assert response.request_idx == 999999
+
+
+class TestRouteResponseRepr:
+    """Tests for RouteResponse __repr__ method."""
+
+    def test_repr_format_ready(self):
+        """Test __repr__ returns expected format for READY status."""
+        body = {"url": "https://test.com"}
+        response = RouteResponse(body)
+        assert repr(response) == "<RouteResponse status=READY>"
+
+    def test_repr_format_waiting(self):
+        """Test __repr__ returns expected format for WAITING status."""
+        body = {}
+        response = RouteResponse(body)
+        assert repr(response) == "<RouteResponse status=WAITING>"
+
+
+class TestRouteResponseGetUrl:
+    """Tests for RouteResponse.get_url() method."""
+
+    def test_get_url_returns_url_from_body(self):
+        """Test get_url() returns url from body when present."""
+        body = {"url": "https://example.com/worker"}
+        response = RouteResponse(body)
+        assert response.get_url() == "https://example.com/worker"
+
+    def test_get_url_none_when_missing(self):
+        """Test get_url() returns None when url not in body."""
+        body = {}
+        response = RouteResponse(body)
+        assert response.get_url() is None
+
+    def test_get_url_with_complex_url(self):
+        """Test get_url() with complex URL including path and query."""
+        body = {"url": "https://worker-123.vast.ai:8080/inference?model=gpt"}
+        response = RouteResponse(body)
+        assert response.get_url() == "https://worker-123.vast.ai:8080/inference?model=gpt"
+
+    def test_get_url_empty_string(self):
+        """Test get_url() when url is empty string."""
+        body = {"url": ""}
+        response = RouteResponse(body)
+        assert response.get_url() == ""
+
+
+class TestEndpointRequest:
+    """Tests for Endpoint.request() method delegation."""
+
+    def test_request_delegates_to_client(self):
+        """Test that request() delegates to client.queue_endpoint_request()."""
+        mock_client = MagicMock()
+        endpoint = Endpoint(client=mock_client, name="test", id=1, api_key="key")
+
+        endpoint.request("/route", {"data": "value"})
+
+        mock_client.queue_endpoint_request.assert_called_once()
+        call_kwargs = mock_client.queue_endpoint_request.call_args[1]
+        assert call_kwargs["endpoint"] is endpoint
+        assert call_kwargs["worker_route"] == "/route"
+        assert call_kwargs["worker_payload"] == {"data": "value"}
+
+    def test_request_passes_optional_params(self):
+        """Test that request() passes optional parameters."""
+        mock_client = MagicMock()
+        endpoint = Endpoint(client=mock_client, name="test", id=1, api_key="key")
+
+        endpoint.request("/route", {"data": "value"}, cost=200, retry=False, stream=True)
+
+        call_kwargs = mock_client.queue_endpoint_request.call_args[1]
+        assert call_kwargs["cost"] == 200
+        assert call_kwargs["retry"] is False
+        assert call_kwargs["stream"] is True
+
+
+class TestEndpointGetWorkers:
+    """Tests for Endpoint.get_workers() method delegation."""
+
+    def test_get_workers_delegates_to_client(self):
+        """Test that get_workers() delegates to client.get_endpoint_workers()."""
+        mock_client = MagicMock()
+        endpoint = Endpoint(client=mock_client, name="test", id=1, api_key="key")
+
+        endpoint.get_workers()
+
+        mock_client.get_endpoint_workers.assert_called_once_with(endpoint)
diff --git a/tests/unit/test_serverless_metrics.py b/tests/unit/test_serverless_metrics.py
new file mode 100644
index 00000000..ad7661d2
--- /dev/null
+++ b/tests/unit/test_serverless_metrics.py
@@ -0,0 +1,338 @@
+"""
+Unit tests for vastai/serverless/server/lib/metrics.py
+
+Tests the Metrics class request lifecycle methods without network calls.
+"""
+import pytest
+from unittest.mock import MagicMock, patch
+import sys
+import os
+from pathlib import Path
+
+# Add vast-cli to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+
+@pytest.fixture
+def mock_env():
+    """Mock environment variables required by Metrics class."""
+    env = {
+        "CONTAINER_ID": "12345",
+        "REPORT_ADDR": "https://run.vast.ai",
+        "PUBLIC_IPADDR": "192.168.1.100",
+        "WORKER_PORT": "8080",
+        "VAST_TCP_PORT_8080": "8080",
+    }
+    with patch.dict(os.environ, env, clear=False):
+        # Clear the cached get_url function so it picks up new env vars
+        from vastai.serverless.server.lib.metrics import get_url
+        get_url.cache_clear()
+        yield env
+
+
+@pytest.fixture
+def metrics(mock_env):
+    """Create Metrics instance with mocked environment."""
+    from vastai.serverless.server.lib.metrics import Metrics
+    return Metrics()
+
+
+@pytest.fixture
+def request_metrics():
+    """Create a RequestMetrics object for testing."""
+    from vastai.serverless.server.lib.data_types import RequestMetrics
+    return RequestMetrics(
+        request_idx=1,
+        reqnum=100,
+        workload=50.0,
+        status="Created"
+    )
+
+
+class TestMetricsInstantiation:
+    """Tests for Metrics class instantiation."""
+
+    def test_metrics_created_with_env_defaults(self, metrics, mock_env):
+        """Metrics instance should use environment variables for defaults."""
+        assert metrics.id == int(mock_env["CONTAINER_ID"])
+        assert mock_env["REPORT_ADDR"] in metrics.report_addr
+        assert metrics.version == "0"
+        assert metrics.mtoken == ""
+        assert metrics.update_pending is False
+
+    def test_metrics_url_constructed_from_env(self, metrics, mock_env):
+        """URL should be constructed from PUBLIC_IPADDR and port."""
+        expected_url = f"http://{mock_env['PUBLIC_IPADDR']}:{mock_env['VAST_TCP_PORT_8080']}"
+        assert metrics.url == expected_url
+
+    def test_metrics_system_metrics_initialized(self, metrics):
+        """System metrics should be initialized with empty factory."""
+        assert metrics.system_metrics is not None
+        assert metrics.system_metrics.model_is_loaded is False
+
+    def test_metrics_model_metrics_initialized(self, metrics):
+        """Model metrics should be initialized with empty factory."""
+        assert metrics.model_metrics is not None
+        assert metrics.model_metrics.workload_pending == 0.0
+        assert metrics.model_metrics.workload_served == 0.0
+
+
+class TestMetricsRequestStart:
+    """Tests for _request_start method."""
+
+    def test_updates_status_to_started(self, metrics, request_metrics):
+        """_request_start should set request status to Started."""
+        metrics._request_start(request_metrics)
+        assert request_metrics.status == "Started"
+
+    def test_increments_workload_pending(self, metrics, request_metrics):
+        """_request_start should increase workload_pending by request workload."""
+        metrics._request_start(request_metrics)
+        assert metrics.model_metrics.workload_pending == request_metrics.workload
+
+    def test_increments_workload_received(self, metrics, request_metrics):
+        """_request_start should increase workload_received by request workload."""
+        metrics._request_start(request_metrics)
+        assert metrics.model_metrics.workload_received == request_metrics.workload
+
+    def test_adds_to_requests_recieved(self, metrics, request_metrics):
+        """_request_start should add reqnum to requests_recieved set."""
+        metrics._request_start(request_metrics)
+        assert request_metrics.reqnum in metrics.model_metrics.requests_recieved
+
+    def test_adds_to_requests_working(self, metrics, request_metrics):
+        """_request_start should add request to requests_working dict."""
+        metrics._request_start(request_metrics)
+        assert request_metrics.reqnum in metrics.model_metrics.requests_working
+        assert metrics.model_metrics.requests_working[request_metrics.reqnum] == request_metrics
+
+    def test_sets_update_pending_true(self, metrics, request_metrics):
+        """_request_start should set update_pending to True."""
+        metrics._request_start(request_metrics)
+        assert metrics.update_pending is True
+
+
+class TestMetricsRequestEnd:
+    """Tests for _request_end method."""
+
+    def test_decrements_workload_pending(self, metrics, request_metrics):
+        """_request_end should decrease workload_pending by request workload."""
+        # Start request first
+        metrics._request_start(request_metrics)
+        initial_pending = metrics.model_metrics.workload_pending
+
+        metrics._request_end(request_metrics)
+        assert metrics.model_metrics.workload_pending == initial_pending - request_metrics.workload
+
+    def test_removes_from_requests_working(self, metrics, request_metrics):
+        """_request_end should remove request from requests_working dict."""
+        metrics._request_start(request_metrics)
+        metrics._request_end(request_metrics)
+        assert request_metrics.reqnum not in metrics.model_metrics.requests_working
+
+    def test_adds_to_requests_deleting(self, metrics, request_metrics):
+        """_request_end should add request to requests_deleting list."""
+        metrics._request_start(request_metrics)
+        metrics._request_end(request_metrics)
+        assert request_metrics in metrics.model_metrics.requests_deleting
+
+    def test_updates_last_request_served(self, metrics, request_metrics):
+        """_request_end should update last_request_served timestamp."""
+        metrics._request_start(request_metrics)
+        metrics._request_end(request_metrics)
+        assert metrics.last_request_served > 0
+
+
+class TestMetricsRequestSuccess:
+    """Tests for _request_success method."""
+
+    def test_increments_workload_served(self, metrics, request_metrics):
+        """_request_success should increase workload_served by request workload."""
+        metrics._request_success(request_metrics)
+        assert metrics.model_metrics.workload_served == request_metrics.workload
+
+    def test_sets_status_to_success(self, metrics, request_metrics):
+        """_request_success should set request status to Success."""
+        metrics._request_success(request_metrics)
+        assert request_metrics.status == "Success"
+
+    def test_sets_success_flag_true(self, metrics, request_metrics):
+        """_request_success should set request success flag to True."""
+        metrics._request_success(request_metrics)
+        assert request_metrics.success is True
+
+    def test_sets_update_pending_true(self, metrics, request_metrics):
+        """_request_success should set update_pending to True."""
+        metrics._request_success(request_metrics)
+        assert metrics.update_pending is True
+
+
+class TestMetricsRequestErrored:
+    """Tests for _request_errored method."""
+
+    def test_increments_workload_errored(self, metrics, request_metrics):
+        """_request_errored should increase workload_errored by request workload."""
+        metrics._request_errored(request_metrics, "Test error")
+        assert metrics.model_metrics.workload_errored == request_metrics.workload
+
+    def test_sets_status_to_error(self, metrics, request_metrics):
+        """_request_errored should set request status to Error."""
+        metrics._request_errored(request_metrics, "Test error")
+        assert request_metrics.status == "Error"
+
+    def test_sets_success_flag_false(self, metrics, request_metrics):
+        """_request_errored should set request success flag to False."""
+        metrics._request_errored(request_metrics, "Test error")
+        assert request_metrics.success is False
+
+    def test_sets_update_pending_true(self, metrics, request_metrics):
+        """_request_errored should set update_pending to True."""
+        metrics._request_errored(request_metrics, "Test error")
+        assert metrics.update_pending is True
+
+
+class TestMetricsRequestCanceled:
+    """Tests for _request_canceled method."""
+
+    def test_increments_workload_cancelled(self, metrics, request_metrics):
+        """_request_canceled should increase workload_cancelled by request workload."""
+        metrics._request_canceled(request_metrics)
+        assert metrics.model_metrics.workload_cancelled == request_metrics.workload
+
+    def test_sets_status_to_cancelled(self, metrics, request_metrics):
+        """_request_canceled should set request status to Cancelled."""
+        metrics._request_canceled(request_metrics)
+        assert request_metrics.status == "Cancelled"
+
+    def test_sets_success_flag_true(self, metrics, request_metrics):
+        """_request_canceled should set request success flag to True (cancelled = successful cleanup)."""
+        metrics._request_canceled(request_metrics)
+        assert request_metrics.success is True
+
+
+class TestMetricsRequestReject:
+    """Tests for _request_reject method."""
+
+    def test_increments_workload_rejected(self, metrics, request_metrics):
+        """_request_reject should increase workload_rejected by request workload."""
+        metrics._request_reject(request_metrics)
+        assert metrics.model_metrics.workload_rejected == request_metrics.workload
+
+    def test_sets_status_to_rejected(self, metrics, request_metrics):
+        """_request_reject should set request status to Rejected."""
+        metrics._request_reject(request_metrics)
+        assert request_metrics.status == "Rejected"
+
+    def test_sets_success_flag_false(self, metrics, request_metrics):
+        """_request_reject should set request success flag to False."""
+        metrics._request_reject(request_metrics)
+        assert request_metrics.success is False
+
+    def test_adds_to_requests_recieved(self, metrics, request_metrics):
+        """_request_reject should add reqnum to requests_recieved set."""
+        metrics._request_reject(request_metrics)
+        assert request_metrics.reqnum in metrics.model_metrics.requests_recieved
+
+    def test_adds_to_requests_deleting(self, metrics, request_metrics):
+        """_request_reject should add request to requests_deleting list."""
+        metrics._request_reject(request_metrics)
+        assert request_metrics in metrics.model_metrics.requests_deleting
+
+    def test_sets_update_pending_true(self, metrics, request_metrics):
+        """_request_reject should set update_pending to True."""
+        metrics._request_reject(request_metrics)
+        assert metrics.update_pending is True
+
+
+class TestMetricsModelLoaded:
+    """Tests for _model_loaded method."""
+
+    def test_sets_model_is_loaded_true(self, metrics):
+        """_model_loaded should set system_metrics.model_is_loaded to True."""
+        metrics._model_loaded(max_throughput=100.0)
+        assert metrics.system_metrics.model_is_loaded is True
+
+    def test_sets_max_throughput(self, metrics):
+        """_model_loaded should set model_metrics.max_throughput."""
+        metrics._model_loaded(max_throughput=150.5)
+        assert metrics.model_metrics.max_throughput == 150.5
+
+    def test_calculates_loading_time(self, metrics):
+        """_model_loaded should calculate model_loading_time from start time."""
+        metrics._model_loaded(max_throughput=100.0)
+        # Loading time should be >= 0 (time since model_loading_start)
+        assert metrics.system_metrics.model_loading_time >= 0
+
+
+class TestMetricsModelErrored:
+    """Tests for _model_errored method."""
+
+    def test_sets_error_msg(self, metrics):
+        """_model_errored should set model_metrics.error_msg."""
+        metrics._model_errored("Model failed to load")
+        assert metrics.model_metrics.error_msg == "Model failed to load"
+
+    def test_sets_model_is_loaded_true(self, metrics):
+        """_model_errored should set system_metrics.model_is_loaded to True."""
+        metrics._model_errored("Model failed to load")
+        assert metrics.system_metrics.model_is_loaded is True
+
+
+class TestMetricsSetters:
+    """Tests for simple setter methods."""
+
+    def test_set_version(self, metrics):
+        """_set_version should update version field."""
+        metrics._set_version("2.0.1")
+        assert metrics.version == "2.0.1"
+
+    def test_set_mtoken(self, metrics):
+        """_set_mtoken should update mtoken field."""
+        metrics._set_mtoken("secret-token-123")
+        assert metrics.mtoken == "secret-token-123"
+
+
+class TestMetricsUrlWithSSL:
+    """Tests for URL construction with SSL enabled."""
+
+    def test_url_with_ssl_enabled(self):
+        """URL should use https when USE_SSL=true."""
+        env = {
+            "CONTAINER_ID": "12345",
+            "REPORT_ADDR": "https://run.vast.ai",
+            "PUBLIC_IPADDR": "192.168.1.100",
+            "WORKER_PORT": "8080",
+            "VAST_TCP_PORT_8080": "8080",
+            "USE_SSL": "true",
+        }
+        with patch.dict(os.environ, env, clear=False):
+            from vastai.serverless.server.lib.metrics import get_url, Metrics
+            get_url.cache_clear()
+            metrics = Metrics()
+            assert metrics.url.startswith("https://")
+
+
+class TestMetricsMultipleRequests:
+    """Tests for handling multiple concurrent requests."""
+
+    def test_multiple_requests_tracked_independently(self, metrics):
+        """Multiple requests should be tracked independently."""
+        from vastai.serverless.server.lib.data_types import RequestMetrics
+
+        req1 = RequestMetrics(request_idx=1, reqnum=100, workload=50.0, status="Created")
+        req2 = RequestMetrics(request_idx=2, reqnum=101, workload=75.0, status="Created")
+
+        metrics._request_start(req1)
+        metrics._request_start(req2)
+
+        # Both should be tracked
+        assert len(metrics.model_metrics.requests_working) == 2
+        assert metrics.model_metrics.workload_pending == 125.0  # 50 + 75
+
+        # End one request
+        metrics._request_success(req1)
+        metrics._request_end(req1)
+
+        # Only one should remain
+        assert len(metrics.model_metrics.requests_working) == 1
+        assert req2.reqnum in metrics.model_metrics.requests_working
diff --git a/tests/unit/test_serverless_worker_config.py b/tests/unit/test_serverless_worker_config.py
new file mode 100644
index 00000000..065adf8b
--- /dev/null
+++ b/tests/unit/test_serverless_worker_config.py
@@ -0,0 +1,455 @@
+"""
+Unit tests for vastai/serverless/server/worker.py
+
+Tests the configuration dataclasses and EndpointHandlerFactory without network calls.
+"""
+import pytest
+from unittest.mock import MagicMock
+import sys
+from pathlib import Path
+
+# Add vast-cli to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from vastai.serverless.server.worker import (
+    LogActionConfig,
+    BenchmarkConfig,
+    HandlerConfig,
+    WorkerConfig,
+    EndpointHandlerFactory,
+)
+from vastai.serverless.server.lib.data_types import LogAction
+
+
+class TestLogActionConfig:
+    """Tests for LogActionConfig dataclass."""
+
+    def test_default_empty_lists(self):
+        """Default factory should create empty lists for all action types."""
+        config = LogActionConfig()
+        assert config.on_load == []
+        assert config.on_error == []
+        assert config.on_info == []
+
+    def test_log_actions_on_load_converts_to_tuples(self):
+        """on_load strings should convert to (LogAction.ModelLoaded, str) tuples."""
+        config = LogActionConfig(on_load=["Server started"])
+        actions = config.log_actions
+        assert (LogAction.ModelLoaded, "Server started") in actions
+
+    def test_log_actions_on_error_converts_to_tuples(self):
+        """on_error strings should convert to (LogAction.ModelError, str) tuples."""
+        config = LogActionConfig(on_error=["Critical failure"])
+        actions = config.log_actions
+        assert (LogAction.ModelError, "Critical failure") in actions
+
+    def test_log_actions_on_info_converts_to_tuples(self):
+        """on_info strings should convert to (LogAction.Info, str) tuples."""
+        config = LogActionConfig(on_info=["Download progress"])
+        actions = config.log_actions
+        assert (LogAction.Info, "Download progress") in actions
+
+    def test_log_actions_combined_all_types(self):
+        """log_actions should combine all three action types."""
+        config = LogActionConfig(
+            on_load=["Model loaded", "Ready to serve"],
+            on_error=["Load failed"],
+            on_info=["Starting download"]
+        )
+        actions = config.log_actions
+        assert len(actions) == 4
+        assert (LogAction.ModelLoaded, "Model loaded") in actions
+        assert (LogAction.ModelLoaded, "Ready to serve") in actions
+        assert (LogAction.ModelError, "Load failed") in actions
+        assert (LogAction.Info, "Starting download") in actions
+
+    def test_log_actions_empty_returns_empty_list(self):
+        """Empty config should return empty log_actions list."""
+        config = LogActionConfig()
+        assert config.log_actions == []
+
+
+class TestBenchmarkConfig:
+    """Tests for BenchmarkConfig dataclass."""
+
+    def test_default_values(self):
+        """Default values should be set correctly."""
+        config = BenchmarkConfig()
+        assert config.dataset is None
+        assert config.generator is None
+        assert config.runs == 8
+        assert config.concurrency == 10
+
+    def test_custom_dataset_stored(self):
+        """Custom dataset should be stored."""
+        test_data = [{"input": "test1"}, {"input": "test2"}]
+        config = BenchmarkConfig(dataset=test_data)
+        assert config.dataset == test_data
+
+    def test_custom_generator_stored(self):
+        """Custom generator function should be stored."""
+        def my_generator():
+            return {"input": "generated"}
+        config = BenchmarkConfig(generator=my_generator)
+        assert config.generator == my_generator
+
+    def test_custom_runs_stored(self):
+        """Custom runs value should be stored."""
+        config = BenchmarkConfig(runs=16)
+        assert config.runs == 16
+
+    def test_custom_concurrency_stored(self):
+        """Custom concurrency value should be stored."""
+        config = BenchmarkConfig(concurrency=5)
+        assert config.concurrency == 5
+
+
+class TestHandlerConfig:
+    """Tests for HandlerConfig dataclass."""
+
+    def test_route_required_and_stored(self):
+        """Route should be stored correctly."""
+        config = HandlerConfig(route="/inference")
+        assert config.route == "/inference"
+
+    def test_default_allow_parallel_requests(self):
+        """Default allow_parallel_requests should be False."""
+        config = HandlerConfig(route="/")
+        assert config.allow_parallel_requests is False
+
+    def test_default_max_queue_time(self):
+        """Default max_queue_time should be 30.0."""
+        config = HandlerConfig(route="/")
+        assert config.max_queue_time == 30.0
+
+    def test_default_benchmark_config_none(self):
+        """Default benchmark_config should be None."""
+        config = HandlerConfig(route="/")
+        assert config.benchmark_config is None
+
+    def test_default_handler_class_none(self):
+        """Default handler_class should be None."""
+        config = HandlerConfig(route="/")
+        assert config.handler_class is None
+
+    def test_default_payload_class_none(self):
+        """Default payload_class should be None."""
+        config = HandlerConfig(route="/")
+        assert config.payload_class is None
+
+    def test_default_request_parser_none(self):
+        """Default request_parser should be None."""
+        config = HandlerConfig(route="/")
+        assert config.request_parser is None
+
+    def test_default_response_generator_none(self):
+        """Default response_generator should be None."""
+        config = HandlerConfig(route="/")
+        assert config.response_generator is None
+
+    def test_default_workload_calculator_none(self):
+        """Default workload_calculator should be None."""
+        config = HandlerConfig(route="/")
+        assert config.workload_calculator is None
+
+    def test_custom_values_stored(self):
+        """Custom values should be stored correctly."""
+        benchmark = BenchmarkConfig(runs=5)
+        config = HandlerConfig(
+            route="/custom",
+            allow_parallel_requests=True,
+            max_queue_time=60.0,
+            benchmark_config=benchmark
+        )
+        assert config.route == "/custom"
+        assert config.allow_parallel_requests is True
+        assert config.max_queue_time == 60.0
+        assert config.benchmark_config == benchmark
+
+
+class TestWorkerConfig:
+    """Tests for WorkerConfig dataclass."""
+
+    def test_default_handlers_empty_list(self):
+        """Default handlers should be empty list."""
+        config = WorkerConfig()
+        assert config.handlers == []
+
+    def test_default_log_action_config(self):
+        """Default log_action_config should be LogActionConfig instance."""
+        config = WorkerConfig()
+        assert isinstance(config.log_action_config, LogActionConfig)
+
+    def test_default_model_server_url_none(self):
+        """Default model_server_url should be None."""
+        config = WorkerConfig()
+        assert config.model_server_url is None
+
+    def test_default_model_server_port_none(self):
+        """Default model_server_port should be None."""
+        config = WorkerConfig()
+        assert config.model_server_port is None
+
+    def test_default_model_log_file_none(self):
+        """Default model_log_file should be None."""
+        config = WorkerConfig()
+        assert config.model_log_file is None
+
+    def test_default_model_healthcheck_url_none(self):
+        """Default model_healthcheck_url should be None."""
+        config = WorkerConfig()
+        assert config.model_healthcheck_url is None
+
+    def test_custom_values_stored(self):
+        """Custom values should be stored correctly."""
+        handler = HandlerConfig(route="/inference")
+        log_config = LogActionConfig(on_load=["Ready"])
+        config = WorkerConfig(
+            model_server_url="http://localhost",
+            model_server_port=8000,
+            model_log_file="/var/log/model.log",
+            model_healthcheck_url="http://localhost:8000/health",
+            handlers=[handler],
+            log_action_config=log_config
+        )
+        assert config.model_server_url == "http://localhost"
+        assert config.model_server_port == 8000
+        assert config.model_log_file == "/var/log/model.log"
+        assert config.model_healthcheck_url == "http://localhost:8000/health"
+        assert config.handlers == [handler]
+        assert config.log_action_config == log_config
+
+
+class TestEndpointHandlerFactory:
+    """Tests for EndpointHandlerFactory class."""
+
+    def test_default_handler_created_when_no_handlers(self):
+        """Factory should create a default handler at '/' when no handlers configured."""
+        config = WorkerConfig(
+            model_server_url="http://localhost",
+            model_server_port=8000,
+        )
+        factory = EndpointHandlerFactory(config)
+        assert factory.has_handlers() is True
+        assert "/" in factory.get_all_handlers()
+
+    def test_get_handler_returns_handler_for_route(self):
+        """get_handler should return handler for registered route."""
+        config = WorkerConfig(
+            model_server_url="http://localhost",
+            model_server_port=8000,
+        )
+        factory = EndpointHandlerFactory(config)
+        handler = factory.get_handler("/")
+        assert handler is not None
+
+    def test_get_handler_returns_none_for_unknown_route(self):
+        """get_handler should return None for unregistered route."""
+        config = WorkerConfig(
+            model_server_url="http://localhost",
+            model_server_port=8000,
+        )
+        factory = EndpointHandlerFactory(config)
+        assert factory.get_handler("/unknown") is None
+
+    def test_get_all_handlers_returns_copy(self):
+        """get_all_handlers should return a copy of handlers dict."""
+        config = WorkerConfig(
+            model_server_url="http://localhost",
+            model_server_port=8000,
+        )
+        factory = EndpointHandlerFactory(config)
+        handlers = factory.get_all_handlers()
+        # Modifying returned dict shouldn't affect internal state
+        handlers["/test"] = "fake_handler"
+        assert "/test" not in factory.get_all_handlers()
+
+    def test_has_handlers_returns_true_when_handlers_exist(self):
+        """has_handlers should return True when handlers are registered."""
+        config = WorkerConfig(
+            model_server_url="http://localhost",
+            model_server_port=8000,
+        )
+        factory = EndpointHandlerFactory(config)
+        assert factory.has_handlers() is True
+
+    def test_model_server_base_url_property(self):
+        """model_server_base_url should return formatted URL with port."""
+        config = WorkerConfig(
+            model_server_url="http://localhost",
+            model_server_port=8000,
+        )
+        factory = EndpointHandlerFactory(config)
+        assert factory.model_server_base_url == "http://localhost:8000"
+
+    def test_builds_handlers_from_config_list(self):
+        """Factory should build handlers from config handlers list."""
+        handler_configs = [
+            HandlerConfig(route="/inference"),
+            HandlerConfig(route="/health"),
+        ]
+        config = WorkerConfig(
+            model_server_url="http://localhost",
+            model_server_port=8000,
+            handlers=handler_configs,
+        )
+        factory = EndpointHandlerFactory(config)
+        handlers = factory.get_all_handlers()
+        assert "/inference" in handlers
+        assert "/health" in handlers
+
+    def test_handler_uses_config_allow_parallel_requests(self):
+        """Created handler should use allow_parallel_requests from config."""
+        handler_config = HandlerConfig(
+            route="/test",
+            allow_parallel_requests=True,
+        )
+        config = WorkerConfig(
+            model_server_url="http://localhost",
+            model_server_port=8000,
+            handlers=[handler_config],
+        )
+        factory = EndpointHandlerFactory(config)
+        handler = factory.get_handler("/test")
+        assert handler.allow_parallel_requests is True
+
+    def test_handler_uses_config_max_queue_time(self):
+        """Created handler should use max_queue_time from config."""
+        handler_config = HandlerConfig(
+            route="/test",
+            max_queue_time=60.0,
+        )
+        config = WorkerConfig(
+            model_server_url="http://localhost",
+            model_server_port=8000,
+            handlers=[handler_config],
+        )
+        factory = EndpointHandlerFactory(config)
+        handler = factory.get_handler("/test")
+        assert handler.max_queue_time == 60.0
+
+    def test_handler_endpoint_property_returns_route(self):
+        """Handler's endpoint property should return the route."""
+        handler_config = HandlerConfig(route="/inference")
+        config = WorkerConfig(
+            model_server_url="http://localhost",
+            model_server_port=8000,
+            handlers=[handler_config],
+        )
+        factory = EndpointHandlerFactory(config)
+        handler = factory.get_handler("/inference")
+        assert handler.endpoint == "/inference"
+
+    def test_get_benchmark_handler_returns_handler_with_benchmark(self):
+        """get_benchmark_handler should return handler with BenchmarkConfig."""
+        benchmark = BenchmarkConfig(
+            dataset=[{"input": "test"}],
+            runs=4,
+            concurrency=2,
+        )
+        handler_config = HandlerConfig(
+            route="/inference",
+            benchmark_config=benchmark,
+        )
+        config = WorkerConfig(
+            model_server_url="http://localhost",
+            model_server_port=8000,
+            handlers=[handler_config],
+        )
+        factory = EndpointHandlerFactory(config)
+        benchmark_handler = factory.get_benchmark_handler()
+        assert benchmark_handler is not None
+        assert benchmark_handler.has_benchmark is True
+
+    def test_get_benchmark_handler_raises_when_missing(self):
+        """get_benchmark_handler should raise when no BenchmarkConfig exists."""
+        handler_config = HandlerConfig(route="/test")
+        config = WorkerConfig(
+            model_server_url="http://localhost",
+            model_server_port=8000,
+            handlers=[handler_config],
+        )
+        factory = EndpointHandlerFactory(config)
+        with pytest.raises(Exception, match="Missing EndpointHandler with BenchmarkConfig"):
+            factory.get_benchmark_handler()
+
+    def test_get_benchmark_handler_raises_when_multiple(self):
+        """get_benchmark_handler should raise when multiple BenchmarkConfigs exist."""
+        benchmark1 = BenchmarkConfig(dataset=[{"input": "test1"}])
+        benchmark2 = BenchmarkConfig(dataset=[{"input": "test2"}])
+        handler_configs = [
+            HandlerConfig(route="/inference1", benchmark_config=benchmark1),
+            HandlerConfig(route="/inference2", benchmark_config=benchmark2),
+        ]
+        config = WorkerConfig(
+            model_server_url="http://localhost",
+            model_server_port=8000,
+            handlers=handler_configs,
+        )
+        factory = EndpointHandlerFactory(config)
+        with pytest.raises(Exception, match="Cannot define BenchmarkConfig for more than one"):
+            factory.get_benchmark_handler()
+
+
+class TestHandlerBenchmarkProperties:
+    """Tests for handler benchmark-related properties."""
+
+    def test_handler_has_benchmark_false_without_config(self):
+        """Handler should have has_benchmark=False without BenchmarkConfig."""
+        handler_config = HandlerConfig(route="/test")
+        config = WorkerConfig(
+            model_server_url="http://localhost",
+            model_server_port=8000,
+            handlers=[handler_config],
+        )
+        factory = EndpointHandlerFactory(config)
+        handler = factory.get_handler("/test")
+        assert handler.has_benchmark is False
+
+    def test_handler_has_benchmark_true_with_config(self):
+        """Handler should have has_benchmark=True with BenchmarkConfig."""
+        benchmark = BenchmarkConfig(dataset=[{"input": "test"}])
+        handler_config = HandlerConfig(
+            route="/test",
+            benchmark_config=benchmark,
+        )
+        config = WorkerConfig(
+            model_server_url="http://localhost",
+            model_server_port=8000,
+            handlers=[handler_config],
+        )
+        factory = EndpointHandlerFactory(config)
+        handler = factory.get_handler("/test")
+        assert handler.has_benchmark is True
+
+    def test_handler_benchmark_runs_from_config(self):
+        """Handler should use runs value from BenchmarkConfig."""
+        benchmark = BenchmarkConfig(dataset=[{"input": "test"}], runs=16)
+        handler_config = HandlerConfig(
+            route="/test",
+            benchmark_config=benchmark,
+        )
+        config = WorkerConfig(
+            model_server_url="http://localhost",
+            model_server_port=8000,
+            handlers=[handler_config],
+        )
+        factory = EndpointHandlerFactory(config)
+        handler = factory.get_handler("/test")
+        assert handler.benchmark_runs == 16
+
+    def test_handler_concurrency_from_config(self):
+        """Handler should use concurrency value from BenchmarkConfig."""
+        benchmark = BenchmarkConfig(dataset=[{"input": "test"}], concurrency=5)
+        handler_config = HandlerConfig(
+            route="/test",
+            benchmark_config=benchmark,
+        )
+        config = WorkerConfig(
+            model_server_url="http://localhost",
+            model_server_port=8000,
+            handlers=[handler_config],
+        )
+        factory = EndpointHandlerFactory(config)
+        handler = factory.get_handler("/test")
+        assert handler.concurrency == 5
diff --git a/tests/unit/test_timezone.py b/tests/unit/test_timezone.py
new file mode 100644
index 00000000..9ea33596
--- /dev/null
+++ b/tests/unit/test_timezone.py
@@ -0,0 +1,125 @@
+"""Unit tests for timezone handling functions.
+
+TEST-03: Unit tests for timezone handling functions.
+
+These tests verify that all timezone conversions produce correct UTC results
+regardless of the local system timezone.
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+import calendar
+from datetime import datetime, timezone
+import pytest
+
+
+class TestStringToUnixEpoch:
+    """Tests for string_to_unix_epoch() function."""
+
+    def test_date_string_to_utc_epoch(self):
+        """Date string converts to correct UTC epoch timestamp."""
+        from vast import string_to_unix_epoch
+
+        # 01/15/2025 00:00:00 UTC = 1736899200
+        result = string_to_unix_epoch("01/15/2025")
+        expected = calendar.timegm((2025, 1, 15, 0, 0, 0, 0, 0, 0))
+
+        assert expected == 1736899200, f"Sanity check failed: expected 1736899200, got {expected}"
+        assert result == expected
+
+    def test_numeric_string_passthrough(self):
+        """Numeric string is converted to float and returned."""
+        from vast import string_to_unix_epoch
+
+        assert string_to_unix_epoch("1736899200") == 1736899200.0
+        assert string_to_unix_epoch("1736899200.5") == 1736899200.5
+
+    def test_none_returns_none(self):
+        """None input returns None."""
+        from vast import string_to_unix_epoch
+
+        assert string_to_unix_epoch(None) is None
+
+    def test_empty_string_raises_value_error(self):
+        """Empty string raises ValueError (not numeric, can't parse as date)."""
+        from vast import string_to_unix_epoch
+
+        # Empty string is not a valid float and not a valid date format
+        with pytest.raises(ValueError):
+            string_to_unix_epoch("")
+
+    def test_various_date_formats(self):
+        """Various date formats parse correctly."""
+        from vast import string_to_unix_epoch
+
+        # Test MM/DD/YYYY format
+        result1 = string_to_unix_epoch("12/31/2024")
+        expected1 = calendar.timegm((2024, 12, 31, 0, 0, 0, 0, 0, 0))
+        assert result1 == expected1
+
+        # Test boundary dates
+        result2 = string_to_unix_epoch("01/01/2025")
+        expected2 = calendar.timegm((2025, 1, 1, 0, 0, 0, 0, 0, 0))
+        assert result2 == expected2
+
+
+class TestFromTimestampUtc:
+    """Tests for UTC-aware datetime.fromtimestamp usage."""
+
+    def test_fromtimestamp_with_utc(self):
+        """datetime.fromtimestamp with UTC timezone gives correct result."""
+        # This tests the pattern used after the fix fix
+        epoch = 1736899200  # 01/15/2025 00:00:00 UTC
+
+        # The correct pattern (after fix)
+        dt_utc = datetime.fromtimestamp(epoch, tz=timezone.utc)
+
+        assert dt_utc.year == 2025
+        assert dt_utc.month == 1
+        assert dt_utc.day == 15
+        assert dt_utc.hour == 0
+        assert dt_utc.minute == 0
+        assert dt_utc.second == 0
+        assert dt_utc.tzinfo == timezone.utc
+
+    def test_calendar_timegm_inverse(self):
+        """calendar.timegm is the inverse of datetime.fromtimestamp(tz=utc)."""
+        original_epoch = 1736899200
+
+        # Convert to datetime
+        dt = datetime.fromtimestamp(original_epoch, tz=timezone.utc)
+
+        # Convert back to epoch
+        timetuple = dt.timetuple()
+        recovered_epoch = calendar.timegm(timetuple)
+
+        assert recovered_epoch == original_epoch
+
+
+class TestTimezoneConsistency:
+    """Tests verifying timezone handling is consistent across functions."""
+
+    def test_known_epoch_value(self):
+        """Test against a known epoch value that's verifiable."""
+        # Unix epoch 0 is January 1, 1970, 00:00:00 UTC
+        epoch_zero = 0
+
+        dt = datetime.fromtimestamp(epoch_zero, tz=timezone.utc)
+
+        assert dt.year == 1970
+        assert dt.month == 1
+        assert dt.day == 1
+        assert dt.hour == 0
+
+    def test_y2k_epoch(self):
+        """Test Y2K timestamp (known reference point)."""
+        # January 1, 2000, 00:00:00 UTC = 946684800
+        y2k_epoch = 946684800
+
+        dt = datetime.fromtimestamp(y2k_epoch, tz=timezone.utc)
+
+        assert dt.year == 2000
+        assert dt.month == 1
+        assert dt.day == 1
+        assert dt.hour == 0
diff --git a/tests/unit/test_vastai_base.py b/tests/unit/test_vastai_base.py
new file mode 100644
index 00000000..1b5792b4
--- /dev/null
+++ b/tests/unit/test_vastai_base.py
@@ -0,0 +1,445 @@
+"""Unit tests for VastAIBase class method signatures and structure.
+
+This module verifies that VastAIBase methods exist with correct signatures,
+ensuring backwards compatibility and API contract stability.
+"""
+
+import pytest
+import inspect
+from abc import ABC
+import sys
+from pathlib import Path
+
+# Add vast-cli to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from vastai.vastai_base import VastAIBase
+
+
+class TestVastAIBaseClassStructure:
+    """Verify VastAIBase class structure and attributes."""
+
+    def test_is_abstract_base_class(self):
+        """VastAIBase should inherit from ABC."""
+        assert issubclass(VastAIBase, ABC)
+
+    def test_has_docstring(self):
+        """VastAIBase should have a class docstring."""
+        assert VastAIBase.__doc__ is not None
+        assert len(VastAIBase.__doc__) > 0
+
+    def test_docstring_mentions_sdk(self):
+        """Docstring should describe SDK purpose."""
+        assert "SDK" in VastAIBase.__doc__ or "sdk" in VastAIBase.__doc__.lower()
+
+
+class TestVastAIBaseInstanceMethodSignatures:
+    """Verify instance method signatures exist with correct parameters."""
+
+    def test_attach_ssh_signature(self):
+        """attach_ssh should have instance_id and ssh_key parameters."""
+        sig = inspect.signature(VastAIBase.attach_ssh)
+        params = list(sig.parameters.keys())
+        assert "self" in params
+        assert "instance_id" in params
+        assert "ssh_key" in params
+
+    def test_cancel_copy_signature(self):
+        """cancel_copy should have dst parameter."""
+        sig = inspect.signature(VastAIBase.cancel_copy)
+        params = list(sig.parameters.keys())
+        assert "self" in params
+        assert "dst" in params
+
+    def test_cancel_sync_signature(self):
+        """cancel_sync should have dst parameter."""
+        sig = inspect.signature(VastAIBase.cancel_sync)
+        params = list(sig.parameters.keys())
+        assert "self" in params
+        assert "dst" in params
+
+    def test_change_bid_signature(self):
+        """change_bid should have id and optional price parameters."""
+        sig = inspect.signature(VastAIBase.change_bid)
+        params = sig.parameters
+        assert "self" in params
+        assert "id" in params
+        assert "price" in params
+        assert params["price"].default is None
+
+    def test_copy_signature(self):
+        """copy should have src, dst, and optional identity parameters."""
+        sig = inspect.signature(VastAIBase.copy)
+        params = sig.parameters
+        assert "self" in params
+        assert "src" in params
+        assert "dst" in params
+        assert "identity" in params
+
+    def test_create_instance_signature(self):
+        """create_instance should have id as int and disk with default 10."""
+        sig = inspect.signature(VastAIBase.create_instance)
+        params = sig.parameters
+        assert "self" in params
+        assert "id" in params
+        assert "disk" in params
+        assert params["disk"].default == 10
+        assert "image" in params
+        assert "ssh" in params
+        assert "jupyter" in params
+
+    def test_create_workergroup_signature(self):
+        """create_workergroup should have expected parameters."""
+        sig = inspect.signature(VastAIBase.create_workergroup)
+        params = sig.parameters
+        assert "self" in params
+        assert "test_workers" in params
+        assert params["test_workers"].default == 3
+        assert "gpu_ram" in params
+        assert "template_hash" in params
+        assert "endpoint_name" in params
+
+    def test_create_endpoint_signature(self):
+        """create_endpoint should have min_load, target_util, cold_mult defaults."""
+        sig = inspect.signature(VastAIBase.create_endpoint)
+        params = sig.parameters
+        assert "self" in params
+        assert "min_load" in params
+        assert params["min_load"].default == 0.0
+        assert "target_util" in params
+        assert params["target_util"].default == 0.9
+        assert "cold_mult" in params
+        assert params["cold_mult"].default == 2.5
+
+    def test_destroy_instance_signature(self):
+        """destroy_instance should have id parameter."""
+        sig = inspect.signature(VastAIBase.destroy_instance)
+        params = list(sig.parameters.keys())
+        assert "self" in params
+        assert "id" in params
+
+    def test_destroy_instances_signature(self):
+        """destroy_instances should have ids list parameter."""
+        sig = inspect.signature(VastAIBase.destroy_instances)
+        params = list(sig.parameters.keys())
+        assert "self" in params
+        assert "ids" in params
+
+    def test_execute_signature(self):
+        """execute should have id and COMMAND parameters."""
+        sig = inspect.signature(VastAIBase.execute)
+        params = list(sig.parameters.keys())
+        assert "self" in params
+        assert "id" in params
+        assert "COMMAND" in params
+
+    def test_search_offers_signature(self):
+        """search_offers should have type, query, limit and other parameters."""
+        sig = inspect.signature(VastAIBase.search_offers)
+        params = sig.parameters
+        assert "self" in params
+        assert "type" in params
+        assert "query" in params
+        assert "limit" in params
+        assert "no_default" in params
+        assert params["no_default"].default is False
+
+    def test_show_instances_signature(self):
+        """show_instances should have quiet parameter with False default."""
+        sig = inspect.signature(VastAIBase.show_instances)
+        params = sig.parameters
+        assert "self" in params
+        assert "quiet" in params
+        assert params["quiet"].default is False
+
+    def test_logs_signature(self):
+        """logs should have INSTANCE_ID and optional tail parameters."""
+        sig = inspect.signature(VastAIBase.logs)
+        params = sig.parameters
+        assert "self" in params
+        assert "INSTANCE_ID" in params
+        assert "tail" in params
+
+
+class TestVastAIBaseVolumeMethodSignatures:
+    """Verify volume method signatures."""
+
+    def test_clone_volume_signature(self):
+        """clone_volume should have source, dest, size, disable_compression."""
+        sig = inspect.signature(VastAIBase.clone_volume)
+        params = sig.parameters
+        assert "self" in params
+        assert "source" in params
+        assert "dest" in params
+        assert "size" in params
+        assert "disable_compression" in params
+        assert params["disable_compression"].default is False
+
+    def test_create_volume_signature(self):
+        """create_volume should have id, size with default 15, and optional name."""
+        sig = inspect.signature(VastAIBase.create_volume)
+        params = sig.parameters
+        assert "self" in params
+        assert "id" in params
+        assert "size" in params
+        assert params["size"].default == 15
+        assert "name" in params
+
+    def test_delete_volume_signature(self):
+        """delete_volume should have id parameter."""
+        sig = inspect.signature(VastAIBase.delete_volume)
+        params = list(sig.parameters.keys())
+        assert "self" in params
+        assert "id" in params
+
+    def test_search_volumes_signature(self):
+        """search_volumes should have query, no_default, limit, storage, order."""
+        sig = inspect.signature(VastAIBase.search_volumes)
+        params = sig.parameters
+        assert "self" in params
+        assert "query" in params
+        assert "no_default" in params
+        assert "limit" in params
+        assert "storage" in params
+        assert params["storage"].default == 1.0
+        assert "order" in params
+        assert params["order"].default == "score-"
+
+    def test_show_volumes_signature(self):
+        """show_volumes should have type parameter with 'all' default."""
+        sig = inspect.signature(VastAIBase.show_volumes)
+        params = sig.parameters
+        assert "self" in params
+        assert "type" in params
+        assert params["type"].default == "all"
+
+
+class TestVastAIBaseClusterMethodSignatures:
+    """Verify cluster method signatures."""
+
+    def test_create_cluster_signature(self):
+        """create_cluster should have subnet and manager_id parameters."""
+        sig = inspect.signature(VastAIBase.create_cluster)
+        params = list(sig.parameters.keys())
+        assert "self" in params
+        assert "subnet" in params
+        assert "manager_id" in params
+
+    def test_delete_cluster_signature(self):
+        """delete_cluster should have cluster_id parameter."""
+        sig = inspect.signature(VastAIBase.delete_cluster)
+        params = list(sig.parameters.keys())
+        assert "self" in params
+        assert "cluster_id" in params
+
+    def test_join_cluster_signature(self):
+        """join_cluster should have cluster_id and machine_ids parameters."""
+        sig = inspect.signature(VastAIBase.join_cluster)
+        params = list(sig.parameters.keys())
+        assert "self" in params
+        assert "cluster_id" in params
+        assert "machine_ids" in params
+
+    def test_show_clusters_signature(self):
+        """show_clusters should exist with self parameter only."""
+        sig = inspect.signature(VastAIBase.show_clusters)
+        params = list(sig.parameters.keys())
+        assert "self" in params
+
+
+class TestVastAIBaseOverlayMethodSignatures:
+    """Verify overlay method signatures."""
+
+    def test_create_overlay_signature(self):
+        """create_overlay should have cluster_id and name parameters."""
+        sig = inspect.signature(VastAIBase.create_overlay)
+        params = list(sig.parameters.keys())
+        assert "self" in params
+        assert "cluster_id" in params
+        assert "name" in params
+
+    def test_delete_overlay_signature(self):
+        """delete_overlay should have overlay_identifier parameter."""
+        sig = inspect.signature(VastAIBase.delete_overlay)
+        params = list(sig.parameters.keys())
+        assert "self" in params
+        assert "overlay_identifier" in params
+
+    def test_join_overlay_signature(self):
+        """join_overlay should have name and instance_id parameters."""
+        sig = inspect.signature(VastAIBase.join_overlay)
+        params = list(sig.parameters.keys())
+        assert "self" in params
+        assert "name" in params
+        assert "instance_id" in params
+
+    def test_show_overlays_signature(self):
+        """show_overlays should exist with self parameter only."""
+        sig = inspect.signature(VastAIBase.show_overlays)
+        params = list(sig.parameters.keys())
+        assert "self" in params
+
+
+class TestVastAIBaseEnvVarMethodSignatures:
+    """Verify environment variable method signatures."""
+
+    def test_create_env_var_signature(self):
+        """create_env_var should have name and value parameters."""
+        sig = inspect.signature(VastAIBase.create_env_var)
+        params = list(sig.parameters.keys())
+        assert "self" in params
+        assert "name" in params
+        assert "value" in params
+
+    def test_delete_env_var_signature(self):
+        """delete_env_var should have name parameter."""
+        sig = inspect.signature(VastAIBase.delete_env_var)
+        params = list(sig.parameters.keys())
+        assert "self" in params
+        assert "name" in params
+
+    def test_update_env_var_signature(self):
+        """update_env_var should have name and value parameters."""
+        sig = inspect.signature(VastAIBase.update_env_var)
+        params = list(sig.parameters.keys())
+        assert "self" in params
+        assert "name" in params
+        assert "value" in params
+
+    def test_show_env_vars_signature(self):
+        """show_env_vars should have show_values parameter with False default."""
+        sig = inspect.signature(VastAIBase.show_env_vars)
+        params = sig.parameters
+        assert "self" in params
+        assert "show_values" in params
+        assert params["show_values"].default is False
+
+
+class TestVastAIBaseBackwardsCompatibility:
+    """Verify backwards compatibility aliases exist and point to correct methods."""
+
+    def test_create_autogroup_is_create_workergroup(self):
+        """create_autogroup should be an alias for create_workergroup."""
+        assert VastAIBase.create_autogroup is VastAIBase.create_workergroup
+
+    def test_delete_autoscaler_is_delete_workergroup(self):
+        """delete_autoscaler should be an alias for delete_workergroup."""
+        assert VastAIBase.delete_autoscaler is VastAIBase.delete_workergroup
+
+    def test_update_autoscaler_is_update_workergroup(self):
+        """update_autoscaler should be an alias for update_workergroup."""
+        assert VastAIBase.update_autoscaler is VastAIBase.update_workergroup
+
+    def test_show_autoscalers_is_show_workergroups(self):
+        """show_autoscalers should be an alias for show_workergroups."""
+        assert VastAIBase.show_autoscalers is VastAIBase.show_workergroups
+
+
+class TestVastAIBaseMethodCount:
+    """Verify expected number of public methods exist."""
+
+    def test_has_many_methods(self):
+        """VastAIBase should have 100+ public methods."""
+        methods = [
+            m for m in dir(VastAIBase)
+            if not m.startswith('_') and callable(getattr(VastAIBase, m))
+        ]
+        assert len(methods) >= 100, f"Expected 100+ methods, got {len(methods)}"
+
+    def test_no_missing_core_methods(self):
+        """Essential methods should exist."""
+        core_methods = [
+            'attach_ssh', 'cancel_copy', 'change_bid', 'copy',
+            'create_instance', 'destroy_instance', 'execute',
+            'search_offers', 'show_instances', 'logs',
+            'create_volume', 'delete_volume', 'show_volumes',
+            'create_cluster', 'show_clusters',
+            'create_overlay', 'show_overlays',
+            'create_env_var', 'show_env_vars',
+        ]
+        for method in core_methods:
+            assert hasattr(VastAIBase, method), f"Missing method: {method}"
+            assert callable(getattr(VastAIBase, method)), f"Not callable: {method}"
+
+
+class TestVastAIBaseMethodDocstrings:
+    """Verify methods have docstrings for IDE autocomplete support."""
+
+    def test_attach_ssh_has_docstring(self):
+        """attach_ssh should have a docstring."""
+        assert VastAIBase.attach_ssh.__doc__ is not None
+
+    def test_create_instance_has_docstring(self):
+        """create_instance should have a docstring."""
+        assert VastAIBase.create_instance.__doc__ is not None
+
+    def test_search_offers_has_docstring(self):
+        """search_offers should have a docstring."""
+        assert VastAIBase.search_offers.__doc__ is not None
+
+    def test_create_volume_has_docstring(self):
+        """create_volume should have a docstring."""
+        assert VastAIBase.create_volume.__doc__ is not None
+
+    def test_create_cluster_has_docstring(self):
+        """create_cluster should have a docstring."""
+        assert VastAIBase.create_cluster.__doc__ is not None
+
+    def test_show_invoices_v1_has_docstring(self):
+        """show_invoices_v1 should have a docstring."""
+        assert VastAIBase.show_invoices_v1.__doc__ is not None
+
+
+class TestVastAIBaseAdditionalMethodSignatures:
+    """Additional method signature tests for coverage."""
+
+    def test_take_snapshot_signature(self):
+        """take_snapshot should have instance_id, repo, and other parameters."""
+        sig = inspect.signature(VastAIBase.take_snapshot)
+        params = sig.parameters
+        assert "self" in params
+        assert "instance_id" in params
+        assert "repo" in params
+        assert "container_registry" in params
+        assert params["container_registry"].default == "docker.io"
+
+    def test_update_instance_signature(self):
+        """update_instance should have id and optional template parameters."""
+        sig = inspect.signature(VastAIBase.update_instance)
+        params = sig.parameters
+        assert "self" in params
+        assert "id" in params
+        assert "template_id" in params
+        assert "template_hash_id" in params
+
+    def test_vm_copy_signature(self):
+        """vm_copy should have src and dst parameters."""
+        sig = inspect.signature(VastAIBase.vm_copy)
+        params = list(sig.parameters.keys())
+        assert "self" in params
+        assert "src" in params
+        assert "dst" in params
+
+    def test_get_endpt_logs_signature(self):
+        """get_endpt_logs should have id, level, and tail parameters."""
+        sig = inspect.signature(VastAIBase.get_endpt_logs)
+        params = sig.parameters
+        assert "self" in params
+        assert "id" in params
+        assert "level" in params
+        assert params["level"].default == 1
+        assert "tail" in params
+
+    def test_show_invoices_v1_signature(self):
+        """show_invoices_v1 should have extensive filtering parameters."""
+        sig = inspect.signature(VastAIBase.show_invoices_v1)
+        params = sig.parameters
+        assert "self" in params
+        assert "invoices" in params
+        assert "charges" in params
+        assert "invoice_type" in params
+        assert "charge_type" in params
+        assert "limit" in params
+        assert params["limit"].default == 20
+        assert "format" in params
+        assert params["format"].default == "table"
diff --git a/vast.py b/vast.py
index 4d737770..ded88cc7 100755
--- a/vast.py
+++ b/vast.py
@@ -9,7 +9,8 @@
 import argparse
 import os
 import time
-from typing import Dict, List, Tuple, Optional
+import calendar
+from typing import Any, Dict, List, Tuple, Optional
 from datetime import date, datetime, timedelta, timezone
 import hashlib
 import math
@@ -21,6 +22,7 @@
 from time import sleep
 from subprocess import PIPE
 import urllib3
+import ssl
 import atexit
 from contextlib import redirect_stdout, redirect_stderr
 from io import StringIO
@@ -43,7 +45,7 @@
 try:
     import argcomplete
     TABCOMPLETE = True
-except:
+except ImportError:
     # No tab-completion for you
     pass
 
@@ -57,15 +59,7 @@
 except ImportError:
     from urllib.parse import quote_plus  # Python 3+
 
-try:
-    JSONDecodeError = json.JSONDecodeError
-except AttributeError:
-    JSONDecodeError = ValueError
-
-try:
-    input = raw_input
-except NameError:
-    pass
+JSONDecodeError = json.JSONDecodeError
 
 
 #server_url_default = "https://vast.ai"
@@ -80,6 +74,10 @@
     format="%(levelname)s - %(message)s"
 )
 
+DEFAULT_TIMEOUT = 30    # seconds -- normal API calls
+LONG_TIMEOUT = 120      # seconds -- file operations, large queries
+RETRYABLE_STATUS_CODES = {429, 502, 503, 504}
+
 def parse_version(version: str) -> tuple[int, ...]:
     parts = version.split(".")
 
@@ -117,14 +115,15 @@ def is_pip_package():
     except Exception:
         return False
 
-def get_update_command(stable_version: str) -> str:
+def get_update_command(stable_version: str) -> list:
     if is_pip_package():
+        cmd = [sys.executable, "-m", "pip", "install", "--force-reinstall", "--no-cache-dir"]
         if "test.pypi.org" in PYPI_BASE_PATH:
-            return f"{sys.executable} -m pip install --force-reinstall --no-cache-dir -i {PYPI_BASE_PATH} vastai=={stable_version}"
-        else:
-            return f"{sys.executable} -m pip install --force-reinstall --no-cache-dir vastai=={stable_version}"
+            cmd.extend(["-i", PYPI_BASE_PATH])
+        cmd.append(f"vastai=={stable_version}")
+        return cmd
     else:
-        return f"git fetch --all --tags --prune && git checkout tags/v{stable_version}"
+        return ["git", "fetch", "--all", "--tags", "--prune"]
 
 
 def get_local_version():
@@ -135,7 +134,7 @@ def get_local_version():
 
 def get_project_data(project_name: str) -> dict[str, dict[str, str]]:
     url = PYPI_BASE_PATH + f"/pypi/{project_name}/json"
-    response = requests.get(url, headers={"Accept": "application/json"})
+    response = requests.get(url, headers={"Accept": "application/json"}, timeout=10)
 
     # this will raise for HTTP status 4xx and 5xx
     response.raise_for_status()
@@ -184,12 +183,20 @@ def check_for_update():
     print("Updating...")
     _ = subprocess.run(
         update_command,
-        shell=True,
         check=True,
         text=True,
         stdout=subprocess.PIPE,
         stderr=subprocess.PIPE,
     )
+    if not is_pip_package():
+        # git case: need a second command to checkout the tag
+        _ = subprocess.run(
+            ["git", "checkout", f"tags/v{pypi_version}"],
+            check=True,
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
 
     print("Update completed successfully!\nAttempt to run your command again!")
     sys.exit(0)
@@ -197,12 +204,6 @@ def check_for_update():
 APP_NAME = "vastai"
 VERSION = get_local_version()
 
-# define emoji support and fallbacks
-_HAS_EMOJI = sys.stdout.encoding and 'utf' in sys.stdout.encoding.lower()
-SUCCESS = "✅" if _HAS_EMOJI else "[OK]"
-WARN    = "⚠️" if _HAS_EMOJI else "[!]"
-FAIL    = "❌" if _HAS_EMOJI else "[X]"
-INFO    = "ℹ️" if _HAS_EMOJI else "[i]"
 
 try:
   # Although xdg-base-dirs is the newer name, there's 
@@ -218,7 +219,7 @@ def check_for_update():
       'temp': xdg.xdg_cache_home()
   }
 
-except:
+except (ImportError, KeyError, OSError):
   # Reasonable defaults.
   DIRS = {
       'config': os.path.join(os.getenv('HOME'), '.config'),
@@ -237,6 +238,13 @@ def check_for_update():
 APIKEY_FILE_HOME = os.path.expanduser("~/.vast_api_key") # Legacy
 TFAKEY_FILE = os.path.join(DIRS['config'], "vast_tfa_key")
 
+# Emoji support with fallbacks for terminals that don't support Unicode
+_HAS_EMOJI = sys.stdout.encoding and 'utf' in sys.stdout.encoding.lower()
+SUCCESS = "\u2705" if _HAS_EMOJI else "[OK]"
+WARN    = "\u26a0\ufe0f" if _HAS_EMOJI else "[!]"
+FAIL    = "\u274c" if _HAS_EMOJI else "[X]"
+INFO    = "\u2139\ufe0f" if _HAS_EMOJI else "[i]"
+
 if not os.path.exists(APIKEY_FILE) and os.path.exists(APIKEY_FILE_HOME):
   #print(f'copying key from {APIKEY_FILE_HOME} -> {APIKEY_FILE}')
   shutil.copyfile(APIKEY_FILE_HOME, APIKEY_FILE)
@@ -287,11 +295,11 @@ def string_to_unix_epoch(date_string):
     except ValueError:
         # If not, parse it as a date string
         date_object = datetime.strptime(date_string, "%m/%d/%Y")
-        return time.mktime(date_object.timetuple())
+        return calendar.timegm(date_object.timetuple())
 
 def unix_to_readable(ts):
     # ts: integer or float, Unix timestamp
-    return datetime.fromtimestamp(ts).strftime('%H:%M:%S|%h-%d-%Y')
+    return datetime.fromtimestamp(ts, tz=timezone.utc).strftime('%H:%M:%S|%h-%d-%Y')
 
 def fix_date_fields(query: Dict[str, Dict], date_fields: List[str]):
     """Takes in a query and date fields to correct and returns query with appropriate epoch dates"""
@@ -330,18 +338,13 @@ def __nonzero__(self):
     def append(self, x):
         self.l.append(x)
 
-def http_request(verb, args, req_url, headers: dict[str, str] | None = None, json_data = None):
+def http_request(verb, args, req_url, headers: dict[str, str] | None = None, json = None, timeout=DEFAULT_TIMEOUT):
     t = 0.15
+    r = None
     for i in range(0, args.retry):
-        req = requests.Request(method=verb, url=req_url, headers=headers, json=json_data)
+        req = requests.Request(method=verb, url=req_url, headers=headers, json=json)
         session = requests.Session()
         prep = session.prepare_request(req)
-        if args.explain:
-            print(f"\n{INFO}  Prepared Request:")
-            print(f"{prep.method} {prep.url}")
-            print(f"Headers: {json.dumps(headers, indent=1)}")
-            print(f"Body: {json.dumps(json_data, indent=1)}" + "\n" + "_"*100 + "\n")
-        
         if ARGS.curl:
             as_curl = curlify.to_curl(prep)
             simple = re.sub(r" -H '[^']*'", '', as_curl)
@@ -352,26 +355,42 @@ def http_request(verb, args, req_url, headers: dict[str, str] | None = None, jso
             print("\n" + ' \\\n  '.join(parts).strip() + "\n")
             sys.exit(0)
         else:
-            r = session.send(prep)
+            try:
+                r = session.send(prep, timeout=timeout)
+            except (requests.exceptions.ConnectionError, requests.exceptions.Timeout) as e:
+                if i < args.retry - 1:
+                    time.sleep(t)
+                    t *= 1.5
+                    continue
+                raise
+            except requests.exceptions.RequestException as e:
+                # Non-retryable request errors (e.g., InvalidURL)
+                raise
 
-        if (r.status_code == 429):
+        if r.status_code in RETRYABLE_STATUS_CODES:
             time.sleep(t)
             t *= 1.5
         else:
             break
     return r
 
-def http_get(args, req_url, headers = None, json = None):
-    return http_request('GET', args, req_url, headers, json)
+def http_get(args, req_url, headers=None, json=None, timeout=DEFAULT_TIMEOUT):
+    return http_request('GET', args, req_url, headers, json, timeout=timeout)
 
-def http_put(args, req_url, headers = None, json = {}):
-    return http_request('PUT', args, req_url, headers, json)
+def http_put(args, req_url, headers=None, json=None, timeout=DEFAULT_TIMEOUT):
+    if json is None:
+        json = {}
+    return http_request('PUT', args, req_url, headers, json, timeout=timeout)
 
-def http_post(args, req_url, headers = None, json={}):
-    return http_request('POST', args, req_url, headers, json)
+def http_post(args, req_url, headers=None, json=None, timeout=DEFAULT_TIMEOUT):
+    if json is None:
+        json = {}
+    return http_request('POST', args, req_url, headers, json, timeout=timeout)
 
-def http_del(args, req_url, headers = None, json={}):
-    return http_request('DELETE', args, req_url, headers, json)
+def http_del(args, req_url, headers=None, json=None, timeout=DEFAULT_TIMEOUT):
+    if json is None:
+        json = {}
+    return http_request('DELETE', args, req_url, headers, json, timeout=timeout)
 
 
 def load_permissions_from_file(file_path):
@@ -630,7 +649,7 @@ def apiheaders(args: argparse.Namespace) -> Dict:
     return result 
 
 
-def deindent(message: str, add_separator: bool = True) -> str:
+def deindent(message: str) -> str:
     """
     Deindent a quoted string. Scans message and finds the smallest number of whitespace characters in any line and
     removes that many from the start of every line.
@@ -642,13 +661,141 @@ def deindent(message: str, add_separator: bool = True) -> str:
     indents = [len(x) for x in re.findall("^ *(?=[^ ])", message, re.MULTILINE) if len(x)]
     a = min(indents)
     message = re.sub(r"^ {," + str(a) + "}", "", message, flags=re.MULTILINE)
-    if add_separator:
-        # For help epilogs - cleanly separating extra help from options
-        line_width = min(150, shutil.get_terminal_size((80, 20)).columns)
-        message = "_"*line_width + "\n"*2 + message.strip() + "\n" + "_"*line_width
     return message.strip()
 
 
+def api_call(
+    args: argparse.Namespace,
+    method: str,
+    path: str,
+    *,
+    json_body: dict[str, Any] | None = None,
+    query_args: dict[str, Any] | None = None,
+) -> dict[str, Any] | list[dict[str, Any]] | None:
+    """Centralized API call: URL construction + HTTP dispatch + status check.
+
+    Args:
+        args: argparse.Namespace with url, api_key, explain, raw, retry, curl.
+        method: HTTP method string ("GET", "POST", "PUT", "DELETE").
+        path: API path (e.g., "/instances/", "/auth/apikeys/{id}/").
+        json_body: Optional dict for request body (POST/PUT/DELETE).
+        query_args: Optional dict for URL query parameters.
+
+    Returns:
+        Parsed JSON response (dict or list), or None for empty responses.
+
+    Raises:
+        requests.exceptions.HTTPError: On non-2xx status codes.
+    """
+    url = apiurl(args, path, query_args)
+    dispatch = {
+        "GET": http_get,
+        "POST": http_post,
+        "PUT": http_put,
+        "DELETE": http_del,
+    }
+    http_fn = dispatch[method]
+
+    if method == "GET":
+        r = http_fn(args, url, headers=headers, json=json_body)
+    else:
+        r = http_fn(args, url, headers=headers, json=json_body if json_body is not None else {})
+
+    r.raise_for_status()
+
+    if r.content:
+        try:
+            return r.json()
+        except JSONDecodeError:
+            return {"_raw_text": r.text}
+    return None
+
+
+def output_result(
+    args: argparse.Namespace,
+    data: list[dict[str, Any]] | dict[str, Any],
+    fields: list[tuple[str, str, str]] | None = None,
+) -> list[dict[str, Any]] | dict[str, Any] | None:
+    """Unified output handler for command results.
+
+    In raw mode: returns data for main() to serialize as JSON.
+    In table mode: calls display_table() if fields are provided.
+    In JSON mode: prints formatted JSON (when no fields defined).
+
+    Args:
+        args: argparse.Namespace with raw flag.
+        data: The response data (dict, list, or None).
+        fields: Optional tuple of field definitions for display_table().
+
+    Returns:
+        data if in raw mode, None otherwise.
+    """
+    if args.raw:
+        return data
+    if data is None:
+        return None
+    if fields:
+        rows = data if isinstance(data, list) else [data]
+        display_table(rows, fields)
+    else:
+        print(json.dumps(data, indent=1, sort_keys=True))
+    return None
+
+
+def error_output(
+    args: argparse.Namespace,
+    status_code: int,
+    message: str,
+    *,
+    detail: str | None = None,
+) -> None:
+    """Output an error in the appropriate format for the current mode.
+
+    In raw mode: prints JSON error object to stderr.
+    In non-raw mode: prints human-readable error to stderr.
+
+    Args:
+        args: argparse.Namespace with raw flag.
+        status_code: HTTP status code or error code.
+        message: Error message string.
+        detail: Optional additional detail string.
+    """
+    if getattr(args, 'raw', False):
+        error = {"error": True, "status_code": status_code, "msg": message}
+        if detail:
+            error["detail"] = detail
+        print(json.dumps(error), file=sys.stderr)
+    else:
+        print(f"failed with error {status_code}: {message}", file=sys.stderr)
+
+
+def require_id(args: argparse.Namespace, field: str = "id") -> int | str:
+    """Extract and validate an ID argument.
+
+    Args:
+        args: argparse.Namespace containing the ID field.
+        field: Name of the attribute on args (default "id").
+
+    Returns:
+        The value of the requested field.
+
+    Raises:
+        SystemExit: If the field is None or missing.
+    """
+    val = getattr(args, field, None)
+    if val is None:
+        print(f"Error: {field} is required", file=sys.stderr)
+        raise SystemExit(1)
+    return val
+
+
+# Field definition tuples: (key, display_name, format_string, converter_or_None, left_justify)
+# key: API response dict key
+# display_name: Column header in table output
+# format_string: Python format spec (e.g., ">8", "<16", ">10.4f")
+# converter_or_None: Lambda to transform value, or None for raw value
+# left_justify: Boolean, True for left-aligned columns
+
 # These are the fields that are displayed when a search is run
 displayable_fields = (
     # ("bw_nvlink", "Bandwidth NVLink", "{}", None, True),
@@ -873,8 +1020,8 @@ def deindent(message: str, add_separator: bool = True) -> str:
 # These fields are displayed when you do 'show maints'
 maintenance_fields = (
     ("machine_id", "Machine ID", "{}", None, True),
-    ("start_time", "Start (Date/Time)", "{}", lambda x: datetime.fromtimestamp(x).strftime('%Y-%m-%d/%H:%M'), True),
-    ("end_time", "End (Date/Time)", "{}", lambda x: datetime.fromtimestamp(x).strftime('%Y-%m-%d/%H:%M'), True),
+    ("start_time", "Start (Date/Time)", "{}", lambda x: datetime.fromtimestamp(x, tz=timezone.utc).strftime('%Y-%m-%d/%H:%M'), True),
+    ("end_time", "End (Date/Time)", "{}", lambda x: datetime.fromtimestamp(x, tz=timezone.utc).strftime('%Y-%m-%d/%H:%M'), True),
     ("duration_hours", "Duration (Hrs)", "{}", None, True),
     ("maintenance_category", "Category", "{}", None, True),
 )
@@ -899,8 +1046,8 @@ def deindent(message: str, add_separator: bool = True) -> str:
     ("id", "Scheduled Job ID", "{}", None, True),
     ("instance_id", "Instance ID", "{}", None, True),
     ("api_endpoint", "API Endpoint", "{}", None, True),
-    ("start_time", "Start (Date/Time in UTC)", "{}", lambda x: datetime.fromtimestamp(x).strftime('%Y-%m-%d/%H:%M'), True),
-    ("end_time", "End (Date/Time in UTC)", "{}", lambda x: datetime.fromtimestamp(x).strftime('%Y-%m-%d/%H:%M'), True),
+    ("start_time", "Start (Date/Time in UTC)", "{}", lambda x: datetime.fromtimestamp(x, tz=timezone.utc).strftime('%Y-%m-%d/%H:%M'), True),
+    ("end_time", "End (Date/Time in UTC)", "{}", lambda x: datetime.fromtimestamp(x, tz=timezone.utc).strftime('%Y-%m-%d/%H:%M'), True),
     ("day_of_the_week", "Day of the Week", "{}", None, True),
     ("hour_of_the_day", "Hour of the Day in UTC", "{}", None, True),
     ("min_of_the_hour", "Minute of the Hour", "{}", None, True),
@@ -1105,13 +1252,16 @@ def parse_query(query_str: str, res: Dict = None, fields = {}, field_alias = {},
 
     for field, op, _, value, _ in opts:
         value = value.strip(",[]")
-        v = res.setdefault(field, {})
         op = op.strip()
         op_name = op_names.get(op)
 
         if field in field_alias:
-            res.pop(field)
+            old_field = field
             field = field_alias[field]
+            if old_field in res:
+                res[field] = res.pop(old_field)
+
+        v = res.setdefault(field, {})
 
         if (field == "driver_version") and ('.' in value):
             value = numeric_version(value)
@@ -1163,23 +1313,35 @@ def parse_query(query_str: str, res: Dict = None, fields = {}, field_alias = {},
     #print(res)
     return res
 
-# ANSI escape codes for background/foreground colors
-BG_DARK_GRAY = '\033[40m'  # Dark gray background
-BG_LIGHT_GRAY = '\033[48;5;240m' # Light gray background
-FG_WHITE = '\033[97m'            # Bright white text
-BG_RESET = '\033[0m'             # Reset all formatting
 
-def display_table(rows: list, fields: Tuple, replace_spaces: bool = True, auto_width: bool = True) -> None:
-    """Basically takes a set of field names and rows containing the corresponding data and prints a nice tidy table
-    of it.
+# ANSI color codes for table formatting
+BG_DARK_GRAY = '\033[40m'       # Dark gray background
+BG_LIGHT_GRAY = '\033[48;5;240m'  # Light gray background
+FG_WHITE = '\033[97m'           # Bright white text
+BG_RESET = '\033[0m'            # Reset all formatting
 
-    :param list rows: Each row is a dict with keys corresponding to the field names (first element) in the fields tuple.
 
-    :param Tuple fields: 5-tuple describing a field. First element is field name, second is human readable version, third is format string, fourth is a lambda function run on the data in that field, fifth is a bool determining text justification. True = left justify, False = right justify. Here is an example showing the tuples in action.
+def display_table(rows: list, fields: Tuple, replace_spaces: bool = True, auto_width: bool = True) -> None:
+    """Display data as a formatted table with automatic column width management.
 
-    :rtype None:
+    Takes a set of field definitions and rows of data and prints a formatted table.
+    When auto_width is enabled, columns are grouped to fit within terminal width,
+    with alternating row colors for readability.
 
-    Example of 5-tuple: ("cpu_ram", "RAM", "{:0.1f}", lambda x: x / 1000, False)
+    Args:
+        rows: List of dicts with keys corresponding to field names in the fields tuple.
+        fields: Tuple of 5-tuples defining each column:
+            - field_name: API response dict key
+            - display_name: Column header text
+            - format_string: Python format spec (e.g., "{:0.1f}")
+            - converter: Lambda to transform value, or None for raw value
+            - left_justify: Boolean, True for left-aligned columns
+        replace_spaces: If True, replace spaces with underscores in cell values.
+        auto_width: If True, automatically group columns to fit terminal width
+            with colored alternating rows. If False, print simple table.
+
+    Example field tuple:
+        ("cpu_ram", "RAM", "{:0.1f}", lambda x: x / 1000, False)
     """
     header = [name for _, name, _, _, _ in fields]
     out_rows = [header]
@@ -1200,7 +1362,7 @@ def display_table(rows: list, fields: Tuple, replace_spaces: bool = True, auto_w
             idx = len(row)
             lengths[idx] = max(len(s), lengths[idx])
             row.append(s)
-    
+
     if auto_width:
         width = shutil.get_terminal_size((80, 20)).columns
         start_col_idxs = [0]
@@ -1210,7 +1372,7 @@ def display_table(rows: list, fields: Tuple, replace_spaces: bool = True, auto_w
             if total_len > width:
                 start_col_idxs.append(i)  # index for the start of the next group
                 total_len = l + 6         # l + 2 + the 4 from the initial length
-        
+
         groups = {}
         for row in out_rows:
             grp_num = 0
@@ -1219,7 +1381,7 @@ def display_table(rows: list, fields: Tuple, replace_spaces: bool = True, auto_w
                 end = start_col_idxs[i+1]-1 if i+1 < len(start_col_idxs) else len(lengths)
                 groups.setdefault(grp_num, []).append(row[start:end])
                 grp_num += 1
-        
+
         for i, group in groups.items():
             idx = start_col_idxs[i]
             group_lengths = lengths[idx:idx+len(group[0])]
@@ -1289,7 +1451,7 @@ def parse_vast_url(url_str):
         try:
             instance_id = int(path)
             path = "/"
-        except:
+        except (ValueError, TypeError):
             pass
 
     valid_unix_path_regex = re.compile('^(/)?([^/\0]+(/)?)+$')
@@ -1317,7 +1479,7 @@ def get_ssh_key(argstr):
         has around 200 or so "base64" characters and ends with 
         some-user@some-where. "Generate public ssh key" would be 
         a good search term if you don't know how to do this.
-      """, add_separator=False))
+      """))
 
     if not ssh_key.lower().startswith('ssh'):
       raise ValueError(deindent("""
@@ -1330,7 +1492,7 @@ def get_ssh_key(argstr):
         {}
 
         And welp, that just don't look right.
-      """.format(ssh_key), add_separator=False))
+      """.format(ssh_key)))
 
     return ssh_key
 
@@ -1338,14 +1500,15 @@ def get_ssh_key(argstr):
 @parser.command(
     argument("instance_id", help="id of instance to attach to", type=int),
     argument("ssh_key", help="ssh key to attach to instance", type=str),
+    description="Attach an SSH key to an instance for remote access",
     usage="vastai attach ssh instance_id ssh_key",
-    help="Attach an ssh key to an instance. This will allow you to connect to the instance with the ssh key",
+    help="Attach an SSH key to an instance for remote access",
     epilog=deindent("""
         Attach an ssh key to an instance. This will allow you to connect to the instance with the ssh key.
 
         Examples:
-         vastai attach "ssh 12371 ssh-rsa AAAAB3NzaC1yc2EAAA..."
-         vastai attach "ssh 12371 ssh-rsa $(cat ~/.ssh/id_rsa)"
+         vastai attach ssh 12371 ssh-rsa AAAAB3NzaC1yc2EAAA...
+         vastai attach ssh 12371 ssh-rsa $(cat ~/.ssh/id_rsa)
     """),
 )
 def attach__ssh(args):
@@ -1354,12 +1517,20 @@ def attach__ssh(args):
     req_json = {"ssh_key": ssh_key}
     r = http_post(args, url, headers=headers, json=req_json)
     r.raise_for_status()
-    print(r.json())
+    try:
+        rj = r.json()
+    except JSONDecodeError:
+        print("Error: API returned invalid JSON response", file=sys.stderr)
+        return
+    if args.raw:
+        return rj
+    print(rj)
 
 @parser.command(
     argument("dst", help="instance_id:/path to target of copy operation", type=str),
+    description="Cancel an in-progress file copy operation",
     usage="vastai cancel copy DST",
-    help="Cancel a remote copy in progress, specified by DST id",
+    help="Cancel an in-progress file copy operation",
     epilog=deindent("""
         Use this command to cancel any/all current remote copy operations copying to a specific named instance, given by DST.
 
@@ -1388,21 +1559,24 @@ def cancel__copy(args: argparse.Namespace):
     req_json = { "client_id": "me", "dst_id": dst_id, }
     r = http_del(args, url, headers=headers,json=req_json)
     r.raise_for_status()
-    if (r.status_code == 200):
+    try:
         rj = r.json();
-        if (rj["success"]):
-            print("Remote copy canceled - check instance status bar for progress updates (~30 seconds delayed).")
-        else:
-            print(rj["msg"]);
+    except JSONDecodeError:
+        print("Error: API returned invalid JSON response", file=sys.stderr)
+        return
+    if args.raw:
+        return rj
+    if rj.get("success"):
+        print("Remote copy canceled - check instance status bar for progress updates (~30 seconds delayed).")
     else:
-        print(r.text);
-        print("failed with error {r.status_code}".format(**locals()));
+        print(rj.get("msg", "Unknown error"));
 
 
 @parser.command(
     argument("dst", help="instance_id:/path to target of sync operation", type=str),
+    description="Cancel an in-progress file sync operation",
     usage="vastai cancel sync DST",
-    help="Cancel a remote copy in progress, specified by DST id",
+    help="Cancel an in-progress file sync operation",
     epilog=deindent("""
         Use this command to cancel any/all current remote cloud sync operations copying to a specific named instance, given by DST.
 
@@ -1431,15 +1605,17 @@ def cancel__sync(args: argparse.Namespace):
     req_json = { "client_id": "me", "dst_id": dst_id, }
     r = http_del(args, url, headers=headers,json=req_json)
     r.raise_for_status()
-    if (r.status_code == 200):
+    try:
         rj = r.json();
-        if (rj["success"]):
-            print("Remote copy canceled - check instance status bar for progress updates (~30 seconds delayed).")
-        else:
-            print(rj["msg"]);
+    except JSONDecodeError:
+        print("Error: API returned invalid JSON response", file=sys.stderr)
+        return
+    if args.raw:
+        return rj
+    if rj.get("success"):
+        print("Remote copy canceled - check instance status bar for progress updates (~30 seconds delayed).")
     else:
-        print(r.text);
-        print("failed with error {r.status_code}".format(**locals()));
+        print(rj.get("msg", "Unknown error"));
 
 def default_start_date():
     return datetime.now(timezone.utc).strftime("%Y-%m-%d")
@@ -1491,6 +1667,7 @@ def parse_hour_cron_style(value):
     argument("--end_date", type=str, default=default_end_date(), help="End date/time in format 'YYYY-MM-DD HH:MM:SS PM' (UTC). Default is 7 days from now. (optional)"),
     argument("--day", type=parse_day_cron_style, help="Day of week you want scheduled job to run on (0-6, where 0=Sunday) or \"*\". Default will be 0. For ex. --day 0", default=0),
     argument("--hour", type=parse_hour_cron_style, help="Hour of day you want scheduled job to run on (0-23) or \"*\" (UTC). Default will be 0. For ex. --hour 16", default=0),
+    description="Change the bid price for a spot/interruptible instance",
     usage="vastai change bid id [--price PRICE]",
     help="Change the bid price for a spot/interruptible instance",
     epilog=deindent("""
@@ -1504,8 +1681,6 @@ def change__bid(args: argparse.Namespace):
     :param argparse.Namespace args: should supply all the command-line options
     :rtype int:
     """
-    url = apiurl(args, "/instances/bid_price/{id}/".format(id=args.id))
-
     json_blob = {"client_id": "me", "price": args.price,}
     if (args.explain):
         print("request json: ")
@@ -1516,12 +1691,13 @@ def change__bid(args: argparse.Namespace):
         cli_command = "change bid"
         api_endpoint = "/api/v0/instances/bid_price/{id}/".format(id=args.id)
         json_blob["instance_id"] = args.id
-        add_scheduled_job(args, json_blob, cli_command, api_endpoint, "PUT", instance_id=args.id)     
+        add_scheduled_job(args, json_blob, cli_command, api_endpoint, "PUT", instance_id=args.id)
         return
-    
-    r = http_put(args, url, headers=headers, json=json_blob)
-    r.raise_for_status()
-    print("Per gpu bid price changed".format(r.json()))
+
+    result = api_call(args, "PUT", "/instances/bid_price/{id}/".format(id=args.id), json_body=json_blob)
+    if args.raw:
+        return result
+    print("Per gpu bid price changed".format(result))
 
 
 
@@ -1530,8 +1706,9 @@ def change__bid(args: argparse.Namespace):
     argument("dest", help="id of volume offer volume is being copied to", type=int),
     argument("-s", "--size", help="Size of new volume contract, in GB. Must be greater than or equal to the source volume, and less than or equal to the destination offer.", type=float),
     argument("-d", "--disable_compression", action="store_true", help="Do not compress volume data before copying."),
+    description="Create a copy of an existing volume",
     usage="vastai copy volume <source_id> <dest_id> [options]",
-    help="Clone an existing volume",
+    help="Create a copy of an existing volume",
     epilog=deindent("""
         Create a new volume with the given offer, by copying the existing volume. 
         Size defaults to the size of the existing volume, but can be increased if there is available space.
@@ -1555,18 +1732,24 @@ def clone__volume(args: argparse.Namespace):
         print(json_blob)
     r = http_post(args, url,  headers=headers,json=json_blob)
     r.raise_for_status()
+    try:
+        rj = r.json()
+    except JSONDecodeError:
+        print("Error: API returned invalid JSON response", file=sys.stderr)
+        return
     if args.raw:
-        return r
+        return rj
     else:
-        print("Created. {}".format(r.json()))
+        print("Created. {}".format(rj))
 
 
 @parser.command(
     argument("src", help="Source location for copy operation (supports multiple formats)", type=str),
     argument("dst", help="Target location for copy operation (supports multiple formats)", type=str),
     argument("-i", "--identity", help="Location of ssh private key", type=str),
+    description="Copy files/directories between instances or between local and instance",
     usage="vastai copy SRC DST",
-    help="Copy directories between instances and/or local",
+    help="Copy files/directories between instances or between local and instance",
     epilog=deindent("""
         Copies a directory from a source location to a target location. Each of source and destination
         directories can be either local or remote, subject to appropriate read and write
@@ -1632,43 +1815,43 @@ def copy(args: argparse.Namespace):
         url = apiurl(args, f"/commands/copy_direct/")
     r = http_put(args, url,  headers=headers,json=req_json)
     r.raise_for_status()
-    if (r.status_code == 200):
+    try:
         rj = r.json()
-        #print(json.dumps(rj, indent=1, sort_keys=True))
-        if (rj["success"]) and ((src_id is None or src_id == "local") or (dst_id is None or dst_id == "local")):
-            homedir = subprocess.getoutput("echo $HOME")
-            #print(f"homedir: {homedir}")
-            remote_port = None
-            identity = f"-i {args.identity}" if (args.identity is not None) else ""
-            if (src_id is None or src_id == "local"):
-                #result = subprocess.run(f"mkdir -p {src_path}", shell=True)
-                remote_port = rj["dst_port"]
-                remote_addr = rj["dst_addr"]
-                cmd = f"rsync -arz -v --progress --rsh=ssh -e 'ssh {identity} -p {remote_port} -o StrictHostKeyChecking=no' {src_path} vastai_kaalia@{remote_addr}::{dst_id}/{dst_path}"
-                print(cmd)
-                result = subprocess.run(cmd, shell=True)
-                #result = subprocess.run(["sudo", "rsync" "-arz", "-v", "--progress", "-rsh=ssh", "-e 'sudo ssh -i {homedir}/.ssh/id_rsa -p {remote_port} -o StrictHostKeyChecking=no'", src_path, "vastai_kaalia@{remote_addr}::{dst_id}"], shell=True)
-            elif (dst_id is None or dst_id == "local"):
-                result = subprocess.run(f"mkdir -p {dst_path}", shell=True)
-                remote_port = rj["src_port"]
-                remote_addr = rj["src_addr"]
-                cmd = f"rsync -arz -v --progress --rsh=ssh -e 'ssh {identity} -p {remote_port} -o StrictHostKeyChecking=no' vastai_kaalia@{remote_addr}::{src_id}/{src_path} {dst_path}"
-                print(cmd)
-                result = subprocess.run(cmd, shell=True)
-                #result = subprocess.run(["sudo", "rsync" "-arz", "-v", "--progress", "-rsh=ssh", "-e 'ssh -i {homedir}/.ssh/id_rsa -p {remote_port} -o StrictHostKeyChecking=no'", "vastai_kaalia@{remote_addr}::{src_id}", dst_path], shell=True)
+    except JSONDecodeError:
+        print("Error: API returned invalid JSON response", file=sys.stderr)
+        return
+    #print(json.dumps(rj, indent=1, sort_keys=True))
+    if rj.get("success") and ((src_id is None or src_id == "local") or (dst_id is None or dst_id == "local")):
+        homedir = os.path.expanduser("~")
+        #print(f"homedir: {homedir}")
+        remote_port = None
+        identity = f"-i {args.identity}" if (args.identity is not None) else ""
+        if (src_id is None or src_id == "local"):
+            remote_port = rj.get("dst_port")
+            remote_addr = rj.get("dst_addr")
+            ssh_cmd = f"ssh {identity} -p {remote_port} -o StrictHostKeyChecking=no".strip()
+            rsync_args = ["rsync", "-arz", "-v", "--progress", "-e", ssh_cmd, src_path, f"vastai_kaalia@{remote_addr}::{dst_id}/{dst_path}"]
+            print(" ".join(rsync_args))
+            result = subprocess.run(rsync_args)
+        elif (dst_id is None or dst_id == "local"):
+            os.makedirs(dst_path, exist_ok=True)
+            remote_port = rj.get("src_port")
+            remote_addr = rj.get("src_addr")
+            ssh_cmd = f"ssh {identity} -p {remote_port} -o StrictHostKeyChecking=no".strip()
+            rsync_args = ["rsync", "-arz", "-v", "--progress", "-e", ssh_cmd, f"vastai_kaalia@{remote_addr}::{src_id}/{src_path}", dst_path]
+            print(" ".join(rsync_args))
+            result = subprocess.run(rsync_args)
+    else:
+        if rj.get("success"):
+            print("Remote to Remote copy initiated - check instance status bar for progress updates (~30 seconds delayed).")
         else:
-            if (rj["success"]):
-                print("Remote to Remote copy initiated - check instance status bar for progress updates (~30 seconds delayed).")
+            msg = rj.get("msg", "Unknown error")
+            if msg == "src_path not supported VMs.":
+                print("copy between VM instances does not currently support subpaths (only full disk copy)")
+            elif msg == "dst_path not supported for VMs.":
+                print("copy between VM instances does not currently support subpaths (only full disk copy)")
             else:
-                if rj["msg"] == "src_path not supported VMs.":
-                    print("copy between VM instances does not currently support subpaths (only full disk copy)")
-                elif rj["msg"] == "dst_path not supported for VMs.":
-                    print("copy between VM instances does not currently support subpaths (only full disk copy)")
-                else:
-                    print(rj["msg"])
-    else:
-        print(r.text)
-        print("failed with error {r.status_code}".format(**locals()));
+                print(msg)
 
 
 '''
@@ -1709,20 +1892,21 @@ def vm__copy(args: argparse.Namespace):
 
     r = http_put(args, url,  headers=headers,json=req_json)
     r.raise_for_status()
-    if (r.status_code == 200):
+    try:
         rj = r.json();
-        if (rj["success"]):
-            print("Remote to Remote copy initiated - check instance status bar for progress updates (~30 seconds delayed).")
-        else:
-            if rj["msg"] == "Invalid src_path.":
-                print("src instance is not a VM")
-            elif rj["msg"] == "Invalid dst_path.":
-                print("dst instance is not a VM")
-            else:
-                print(rj["msg"]);
+    except JSONDecodeError:
+        print("Error: API returned invalid JSON response", file=sys.stderr)
+        return
+    if rj.get("success"):
+        print("Remote to Remote copy initiated - check instance status bar for progress updates (~30 seconds delayed).")
     else:
-        print(r.text);
-        print("failed with error {r.status_code}".format(**locals()));
+        msg = rj.get("msg", "Unknown error")
+        if msg == "Invalid src_path.":
+            print("src instance is not a VM")
+        elif msg == "Invalid dst_path.":
+            print("dst instance is not a VM")
+        else:
+            print(msg);
 '''
 
 @parser.command(
@@ -1741,8 +1925,9 @@ def vm__copy(args: argparse.Namespace):
     argument("--end_date", type=str, help="End date/time in format 'YYYY-MM-DD HH:MM:SS PM' (UTC). Default is contract's end. (optional)"),
     argument("--day", type=parse_day_cron_style, help="Day of week you want scheduled job to run on (0-6, where 0=Sunday) or \"*\". Default will be 0. For ex. --day 0", default=0),
     argument("--hour", type=parse_hour_cron_style, help="Hour of day you want scheduled job to run on (0-23) or \"*\" (UTC). Default will be 0. For ex. --hour 16", default=0),
+    description="Copy files between instances and cloud storage (S3, GCS, Azure)",
     usage="vastai cloud copy --src SRC --dst DST --instance INSTANCE_ID -connection CONNECTION_ID --transfer TRANSFER_TYPE",
-    help="Copy files/folders to and from cloud providers",
+    help="Copy files between instances and cloud storage (S3, GCS, Azure)",
     epilog=deindent("""
         Copies a directory from a source location to a target location. Each of source and destination
         directories can be either local or remote, subject to appropriate read and write
@@ -1810,8 +1995,13 @@ def cloud__copy(args: argparse.Namespace):
         req_url = apiurl(args, "/instances/{id}/".format(id=args.instance) , {"owner": "me"} )
         r = http_get(args, req_url)
         r.raise_for_status()
-        row = r.json()["instances"]
-        
+        try:
+            rj = r.json()
+        except JSONDecodeError:
+            print("Error: API returned invalid JSON response", file=sys.stderr)
+            return
+        row = rj.get("instances")
+
         if args.transfer.lower() == "instance to cloud":
             if row: 
                 # Get the cost per TB of internet upload
@@ -1838,12 +2028,8 @@ def cloud__copy(args: argparse.Namespace):
         
     r = http_post(args, url, headers=headers,json=req_json)
     r.raise_for_status()
-    if (r.status_code == 200):
-        print("Cloud Copy Started - check instance status bar for progress updates (~30 seconds delayed).")
-        print("When the operation is finished you should see 'Cloud Copy Operation Finished' in the instance status bar.")  
-    else:
-        print(r.text);
-        print("failed with error {r.status_code}".format(**locals()));
+    print("Cloud Copy Started - check instance status bar for progress updates (~30 seconds delayed).")
+    print("When the operation is finished you should see 'Cloud Copy Operation Finished' in the instance status bar.")
 
 
 @parser.command(
@@ -1853,10 +2039,11 @@ def cloud__copy(args: argparse.Namespace):
     argument("--docker_login_user",help="Username for container registry with repo",     type=str),
     argument("--docker_login_pass",help="Password or token for container registry with repo",     type=str),
     argument("--pause",            help="Pause container's processes being executed by the CPU to take snapshot (true/false). Default will be true", type=str, default="true"),
+    description="Create a snapshot of a running container and push to registry",
     usage="vastai take snapshot INSTANCE_ID "
           "--repo REPO --docker_login_user USER --docker_login_pass PASS"
           "[--container_registry REGISTRY] [--pause true|false]",
-    help="Schedule a snapshot of a running container and push it to your repo in a container registry",
+    help="Create a snapshot of a running container and push to registry",
     epilog=deindent("""
         Takes a snapshot of a running container instance and pushes snapshot to the specified repository in container registry.
         
@@ -1901,16 +2088,15 @@ def take__snapshot(args: argparse.Namespace):
     # POST to the snapshot endpoint
     r = http_post(args, url, headers=headers, json=req_json)
     r.raise_for_status()
-
-    if r.status_code == 200:
+    try:
         data = r.json()
-        if data.get("success"):
-            print(f"Snapshot request sent successfully. Please check your repo {repo} in container registry {container_registry} in 5-10 mins. It can take longer than 5-10 mins to push your snapshot image to your repo depending on the size of your image.")
-        else:
-            print(data.get("msg", "Unknown error with snapshot request"))
+    except JSONDecodeError:
+        print("Error: API returned invalid JSON response", file=sys.stderr)
+        return
+    if data.get("success"):
+        print(f"Snapshot request sent successfully. Please check your repo {repo} in container registry {container_registry} in 5-10 mins. It can take longer than 5-10 mins to push your snapshot image to your repo depending on the size of your image.")
     else:
-        print(r.text);
-        print("failed with error {r.status_code}".format(**locals()));
+        print(data.get("msg", "Unknown error with snapshot request"))
 
 def validate_frequency_values(day_of_the_week, hour_of_the_day, frequency):
 
@@ -1961,7 +2147,7 @@ def add_scheduled_job(args, req_json, cli_command, api_endpoint, request_method,
                 "instance_id": instance_id
             }
                 # Send a POST request
-    response = requests.post(schedule_job_url, headers=headers, json=request_body)
+    response = http_post(args, schedule_job_url, headers=headers, json=request_body)
 
     if args.explain:
         print("request json: ")
@@ -1975,29 +2161,33 @@ def add_scheduled_job(args, req_json, cli_command, api_endpoint, request_method,
     elif response.status_code == 422:
         user_input = input("Existing scheduled job found. Do you want to update it (y|n)? ")
         if user_input.strip().lower() == "y":
-            scheduled_job_id = response.json()["scheduled_job_id"]
+            try:
+                resp_data = response.json()
+            except JSONDecodeError:
+                print("Error: API returned invalid JSON response", file=sys.stderr)
+                return
+            scheduled_job_id = resp_data.get("scheduled_job_id")
+            if not scheduled_job_id:
+                print("Error: API response missing required 'scheduled_job_id' field", file=sys.stderr)
+                return
             schedule_job_url = apiurl(args, f"/commands/schedule_job/{scheduled_job_id}/")
-            response = update_scheduled_job(cli_command, schedule_job_url, frequency, args.start_date, args.end_date, request_body)
+            response = update_scheduled_job(args, cli_command, schedule_job_url, frequency, args.start_date, args.end_date, request_body)
         else:
             print("Job update aborted by the user.")
     else:
             # print(r.text)
         print(f"add_scheduled_job insert: failed error: {response.status_code}. Response body: {response.text}")        
 
-def update_scheduled_job(cli_command, schedule_job_url, frequency, start_date, end_date, request_body):
-    response = requests.put(schedule_job_url, headers=headers, json=request_body)
+def update_scheduled_job(args, cli_command, schedule_job_url, frequency, start_date, end_date, request_body):
+    response = http_put(args, schedule_job_url, headers=headers, json=request_body)
 
-        # Raise an exception for HTTP errors
+    # Raise an exception for HTTP errors
     response.raise_for_status()
-    if response.status_code == 200:
-        print(f"add_scheduled_job update: success - Scheduling {frequency} job to {cli_command} from {start_date} UTC to {end_date} UTC")
-        print(response.json())
-    elif response.status_code == 401:
-        print(f"add_scheduled_job update: failed status_code: {response.status_code}. It could be because you aren't using a valid api_key.")
-    else:
-            # print(r.text)
-        print(f"add_scheduled_job update: failed status_code: {response.status_code}.")
+    print(f"add_scheduled_job update: success - Scheduling {frequency} job to {cli_command} from {start_date} UTC to {end_date} UTC")
+    try:
         print(response.json())
+    except JSONDecodeError:
+        print(response.text)
 
     return response
 
@@ -2006,8 +2196,9 @@ def update_scheduled_job(cli_command, schedule_job_url, frequency, start_date, e
     argument("--name", help="name of the api-key", type=str),
     argument("--permission_file", help="file path for json encoded permissions, see https://vast.ai/docs/cli/roles-and-permissions for more information", type=str),
     argument("--key_params", help="optional wildcard key params for advanced keys", type=str),
+    description="Create a new API key with custom permissions",
     usage="vastai create api-key --name NAME --permission_file PERMISSIONS",
-    help="Create a new api-key with restricted permissions. Can be sent to other users and teammates",
+    help="Create a new API key with custom permissions",
     epilog=deindent("""
         In order to create api keys you must understand how permissions must be sent via json format. 
         You can find more information about permissions here: https://vast.ai/docs/cli/roles-and-permissions
@@ -2019,7 +2210,14 @@ def create__api_key(args):
         permissions = load_permissions_from_file(args.permission_file)
         r = http_post(args, url, headers=headers, json={"name": args.name, "permissions": permissions, "key_params": args.key_params})
         r.raise_for_status()
-        print("api-key created {}".format(r.json()))
+        try:
+            rj = r.json()
+        except JSONDecodeError:
+            print("Error: API returned invalid JSON response", file=sys.stderr)
+            return
+        if args.raw:
+            return rj
+        print("api-key created {}".format(rj))
     except FileNotFoundError:
         print("Error: Permission file '{}' not found.".format(args.permission_file))
     except requests.exceptions.RequestException as e:
@@ -2031,8 +2229,9 @@ def create__api_key(args):
 @parser.command(
     argument("subnet", help="local subnet for cluster, ex: '0.0.0.0/24'", type=str),
     argument("manager_id", help="Machine ID of manager node in cluster. Must exist already.", type=int),
+    description="[Beta] Create a new machine cluster",
     usage="vastai create cluster SUBNET MANAGER_ID",
-    help="Create Vast cluster",
+    help="[Beta] Create a new machine cluster",
     epilog=deindent("""
         Create Vast Cluster by defining a local subnet and manager id.""")
 )
@@ -2052,25 +2251,31 @@ def create__cluster(args: argparse.Namespace):
     r  = http_post(args, req_url, json=json_blob)
     r.raise_for_status()
 
+    try:
+        rj = r.json()
+    except JSONDecodeError:
+        print("Error: API returned invalid JSON response", file=sys.stderr)
+        return
+
     if args.raw:
-        return r
+        return rj
 
-    print(r.json()["msg"])
+    print(rj.get("msg", "Unknown error"))
 
 @parser.command(
     argument("name", help="Environment variable name", type=str),
     argument("value", help="Environment variable value", type=str),
+    description="Create a new account-level environment variable",
     usage="vastai create env-var <name> <value>",
-    help="Create a new user environment variable",
+    help="Create a new account-level environment variable",
 )
 def create__env_var(args):
     """Create a new environment variable for the current user."""
-    url = apiurl(args, "/secrets/")
     data = {"key": args.name, "value": args.value}
-    r = http_post(args, url, headers=headers, json=data)
-    r.raise_for_status()
+    result = api_call(args, "POST", "/secrets/", json_body=data)
 
-    result = r.json()
+    if args.raw:
+        return result
     if result.get("success"):
         print(result.get("msg", "Environment variable created successfully."))
     else:
@@ -2079,8 +2284,9 @@ def create__env_var(args):
 @parser.command(
     argument("ssh_key", help="add your existing ssh public key to your account (from the .pub file). If no public key is provided, a new key pair will be generated.", type=str, nargs='?'),
     argument("-y", "--yes", help="automatically answer yes to prompts", action="store_true"),
+    description="Add an SSH public key to your account",
     usage="vastai create ssh-key [ssh_public_key] [-y]",
-    help="Create a new ssh-key",
+    help="Add an SSH public key to your account",
     epilog=deindent("""
         You may use this command to add an existing public key, or create a new ssh key pair and add that public key, to your Vast account. 
         
@@ -2101,20 +2307,20 @@ def create__env_var(args):
 
 def create__ssh_key(args):
     ssh_key_content = args.ssh_key
-    
+
     # If no SSH key provided, generate one
     if not ssh_key_content:
         ssh_key_content = generate_ssh_key(args.yes)
     else:
         print("Adding provided SSH public key to account...")
-    
+
     # Send the SSH key to the API
-    url = apiurl(args, "/ssh/")
-    r = http_post(args, url, headers=headers, json={"ssh_key": ssh_key_content})
-    r.raise_for_status()
-    
+    result = api_call(args, "POST", "/ssh/", json_body={"ssh_key": ssh_key_content})
+
+    if args.raw:
+        return result
     # Print json response
-    print("ssh-key created {}\nNote: You may need to add the new public key to any pre-existing instances".format(r.json()))
+    print("ssh-key created {}\nNote: You may need to add the new public key to any pre-existing instances".format(result))
 
 
 def generate_ssh_key(auto_yes=False):
@@ -2245,8 +2451,9 @@ def generate_ssh_key(auto_yes=False):
     argument("--cold_mult",   help="[NOTE: this field isn't currently used at the workergroup level]cold/stopped instance capacity target as multiple of hot capacity target (default 2.0)", type=float),
     argument("--cold_workers",   help="min number of workers to keep 'cold' for this workergroup", type=int),
     argument("--auto_instance", help=argparse.SUPPRESS, type=str, default="prod"),
+    description="Create an autoscaling worker group for serverless inference",
     usage="vastai workergroup create [OPTIONS]",
-    help="Create a new autoscale group",
+    help="Create an autoscaling worker group for serverless inference",
     epilog=deindent("""
         Create a new autoscaling group to manage a pool of worker instances.
                     
@@ -2275,7 +2482,10 @@ def create__workergroup(args):
     r.raise_for_status()
     if 'application/json' in r.headers.get('Content-Type', ''):
         try:
-            print("workergroup create {}".format(r.json()))
+            rj = r.json()
+            if args.raw:
+                return rj
+            print("workergroup create {}".format(rj))
         except requests.exceptions.JSONDecodeError:
             print("The response is not valid JSON.")
             print(r)
@@ -2295,8 +2505,9 @@ def create__workergroup(args):
     argument("--endpoint_name", help="deployment endpoint name (allows multiple autoscale groups to share same deployment endpoint)", type=str),
     argument("--auto_instance", help=argparse.SUPPRESS, type=str, default="prod"),
 
+    description="Create a serverless inference endpoint",
     usage="vastai create endpoint [OPTIONS]",
-    help="Create a new endpoint group",
+    help="Create a serverless inference endpoint",
     epilog=deindent("""
         Create a new endpoint group to manage many autoscaling groups
                     
@@ -2311,11 +2522,14 @@ def create__endpoint(args):
     if (args.explain):
         print("request json: ")
         print(json_blob)
-    r = requests.post(url, headers=headers,json=json_blob)
+    r = http_post(args, url, headers=headers, json=json_blob)
     r.raise_for_status()
     if 'application/json' in r.headers.get('Content-Type', ''):
         try:
-            print("create endpoint {}".format(r.json()))
+            rj = r.json()
+            if args.raw:
+                return rj
+            print("create endpoint {}".format(rj))
         except requests.exceptions.JSONDecodeError:
             print("The response is not valid JSON.")
             print(r)
@@ -2414,8 +2628,9 @@ def validate_portal_config(json_blob):
     argument("--mount-path", help="The path to the volume from within the new instance container. e.g. /root/volume", type=str),
     argument("--volume-label", help="(optional) A name to give the new volume. Only usable with --create-volume", type=str),
     
+    description="Create a new GPU instance from an offer",
     usage="vastai create instance ID [OPTIONS] [--args ...]",
-    help="Create a new instance",
+    help="Create a new GPU instance from an offer",
     epilog=deindent("""
         Performs the same action as pressing the "RENT" button on the website at https://console.vast.ai/create/ 
         Creates an instance from an offer ID (which is returned from "search offers"). Each offer ID can only be used to create one instance.
@@ -2507,7 +2722,7 @@ def create__instance(args: argparse.Namespace):
     r = http_put(args, url,  headers=headers,json=json_blob)
     r.raise_for_status()
     if args.raw:
-        return r
+        return r.json()
     else:
         print("Started. {}".format(r.json()))
 
@@ -2516,8 +2731,9 @@ def create__instance(args: argparse.Namespace):
     argument("--username", help="username to use for login", type=str),
     argument("--password", help="password to use for login", type=str),
     argument("--type", help="host/client", type=str),
+    description="Create a subaccount for delegated access",
     usage="vastai create subaccount --email EMAIL --username USERNAME --password PASSWORD --type TYPE",
-    help="Create a subaccount",
+    help="Create a subaccount for delegated access",
     epilog=deindent("""
        Creates a new account that is considered a child of your current account as defined via the API key. 
 
@@ -2531,7 +2747,7 @@ def create__subaccount(args):
     """
     # Default value for host_only, can adjust based on expected default behavior
     host_only = False
-    
+
     # Only process the --account_type argument if it's provided
     if args.type:
         host_only = args.type.lower() == "host"
@@ -2554,20 +2770,18 @@ def create__subaccount(args):
     url = apiurl(args, "/users/")
     r = http_post(args, url, headers=headers, json=json_blob)
     r.raise_for_status()
-
-    if r.status_code == 200:
-        rj = r.json()
-        print(rj)
-    else:
-        print(r.text)
-        print(f"Failed with error {r.status_code}")
+    rj = r.json()
+    if args.raw:
+        return rj
+    print(rj)
 
 @parser.command(
     argument("--team_name", help="name of the team", type=str),
+    description="Create a new team",
     usage="vastai create-team --team_name TEAM_NAME",
     help="Create a new team",
     epilog=deindent("""
-         Creates a new team under your account. 
+         Creates a new team under your account.
 
         Unlike legacy teams, this command does NOT convert your personal account into a team.
         Each team is created as a separate account, and you can be a member of multiple teams.
@@ -2578,13 +2792,9 @@ def create__subaccount(args):
           - Default roles (owner, manager, member) are automatically created.
           - You can invite others, assign roles, and manage resources within the team.
 
-        Optional:
-          You can transfer a portion of your existing personal credits to the team by using 
-          the `--transfer_credit` flag. Example:
-              vastai create-team --team_name myteam --transfer_credit 25
-
         Notes:
           - You cannot create a team from within another team account.
+          - To transfer credits to a team, use `vastai transfer credit <team_email> <amount>` after team creation.
 
         For more details, see:
         https://vast.ai/docs/teams-quickstart
@@ -2592,27 +2802,28 @@ def create__subaccount(args):
 )
 
 def create__team(args):
-    url = apiurl(args, "/team/")
-    r = http_post(args, url, headers=headers, json={"team_name": args.team_name})
-    r.raise_for_status()
-    print(r.json())
+    result = api_call(args, "POST", "/team/", json_body={"team_name": args.team_name})
+    if args.raw:
+        return result
+    print(result)
 
 @parser.command(
     argument("--name", help="name of the role", type=str),
     argument("--permissions", help="file path for json encoded permissions, look in the docs for more information", type=str),
+    description="Create a custom role with specific permissions",
     usage="vastai create team-role --name NAME --permissions PERMISSIONS",
-    help="Add a new role to your team",
+    help="Create a custom role with specific permissions",
     epilog=deindent("""
         Creating a new team role involves understanding how permissions must be sent via json format.
         You can find more information about permissions here: https://vast.ai/docs/cli/roles-and-permissions
     """)
 )
 def create__team_role(args):
-    url = apiurl(args, "/team/roles/")
     permissions = load_permissions_from_file(args.permissions)
-    r = http_post(args, url, headers=headers, json={"name": args.name, "permissions": permissions})
-    r.raise_for_status()
-    print(r.json())
+    result = api_call(args, "POST", "/team/roles/", json_body={"name": args.name, "permissions": permissions})
+    if args.raw:
+        return result
+    print(result)
 
 def get_template_arguments():
     return [
@@ -2640,8 +2851,9 @@ def get_template_arguments():
 
 @parser.command(
     *get_template_arguments(),
+    description="Create a reusable instance configuration template",
     usage="vastai create template",
-    help="Create a new template",
+    help="Create a reusable instance configuration template",
     epilog=deindent("""
         Create a template that can be used to create instances with
 
@@ -2668,7 +2880,7 @@ def create__template(args):
     default_search_query = {}
     if not args.no_default:
         default_search_query = {"verified": {"eq": True}, "external": {"eq": False}, "rentable": {"eq": True}, "rented": {"eq": False}}
-    
+
     extra_filters = parse_query(args.search_params, default_search_query, offers_fields, offers_alias, offers_mult)
     template = {
         "name" : args.name,
@@ -2701,10 +2913,12 @@ def create__template(args):
     r.raise_for_status()
     try:
         rj = r.json()
-        if rj["success"]:
-            print(f"New Template: {rj['template']}")
+        if args.raw:
+            return rj
+        if rj.get("success"):
+            print(f"New Template: {rj.get('template', '')}")
         else:
-            print(rj['msg'])
+            print(rj.get('msg', 'Unknown error'))
     except requests.exceptions.JSONDecodeError:
         print("The response is not valid JSON.")
 
@@ -2714,15 +2928,16 @@ def create__template(args):
     argument("-s", "--size",
              help="size in GB of volume. Default %(default)s GB.", default=15, type=float),
     argument("-n", "--name", help="Optional name of volume.", type=str),
+    description="Create a new persistent storage volume",
     usage="vastai create volume ID [options]",
-    help="Create a new volume",
+    help="Create a new persistent storage volume",
     epilog=deindent("""
         Creates a volume from an offer ID (which is returned from "search volumes"). Each offer ID can be used to create multiple volumes,
         provided the size of all volumes does not exceed the size of the offer.
     """)
 )
 def create__volume(args: argparse.Namespace):
-    
+
     json_blob ={
         "size": int(args.size),
         "id": int(args.id)
@@ -2738,7 +2953,7 @@ def create__volume(args: argparse.Namespace):
     r = http_put(args, url,  headers=headers,json=json_blob)
     r.raise_for_status()
     if args.raw:
-        return r
+        return r.json()
     else:
         print("Created. {}".format(r.json()))
 
@@ -2748,8 +2963,9 @@ def create__volume(args: argparse.Namespace):
     argument("-s", "--size",
              help="size in GB of network volume. Default %(default)s GB.", default=15, type=float),
     argument("-n", "--name", help="Optional name of network volume.", type=str),
+    description="[Host] [Beta] Create a new network-attached storage volume",
     usage="vastai create network volume ID [options]",
-    help="Create a new network volume",
+    help="[Host] [Beta] Create a new network-attached storage volume",
     epilog=deindent("""
         Creates a network volume from an offer ID (which is returned from "search network volumes"). Each offer ID can be used to create multiple volumes,
         provided the size of all volumes does not exceed the size of the offer.
@@ -2772,15 +2988,16 @@ def create__network_volume(args: argparse.Namespace):
     r = http_put(args, url,  headers=headers,json=json_blob)
     r.raise_for_status()
     if args.raw:
-        return r
+        return r.json()
     else:
         print("Created. {}".format(r.json()))
 
 @parser.command(
     argument("cluster_id", help="ID of cluster to create overlay on top of", type=int),
     argument("name", help="overlay network name"),
+    description="[Beta] Create a virtual overlay network on a cluster",
     usage="vastai create overlay CLUSTER_ID OVERLAY_NAME",
-    help="Creates overlay network on top of a physical cluster",
+    help="[Beta] Create a virtual overlay network on a cluster",
     epilog=deindent("""
     Creates an overlay network to allow local networking between instances on a physical cluster""")
 )
@@ -2798,49 +3015,53 @@ def create__overlay(args: argparse.Namespace):
     r.raise_for_status()
 
     if args.raw:
-        return r
+        return r.json()
 
-    print(r.json()["msg"])
+    print(r.json().get("msg", "Unknown error"))
 
 @parser.command(
     argument("id", help="id of apikey to remove", type=int),
+    description="Delete an API key",
     usage="vastai delete api-key ID",
-    help="Remove an api-key",
+    help="Delete an API key",
 )
 def delete__api_key(args):
-    url = apiurl(args, "/auth/apikeys/{id}/".format(id=args.id))
-    r = http_del(args, url, headers=headers)
-    r.raise_for_status()
-    print(r.json())
+    result = api_call(args, "DELETE", f"/auth/apikeys/{args.id}/")
+    if args.raw:
+        return result
+    print(result)
 
 @parser.command(
     argument("id", help="id ssh key to delete", type=int),
+    description="Remove an SSH key from your account",
     usage="vastai delete ssh-key ID",
-    help="Remove an ssh-key",
+    help="Remove an SSH key from your account",
 )
 def delete__ssh_key(args):
-    url = apiurl(args, "/ssh/{id}/".format(id=args.id))
-    r = http_del(args, url, headers=headers)
-    r.raise_for_status()
-    print(r.json())
+    result = api_call(args, "DELETE", f"/ssh/{args.id}/")
+    if args.raw:
+        return result
+    print(result)
 
 @parser.command(
     argument("id", help="id of scheduled job to remove", type=int),
+    description="Delete a scheduled job",
     usage="vastai delete scheduled-job ID",
     help="Delete a scheduled job",
 )
 def delete__scheduled_job(args):
-    url = apiurl(args, "/commands/schedule_job/{id}/".format(id=args.id))
-    r = http_del(args, url, headers=headers)
-    r.raise_for_status()
-    print(r.json())
+    result = api_call(args, "DELETE", f"/commands/schedule_job/{args.id}/")
+    if args.raw:
+        return result
+    print(result)
 
 
 
 @parser.command(
     argument("cluster_id", help="ID of cluster to delete", type=int),
+    description="[Beta] Delete a machine cluster",
     usage="vastai delete cluster CLUSTER_ID",
-    help="Delete Cluster",
+    help="[Beta] Delete a machine cluster",
     epilog=deindent("""
         Delete Vast Cluster""")
 )
@@ -2852,28 +3073,27 @@ def delete__cluster(args: argparse.Namespace):
     if args.explain:
         print("request json:", json_blob)
 
-    req_url = apiurl(args, "/cluster/")
-    r = http_del(args, req_url, json=json_blob)
-    r.raise_for_status()
+    result = api_call(args, "DELETE", "/cluster/", json_body=json_blob)
 
     if args.raw:
-        return r
+        return result
 
-    print(r.json()["msg"])
+    print(result.get("msg", "Unknown error"))
 
 
 @parser.command(
     argument("id", help="id of group to delete", type=int),
+    description="Delete an autoscaling worker group",
     usage="vastai delete workergroup ID ",
-    help="Delete a workergroup group",
+    help="Delete an autoscaling worker group",
     epilog=deindent("""
         Note that deleting a workergroup doesn't automatically destroy all the instances that are associated with your workergroup.
         Example: vastai delete workergroup 4242
     """),
 )
 def delete__workergroup(args):
-    id  = args.id
-    url = apiurl(args, f"/autojobs/{id}/" )
+    workergroup_id = args.id
+    url = apiurl(args, f"/autojobs/{workergroup_id}/")
     json_blob = {"client_id": "me", "autojob_id": args.id}
     if (args.explain):
         print("request json: ")
@@ -2882,7 +3102,10 @@ def delete__workergroup(args):
     r.raise_for_status()
     if 'application/json' in r.headers.get('Content-Type', ''):
         try:
-            print("workergroup delete {}".format(r.json()))
+            rj = r.json()
+            if args.raw:
+                return rj
+            print("workergroup delete {}".format(rj))
         except requests.exceptions.JSONDecodeError:
             print("The response is not valid JSON.")
             print(r)
@@ -2893,15 +3116,16 @@ def delete__workergroup(args):
 
 @parser.command(
     argument("id", help="id of endpoint group to delete", type=int),
+    description="Delete a serverless inference endpoint",
     usage="vastai delete endpoint ID ",
-    help="Delete an endpoint group",
+    help="Delete a serverless inference endpoint",
     epilog=deindent("""
         Example: vastai delete endpoint 4242
     """),
 )
 def delete__endpoint(args):
-    id  = args.id
-    url = apiurl(args, f"/endptjobs/{id}/" )
+    endpoint_id = args.id
+    url = apiurl(args, f"/endptjobs/{endpoint_id}/")
     json_blob = {"client_id": "me", "endptjob_id": args.id}
     if (args.explain):
         print("request json: ")
@@ -2910,7 +3134,10 @@ def delete__endpoint(args):
     r.raise_for_status()
     if 'application/json' in r.headers.get('Content-Type', ''):
         try:
-            print("delete endpoint {}".format(r.json()))
+            rj = r.json()
+            if args.raw:
+                return rj
+            print("delete endpoint {}".format(rj))
         except requests.exceptions.JSONDecodeError:
             print("The response is not valid JSON.")
             print(r)
@@ -2921,6 +3148,7 @@ def delete__endpoint(args):
 
 @parser.command(
     argument("name", help="Environment variable name to delete", type=str),
+    description="Delete a user environment variable",
     usage="vastai delete env-var <name>",
     help="Delete a user environment variable",
 )
@@ -2931,7 +3159,13 @@ def delete__env_var(args):
     r = http_del(args, url, headers=headers, json=data)
     r.raise_for_status()
 
-    result = r.json()
+    try:
+        result = r.json()
+    except JSONDecodeError:
+        print("Error: API returned invalid JSON response", file=sys.stderr)
+        return
+    if args.raw:
+        return result
     if result.get("success"):
         print(result.get("msg", "Environment variable deleted successfully."))
     else:
@@ -2939,8 +3173,9 @@ def delete__env_var(args):
 
 @parser.command(
     argument("overlay_identifier", help="ID (int) or name (str) of overlay to delete", nargs="?"),
+    description="[Beta] Delete an overlay network and its instances",
     usage="vastai delete overlay OVERLAY_IDENTIFIER",
-    help="Deletes overlay and removes all of its associated instances"
+    help="[Beta] Delete an overlay network and its instances"
 )
 def delete__overlay(args: argparse.Namespace):
     identifier = args.overlay_identifier
@@ -2957,20 +3192,19 @@ def delete__overlay(args: argparse.Namespace):
     if args.explain:
         print("request json:", json_blob)
 
-    req_url = apiurl(args, "/overlay/")
-    r = http_del(args, req_url, json=json_blob)
-    r.raise_for_status()
+    result = api_call(args, "DELETE", "/overlay/", json_body=json_blob)
 
     if args.raw:
-        return r
+        return result
 
-    print(r.json()["msg"])
+    print(result.get("msg", "Unknown error"))
 
 @parser.command(
     argument("--template-id", help="Template ID of Template to Delete", type=int),
     argument("--hash-id", help="Hash ID of Template to Delete", type=str),
+    description="Delete a template",
     usage="vastai delete template [--template-id <id> | --hash-id <hash_id>]",
-    help="Delete a Template",
+    help="Delete a template",
     epilog=deindent("""
         Note: Deleting a template only removes the user's replationship to a template. It does not get destroyed
         Example: vastai delete template --template-id 12345
@@ -2979,7 +3213,7 @@ def delete__overlay(args: argparse.Namespace):
 )
 def delete__template(args):
     url = apiurl(args, f"/template/" )
-    
+
     if args.hash_id:
         json_blob = { "hash_id": args.hash_id }
     elif args.template_id:
@@ -2987,18 +3221,20 @@ def delete__template(args):
     else:
         print('ERROR: Must Specify either Template ID or Hash ID to delete a template')
         return
-    
+
     if (args.explain):
         print("request json: ")
         print(json_blob)
         print(args)
         print(url)
     r = http_del(args, url, headers=headers,json=json_blob)
-    print(r)
     # r.raise_for_status()
     if 'application/json' in r.headers.get('Content-Type', ''):
         try:
-            print(r.json()['msg'])
+            rj = r.json()
+            if args.raw:
+                return rj
+            print(rj.get('msg', 'Unknown error'))
         except requests.exceptions.JSONDecodeError:
             print("The response is not valid JSON.")
             print(r)
@@ -3010,20 +3246,19 @@ def delete__template(args):
 
 @parser.command(
     argument("id", help="id of volume contract", type=int),
+    description="Delete a persistent storage volume",
     usage="vastai delete volume ID",
-    help="Delete a volume",
+    help="Delete a persistent storage volume",
     epilog=deindent("""
         Deletes volume with the given ID. All instances using the volume must be destroyed before the volume can be deleted.
     """)
 )
 def delete__volume(args: argparse.Namespace):
-    url = apiurl(args, "/volumes/", query_args={"id": args.id})
-    r = http_del(args, url, headers=headers)
-    r.raise_for_status()
+    result = api_call(args, "DELETE", "/volumes/", query_args={"id": args.id})
     if args.raw:
-        return r
+        return result
     else:
-        print("Deleted. {}".format(r.json()))
+        print("Deleted. {}".format(result))
 
 
 def destroy_instance(id,args):
@@ -3031,25 +3266,32 @@ def destroy_instance(id,args):
     r = http_del(args, url, headers=headers,json={})
     r.raise_for_status()
     if args.raw:
-        return r
-    elif (r.status_code == 200):
-        rj = r.json();
-        if (rj["success"]):
-            print("destroying instance {id}.".format(**(locals())));
-        else:
-            print(rj["msg"]);
+        return r.json()
+    rj = r.json();
+    if rj.get("success"):
+        print("destroying instance {id}.".format(**(locals())));
     else:
-        print(r.text);
-        print("failed with error {r.status_code}".format(**locals()));
+        print(rj.get("msg", "Unknown error"));
 
 
 @parser.command(
     argument("id", help="id of instance to delete", type=int),
+    description="Destroy an instance (irreversible, deletes data)",
     usage="vastai destroy instance id [-h] [--api-key API_KEY] [--raw]",
     help="Destroy an instance (irreversible, deletes data)",
     epilog=deindent("""
-        Perfoms the same action as pressing the "DESTROY" button on the website at https://console.vast.ai/instances/
-        Example: vastai destroy instance 4242
+        Performs the same action as pressing the "DESTROY" button on the website at https://console.vast.ai/instances/
+
+        WARNING: This action is IMMEDIATE and IRREVERSIBLE. All data on the instance will be permanently
+        deleted unless you have saved it to a persistent volume or external storage.
+
+        Examples:
+            vastai destroy instance 12345              # Destroy instance with ID 12345
+
+        Before destroying:
+          - Save any important data using 'vastai copy' or by mounting a persistent volume
+          - Check instance ID carefully with 'vastai show instances'
+          - Consider using 'vastai stop instance' if you want to pause without data loss
     """),
 )
 def destroy__instance(args):
@@ -3060,8 +3302,9 @@ def destroy__instance(args):
     destroy_instance(args.id,args)
 
 @parser.command(
-    argument("ids", help="ids of instance to destroy", type=int, nargs='+'),
-    usage="vastai destroy instances [--raw] <id>",
+    argument("ids", help="ids of instances to destroy", type=int, nargs='+'),
+    description="Destroy a list of instances (irreversible, deletes data)",
+    usage="vastai destroy instances IDS [OPTIONS]",
     help="Destroy a list of instances (irreversible, deletes data)",
 )
 def destroy__instances(args):
@@ -3071,20 +3314,22 @@ def destroy__instances(args):
         destroy_instance(id, args)
 
 @parser.command(
+    description="Delete your team and remove all members",
     usage="vastai destroy team",
-    help="Destroy your team",
+    help="Delete your team and remove all members",
 )
 def destroy__team(args):
-    url = apiurl(args, "/team/")
-    r = http_del(args, url, headers=headers)
-    r.raise_for_status()
-    print(r.json())
+    result = api_call(args, "DELETE", "/team/")
+    if args.raw:
+        return result
+    print(result)
 
 @parser.command(
     argument("instance_id", help="id of the instance", type=int),
     argument("ssh_key_id", help="id of the key to detach to the instance", type=str),
+    description="Remove an SSH key from an instance",
     usage="vastai detach instance_id ssh_key_id",
-    help="Detach an ssh key from an instance",
+    help="Remove an SSH key from an instance",
     epilog=deindent("""
         Example: vastai detach 99999 12345
     """)
@@ -3093,7 +3338,13 @@ def detach__ssh(args):
     url = apiurl(args, "/instances/{id}/ssh/{ssh_key_id}/".format(id=args.instance_id, ssh_key_id=args.ssh_key_id))
     r = http_del(args, url, headers=headers)
     r.raise_for_status()
-    print(r.json())
+    try:
+        rj = r.json()
+    except JSONDecodeError:
+        rj = {"response": r.text}
+    if args.raw:
+        return rj
+    print(rj)
 
 @parser.command(
     argument("id", help="id of instance to execute on", type=int),
@@ -3103,8 +3354,9 @@ def detach__ssh(args):
     argument("--end_date", type=str, default=default_end_date(), help="End date/time in format 'YYYY-MM-DD HH:MM:SS PM' (UTC). Default is 7 days from now. (optional)"),
     argument("--day", type=parse_day_cron_style, help="Day of week you want scheduled job to run on (0-6, where 0=Sunday) or \"*\". Default will be 0. For ex. --day 0", default=0),
     argument("--hour", type=parse_hour_cron_style, help="Hour of day you want scheduled job to run on (0-23) or \"*\" (UTC). Default will be 0. For ex. --hour 16", default=0),
+    description="Execute a command on a running instance",
     usage="vastai execute id COMMAND",
-    help="Execute a (constrained) remote command on a machine",
+    help="Execute a command on a running instance",
     epilog=deindent("""
         Examples:
           vastai execute 99999 'ls -l -o -r'
@@ -3141,22 +3393,21 @@ def execute(args):
         add_scheduled_job(args, json_blob, cli_command, api_endpoint, "PUT", instance_id=args.id)
         return
 
-    if (r.status_code == 200):
-        rj = r.json()
-        if (rj["success"]):
-            for i in range(0,30):
-                time.sleep(0.3)
-                url = rj["result_url"]
-                r = requests.get(url)
-                if (r.status_code == 200):
-                    filtered_text = r.text.replace(rj["writeable_path"], '');
-                    print(filtered_text)
-                    break
-        else:
-            print(rj);
+    rj = r.json()
+    if rj.get("success"):
+        url = rj.get("result_url")
+        if not url:
+            print("Error: API response missing required 'result_url' field", file=sys.stderr)
+            return
+        for i in range(0,30):
+            time.sleep(0.3)
+            r = http_get(args, url)
+            if (r.status_code == 200):
+                filtered_text = r.text.replace(rj.get("writeable_path", ''), '');
+                print(filtered_text)
+                break
     else:
-        print(r.text);
-        print("failed with error {r.status_code}".format(**locals()));
+        print(rj);
 
 
 
@@ -3164,8 +3415,9 @@ def execute(args):
     argument("id", help="id of endpoint group to fetch logs from", type=int),
     argument("--level", help="log detail level (0 to 3)", type=int, default=1),
     argument("--tail", help="", type=int, default=None),
+    description="Get logs for a serverless endpoint",
     usage="vastai get endpt-logs ID [--api-key API_KEY]",
-    help="Fetch logs for a specific serverless endpoint group",
+    help="Get logs for a serverless endpoint",
     epilog=deindent("""
         Example: vastai get endpt-logs 382
     """),
@@ -3175,7 +3427,7 @@ def get__endpt_logs(args):
     if args.url == server_url_default:
         args.url = None
     url = (args.url or "https://run.vast.ai") + "/get_endpoint_logs/"
-    json_blob = {"id": args.id, "api_key": args.api_key}
+    json_blob = {"id": args.id}
     if args.tail: json_blob["tail"] = args.tail
     if (args.explain):
         print(f"{url} with request json: ")
@@ -3185,29 +3437,27 @@ def get__endpt_logs(args):
     r.raise_for_status()
     levels = {0 : "info0", 1: "info1", 2: "trace", 3: "debug"}
 
-    if (r.status_code == 200):
-        rj = None
-        try:
-            rj = r.json()
-        except Exception as e:
-            print(str(e))
-            print(r.text)
-        if args.raw:
-            # sort_keys
-            return rj or r.text
-        else:
-            dbg_lvl = levels[args.level]
-            if rj and dbg_lvl: print(rj[dbg_lvl])
-            #print(json.dumps(rj, indent=1, sort_keys=True))
-    else:
+    rj = None
+    try:
+        rj = r.json()
+    except Exception as e:
+        print(str(e))
         print(r.text)
+    if args.raw:
+        # sort_keys
+        return rj or r.text
+    else:
+        dbg_lvl = levels[args.level]
+        if rj and dbg_lvl: print(rj[dbg_lvl])
+        #print(json.dumps(rj, indent=1, sort_keys=True))
 
 @parser.command(
     argument("id", help="id of endpoint group to fetch logs from", type=int),
     argument("--level", help="log detail level (0 to 3)", type=int, default=1),
     argument("--tail", help="", type=int, default=None),
+    description="Get logs for an autoscaling worker group",
     usage="vastai get wrkgrp-logs ID [--api-key API_KEY]",
-    help="Fetch logs for a specific serverless worker group group",
+    help="Get logs for an autoscaling worker group",
     epilog=deindent("""
         Example: vastai get endpt-logs 382
     """),
@@ -3217,7 +3467,7 @@ def get__wrkgrp_logs(args):
     if args.url == server_url_default:
         args.url = None
     url = (args.url or "https://run.vast.ai") + "/get_autogroup_logs/"
-    json_blob = {"id": args.id, "api_key": args.api_key}
+    json_blob = {"id": args.id}
     if args.tail: json_blob["tail"] = args.tail
     if (args.explain):
         print(f"{url} with request json: ")
@@ -3227,45 +3477,46 @@ def get__wrkgrp_logs(args):
     r.raise_for_status()
     levels = {0 : "info0", 1: "info1", 2: "trace", 3: "debug"}
 
-    if (r.status_code == 200):
-        rj = None
-        try:
-            rj = r.json()
-        except Exception as e:
-            print(str(e))
-            print(r.text)
-        if args.raw:
-            # sort_keys
-            return rj or r.text
-        else:
-            dbg_lvl = levels[args.level]
-            if rj and dbg_lvl: print(rj[dbg_lvl])
-            #print(json.dumps(rj, indent=1, sort_keys=True))
-    else:
+    rj = None
+    try:
+        rj = r.json()
+    except Exception as e:
+        print(str(e))
         print(r.text)
+    if args.raw:
+        # sort_keys
+        return rj or r.text
+    else:
+        dbg_lvl = levels[args.level]
+        if rj and dbg_lvl: print(rj[dbg_lvl])
+        #print(json.dumps(rj, indent=1, sort_keys=True))
 
 @parser.command(
     argument("--email", help="email of user to be invited", type=str),
     argument("--role", help="role of user to be invited", type=str),
+    description="Invite a user to join your team",
     usage="vastai invite member --email EMAIL --role ROLE",
-    help="Invite a team member",
+    help="Invite a user to join your team",
 )
 def invite__member(args):
     url = apiurl(args, "/team/invite/", query_args={"email": args.email, "role": args.role})
     r = http_post(args, url, headers=headers)
     r.raise_for_status()
-    if (r.status_code == 200):
-        print(f"successfully invited {args.email} to your current team")
-    else:
-        print(r.text);
-        print(f"failed with error {r.status_code}")
+    try:
+        rj = r.json()
+    except JSONDecodeError:
+        rj = {"success": True, "email": args.email}
+    if args.raw:
+        return rj
+    print(f"successfully invited {args.email} to your current team")
 
 
 @parser.command(
     argument("cluster_id", help="ID of cluster to add machine to", type=int),
     argument("machine_ids", help="machine id(s) to join cluster", type=int, nargs="+"),
+    description="[Beta] Add a machine to an existing cluster",
     usage="vastai join cluster CLUSTER_ID MACHINE_IDS",
-    help="Join Machine to Cluster",
+    help="[Beta] Add a machine to an existing cluster",
     epilog=deindent("""
         Join's Machine to Vast Cluster
     """)
@@ -3284,16 +3535,17 @@ def join__cluster(args: argparse.Namespace):
     r.raise_for_status()
 
     if args.raw:
-        return r
+        return r.json()
 
-    print(r.json()["msg"])
+    print(r.json().get("msg", "Unknown error"))
 
 
 @parser.command(
     argument("name", help="Overlay network name to join instance to.", type=str),
     argument("instance_id", help="Instance ID to add to overlay.", type=int),
+    description="[Beta] Connect an instance to an overlay network",
     usage="vastai join overlay OVERLAY_NAME INSTANCE_ID",
-    help="Adds instance to an overlay network",
+    help="[Beta] Connect an instance to an overlay network",
     epilog=deindent("""
     Adds an instance to a compatible overlay network.""")
 )
@@ -3311,15 +3563,16 @@ def join__overlay(args: argparse.Namespace):
     r.raise_for_status()
 
     if args.raw:
-        return r
+        return r.json()
 
-    print(r.json()["msg"])
+    print(r.json().get("msg", "Unknown error"))
 
 
 
 @parser.command(
     argument("id", help="id of instance to label", type=int),
     argument("label", help="label to set", type=str),
+    description="Assign a string label to an instance",
     usage="vastai label instance <id> <label>",
     help="Assign a string label to an instance",
 )
@@ -3329,23 +3582,22 @@ def label__instance(args):
     :param argparse.Namespace args: should supply all the command-line options
     :rtype:
     """
-    url       = apiurl(args, "/instances/{id}/".format(id=args.id))
     json_blob = { "label": args.label }
     if (args.explain):
         print("request json: ")
         print(json_blob)
-    r = http_put(args, url,  headers=headers,json=json_blob)
-    r.raise_for_status()
+    result = api_call(args, "PUT", "/instances/{id}/".format(id=args.id), json_body=json_blob)
 
-    rj = r.json();
-    if rj["success"]:
+    if args.raw:
+        return result
+    if result.get("success"):
         print("label for {args.id} set to {args.label}.".format(**(locals())));
     else:
-        print(rj["msg"]);
+        print(result.get("msg", "Unknown error"));
 
 
 def fetch_url_content(url):
-    response = requests.get(url)
+    response = requests.get(url, timeout=DEFAULT_TIMEOUT)
     response.raise_for_status()  # Raises an HTTPError for bad responses
     return response.text
 
@@ -3357,7 +3609,7 @@ def is_cache_valid() -> bool:
         """Checks if the cache file exists and is less than 24 hours old."""
         if not os.path.exists(CACHE_FILE):
             return False
-        cache_age = datetime.now() - datetime.fromtimestamp(os.path.getmtime(CACHE_FILE))
+        cache_age = datetime.now(tz=timezone.utc) - datetime.fromtimestamp(os.path.getmtime(CACHE_FILE), tz=timezone.utc)
         return cache_age < CACHE_DURATION
     
     if is_cache_valid():
@@ -3366,7 +3618,7 @@ def is_cache_valid() -> bool:
     else:
         endpoint = "/api/v0/gpu_names/unique/"
         url = f"{server_url_default}{endpoint}"
-        r = requests.get(url, headers={})
+        r = requests.get(url, headers={}, timeout=DEFAULT_TIMEOUT)
         r.raise_for_status()  # Will raise an exception for HTTP errors
         gpu_names = r.json()
         with open(CACHE_FILE, "w") as file:
@@ -3379,12 +3631,12 @@ def is_cache_valid() -> bool:
 
 
 REGIONS = {
-"North_America": "[AG, BS, BB, BZ, CA, CR, CU, DM, DO, SV, GD, GT, HT, HN, JM, MX, NI, PA, KN, LC, VC, TT, US]",
-"South_America": "[AR, BO, BR, CL, CO, EC, FK, GF, GY, PY, PE, SR, UY, VE]",
-"Europe": "[AL, AD, AT, BY, BE, BA, BG, HR, CY, CZ, DK, EE, FI, FR, DE, GR, HU, IS, IE, IT, LV, LI, LT, LU, MT, MD, MC, ME, NL, MK, NO, PL, PT, RO, RU, SM, RS, SK, SI, ES, SE, CH, UA, GB, VA, XK]",
-"Asia": "[AF, AM, AZ, BH, BD, BT, BN, KH, CN, GE, IN, ID, IR, IQ, IL, JP, JO, KZ, KW, KG, LA, LB, MY, MV, MN, MM, NP, KP, OM, PK, PH, QA, SA, SG, KR, LK, SY, TW, TJ, TH, TL, TR, TM, AE, UZ, VN, YE, HK, MO]",
-"Oceania": "[AS, AU, CK, FJ, PF, GU, KI, MH, FM, NR, NC, NZ, NU, MP, PW, PG, PN, WS, SB, TK, TO, TV, VU, WF]",
-"Africa": "[DZ, AO, BJ, BW, BF, BI, CV, CM, CF, TD, KM, CG, CD, CI, DJ, EG, GQ, ER, SZ, ET, GA, GM, GH, GN, GW, KE, LS, LR, LY, MG, MW, ML, MR, MU, MA, MZ, NA, NE, NG, RW, ST, SN, SC, SL, SO, ZA, SS, SD, TZ, TG, TN, UG, ZM, ZW]"
+    "North_America": "[US, CA]",
+    "South_America": "[BR, AR, CL]",
+    "Europe": "[SE, UA, GB, PL, PT, SI, DE, IT, CH, LT, GR, FI, IS, AT, FR, RO, MD, HU, NO, MK, BG, ES, HR, NL, CZ, EE",
+    "Asia": "[CN, JP, KR, ID, IN, HK, MY, IL, TH, QA, TR, RU, VN, TW, OM, SG, AE, KZ]",
+    "Oceania": "[AU, NZ]",
+    "Africa": "[EG, ZA]",
 }
 
 def _is_valid_region(region):
@@ -3428,8 +3680,9 @@ def _parse_region(region):
     argument("--force", help="Skip sanity checks when creating from an existing instance", action="store_true"),
     argument("--cancel-unavail", help="Return error if scheduling fails (rather than creating a stopped instance)", action="store_true"),
     argument("--template_hash",   help="template hash which contains all relevant information about an instance. This can be used as a replacement for other parameters describing the instance configuration", type=str),
+    description="Launch a new instance using search parameters to auto-select the best offer",
     usage="vastai launch instance [--help] [--api-key API_KEY] <gpu_name> <num_gpus> <image> [geolocation] [disk_space]",
-    help="Launch the top instance from the search offers based on the given parameters",
+    help="Launch a new instance using search parameters to auto-select the best offer",
     epilog=deindent("""
         Launches an instance based on the given parameters. The instance will be created with the top offer from the search results.
         Besides the gpu_name and num_gpus, you must pass in an '--image' argument as a minimum.
@@ -3487,12 +3740,12 @@ def launch__instance(args):
         if not name: continue
         direction = "asc"
         field = name
-        if name.strip("-") != name:
+        if name.startswith("-"):
             direction = "desc"
-            field = name.strip("-")
-        if name.strip("+") != name:
+            field = name.lstrip("-")
+        elif name.startswith("+"):
             direction = "asc"
-            field = name.strip("+")
+            field = name.lstrip("+")
         #print(f"{field} {name} {direction}")
         if field in offers_alias:
             field = offers_alias[field];
@@ -3522,7 +3775,6 @@ def launch__instance(args):
         "disk": args.disk,  
         "q" : query,
         "env" : parse_env(args.env),
-        "disk": args.disk,
         "label": args.label,
         "extra": args.extra,
         "onstart": args.onstart_cmd,
@@ -3555,7 +3807,7 @@ def launch__instance(args):
         r.raise_for_status()  # This will raise an exception for HTTP error codes
         response_data = r.json()
         if args.raw:
-            return r
+            return r.json()
         else:
             print("Started. {}".format(r.json()))
         if response_data.get('success'):
@@ -3573,6 +3825,7 @@ def launch__instance(args):
     argument("--tail", help="Number of lines to show from the end of the logs (default '1000')", type=str),
     argument("--filter", help="Grep filter for log entries", type=str),
     argument("--daemon-logs", help="Fetch daemon system logs instead of container logs", action="store_true"),
+    description="Get the logs for an instance",
     usage="vastai logs INSTANCE_ID [OPTIONS] ",
     help="Get the logs for an instance",
 )
@@ -3592,32 +3845,31 @@ def logs(args):
 
     r = http_put(args, url, headers=headers, json=json_blob)
     r.raise_for_status()
-
-    if r.status_code == 200:
-        rj = r.json()
-        for i in range(0, 30):
-            time.sleep(0.3)
-            url = rj["result_url"]
-            print(f"waiting on logs for instance {args.INSTANCE_ID} fetching from {url}")
-            r = requests.get(url)
-            if r.status_code == 200:
-                result = r.text
-                cleaned_text = re.sub(r'\n\s*\n', '\n', result)
-                print(cleaned_text)
-                break
-        else:
-            print(rj["msg"])
+    rj = r.json()
+    url = rj.get("result_url")
+    if not url:
+        print("Error: API response missing required 'result_url' field", file=sys.stderr)
+        return
+    for i in range(0, 30):
+        time.sleep(0.3)
+        print(f"waiting on logs for instance {args.INSTANCE_ID} fetching from {url}")
+        r = http_get(args, url)
+        if r.status_code == 200:
+            result = r.text
+            cleaned_text = re.sub(r'\n\s*\n', '\n', result)
+            print(cleaned_text)
+            break
     else:
-        print(r.text)
-        print(f"failed with error {r.status_code}")
+        print(rj.get("msg", "Unknown error"))
 
 
 
 @parser.command(
     argument("id", help="id of instance to prepay for", type=int),
     argument("amount", help="amount of instance credit prepayment (default discount func of 0.2 for 1 month, 0.3 for 3 months)", type=float),
+    description="Prepay credits for a reserved instance to prevent interruption",
     usage="vastai prepay instance ID AMOUNT",
-    help="Deposit credits into reserved instance",
+    help="Prepay credits for a reserved instance to prevent interruption",
 )
 def prepay__instance(args):
     """
@@ -3632,13 +3884,19 @@ def prepay__instance(args):
     r = http_put(args, url,  headers=headers,json=json_blob)
     r.raise_for_status()
 
-    rj = r.json();
-    if rj["success"]:
-        timescale = round( rj["timescale"], 3)
-        discount_rate = 100.0*round( rj["discount_rate"], 3)
+    try:
+        rj = r.json();
+    except JSONDecodeError:
+        print("Error: API returned invalid JSON response", file=sys.stderr)
+        return
+    if args.raw:
+        return rj
+    if rj.get("success"):
+        timescale = round( rj.get("timescale", 0), 3)
+        discount_rate = 100.0*round( rj.get("discount_rate", 0), 3)
         print("prepaid for {timescale} months of instance {args.id} applying ${args.amount} credits for a discount of {discount_rate}%".format(**(locals())));
     else:
-        print(rj["msg"]);
+        print(rj.get("msg", "Unknown error"));
 
 '''
 '''
@@ -3651,6 +3909,7 @@ def prepay__instance(args):
     argument("--end_date", type=str, default=default_end_date(), help="End date/time in format 'YYYY-MM-DD HH:MM:SS PM' (UTC). Default is 7 days from now. (optional)"),
     argument("--day", type=parse_day_cron_style, help="Day of week you want scheduled job to run on (0-6, where 0=Sunday) or \"*\". Default will be 0. For ex. --day 0", default=0),
     argument("--hour", type=parse_hour_cron_style, help="Hour of day you want scheduled job to run on (0-23) or \"*\" (UTC). Default will be 0. For ex. --hour 16", default=0),
+    description="Reboot (stop/start) an instance",
     usage="vastai reboot instance ID [OPTIONS]",
     help="Reboot (stop/start) an instance",
     epilog=deindent("""
@@ -3662,9 +3921,7 @@ def reboot__instance(args):
     :param argparse.Namespace args: should supply all the command-line options
     :rtype:
     """
-    url = apiurl(args, "/instances/reboot/{id}/".format(id=args.id))
-    r = http_put(args, url,  headers=headers,json={})
-    r.raise_for_status()
+    result = api_call(args, "PUT", "/instances/reboot/{id}/".format(id=args.id))
 
     if (args.schedule):
         validate_frequency_values(args.day, args.hour, args.schedule)
@@ -3674,21 +3931,19 @@ def reboot__instance(args):
         add_scheduled_job(args, json_blob, cli_command, api_endpoint, "PUT", instance_id=args.id)
         return
 
-    if (r.status_code == 200):
-        rj = r.json();
-        if (rj["success"]):
-            print("Rebooting instance {args.id}.".format(**(locals())));
-        else:
-            print(rj["msg"]);
+    if args.raw:
+        return result
+    if result and result.get("success"):
+        print("Rebooting instance {args.id}.".format(**(locals())));
     else:
-        print(r.text);
-        print("failed with error {r.status_code}".format(**locals()));
+        print(result.get("msg", "") if result else "");
 
 
 @parser.command(
     argument("id", help="id of instance to recycle", type=int),
+    description="Destroy and recreate an instance with the same configuration",
     usage="vastai recycle instance ID [OPTIONS]",
-    help="Recycle (destroy/create) an instance",
+    help="Destroy and recreate an instance with the same configuration",
     epilog=deindent("""
         Destroys and recreates container in place (from newly pulled image) without any risk of losing GPU priority.
     """),
@@ -3698,46 +3953,44 @@ def recycle__instance(args):
     :param argparse.Namespace args: should supply all the command-line options
     :rtype:
     """
-    url = apiurl(args, "/instances/recycle/{id}/".format(id=args.id))
-    r = http_put(args, url,  headers=headers,json={})
-    r.raise_for_status()
+    result = api_call(args, "PUT", "/instances/recycle/{id}/".format(id=args.id))
 
-    if (r.status_code == 200):
-        rj = r.json()
-        if (rj["success"]):
-            print("Recycling instance {args.id}.".format(**(locals())));
-        else:
-            print(rj["msg"]);
+    if args.raw:
+        return result
+    if result and result.get("success"):
+        print("Recycling instance {args.id}.".format(**(locals())));
     else:
-        print(r.text)
-        print("failed with error {r.status_code}".format(**locals()));
+        print(result.get("msg", "") if result else "");
 
 @parser.command(
     argument("id", help="id of user to remove", type=int),
+    description="Remove a team member",
     usage="vastai remove member ID",
     help="Remove a team member",
 )
 def remove__member(args):
-    url = apiurl(args, "/team/members/{id}/".format(id=args.id))
-    r = http_del(args, url, headers=headers)
-    r.raise_for_status()
-    print(r.json())
+    result = api_call(args, "DELETE", f"/team/members/{args.id}/")
+    if args.raw:
+        return result
+    print(result)
 
 @parser.command(
     argument("NAME", help="name of the role", type=str),
+    description="Delete a custom role from your team",
     usage="vastai remove team-role NAME",
-    help="Remove a role from your team",
+    help="Delete a custom role from your team",
 )
 def remove__team_role(args):
-    url = apiurl(args, "/team/roles/{id}/".format(id=args.NAME))
-    r = http_del(args, url, headers=headers)
-    r.raise_for_status()
-    print(r.json())
+    result = api_call(args, "DELETE", f"/team/roles/{args.NAME}/")
+    if args.raw:
+        return result
+    print(result)
 
 @parser.command(
     argument("id", help="machine id", type=int),
+    description="[Host] Get usage and performance reports for a machine",
     usage="vastai reports ID",
-    help="Get the user reports for a given machine",
+    help="[Host] Get usage and performance reports for a machine",
 )
 def reports(args):
     """
@@ -3750,17 +4003,19 @@ def reports(args):
     if (args.explain):
         print("request json: ")
         print(json_blob)
-    
-    r = requests.get(url, headers=headers, json=json_blob)
-    r.raise_for_status()
 
-    if (r.status_code == 200):
-        print(f"reports: {json.dumps(r.json(), indent=2)}")
+    r = http_get(args, url, headers=headers, json=json_blob)
+    r.raise_for_status()
+    rj = r.json()
+    if args.raw:
+        return rj
+    print(f"reports: {json.dumps(rj, indent=2)}")
 
 
 @parser.command(
+    description="Invalidate current API key and generate a new one",
     usage="vastai reset api-key",
-    help="Reset your api-key (get new key from website)",
+    help="Invalidate current API key and generate a new one",
 )
 def reset__api_key(args):
     """Caution: a bad API key will make it impossible to connect to the servers.
@@ -3774,7 +4029,13 @@ def reset__api_key(args):
         print(json_blob)
     r = http_put(args, url,  headers=headers,json=json_blob)
     r.raise_for_status()
-    print("api-key reset ".format(r.json()))
+    try:
+        rj = r.json()
+    except JSONDecodeError:
+        rj = {"success": True, "message": "api-key reset"}
+    if args.raw:
+        return rj
+    print("api-key reset")
 
 
 def exec_with_threads(f, args, nt=16, max_retries=5):
@@ -3837,21 +4098,16 @@ def start_instance(id,args):
         print(json_blob)
     r = http_put(args, url,  headers=headers,json=json_blob)
     r.raise_for_status()
-
-    if (r.status_code == 200):
-        rj = r.json()
-        if (rj["success"]):
-            print("starting instance {id}.".format(**(locals())))
-        else:
-            print(rj["msg"])
-        return True
+    rj = r.json()
+    if rj.get("success"):
+        print("starting instance {id}.".format(**(locals())))
     else:
-        print(r.text)
-        print("failed with error {r.status_code}".format(**locals()))
-    return False
+        print(rj.get("msg", "Unknown error"))
+    return True
 
 @parser.command(
     argument("id", help="ID of instance to start/restart", type=int),
+    description="Start a stopped instance",
     usage="vastai start instance ID [OPTIONS]",
     help="Start a stopped instance",
     epilog=deindent("""
@@ -3872,15 +4128,15 @@ def start__instance(args):
 
 
 @parser.command(
-    argument("ids", help="ids of instance to start", type=int, nargs='+'),
-    usage="vastai start instances [OPTIONS] ID0 ID1 ID2...",
-    help="Start a list of instances",
+    argument("ids", help="ids of instances to start", type=int, nargs='+'),
+    description="Start multiple stopped instances",
+    usage="vastai start instances IDS [OPTIONS]",
+    help="Start multiple stopped instances",
 )
 def start__instances(args):
-    """
-    for id in args.IDs:
+    """Start multiple instances."""
+    for id in args.ids:
         start_instance(id, args)
-    """
 
     #start_instance(args.IDs, args)
     #exec_with_threads(lambda id : start_instance(id, args), args.IDs)
@@ -3904,22 +4160,17 @@ def stop_instance(id,args):
         print(json_blob)
     r = http_put(args, url,  headers=headers,json=json_blob)
     r.raise_for_status()
-
-    if (r.status_code == 200):
-        rj = r.json()
-        if (rj["success"]):
-            print("stopping instance {id}.".format(**(locals())))
-        else:
-            print(rj["msg"])
-        return True
+    rj = r.json()
+    if rj.get("success"):
+        print("stopping instance {id}.".format(**(locals())))
     else:
-        print(r.text)
-        print("failed with error {r.status_code}".format(**locals()))
-    return False
+        print(rj.get("msg", "Unknown error"))
+    return True
 
 
 @parser.command(
     argument("id", help="id of instance to stop", type=int),
+    description="Stop a running instance",
     usage="vastai stop instance ID [OPTIONS]",
     help="Stop a running instance",
     epilog=deindent("""
@@ -3937,20 +4188,20 @@ def stop__instance(args):
     stop_instance(args.id,args)
 
 @parser.command(
-    argument("ids", help="ids of instance to stop", type=int, nargs='+'),
-    usage="vastai stop instances [OPTIONS] ID0 ID1 ID2...",
-    help="Stop a list of instances",
+    argument("ids", help="ids of instances to stop", type=int, nargs='+'),
+    description="Stop multiple running instances",
+    usage="vastai stop instances IDS [OPTIONS]",
+    help="Stop multiple running instances",
     epilog=deindent("""
-        Examples: 
+        Examples:
             vastai stop instances $(vastai show instances -q)
             vastai stop instances 329838 984849
     """),
 )
 def stop__instances(args):
-    """
-    for id in args.IDs:
+    """Stop multiple instances."""
+    for id in args.ids:
         stop_instance(id, args)
-    """
 
     idlist = split_list(args.ids, 64)
     #stop_instance(args.IDs, args)
@@ -3981,2607 +4232,2782 @@ def numeric_version(version_str):
         return None
 
 
-benchmarks_fields = {
-    "contract_id",#             int        ID of instance/contract reporting benchmark
-    "id",#                      int        benchmark unique ID
-    "image",#                   string     image used for benchmark
-    "last_update",#             float      date of benchmark
-    "machine_id",#              int        id of machine benchmarked
-    "model",#                   string     name of model used in benchmark
-    "name",#                    string     name of benchmark
-    "num_gpus",#                int        number of gpus used in benchmark
-    "score"#                   float      benchmark score result
-}
+# =============================================================================
+# Two-Factor Authentication (TFA/2FA) Helper Functions
+# =============================================================================
 
-@parser.command(
-    argument("query", help="Search query in simple query syntax (see below)", nargs="*", default=None),
-    usage="vastai search benchmarks [--help] [--api-key API_KEY] [--raw] <query>",
-    help="Search for benchmark results using custom query",
-    epilog=deindent("""
-        Query syntax:
+def handle_failed_tfa_verification(args, e):
+    """Handle and display errors from failed TFA verification attempts.
 
-            query = comparison comparison...
-            comparison = field op value
-            field = <name of a field>
-            op = one of: <, <=, ==, !=, >=, >, in, notin
-            value = <bool, int, float, string> | 'any' | [value0, value1, ...]
-            bool: True, False
+    Parses error responses and provides helpful context for common TFA errors
+    like lockouts, expired codes, and verification failures.
 
-        note: to pass '>' and '<' on the command line, make sure to use quotes
-        note: to encode a string query value (ie for gpu_name), replace any spaces ' ' with underscore '_'
+    Args:
+        args: Namespace with command arguments (may include 'raw' for JSON output).
+        e: HTTPError exception from the failed request.
+    """
+    error_data = e.response.json()
+    error_msg = error_data.get("msg", str(e))
+    error_code = error_data.get("error", "")
 
-        Examples:
+    if args.raw:
+        print(json.dumps(error_data, indent=2))
 
-            # search for benchmarks with score > 100 for llama2_70B model on 2 specific machines
-            vastai search benchmarks 'score > 100.0  model=llama2_70B  machine_id in [302,402]'
+    print(f"\n{FAIL} Error: {error_msg}")
 
-        Available fields:
+    # Provide helpful context for common errors
+    if error_code in {"tfa_locked", "2fa_verification_failed"}:
+        fail_count = error_data.get("fail_count", 0)
+        locked_until = error_data.get("locked_until")
 
-              Name                  Type       Description
+        if fail_count > 0:
+            print(f"   Failed attempts: {fail_count}")
+        if locked_until:
+            lock_time_sec = (datetime.fromtimestamp(locked_until, tz=timezone.utc) - datetime.now(tz=timezone.utc)).seconds
+            minutes, seconds = divmod(lock_time_sec, 60)
+            print(f"   Time Remaining for 2FA Lock: {minutes} minutes and {seconds} seconds...")
 
-            contract_id             int        ID of instance/contract reporting benchmark
-            id                      int        benchmark unique ID
-            image                   string     image used for benchmark
-            last_update             float      date of benchmark
-            machine_id              int        id of machine benchmarked
-            model                   string     name of model used in benchmark
-            name                    string     name of benchmark
-            num_gpus                int        number of gpus used in benchmark
-            score                   float      benchmark score result
-    """),
-    aliases=hidden_aliases(["search benchmarks"]),
-)
-def search__benchmarks(args):
-    """Creates a query based on search parameters as in the examples above.
-    :param argparse.Namespace args: should supply all the command-line options
-    """
-    try:
-        query = {}
-        if args.query is not None:
-            query = parse_query(args.query, query, benchmarks_fields)
-            query = fix_date_fields(query, ['last_update'])
+    elif error_code == "2fa_expired":
+        # Note: Only SMS uses tfa challenges that expire when verifying
+        print("\n   The SMS code and secret have expired. Please start over:")
+        print("     vastai tfa send-sms")
 
-    except ValueError as e:
-        print("Error: ", e)
-        return 1  
-    #url = apiurl(args, "/benchmarks", {"select_cols" : ['id','last_update','machine_id','score'], "select_filters" : query})
-    url = apiurl(args, "/benchmarks", {"select_cols" : ['*'], "select_filters" : query})
-    r = requests.get(url, headers=headers)
-    r.raise_for_status()
-    rows = r.json()
-    if True: # args.raw:
-        return rows
-    else:
-        display_table(rows, displayable_fields)
 
+def format_backup_codes(backup_codes):
+    """Format backup codes for display or file output.
 
+    Args:
+        backup_codes: List of backup code strings.
 
-invoices_fields = {
-    'id',#               int,                   
-    'user_id',#          int,      
-    'when',#             float,                     
-    'paid_on',#          float,                     
-    'payment_expected',# float,                     
-    'amount_cents',#     int,                   
-    'is_credit',#        bool,                   
-    'is_delayed',#       bool,                   
-    'balance_before',#   float,                     
-    'balance_after',#    float,                     
-    'original_amount',#  int,                   
-    'event_id',#         string,                    
-    'cut_amount',#       int,                   
-    'cut_percent',#      float,                     
-    'extra',#            json,           
-    'service',#          string,                    
-    'stripe_charge',#    json,           
-    'stripe_refund',#    json,           
-    'stripe_payout',#    json,           
-    'error',#            json,           
-    'paypal_email',#     string,                    
-    'transfer_group',#   string,                    
-    'failed',#           bool,                   
-    'refunded',#         bool,                   
-    'is_check',#         bool,                   
-}
+    Returns:
+        Formatted string with header, codes, and instructions.
+    """
+    output_lines = [
+        "=" * 60, "  VAST.AI 2FA BACKUP CODES", "=" * 60,
+        f"\nGenerated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
+        f"\n{WARN}  WARNING: All previous backup codes are now invalid!",
+        "\nYour New Backup Codes (one-time use only):",
+        "-" * 40,
+    ]
 
-@parser.command(
-    argument("query", help="Search query in simple query syntax (see below)", nargs="*", default=None),
-    usage="vastai search invoices [--help] [--api-key API_KEY] [--raw] <query>",
-    help="Search for invoices using custom query",
-    epilog=deindent("""
-        Query syntax:
+    for i, code in enumerate(backup_codes, 1):
+        output_lines.append(f"  {i:2d}. {code}")
 
-            query = comparison comparison...
-            comparison = field op value
-            field = <name of a field>
-            op = one of: <, <=, ==, !=, >=, >, in, notin
-            value = <bool, int, float, string> | 'any' | [value0, value1, ...]
-            bool: True, False
+    output_lines.extend([
+        "-" * 40,
+        "\nIMPORTANT:",
+        " - Each code can only be used once",
+        " - Store them in a secure location",
+        " - Use these codes to log in if you lose access to your 2FA device",
+        "\n" + "=" * 60,
+    ])
+    return "\n".join(output_lines)
 
-        note: to pass '>' and '<' on the command line, make sure to use quotes
-        note: to encode a string query value (ie for gpu_name), replace any spaces ' ' with underscore '_'
 
-        Examples:
+def confirm_destructive_action(prompt="Are you sure? (y/n): "):
+    """Prompt user for confirmation of destructive actions.
 
-            # search for somewhat reliable single RTX 3090 instances, filter out any duplicates or offers that conflict with our existing stopped instances
-            vastai search invoices 'amount_cents>3000  '
-
-        Available fields:
+    Args:
+        prompt: The confirmation prompt to display.
 
-      Name                  Type       Description
+    Returns:
+        True if user confirmed with 'y', False otherwise.
 
-    id                  int,            
-    user_id             int,            
-    when                float,          utc epoch timestamp of initial invoice creation
-    paid_on             float,          actual payment date (utc epoch timestamp )
-    payment_expected    float,          expected payment date (utc epoch timestamp )
-    amount_cents        int,            amount of payment in cents
-    is_credit           bool,           is a credit purchase
-    is_delayed          bool,           is not yet paid
-    balance_before      float,          balance before
-    balance_after       float,          balance after
-    original_amount     int,            original amount of payment
-    event_id            string,           
-    cut_amount          int,               
-    cut_percent         float,            
-    extra               json,           
-    service             string,         type of payment 
-    stripe_charge       json,           
-    stripe_refund       json,           
-    stripe_payout       json,           
-    error               json,           
-    paypal_email        string,         email for paypal/wise payments
-    transfer_group      string,         
-    failed              bool,                   
-    refunded            bool,                   
-    is_check            bool,                   
-    """),
-    aliases=hidden_aliases(["search invoices"]),
-)
-def search__invoices(args):
-    """Creates a query based on search parameters as in the examples above.
-    :param argparse.Namespace args: should supply all the command-line options
+    Raises:
+        EOFError/KeyboardInterrupt: If user cancels input.
     """
     try:
-        query = {}
-        if args.query is not None:
-            query = parse_query(args.query, query, invoices_fields)
-            query = fix_date_fields(query, ['when', 'paid_on', 'payment_expected', 'balance_before', 'balance_after'])
-
-    except ValueError as e:
-        print("Error: ", e)
-        return 1  
-    url = apiurl(args, "/invoices", {"select_cols" : ['*'], "select_filters" : query})
-    r = requests.get(url, headers=headers)
-    r.raise_for_status()
-    rows = r.json()
-    if True: # args.raw:
-        return rows
-    else:
-        display_table(rows, displayable_fields)
-
-
-@parser.command(
-    argument("-t", "--type", default="on-demand", help="Show 'on-demand', 'reserved', or 'bid'(interruptible) pricing. default: on-demand"),
-    argument("-i", "--interruptible", dest="type", const="bid", action="store_const", help="Alias for --type=bid"),
-    argument("-b", "--bid", dest="type", const="bid", action="store_const", help="Alias for --type=bid"),
-    argument("-r", "--reserved", dest="type", const="reserved", action="store_const", help="Alias for --type=reserved"),
-    argument("-d", "--on-demand", dest="type", const="on-demand", action="store_const", help="Alias for --type=on-demand"),
-    argument("-n", "--no-default", action="store_true", help="Disable default query"),
-    argument("--new", action="store_true", help="New search exp"),
-    argument("--limit", type=int, help=""),
-    argument("--disable-bundling", action="store_true", help="Deprecated"),
-    argument("--storage", type=float, default=5.0, help="Amount of storage to use for pricing, in GiB. default=5.0GiB"),
-    argument("-o", "--order", type=str, help="Comma-separated list of fields to sort on. postfix field with - to sort desc. ex: -o 'num_gpus,total_flops-'.  default='score-'", default='score-'),
-    argument("query", help="Query to search for. default: 'external=false rentable=true verified=true', pass -n to ignore default", nargs="*", default=None),
-    usage="vastai search offers [--help] [--api-key API_KEY] [--raw] <query>",
-    help="Search for instance types using custom query",
-    epilog=deindent("""
-        Query syntax:
+        response = input(f" {prompt}").strip().lower()
+        return 'y' in response
+    except (EOFError, KeyboardInterrupt):
+        print("\nOperation cancelled.")
+        raise
 
-            query = comparison comparison...
-            comparison = field op value
-            field = <name of a field>
-            op = one of: <, <=, ==, !=, >=, >, in, notin
-            value = <bool, int, float, string> | 'any' | [value0, value1, ...]
-            bool: True, False
 
-        note: to pass '>' and '<' on the command line, make sure to use quotes
-        note: to encode a string query value (ie for gpu_name), replace any spaces ' ' with underscore '_'
+def save_to_file(content, filepath):
+    """Save content to file, creating parent directories if needed.
 
-        Examples:
+    Args:
+        content: String content to write.
+        filepath: Target file path (will be expanded and made absolute).
 
-            # search for somewhat reliable single RTX 3090 instances, filter out any duplicates or offers that conflict with our existing stopped instances
-            vastai search offers 'reliability > 0.98 num_gpus=1 gpu_name=RTX_3090 rented=False'
+    Returns:
+        True on success, False on failure.
+    """
+    try:
+        filepath = os.path.abspath(os.path.expanduser(filepath))
 
-            # search for datacenter gpus with minimal compute_cap and total_flops
-            vastai search offers 'compute_cap > 610 total_flops > 5 datacenter=True'
+        # If directory provided, this should be handled by caller
+        parent_dir = os.path.dirname(filepath)
+        if parent_dir:
+            os.makedirs(parent_dir, exist_ok=True)
 
-            # search for reliable 4 gpu offers in Taiwan or Sweden
-            vastai search offers 'reliability>0.99 num_gpus=4 geolocation in [TW,SE]'
+        with open(filepath, "w") as f:
+            f.write(content)
+        return True
+    except (IOError, OSError) as e:
+        print(f"\n{FAIL} Error saving file: {e}")
+        return False
 
-            # search for reliable RTX 3090 or 4090 gpus NOT in China or Vietnam
-            vastai search offers 'reliability>0.99 gpu_name in ["RTX 4090", "RTX 3090"] geolocation notin [CN,VN]'
 
-            # search for machines with nvidia drivers 535.86.05 or greater (and various other options)
-            vastai search offers 'disk_space>146 duration>24 gpu_ram>10 cuda_vers>=12.1 direct_port_count>=2 driver_version >= 535.86.05'
+def get_backup_codes_filename():
+    """Generate a timestamped filename for backup codes.
 
-            # search for reliable machines with at least 4 gpus, unverified, order by num_gpus, allow conflicts
-            vastai search offers 'reliability > 0.99  num_gpus>=4 verified=False rented=any' -o 'num_gpus-'
+    Returns:
+        Filename string in format 'vastai_backup_codes_YYYY-MM-DD_HH-MM-SS.txt'.
+    """
+    timestamp = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
+    return f"vastai_backup_codes_{timestamp}.txt"
 
-            # search for arm64 cpu architecture
-            vastai search offers 'cpu_arch=arm64'
-            
-        Available fields:
 
-              Name                  Type       Description
+def save_backup_codes(backup_codes):
+    """Save or display 2FA backup codes based on user choice.
 
-            bw_nvlink               float     bandwidth NVLink
-            compute_cap:            int       cuda compute capability*100  (ie:  650 for 6.5, 700 for 7.0)
-            cpu_arch                string    host machine cpu architecture (e.g. amd64, arm64)
-            cpu_cores:              int       # virtual cpus
-            cpu_ghz:                Float     # cpu clock speed GHZ
-            cpu_cores_effective:    float     # virtual cpus you get
-            cpu_ram:                float     system RAM in gigabytes
-            cuda_vers:              float     machine max supported cuda version (based on driver version)
-            datacenter:             bool      show only datacenter offers
-            direct_port_count       int       open ports on host's router
-            disk_bw:                float     disk read bandwidth, in MB/s
-            disk_space:             float     disk storage space, in GB
-            dlperf:                 float     DL-perf score  (see FAQ for explanation)
-            dlperf_usd:             float     DL-perf/$
-            dph:                    float     $/hour rental cost
-            driver_version:         string    machine's nvidia/amd driver version as 3 digit string ex. "535.86.05,"
-            duration:               float     max rental duration in days
-            external:               bool      show external offers in addition to datacenter offers
-            flops_usd:              float     TFLOPs/$
-            geolocation:            string    Two letter country code. Works with operators =, !=, in, notin (e.g. geolocation not in ['XV','XZ'])
-            gpu_arch                string    host machine gpu architecture (e.g. nvidia, amd)
-            gpu_max_power           float     GPU power limit (watts)
-            gpu_max_temp            float     GPU temp limit (C)
-            gpu_mem_bw:             float     GPU memory bandwidth in GB/s
-            gpu_name:               string    GPU model name (no quotes, replace spaces with underscores, ie: RTX_3090 rather than 'RTX 3090')
-            gpu_ram:                float     per GPU RAM in GB
-            gpu_total_ram:          float     total GPU RAM in GB
-            gpu_frac:               float     Ratio of GPUs in the offer to gpus in the system
-            gpu_display_active:     bool      True if the GPU has a display attached
-            has_avx:                bool      CPU supports AVX instruction set.
-            id:                     int       instance unique ID
-            inet_down:              float     internet download speed in Mb/s
-            inet_down_cost:         float     internet download bandwidth cost in $/GB
-            inet_up:                float     internet upload speed in Mb/s
-            inet_up_cost:           float     internet upload bandwidth cost in $/GB
-            machine_id              int       machine id of instance
-            min_bid:                float     current minimum bid price in $/hr for interruptible
-            num_gpus:               int       # of GPUs
-            pci_gen:                float     PCIE generation
-            pcie_bw:                float     PCIE bandwidth (CPU to GPU)
-            reliability:            float     machine reliability score (see FAQ for explanation)
-            rentable:               bool      is the instance currently rentable
-            rented:                 bool      allow/disallow duplicates and potential conflicts with existing stopped instances
-            storage_cost:           float     storage cost in $/GB/month
-            static_ip:              bool      is the IP addr static/stable
-            total_flops:            float     total TFLOPs from all GPUs
-            ubuntu_version          string    host machine ubuntu OS version
-            verified:               bool      is the machine verified
-            vms_enabled:            bool      is the machine a VM instance
-    """),
-    aliases=hidden_aliases(["search instances"]),
-)
-def search__offers(args):
-    """Creates a query based on search parameters as in the examples above.
+    Prompts user to choose between saving to default location, custom path,
+    or printing to screen. Handles file saving with appropriate warnings.
 
-    :param argparse.Namespace args: should supply all the command-line options
+    Args:
+        backup_codes: List of backup code strings.
     """
+    print(f"\nBackup codes regenerated successfully! {SUCCESS}")
+    print(f"\n{WARN}  WARNING: All previous backup codes are now invalid!")
 
-    try:
+    formatted_content = format_backup_codes(backup_codes)
+    filename = get_backup_codes_filename()
 
-        if args.no_default:
-            query = {}
-        else:
-            query = {"verified": {"eq": True}, "external": {"eq": False}, "rentable": {"eq": True}, "rented": {"eq": False}}
-            #query = {"verified": {"eq": True}, "external": {"eq": False}, "rentable": {"eq": True} }
+    while True:
+        print("\nHow would you like to save your new backup codes?")
+        print(f"  1. Save to default location (~/Downloads/{filename})")
+        print(f"  2. Save to a custom path")
+        print(f"  3. Print to screen ({WARN}  potentially unsafe - visible to onlookers)")
 
-        if args.query is not None:
-            query = parse_query(args.query, query, offers_fields, offers_alias, offers_mult)
+        try:
+            choice = input("\nEnter choice (1-3): ").strip()
 
-        order = []
-        for name in args.order.split(","):
-            name = name.strip()
-            if not name: continue
-            direction = "asc"
-            field = name
-            if name.strip("-") != name:
-                direction = "desc"
-                field = name.strip("-")
-            if name.strip("+") != name:
-                direction = "asc"
-                field = name.strip("+")
-            #print(f"{field} {name} {direction}")
-            if field in offers_alias:
-                field = offers_alias[field];
-            order.append([field, direction])
+            if choice in {'1', '2'}:
+                # Determine filepath
+                if choice == '1':
+                    downloads_dir = os.path.expanduser("~/Downloads")
+                    filepath = os.path.join(downloads_dir, filename)
+                else:  # choice == '2'
+                    custom_path = input("\nEnter full path for backup codes file: ").strip()
+                    if not custom_path:
+                        print("Error: Path cannot be empty")
+                        continue
 
-        query["order"] = order
-        query["type"] = args.type
-        if (args.limit):
-            query["limit"] = int(args.limit)
-        query["allocated_storage"] = args.storage
-        # For backwards compatibility, support --type=interruptible option
-        if query["type"] == 'interruptible':
-            query["type"] = 'bid'
-        if args.disable_bundling:
-            query["disable_bundling"] = True
-    except ValueError as e:
-        print("Error: ", e)
-        return 1
+                    filepath = os.path.abspath(os.path.expanduser(custom_path))
 
-    new_search_ept = args.new
-    
-    #json_blob = {"select_cols" : ['*'], "q" : query}
-    json_blob = query
+                    # If directory provided, add filename
+                    if os.path.isdir(filepath):
+                        filepath = os.path.join(filepath, filename)
 
-    if new_search_ept:
-        #geolocation = query.pop("geolocation", None)
-        #query = {'reliability2': {'gt': '0.1'}}
-        json_blob = {"select_cols" : ['*'], "q" : query}
-        url = apiurl(args, "/search/asks/")
-        stime = time.time()
+                # Try to save
+                if save_to_file(formatted_content, filepath):
+                    print(f"\n{SUCCESS} Backup codes saved to: {filepath}")
+                    print(f"\nIMPORTANT:")
+                    print(f" - The file contains {len(backup_codes)} one-time use backup codes")
+                    if choice == '1':
+                        print(f" - Move this file to a secure location")
+                    return
+                else:
+                    print("Please try again with a different path.")
+                    continue
 
-        if (args.explain):
-            print("request json: ")
-            print(json_blob)
+            elif choice == '3':
+                print(f"\n{WARN}  WARNING: Printing sensitive codes to screen!")
+                confirm = input("\nAre you sure? Anyone nearby can see these codes. (yes/no): ").strip().lower()
 
-        r = http_put(args, url, headers=headers, json=json_blob)
-        etime = time.time()
-        print(f"request took {etime-stime}s")
+                if confirm in {'yes', 'y'}:
+                    print("\n" + formatted_content + "\n")
+                    return
+                else:
+                    print("Cancelled. Please choose another option.")
+                    continue
 
-    else:
-        if (args.explain):
-            print("request json: ")
-            print(json_blob)
-        #url = apiurl(args, "/bundles", {"q": query})
-        #r = requests.get(url, headers=headers)
-        url = apiurl(args, "/bundles/")
-        r = http_post(args, url, headers=headers, json=json_blob)
+            else:
+                print("Invalid choice. Please enter 1, 2, or 3.")
 
-    r.raise_for_status()
-   
-    if (r.headers.get('Content-Type') != 'application/json'):
-        print(f"invalid return Content-Type: {r.headers.get('Content-Type')}")
-        return   
+        except (EOFError, KeyboardInterrupt):
+            print("\n\nOperation cancelled. Your backup codes were generated but not saved.")
+            print("You will need to regenerate them to get new codes.")
+            raise
 
-    rows = r.json()["offers"]
 
-    # TODO: add this post-query geolocation filter to the database call rather than handling it locally
-    if 'rented' in query:
-        filter_q  = query['rented']
-        filter_op = list(filter_q.keys())[0]
-        target    = filter_q[filter_op]
-        new_rows  = []
-        for row in rows:
-            rented = False
-            if "rented" in row and row["rented"] is not None:
-                rented = row["rented"]
-            if filter_op == "eq" and rented == target:
-                new_rows.append(row)
-            if filter_op == "neq" and rented != target:
-                new_rows.append(row)
-            if filter_op == "in" and rented in target:
-                new_rows.append(row)
-            if filter_op == "notin" and rented not in target:
-                new_rows.append(row)
-        rows = new_rows
+def build_tfa_verification_payload(args, **kwargs):
+    """Build common payload for TFA verification requests.
 
-    if args.raw:
-        return rows
-    else:
-        if args.type == "reserved":           
-            display_table(rows, displayable_fields_reserved)
-        else:
-            display_table(rows, displayable_fields)
+    Extracts TFA-related fields from args and combines with any additional
+    keyword arguments to create the API request payload.
 
+    Args:
+        args: Namespace with TFA-related attributes (method_id, sms, code, etc.).
+        **kwargs: Additional payload fields (e.g., phone_number, label, target_id).
 
-templates_fields = {
-    "creator_id",#              int        ID of creator
-    "created_at",#              float      time of initial template creation (UTC epoch timestamp)
-    "count_created",#           int        #instances created (popularity)
-    "default_tag",#             string     image default tag
-    "docker_login_repo",#       string     image docker repository
-    "id",#                      int        template unique ID
-    "image",#                   string     image used for benchmark
-    "jup_direct",#              bool       supports jupyter direct
-    "hash_id",#                 string     unique hash ID of template
-    "private",#                 bool       true: only your templates, None: public templates
-    "name",#                    string     displayable name
-    "recent_create_date",#      float      last time of instance creation (UTC epoch timestamp)
-    "recommended_disk_space",#  float      min disk space required
-    "recommended",#             bool       is templated on our recommended list
-    "ssh_direct",#              bool       supports ssh direct
-    "tag",#                     string     image tag
-    "use_ssh",#                 string     supports ssh (direct or proxy)
-}
+    Returns:
+        Dict with non-None TFA payload fields.
+    """
+    payload = {
+        "tfa_method_id": getattr(args, 'method_id', None),
+        "tfa_method": "sms" if getattr(args, 'sms', False) else "totp",
+        "code": getattr(args, 'code', None),
+        "backup_code": getattr(args, 'backup_code', None),
+        "secret": getattr(args, 'secret', None),
+    }
+    for key, value in kwargs.items():
+        payload[key] = value
+
+    return {k: v for k, v in payload.items() if v}
+
+
+# TFA method display fields for table output
+TFA_METHOD_FIELDS = (
+    ("id", "ID", "{}", None, True),
+    ("user_id", "User ID", "{}", None, True),
+    ("is_primary", "Primary", "{}", None, True),
+    ("method", "Method", "{}", None, True),
+    ("label", "Label", "{}", None, True),
+    ("phone_number", "Phone Number", "{}", None, False),
+    ("created_at", "Created", "{}", lambda x: datetime.fromtimestamp(x, tz=timezone.utc).strftime('%Y-%m-%d %H:%M:%S') if x else "N/A", True),
+    ("last_used", "Last Used", "{}", lambda x: datetime.fromtimestamp(x, tz=timezone.utc).strftime('%Y-%m-%d %H:%M:%S') if x else "Never", True),
+    ("fail_count", "Failures", "{}", None, True),
+    ("locked_until", "Locked Until", "{}", lambda x: datetime.fromtimestamp(x, tz=timezone.utc).strftime('%Y-%m-%d %H:%M:%S') if x else "N/A", True),
+)
+
+
+def display_tfa_methods(methods):
+    """Display 2FA methods in a formatted table.
+
+    Args:
+        methods: List of TFA method dicts from the API.
+    """
+    method_fields = TFA_METHOD_FIELDS
+    has_sms = any(m['method'] == 'sms' for m in methods)
+    if not has_sms:  # Don't show Phone Number column if the user has no SMS methods
+        method_fields = tuple(field for field in TFA_METHOD_FIELDS if field[0] != 'phone_number')
+
+    display_table(methods, method_fields, replace_spaces=False)
+
+
+# =============================================================================
+# Two-Factor Authentication (TFA/2FA) Commands
+# =============================================================================
 
 @parser.command(
-    argument("query", help="Search query in simple query syntax (see below)", nargs="*", default=None),
-    usage="vastai search templates [--help] [--api-key API_KEY] [--raw] <query>",
-    help="Search for template results using custom query",
+    argument("code", help="6-digit verification code from SMS or Authenticator app", type=str),
+    argument("--sms", help="Use SMS 2FA method instead of TOTP", action="store_true"),
+    argument("--secret", help="Secret token from setup process (required)", type=str, required=True),
+    argument("--phone-number", help="Phone number for SMS method (E.164 format)", type=str, default=None),
+    argument("-l", "--label", help="Label for the new 2FA method", type=str, default=None),
+    description="Activate a new 2FA method by verifying the setup code",
+    usage="vastai tfa activate CODE --secret SECRET [--sms] [--phone-number PHONE_NUMBER] [--label LABEL]",
+    help="Activate a new 2FA method by verifying the code",
     epilog=deindent("""
-        Query syntax:
+        Complete the 2FA setup process by verifying your code.
 
-            query = comparison comparison...
-            comparison = field op value
-            field = <name of a field>
-            op = one of: <, <=, ==, !=, >=, >, in, notin
-            value = <bool, int, float, string> | 'any' | [value0, value1, ...]
-            bool: True, False
+        For TOTP (Authenticator app):
+         1. Run 'vastai tfa totp-setup' to get the manual key/QR code and secret
+         2. Enter the manual key or scan the QR code with your Authenticator app
+         3. Run this command with the 6-digit code from your app and the secret token from step 1
 
-        note: to pass '>' and '<' on the command line, make sure to use quotes
-        note: to encode a string query value (ie for gpu_name), replace any spaces ' ' with underscore '_'
+        For SMS:
+         1. Run 'vastai tfa send-sms --phone-number <PHONE_NUMBER>' to receive SMS and get secret token
+         2. Run this command with the code you received via SMS and the phone number it was sent to
+
+        If this is your first 2FA method, backup codes will be generated and displayed.
+        Save these backup codes in a secure location!
 
         Examples:
+         vastai tfa activate --secret abc123def456 123456
+         vastai tfa activate --secret abc123def456 --sms --phone-number +12345678901 123456
+         vastai tfa activate --secret abc123def456 --sms --phone-number +12345678901 --label "Work Phone" 123456
+    """),
+)
+def tfa__activate(args):
+    """Activate a new 2FA method by confirming the verification code."""
+    url = apiurl(args, "/api/v0/tfa/test-submit/")
 
-            # search for somewhat reliable single RTX 3090 instances, filter out any duplicates or offers that conflict with our existing stopped instances
-            vastai search templates 'count_created > 100  creator_id in [38382,48982]'
+    # Build the request payload
+    payload = build_tfa_verification_payload(args, phone_number=args.phone_number, label=args.label)
 
-        Available fields:
+    r = http_post(args, url, headers=apiheaders(args), json=payload)
+    r.raise_for_status()
 
-      Name                  Type       Description
+    response_data = r.json()
 
-    creator_id              int        ID of creator
-    created_at              float      time of initial template creation (UTC epoch timestamp)
-    count_created           int        #instances created (popularity)
-    default_tag             string     image default tag
-    docker_login_repo       string     image docker repository
-    id                      int        template unique ID
-    image                   string     image used for template
-    jup_direct              bool       supports jupyter direct
-    hash_id                 string     unique hash ID of template
-    name                    string     displayable name
-    recent_create_date      float      last time of instance creation (UTC epoch timestamp)
-    recommended_disk_space  float      min disk space required
-    recommended             bool       is templated on our recommended list
-    ssh_direct              bool       supports ssh direct
-    tag                     string     image tag
-    use_ssh                 bool       supports ssh (direct or proxy)    """),
-    aliases=hidden_aliases(["search templates"]),
-)
-def search__templates(args):
-    """Creates a query based on search parameters as in the examples above.
-    :param argparse.Namespace args: should supply all the command-line options
-    """
-    try:
-        query = {}
-        if args.query is not None:
-            query = parse_query(args.query, query, templates_fields)
-            query = fix_date_fields(query, ['created_at', 'recent_create_date'])
+    # Display success message
+    method_name = "SMS" if args.phone_number or args.sms else "TOTP (Authenticator App)"
+    print(f"\n{SUCCESS} {method_name} 2FA method activated successfully!")
+
+    # Display backup codes if this is the first 2FA method
+    if "backup_codes" in response_data:
+        save_backup_codes(response_data["backup_codes"])
 
-    except ValueError as e:
-        print("Error: ", e)
-        return 1  
-    url = apiurl(args, "/template/", {"select_cols" : ['*'], "select_filters" : query})
-    r = http_get(args, url, headers=headers)
-    if r.status_code != 200:
-        print(r.text)
-        r.raise_for_status()
-    elif 'json' in r.headers.get("Content-Type"):
-        rows = r.json().get('templates', [])
-        if True: #args.raw:
-            print(json.dumps(rows, indent=1, sort_keys=True))
-        else:
-            display_table(rows, displayable_fields)
-    else:
-        print(r.text)
-        print("failed with error {r.status_code}".format(**locals()))
 
 @parser.command(
-    argument("-n", "--no-default", action="store_true", help="Disable default query"),
-    argument("--limit", type=int, help=""),
-    argument("--storage", type=float, default=1.0, help="Amount of storage to use for pricing, in GiB. default=1.0GiB"),
-    argument("-o", "--order", type=str, help="Comma-separated list of fields to sort on. postfix field with - to sort desc. ex: -o 'disk_space,inet_up-'.  default='score-'", default='score-'),
-    argument("query", help="Query to search for. default: 'external=false verified=true disk_space>=1', pass -n to ignore default", nargs="*", default=None),
-    usage="vastai search volumes [--help] [--api-key API_KEY] [--raw] <query>",
-    help="Search for volume offers using custom query",
+    argument("-id", "--id-to-delete", help="ID of the 2FA method to delete (see `vastai tfa status`)", type=int, default=None),
+    argument("-c", "--code", mutex_group='code_grp', required=True, help="2FA code from your Authenticator app or SMS to authorize deletion", type=str),
+    argument("--sms", mutex_group="type_grp", help="Use SMS 2FA method instead of TOTP", action="store_true"),
+    argument("-s", "--secret", help="Secret token (required for SMS authorization)", type=str, default=None),
+    argument("-bc", "--backup-code", mutex_group='code_grp', required=True, help="One-time backup code (alternative to regular 2FA code)", type=str, default=None),
+    argument("--method-id", help="2FA Method ID if you have more than one of the same type ('id' from `tfa status`)", type=str, default=None),
+    description="Remove a 2FA method from your account",
+    usage="vastai tfa delete [--id-to-delete ID] [--code CODE] [--sms] [--secret SECRET] [--backup-code BACKUP_CODE] [--method-id ID]",
+    help="Remove a 2FA method from your account",
     epilog=deindent("""
-        Query syntax:
+        Remove a 2FA method from your account.
 
-            query = comparison comparison...
-            comparison = field op value
-            field = <name of a field>
-            op = one of: <, <=, ==, !=, >=, >, in, notin
-            value = <bool, int, float, string> | 'any' | [value0, value1, ...]
-            bool: True, False
+        This action requires 2FA verification to prevent unauthorized removals.
 
-        note: to pass '>' and '<' on the command line, make sure to use quotes
-        note: to encode a string query value (ie for gpu_name), replace any spaces ' ' with underscore '_'
+        NOTE: If you do not specify --id-to-delete, the system will attempt to delete the method
+        you are using to authenticate. However, it is much safer to specify the ID to avoid
+        confusion if you have multiple methods.
+
+        Use `vastai tfa status` to see your active methods and their IDs.
 
         Examples:
+         # Delete method #123, authorize with TOTP/Authenticator code
+         vastai tfa delete --id-to-delete 123 --code 456789
 
-            # search for volumes with greater than 50GB of available storage and greater than 500 Mb/s upload and download speed
-            vastai search volumes "disk_space>50 inet_up>500 inet_down>500"
-            
-        Available fields:
+         # Delete method #123, authorize with SMS and secret from `tfa send-sms`
+         vastai tfa delete -id 123 --sms --secret abc123def456 -c 456789
 
-              Name                  Type       Description
+         # Delete method #123, authorize with backup code
+         vastai tfa delete --id-to-delete 123 --backup-code ABCD-EFGH-IJKL
 
-            cpu_arch:               string    host machine cpu architecture (e.g. amd64, arm64)
-            cuda_vers:              float     machine max supported cuda version (based on driver version)
-            datacenter:             bool      show only datacenter offers
-            disk_bw:                float     disk read bandwidth, in MB/s
-            disk_space:             float     disk storage space, in GB
-            driver_version:         string    machine's nvidia/amd driver version as 3 digit string ex. "535.86.05"
-            duration:               float     max rental duration in days
-            geolocation:            string    Two letter country code. Works with operators =, !=, in, notin (e.g. geolocation not in ['XV','XZ'])
-            gpu_arch:               string    host machine gpu architecture (e.g. nvidia, amd)
-            gpu_name:               string    GPU model name (no quotes, replace spaces with underscores, ie: RTX_3090 rather than 'RTX 3090')
-            has_avx:                bool      CPU supports AVX instruction set.
-            id:                     int       volume offer unique ID
-            inet_down:              float     internet download speed in Mb/s
-            inet_up:                float     internet upload speed in Mb/s
-            machine_id:             int       machine id of volume offer
-            pci_gen:                float     PCIE generation
-            pcie_bw:                float     PCIE bandwidth (CPU to GPU)
-            reliability:            float     machine reliability score (see FAQ for explanation)
-            storage_cost:           float     storage cost in $/GB/month
-            static_ip:              bool      is the IP addr static/stable
-            total_flops:            float     total TFLOPs from all GPUs
-            ubuntu_version:         string    host machine ubuntu OS version
-            verified:               bool      is the machine verified
+         # Delete method #123, specify which TOTP method to use if you have multiple
+         vastai tfa delete -id 123 --method-id 456 -c 456789
+
+         # Delete the TOTP method you are using to authenticate (use with caution)
+         vastai tfa delete -c 456789
     """),
 )
-def search__volumes(args: argparse.Namespace):
-    try:
-
-        if args.no_default:
-            query = {}
-        else:
-            query = {"verified": {"eq": True}, "external": {"eq": False}, "disk_space": {"gte": 1}}
-
-        if args.query is not None:
-            query = parse_query(args.query, query, vol_offers_fields, {}, offers_mult)
-
-        order = []
-        for name in args.order.split(","):
-            name = name.strip()
-            if not name: continue
-            direction = "asc"
-            field = name
-            if name.strip("-") != name:
-                direction = "desc"
-                field = name.strip("-")
-            if name.strip("+") != name:
-                direction = "asc"
-                field = name.strip("+")
-            if field in offers_alias:
-                field = offers_alias[field];
-            order.append([field, direction])
+def tfa__delete(args):
+    """Remove a 2FA method from the user's account after verifying authorization."""
+    url = apiurl(args, "/api/v0/tfa/")
 
-        query["order"] = order
-        if (args.limit):
-            query["limit"] = int(args.limit)
-        query["allocated_storage"] = args.storage
-    except ValueError as e:
-        print("Error: ", e)
+    if args.sms and not args.secret:
+        print(f"\n{FAIL} Error: --secret is required for deletion authorization when using --sms.")
+        print("\nPlease use:  `vastai tfa send-sms` to get the missing secret and try again.")
         return 1
 
-    json_blob = query
+    # Confirm action since this invalidates existing codes
+    prompt = "\nAre you sure you want to delete this 2FA method? (y|n): "
+    if confirm_destructive_action(prompt) == False:
+        print("Operation cancelled.")
+        return
 
-    if (args.explain):
-        print("request json: ")
-        print(json_blob)
-    url = apiurl(args, "/volumes/search/")
-    r = http_post(args, url, headers=headers, json=json_blob)
+    # Build the request payload
+    payload = build_tfa_verification_payload(args, target_id=args.id_to_delete)
+    try:
+        r = http_del(args, url, headers=apiheaders(args), json=payload)
+        r.raise_for_status()
 
-    r.raise_for_status()
-   
-    if (r.headers.get('Content-Type') != 'application/json'):
-        print(f"invalid return Content-Type: {r.headers.get('Content-Type')}")
-        return   
+        response_data = r.json()
 
-    rows = r.json()["offers"]
-    
-    if args.raw:
-        return rows
-    else:
-        display_table(rows, vol_displayable_fields)
+        print(f"\n{SUCCESS} 2FA method deleted successfully.")
+
+        if "remaining_methods" in response_data:
+            remaining = response_data["remaining_methods"]
+            print(f"\nYou have {remaining} 2FA method{'s' if remaining != 1 else ''} remaining.")
+        else:
+            print(f"\n{WARN}  WARNING: You have removed all 2FA methods from your account.")
+            print("Your backup codes have been invalidated and 2FA is now fully disabled.")
 
+    except requests.exceptions.HTTPError as e:
+        handle_failed_tfa_verification(args, e)
+        return 1
 
 
 @parser.command(
-    argument("-n", "--no-default", action="store_true", help="Disable default query"),
-    argument("--limit", type=int, help=""),
-    argument("--storage", type=float, default=1.0, help="Amount of storage to use for pricing, in GiB. default=1.0GiB"),
-    argument("-o", "--order", type=str, help="Comma-separated list of fields to sort on. postfix field with - to sort desc. ex: -o 'disk_space,inet_up-'.  default='score-'", default='score-'),
-    argument("query", help="Query to search for. default: 'external=false verified=true disk_space>=1', pass -n to ignore default", nargs="*", default=None),
-    usage="vastai search network volumes [--help] [--api-key API_KEY] [--raw] <query>",
-    help="Search for network volume offers using custom query",
+    argument("-c", "--code", mutex_group='code_grp', required=True, help="2FA code from Authenticator app (default) or SMS", type=str),
+    argument("--sms", mutex_group="type_grp", help="Use SMS 2FA method instead of TOTP", action="store_true"),
+    argument("-s", "--secret", help="Secret token from previous login step (required for SMS)", type=str, default=None),
+    argument("-bc", "--backup-code", mutex_group='code_grp', required=True, help="One-time backup code (alternative to regular 2FA code)", type=str, default=None),
+    argument("-id", "--method-id", mutex_group="type_grp", help="2FA Method ID if you have more than one of the same type ('id' from `tfa status`)", type=str, default=None),
+    description="Complete 2FA login by verifying code and obtaining session key",
+    usage="vastai tfa login [--code CODE] [--sms] [--secret SECRET] [--backup-code BACKUP_CODE]",
+    help="Complete 2FA login by verifying code",
     epilog=deindent("""
-        Query syntax:
-
-            query = comparison comparison...
-            comparison = field op value
-            field = <name of a field>
-            op = one of: <, <=, ==, !=, >=, >, in, notin
-            value = <bool, int, float, string> | 'any' | [value0, value1, ...]
-            bool: True, False
+        Complete Two-Factor Authentication login by providing the 2FA code.
 
-        note: to pass '>' and '<' on the command line, make sure to use quotes
-        note: to encode a string query value (ie for gpu_name), replace any spaces ' ' with underscore '_'
+        For TOTP (default): Provide the 6-digit code from your Authenticator app
+        For SMS: Include the --sms flag and provide -s/--secret from the `tfa send-sms` command response
+        For backup code: Use --backup-code instead of code (codes may only be used once)
 
         Examples:
-
-            # search for volumes with greater than 50GB of available storage and greater than 500 Mb/s upload and download speed
-            vastai search volumes "disk_space>50 inet_up>500 inet_down>500"
-            
-        Available fields:
-
-              Name                  Type       Description
-            duration:               float     max rental duration in days
-            geolocation:            string    Two letter country code. Works with operators =, !=, in, notin (e.g. geolocation not in ['XV','XZ'])
-            id:                     int       volume offer unique ID
-            inet_down:              float     internet download speed in Mb/s
-            inet_up:                float     internet upload speed in Mb/s
-            reliability:            float     machine reliability score (see FAQ for explanation)
-            storage_cost:           float     storage cost in $/GB/month
-            verified:               bool      is the machine verified
+         vastai tfa login -c 123456
+         vastai tfa login --code 123456 --sms --secret abc123def456
+         vastai tfa login --backup-code ABCD-EFGH-IJKL
     """),
 )
-def search__network_volumes(args: argparse.Namespace):
-    try:
-
-        if args.no_default:
-            query = {}
-        else:
-            query = {"verified": {"eq": True}, "external": {"eq": False}, "disk_space": {"gte": 1}}
-
-        if args.query is not None:
-            query = parse_query(args.query, query, vol_offers_fields, {}, offers_mult)
+def tfa__login(args):
+    """Complete 2FA login and store the session key."""
+    url = apiurl(args, "/api/v0/tfa/")
 
-        order = []
-        for name in args.order.split(","):
-            name = name.strip()
-            if not name: continue
-            direction = "asc"
-            field = name
-            if name.strip("-") != name:
-                direction = "desc"
-                field = name.strip("-")
-            if name.strip("+") != name:
-                direction = "asc"
-                field = name.strip("+")
-            if field in offers_alias:
-                field = offers_alias[field];
-            order.append([field, direction])
+    # Build the request payload
+    payload = build_tfa_verification_payload(args)
 
-        query["order"] = order
-        if (args.limit):
-            query["limit"] = int(args.limit)
-        query["allocated_storage"] = args.storage
-    except ValueError as e:
-        print("Error: ", e)
-        return 1
+    try:
+        r = http_post(args, url, headers=apiheaders(args), json=payload)
+        r.raise_for_status()
 
-    json_blob = query
+        response_data = r.json()
 
-    if (args.explain):
-        print("request json: ")
-        print(json_blob)
-    url = apiurl(args, "/network_volumes/search/")
-    r = http_post(args, url, headers=headers, json=json_blob)
+        # Check for session_key in response and save it
+        if "session_key" in response_data:
+            session_key = response_data["session_key"]
+            if session_key != args.api_key:
+                # Write the session key to the TFA key file
+                with open(TFAKEY_FILE, "w") as f:
+                    f.write(session_key)
+                print(f"{SUCCESS} 2FA login successful! Session key saved to {TFAKEY_FILE}")
+            else:
+                print(f"{SUCCESS} 2FA login successful! Your session key has been refreshed.")
 
-    r.raise_for_status()
-   
-    if (r.headers.get('Content-Type') != 'application/json'):
-        print(f"invalid return Content-Type: {r.headers.get('Content-Type')}")
-        return   
+            # Display remaining backup codes if present
+            if "backup_codes_remaining" in response_data:
+                remaining = response_data["backup_codes_remaining"]
+                if remaining == 0:
+                    print(f"{WARN}  Warning: You have no backup codes remaining! Please generate new backup codes immediately to avoid being locked out of your account if you lose access to your 2FA device.")
+                elif remaining <= 3:
+                    print(f"{WARN}  Warning: You only have {remaining} backup codes remaining. Consider regenerating them.")
+                else:
+                    print(f"Backup codes remaining: {remaining}")
+        else:
+            print("2FA login successful but a session key was not returned. Please check that you have an API Key that's properly set up")
 
-    rows = r.json()["offers"]
-    
-    if args.raw:
-        return rows
-    else:
-        display_table(rows, nw_vol_displayable_fields)
+    except requests.exceptions.HTTPError as e:
+        handle_failed_tfa_verification(args, e)
+        return 1
 
 
 @parser.command(
-    argument("new_api_key", help="Api key to set as currently logged in user"),
-    usage="vastai set api-key APIKEY",
-    help="Set api-key (get your api-key from the console/CLI)",
-)
-def set__api_key(args):
-    """Caution: a bad API key will make it impossible to connect to the servers.
-    :param argparse.Namespace args: should supply all the command-line options
-    """
-    with open(APIKEY_FILE, "w") as writer:
-        writer.write(args.new_api_key)
-    print("Your api key has been saved in {}".format(APIKEY_FILE))
-    
-    APIKEY_FILE_HOME = os.path.expanduser("~/.vast_api_key") # Legacy
-    if os.path.exists(APIKEY_FILE_HOME):
-        os.remove(APIKEY_FILE_HOME)
-        print("Your api key has been removed from {}".format(APIKEY_FILE_HOME))
+    argument("-c", "--code", mutex_group='code_grp', required=True, help="2FA code from Authenticator app (default) or SMS", type=str),
+    argument("--sms", mutex_group="type_grp", help="Use SMS 2FA method instead of TOTP", action="store_true"),
+    argument("-s", "--secret", help="Secret token from previous login step (required for SMS)", type=str, default=None),
+    argument("-bc", "--backup-code", mutex_group='code_grp', required=True, help="One-time backup code (alternative to regular 2FA code)", type=str, default=None),
+    argument("-id", "--method-id", mutex_group="type_grp", help="2FA Method ID if you have more than one of the same type ('id' from `tfa status`)", type=str, default=None),
+    description="Regenerate backup codes for 2FA recovery",
+    usage="vastai tfa regen-codes [--code CODE] [--sms] [--secret SECRET] [--backup-code BACKUP_CODE] [--method-id ID]",
+    help="Regenerate backup codes for 2FA",
+    epilog=deindent("""
+        Generate a new set of backup codes for your account.
 
+        This action requires 2FA verification to prevent unauthorized regeneration.
 
+        WARNING: This will invalidate all existing backup codes!
+        Any previously generated codes will no longer work.
 
-@parser.command(
-    argument("--file", help="file path for params in json format", type=str),
-    usage="vastai set user --file FILE",
-    help="Update user data from json file",
-    epilog=deindent("""
+        Backup codes are one-time use codes that allow you to log in
+        if you lose access to your primary 2FA method (lost phone, etc).
 
-    Available fields:
+        You should regenerate your backup codes if:
+        - You've used several codes and are running low
+        - You think your codes may have been compromised
+        - You lost your saved codes and need new ones
 
-    Name                            Type       Description
+        Important: Save the new codes in a secure location immediately!
+        They will not be shown again.
 
-    ssh_key                         string
-    paypal_email                    string
-    wise_email                      string
-    email                           string
-    normalized_email                string
-    username                        string
-    fullname                        string
-    billaddress_line1               string
-    billaddress_line2               string
-    billaddress_city                string
-    billaddress_zip                 string
-    billaddress_country             string
-    billaddress_taxinfo             string
-    balance_threshold_enabled       string
-    balance_threshold               string
-    autobill_threshold              string
-    phone_number                    string
+        Examples:
+         vastai tfa regen-codes --code 123456
+         vastai tfa regen-codes -c 123456 --sms --secret abc123def456
+         vastai tfa regen-codes --backup-code ABCD-EFGH-IJKL
     """),
 )
-def set__user(args):
-    params = None
-    with open(args.file, 'r') as file:
-        params = json.load(file)
-    url = apiurl(args, "/users/")
-    r = requests.put(url, headers=headers, json=params)
-    r.raise_for_status()
-    print(f"{r.json()}")
+def tfa__regen_codes(args):
+    """Regenerate backup codes for 2FA recovery."""
+    url = apiurl(args, "/api/v0/tfa/regen-backup-codes/")
 
+    # Confirm action since this invalidates existing codes
+    prompt = "\nThis will invalidate all existing backup codes. Continue? (y|n): "
+    if confirm_destructive_action(prompt) == False:
+        print("Operation cancelled.")
+        return
+
+    # Build the request payload with verification
+    payload = build_tfa_verification_payload(args)
+    try:
+        r = http_put(args, url, headers=apiheaders(args), json=payload)
+        r.raise_for_status()
 
+        response_data = r.json()
 
-@parser.command(
-    argument("id", help="id of instance", type=int),
-    usage="vastai ssh-url ID",
-    help="ssh url helper",
-)
-def ssh_url(args):
-    """
+        # Display the new backup codes
+        if "backup_codes" in response_data:
+            save_backup_codes(response_data["backup_codes"])
+        else:
+            print(f"\n{SUCCESS} Backup codes regenerated successfully!")
+            print("(No codes returned in response - this may be an error)")
 
-    :param argparse.Namespace args: should supply all the command-line options
-    :rtype:
-    """
-    return _ssh_url(args, "ssh://")
+    except requests.exceptions.HTTPError as e:
+        handle_failed_tfa_verification(args, e)
+        return 1
 
 
 @parser.command(
-    argument("id",   help="id", type=int),
-    usage="vastai scp-url ID",
-    help="scp url helper",
-)
-def scp_url(args):
-    """
+    argument("-p", "--phone-number", help="Phone number to receive SMS code (E.164 format, e.g., +1234567890)", type=str, default=None),
+    argument("-s", "--secret", help="Secret token from the original 2FA login attempt", type=str, required=True),
+    description="Resend SMS 2FA verification code",
+    usage="vastai tfa resend-sms --secret SECRET [--phone-number PHONE_NUMBER]",
+    help="Resend SMS 2FA code",
+    epilog=deindent("""
+        Resend the SMS verification code to your phone.
 
-    :param argparse.Namespace args: should supply all the command-line options
-    :rtype:
-    """
-    return _ssh_url(args, "scp://")
+        This is useful if:
+        - You didn't receive the original SMS
+        - The code expired before you could use it
+        - You accidentally deleted the message
 
+        You must provide the same secret token from the original request.
 
-def _ssh_url(args, protocol):
+        Example:
+         vastai tfa resend-sms --secret abc123def456
+    """),
+)
+def tfa__resend_sms(args):
+    """Resend SMS 2FA code to the user's phone."""
+    url = apiurl(args, "/api/v0/tfa/resend/")
+    payload = build_tfa_verification_payload(args, phone_number=args.phone_number)
 
-    json_object = None
+    r = http_post(args, url, headers=apiheaders(args), json=payload)
+    r.raise_for_status()
 
-    # Opening JSON file
-    try:
-        with open(f"{DIRS['temp']}/ssh_{args.id}.json", 'r') as openfile:
-            json_object = json.load(openfile)
-    except:
-        pass
+    response_data = r.json()
 
-    port      = None
-    ipaddr    = None
+    print(f"{SUCCESS} SMS code resent successfully!")
+    print(f"\n{response_data['msg']}")
+    print(f"\nOnce you receive the SMS code, complete your 2FA login with:")
+    print(f"  vastai tfa login --sms --secret {args.secret} -c <CODE>")
 
-    if json_object is not None:
-        ipaddr = json_object["ipaddr"]
-        port   = json_object["port"]
 
-    if ipaddr is None or ipaddr.endswith('.vast.ai'):
-        req_url = apiurl(args, "/instances", {"owner": "me"})
-        r = http_get(args, req_url)
-        r.raise_for_status()
-        rows = r.json()["instances"]
+@parser.command(
+    argument("-p", "--phone-number", help="Phone number to receive SMS code (E.164 format, e.g., +1234567890)", type=str, default=None),
+    description="Request a 2FA SMS verification code to be sent",
+    usage="vastai tfa send-sms [--phone-number PHONE_NUMBER]",
+    help="Request a 2FA SMS verification code",
+    epilog=deindent("""
+        Request a two-factor authentication code to be sent via SMS.
 
-        if args.id:
-            matches = [r for r in rows if r['id'] == args.id]
-            if not matches:
-                print(f"error: no instance found with id {args.id}")
-                return 1
-            instance = matches[0]
-        elif len(rows) > 1:
-            print("Found multiple running instances")
-            return 1
-        else:
-            instance = rows[0]
+        If --phone-number is not provided, uses the phone number on your account.
+        The secret token will be returned and must be used with 'vastai tfa activate'.
 
-        ports     = instance.get("ports",{})
-        port_22d  = ports.get("22/tcp",None)
-        port      = -1
-        try:
-            if (port_22d is not None):
-                ipaddr = instance["public_ipaddr"]
-                port   = int(port_22d[0]["HostPort"])
-            else:        
-                ipaddr = instance["ssh_host"]
-                port   = int(instance["ssh_port"])+1 if "jupyter" in instance["image_runtype"] else int(instance["ssh_port"])
-        except:
-            port = -1
+        Examples:
+         vastai tfa send-sms
+         vastai tfa send-sms --phone-number +12345678901
+    """),
+)
+def tfa__send_sms(args):
+    """Request a 2FA SMS code to be sent to the user's phone."""
+    url = apiurl(args, "/api/v0/tfa/test/")
 
-    if (port > 0):
-        print(f'{protocol}root@{ipaddr}:{port}')
-    else:
-        print(f'error: ssh port not found')
+    # Build the request payload
+    payload = {}
 
-   
-    # Writing to sample.json
-    try:
-        with open(f"{DIRS['temp']}/ssh_{args.id}.json", "w") as outfile:
-            json.dump({"ipaddr":ipaddr, "port":port}, outfile)
-    except:
-        pass
+    # Add phone number if provided
+    if args.phone_number:
+        payload["phone_number"] = args.phone_number
 
-@parser.command(
-    argument("id", help="id of apikey to get", type=int),
-    usage="vastai show api-key",
-    help="Show an api-key",
-)
-def show__api_key(args):
-    url = apiurl(args, "/auth/apikeys/{id}/".format(id=args.id))
-    r = http_get(args, url, headers=headers)
+    r = http_post(args, url, headers=apiheaders(args), json=payload)
     r.raise_for_status()
-    print(r.json())
 
-@parser.command(
-    usage="vastai show api-keys",
-    help="List your api-keys associated with your account",
-)
-def show__api_keys(args):
-    url = apiurl(args, "/auth/apikeys/")
-    r = http_get(args, url, headers=headers)
-    r.raise_for_status()
-    if args.raw:
-        return r
-    else:
-        print(r.json())
+    response_data = r.json()
+
+    # Extract and display the secret token
+    secret = response_data["secret"]
+    print(f"{SUCCESS} SMS code sent successfully!")
+    print(f"  Secret token: {secret}")
+    print(f"\nOnce you receive the SMS code:")
+    print(f"\n  If you are setting up SMS 2FA for the first time, run:")
+    phone_num = f"--phone-number {args.phone_number}" if args.phone_number else "[--phone-number <PHONE_NUMBER>]"
+    print(f"    vastai tfa activate --sms --secret {secret} {phone_num} [--label <LABEL>] <CODE>")
+    print(f"\n  Otherwise you can complete your 2FA log in with:")
+    print(f"    vastai tfa login --sms --secret {secret} -c <CODE>\n")
 
 
 @parser.command(
-    usage="vastai show audit-logs [--api-key API_KEY] [--raw]",
-    help="Display account's history of important actions"
+    description="Show the current 2FA status and configured methods for your account",
+    help="Shows the current 2FA status and configured methods",
+    epilog=deindent("""
+        Show the current 2FA status for your account, including:
+         - Whether or not 2FA is enabled
+         - A list of active 2FA methods
+         - The number of backup codes remaining (if 2FA is enabled)
+    """)
 )
-def show__audit_logs(args):
-    """
-    Shows the history of ip address accesses to console.vast.ai endpoints
-
-    :param argparse.Namespace args: should supply all the command-line options
-    :rtype:
-    """
-    req_url = apiurl(args, "/audit_logs/")
-    r = http_get(args, req_url)
+def tfa__status(args):
+    """Show the current 2FA status for the user."""
+    url = apiurl(args, "/tfa/status/")
+    r = http_get(args, url)
     r.raise_for_status()
-    rows = r.json()
+    response_data = r.json()
+
     if args.raw:
-        return rows
-    else:
-        display_table(rows, audit_log_fields)
+        print(json.dumps(response_data, indent=2))
+        return
 
-def normalize_schedule_fields(job):
-    """
-    Mutates the job dict to replace None values with readable scheduling labels.
-    """
-    if job.get("day_of_the_week") is None:
-        job["day_of_the_week"] = "Everyday"
-    else:
-        days = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]
-        job["day_of_the_week"] = days[int(job["day_of_the_week"])]
-    
-    if job.get("hour_of_the_day") is None:
-        job["hour_of_the_day"] = "Every hour"
-    else:
-        hour = int(job["hour_of_the_day"])
-        suffix = "AM" if hour < 12 else "PM"
-        hour_12 = hour % 12
-        hour_12 = 12 if hour_12 == 0 else hour_12
-        job["hour_of_the_day"] = f"{hour_12}_{suffix}"
+    tfa_enabled = response_data.get("tfa_enabled", False)
+    methods = response_data.get("methods", [])
+    backup_codes_remaining = response_data.get("backup_codes_remaining", 0)
 
-    if job.get("min_of_the_hour") is None:
-        job["min_of_the_hour"] = "Every minute"
+    if not tfa_enabled or not methods:
+        print(f"{WARN}  No active 2FA methods found")
     else:
-        job["min_of_the_hour"] = f"{int(job['min_of_the_hour']):02d}"
-    
-    return job
-
-def normalize_jobs(jobs):
-    """
-    Applies normalization to a list of job dicts.
-    """
-    return [normalize_schedule_fields(job) for job in jobs]
+        print(f"2FA Status: Enabled {SUCCESS}")
+        print(f"\nActive 2FA Methods:")
+        display_tfa_methods(methods)
+        print(f"\nBackup codes remaining: {backup_codes_remaining}")
 
 
 @parser.command(
-    usage="vastai show scheduled-jobs [--api-key API_KEY] [--raw]",
-    help="Display the list of scheduled jobs"
-)
-def show__scheduled_jobs(args):
-    """
-    Shows the list of scheduled jobs for the account.
+    description="Generate TOTP secret and QR code for Authenticator app setup",
+    usage="vastai tfa totp-setup",
+    help="Generate TOTP secret and QR code for Authenticator app setup",
+    epilog=deindent("""
+        Set up TOTP (Time-based One-Time Password) 2FA using an Authenticator app.
 
-    :param argparse.Namespace args: should supply all the command-line options
-    :rtype:
-    """
-    req_url = apiurl(args, "/commands/schedule_job/")
-    r = http_get(args, req_url)
-    r.raise_for_status()
-    rows = r.json()
-    if args.raw:
-        return rows
-    else:
-        rows = normalize_jobs(rows)
-        display_table(rows, scheduled_jobs_fields)
+        This command generates a new TOTP secret and displays:
+        - A QR code (for scanning with your app)
+        - A manual entry key (for typing into your app)
+        - A secret token (needed for the next step)
 
-@parser.command(
-    usage="vastai show ssh-keys",
-    help="List your ssh keys associated with your account",
-)
-def show__ssh_keys(args):
-    url = apiurl(args, "/ssh/")
-    r = http_get(args, url, headers=headers)
-    r.raise_for_status()
-    if args.raw:
-        return r
-    else:
-        print(r.json())
+        Workflow:
+         1. Run this command to generate the TOTP secret
+         2. Add the account to your Authenticator app by either:
+            - Scanning the displayed QR code, OR
+            - Manually entering the key shown
+         3. Once added, your app will display a 6-digit code
+         4. Complete setup by running:
+            vastai tfa activate --secret <SECRET> <CODE>
 
-@parser.command(
-    usage="vastai show workergroups [--api-key API_KEY]",
-    help="Display user's current workergroups",
-    epilog=deindent("""
-        Example: vastai show workergroups 
+        Supported Authenticator Apps:
+         - Google Authenticator
+         - Microsoft Authenticator
+         - Authy
+         - 1Password
+         - Any TOTP-compatible app
+
+        Example:
+         vastai tfa totp-setup
     """),
 )
-def show__workergroups(args):
-    url = apiurl(args, "/autojobs/" )
-    json_blob = {"client_id": "me", "api_key": args.api_key}
-    if (args.explain):
-        print("request json: ")
-        print(json_blob)
-    r = http_get(args, url, headers=headers,json=json_blob)
+def tfa__totp_setup(args):
+    """Generate a TOTP secret and QR code for setting up Authenticator app 2FA."""
+    url = apiurl(args, "/api/v0/tfa/totp-setup/")
+
+    r = http_post(args, url, headers=apiheaders(args), json={})
     r.raise_for_status()
-    #print("workergroup list ".format(r.json()))
 
-    if (r.status_code == 200):
-        rj = r.json();
-        if (rj["success"]):
-            rows = rj["results"] 
-            if args.raw:
-                return rows
-            else:
-                #print(rows)
-                print(json.dumps(rows, indent=1, sort_keys=True))
-        else:
-            print(rj["msg"]);
+    response_data = r.json()
+    if args.raw:
+        print(json.dumps(response_data, indent=2))
+        return
 
-@parser.command(
-    usage="vastai show endpoints [--api-key API_KEY]",
-    help="Display user's current endpoint groups",
-    epilog=deindent("""
-        Example: vastai show endpoints
-    """),
-)
-def show__endpoints(args):
-    url = apiurl(args, "/endptjobs/" )
-    json_blob = {"client_id": "me", "api_key": args.api_key}
-    if (args.explain):
-        print("request json: ")
-        print(json_blob)
-    r = http_get(args, url, headers=headers,json=json_blob)
-    r.raise_for_status()
-    #print("workergroup list ".format(r.json()))
+    # Extract the secret and provisioning URI
+    secret = response_data["secret"]
+    provisioning_uri = response_data["provisioning_uri"]
 
-    if (r.status_code == 200):
-        rj = r.json();
-        if (rj["success"]):
-            rows = rj["results"]
-            for row in rows:
-                row.pop("api_key", None)
-                row.pop("auto_delete_in_seconds", None)
-                row.pop("auto_delete_due_24h", None)
-            if args.raw:
-                return rows
-            else:
-                print(json.dumps(rows, indent=1, sort_keys=True))
-        else:
-            print(rj["msg"]);
+    # Display the setup information
+    print("\n" + "="*60)
+    print("TOTP (Authenticator App) 2FA Setup")
+    print("="*60)
 
+    print("\nScan this QR code with your Authenticator app:\n")
 
-@parser.command(
-    usage="vastai show connections [--api-key API_KEY] [--raw]",
-    help="Display user's cloud connections"
-)
-def show__connections(args):
-    """
-    Shows the stats on the machine the user is renting.
+    try:  # Generate and display QR code in terminal
+        import qrcode
+        qr = qrcode.QRCode(border=2)
+        qr.add_data(provisioning_uri)
+        qr.make()
+        qr.print_ascii(tty=True)
+    except ImportError:
+        print("  [QR code display requires 'qrcode' package]")
+        print(f"  Install with: pip install qrcode")
+        print(f"\n  Or manually enter this URI in your app:")
+        print(f"  {provisioning_uri}")
 
-    :param argparse.Namespace args: should supply all the command-line options
-    :rtype:
-    """
-    req_url = apiurl(args, "/users/cloud_integrations/");
-    print(req_url)
-    r = http_get(args, req_url, headers=headers);
-    r.raise_for_status()
-    rows = r.json()
+    print("\nOR Manual Entry Key (type this into your Authenticator app):")
+    print(f"  {secret}")
 
-    if args.raw:
-        return rows
-    else:
-        display_table(rows, connection_fields)
+    print("\nNext Steps:")
+    print("  1. Your Authenticator app should now display a 6-digit code")
+    print("  2. Complete setup by running:")
+    print(f"     vastai tfa activate --secret {secret} <CODE>")
+    print("\n" + "="*60 + "\n")
 
 
 @parser.command(
-    argument("id", help="id of instance to get info for", type=int),
-    usage="vastai show deposit ID [options]",
-    help="Display reserve deposit info for an instance"
-)
-def show__deposit(args):
-    """
-    Shows reserve deposit info for an instance.
+    argument("method_id", metavar="METHOD_ID", help="ID of the 2FA method to update (see `vastai tfa status`)", type=int),
+    argument("-l", "--label", help="New label/name for this 2FA method", type=str, default=None),
+    argument("-p", "--set-primary", help="Set this method as the primary/default 2FA method", default=None),
+    description="Update a 2FA method's settings (label or primary status)",
+    usage="vastai tfa update METHOD_ID [--label LABEL] [--set-primary]",
+    help="Update a 2FA method's settings",
+    epilog=deindent("""
+        Update the label or primary status of a 2FA method.
 
-    :param argparse.Namespace args: should supply all the command-line options
-    :rtype:
-    """
-    req_url = apiurl(args, "/instances/balance/{id}/".format(id=args.id) , {"owner": "me"} )
-    r = http_get(args, req_url)
-    r.raise_for_status()
-    print(json.dumps(r.json(), indent=1, sort_keys=True))
+        The label is a friendly name to help you identify different methods
+        (e.g. "Work Phone", "Personal Authenticator").
 
+        The primary method is your preferred/default 2FA method.
 
-@parser.command(
-    argument("-q", "--quiet", action="store_true", help="only display numeric ids"),
-    argument("-s", "--start_date", help="start date and time for report. Many formats accepted", type=str),
-    argument("-e", "--end_date", help="end date and time for report. Many formats accepted ", type=str),
-    argument("-m", "--machine_id", help="Machine id (optional)", type=int),
-    usage="vastai show earnings [OPTIONS]",
-    help="Get machine earning history reports",
+        Examples:
+         vastai tfa update 123 --label "Work Phone"
+         vastai tfa update 456 --set-primary
+         vastai tfa update 789 --label "Backup Authenticator" --set-primary
+    """),
 )
-def show__earnings(args):
-    """
-    Show earnings history for a time range, optionally per machine. Various options available to limit time range and type of items.
-
-    :param argparse.Namespace args: should supply all the command-line options
-    :rtype:
-    """
+def tfa__update(args):
+    """Update settings for an existing 2FA method."""
+    url = apiurl(args, "/api/v0/tfa/update/")
 
-    Minutes = 60.0
-    Hours	= 60.0*Minutes
-    Days	= 24.0*Hours
-    Years	= 365.0*Days
-    cday    = time.time() / Days
-    sday = cday - 1.0
-    eday = cday - 1.0
+    # Build payload with only provided fields
+    payload = {
+        "tfa_method_id": args.method_id
+    }
 
-    try:
-        import dateutil
-        from dateutil import parser
+    if args.label is not None:
+        payload["label"] = args.label
 
-    except ImportError:
-        print("""\nWARNING: Missing dateutil, can't parse time format""")
+    if args.set_primary is not None:
+        if args.set_primary.lower() in {'true', 't'}:
+            args.set_primary = True
+        elif args.set_primary.lower() in {'false', 'f'}:
+            args.set_primary = False
+        else:
+            print("Error: --set-primary must be <t|true> or <f|false>")
+            return
 
-    if args.end_date:
-        try:
-            end_date = dateutil.parser.parse(str(args.end_date))
-            end_date_txt = end_date.isoformat()
-            end_timestamp = end_date.timestamp()
-            eday = end_timestamp / Days
-        except ValueError as e:
-            print(f"Warning: Invalid end date format! Ignoring end date! \n {str(e)}")
+        payload["is_primary"] = args.set_primary
 
-    if args.start_date:
-        try:
-            start_date = dateutil.parser.parse(str(args.start_date))
-            start_date_txt = start_date.isoformat()
-            start_timestamp = start_date.timestamp()
-            sday = start_timestamp / Days
-        except ValueError as e:
-            print(f"Warning: Invalid start date format! Ignoring start date! \n {str(e)}")
+    # Validate that at least one update field was provided
+    if len(payload) == 1:  # only method_id
+        print("Error: You must specify at least one field to update (--label or --set-primary)")
+        return 1
 
-    req_url = apiurl(args, "/users/me/machine-earnings", {"owner": "me", "sday": sday, "eday": eday, "machid" :args.machine_id});
-    r = http_get(args, req_url)
+    r = http_put(args, url, headers=apiheaders(args), json=payload)
     r.raise_for_status()
-    rows = r.json()
 
+    response_data = r.json()
     if args.raw:
-        return rows
-    print(json.dumps(rows, indent=1, sort_keys=True))
+        print(json.dumps(response_data, indent=2))
+        return
 
+    method_info = response_data.get("method", {})
 
-def sum(X, k):
-    y = 0
-    for x in X:
-        a = float(x.get(k,0))
-        y += a
-    return y
+    print(f"\n{SUCCESS} 2FA method updated successfully!")
+    if args.label:
+        print(f"   New label: {args.label}")
+    if args.set_primary is not None:
+        print(f"   Set as primary method = {args.set_primary}")
+    if method_info:
+        print("\nUpdated 2FA Method:")
+        display_tfa_methods([method_info])
 
-def select(X,k):
-    Y = set()
-    for x in X:
-        v = x.get(k,None)
-        if v is not None:
-            Y.add(v)
-    return Y
 
-@parser.command(
-    argument("-s", "--show-values", action="store_true", help="Show the values of environment variables"),
-    usage="vastai show env-vars [-s]",
-    help="Show user environment variables",
-)
-def show__env_vars(args):
-    """Show the environment variables for the current user."""
-    url = apiurl(args, "/secrets/")
-    r = http_get(args, url, headers=headers)
-    r.raise_for_status()
+benchmarks_fields = {
+    "contract_id",#             int        ID of instance/contract reporting benchmark
+    "id",#                      int        benchmark unique ID
+    "image",#                   string     image used for benchmark
+    "last_update",#             float      date of benchmark
+    "machine_id",#              int        id of machine benchmarked
+    "model",#                   string     name of model used in benchmark
+    "name",#                    string     name of benchmark
+    "num_gpus",#                int        number of gpus used in benchmark
+    "score"#                   float      benchmark score result
+}
 
-    env_vars = r.json().get("secrets", {})
+@parser.command(
+    argument("query", help="Search query in simple query syntax (see below)", nargs="*", default=None),
+    description="Search machine benchmark results with filters",
+    usage="vastai search benchmarks [--help] [--api-key API_KEY] [--raw] <query>",
+    help="Search machine benchmark results with filters",
+    epilog=deindent("""
+        Query syntax:
 
-    if args.raw:
-        if not args.show_values:
-            # Replace values with placeholder in raw output
-            masked_env_vars = {k: "*****" for k, v in env_vars.items()}
-            # indent was 2
-            return masked_env_vars
-        else:
-            return env_vars
-    else:
-        if not env_vars:
-            print("No environment variables found.")
-        else:
-            for key, value in env_vars.items():
-                print(f"Name: {key}")
-                if args.show_values:
-                    print(f"Value: {value}")
-                else:
-                    print("Value: *****")
-                print("---")
-
-    if not args.show_values:
-        print("\nNote: Values are hidden. Use --show-values or -s option to display them.")
-
-@parser.command(
-    argument("-q", "--quiet", action="store_true", help="only display numeric ids"),
-    argument("-s", "--start_date", help="start date and time for report. Many formats accepted (optional)", type=str),
-    argument("-e", "--end_date", help="end date and time for report. Many formats accepted (optional)", type=str),
-    argument("-c", "--only_charges", action="store_true", help="Show only charge items"),
-    argument("-p", "--only_credits", action="store_true", help="Show only credit items"),
-    argument("--instance_label", help="Filter charges on a particular instance label (useful for autoscaler groups)"),
-    usage="(DEPRECATED) vastai show invoices [OPTIONS]",
-    help="(DEPRECATED) Get billing history reports",
-)
-def show__invoices(args):
-    """
-    Show current payments and charges. Various options available to limit time range and type
-    of items. Default is to show everything for user's entire billing history.
-
-    :param argparse.Namespace args: should supply all the command-line options
-    :rtype:
-    """
-
-    sdate,edate = convert_dates_to_timestamps(args)
-    req_url = apiurl(args, "/users/me/invoices", {"owner": "me", "sdate":sdate, "edate":edate, "inc_charges" : not args.only_credits});
-
-    r = http_get(args, req_url)
-    r.raise_for_status()
-    rows = r.json()["invoices"]
-    # print("Timestamp for first row: ", rows[0]["timestamp"])
-    invoice_filter_data = filter_invoice_items(args, rows)
-    rows = invoice_filter_data["rows"]
-    filter_header = invoice_filter_data["header_text"]
-
-    contract_ids = None
+            query = comparison comparison...
+            comparison = field op value
+            field = <name of a field>
+            op = one of: <, <=, ==, !=, >=, >, in, notin
+            value = <bool, int, float, string> | 'any' | [value0, value1, ...]
+            bool: True, False
 
-    if (args.instance_label):
-        #print(rows)
-        contract_ids = select(rows, 'instance_id')
-        #print(contract_ids)
+        note: to pass '>' and '<' on the command line, make sure to use quotes
+        note: to encode a string query value (ie for gpu_name), replace any spaces ' ' with underscore '_'
 
-        url = apiurl(args, f"/contracts/fetch/")
+        Examples:
 
-        req_json = {
-            "label": args.instance_label,
-            "contract_ids": list(contract_ids)
-        }
+            # search for benchmarks with score > 100 for llama2_70B model on 2 specific machines
+            vastai search benchmarks 'score > 100.0  model=llama2_70B  machine_id in [302,402]'
 
-        if (args.explain):
-            print("request json: ")
-            print(req_json)
-        
-        result = http_post(args, url, headers=headers,json=req_json)
-        result.raise_for_status()
-        filtered_rows = result.json()["contracts"]
-        #print(rows)
+        Available fields:
 
-        contract_ids = select(filtered_rows, 'id')
-        #print(contract_ids)
+              Name                  Type       Description
 
-        rows2 = []
-        for row in rows:
-            id = row.get("instance_id", None)
-            if id in contract_ids:
-                rows2.append(row)
-        rows = rows2
+            contract_id             int        ID of instance/contract reporting benchmark
+            id                      int        benchmark unique ID
+            image                   string     image used for benchmark
+            last_update             float      date of benchmark
+            machine_id              int        id of machine benchmarked
+            model                   string     name of model used in benchmark
+            name                    string     name of benchmark
+            num_gpus                int        number of gpus used in benchmark
+            score                   float      benchmark score result
+    """),
+    aliases=hidden_aliases(["search benchmarks"]),
+)
+def search__benchmarks(args):
+    """Creates a query based on search parameters as in the examples above.
+    :param argparse.Namespace args: should supply all the command-line options
+    """
+    try:
+        query = {}
+        if args.query is not None:
+            query = parse_query(args.query, query, benchmarks_fields)
+            query = fix_date_fields(query, ['last_update'])
 
-    current_charges = r.json()["current"]
-    if args.quiet:
-        for row in rows:
-            id = row.get("id", None)
-            if id is not None:
-                print(id)
-    elif args.raw:
-        # sort keys
+    except ValueError as e:
+        print("Error: ", e)
+        return 1  
+    #url = apiurl(args, "/benchmarks", {"select_cols" : ['id','last_update','machine_id','score'], "select_filters" : query})
+    url = apiurl(args, "/benchmarks", {"select_cols" : ['*'], "select_filters" : query})
+    r = http_get(args, url, headers=headers)
+    r.raise_for_status()
+    try:
+        rows = r.json()
+    except JSONDecodeError:
+        print("Error: API returned invalid JSON response", file=sys.stderr)
+        return 1
+    if args.raw:
         return rows
-        # print("Current: ", current_charges)
     else:
-        print(filter_header)
-        display_table(rows, invoice_fields)
-        print(f"Total: ${sum(rows, 'amount')}")
-        print("Current: ", current_charges)
+        display_table(rows, displayable_fields)
 
-# Helper to convert date string or int to timestamp
-def to_timestamp_(val):
-    if isinstance(val, int):
-        return val
-    if isinstance(val, str):
-        if val.isdigit():
-            return int(val)
-        return int(datetime.strptime(val + "+0000", '%Y-%m-%d%z').timestamp())
-    raise ValueError("Invalid date format")
 
-charge_types = ['instance','volume','serverless', 'i', 'v', 's']
-invoice_types = {
-    "transfers": "transfer",
-    "stripe": "stripe_payments",
-    "bitpay": "bitpay",
-    "coinbase": "coinbase",
-    "crypto.com": "crypto.com",
-    "reserved": "instance_prepay",
-    "payout_paypal": "paypal_manual",
-    "payout_wise": "wise_manual"
+
+invoices_fields = {
+    'id',#               int,                   
+    'user_id',#          int,      
+    'when',#             float,                     
+    'paid_on',#          float,                     
+    'payment_expected',# float,                     
+    'amount_cents',#     int,                   
+    'is_credit',#        bool,                   
+    'is_delayed',#       bool,                   
+    'balance_before',#   float,                     
+    'balance_after',#    float,                     
+    'original_amount',#  int,                   
+    'event_id',#         string,                    
+    'cut_amount',#       int,                   
+    'cut_percent',#      float,                     
+    'extra',#            json,           
+    'service',#          string,                    
+    'stripe_charge',#    json,           
+    'stripe_refund',#    json,           
+    'stripe_payout',#    json,           
+    'error',#            json,           
+    'paypal_email',#     string,                    
+    'transfer_group',#   string,                    
+    'failed',#           bool,                   
+    'refunded',#         bool,                   
+    'is_check',#         bool,                   
 }
 
 @parser.command(
-    argument('-i', '--invoices', mutex_group='grp', action='store_true', required=True, help='Show invoices instead of charges'),
-    argument('-it', '--invoice-type', choices=invoice_types.keys(), nargs='+', metavar='type', help=f'Filter which types of invoices to show: {{{", ".join(invoice_types.keys())}}}'),
-    argument('-c', '--charges', mutex_group='grp', action='store_true', required=True, help='Show charges instead of invoices'),
-    argument('-ct', '--charge-type', choices=charge_types, nargs='+', metavar='type', help='Filter which types of charges to show: {i|instance, v|volume, s|serverless}'),
-    argument('-s', '--start-date', help='Start date (YYYY-MM-DD or timestamp)'),
-    argument('-e', '--end-date', help='End date (YYYY-MM-DD or timestamp)'),
-    argument('-l', '--limit', type=int, default=20, help='Number of results per page (default: 20, max: 100)'),
-    argument('-t', '--next-token', help='Pagination token for next page'),
-    argument('-f', '--format', choices=['table', 'tree'], default='table', help='Output format for charges (default: table)'),
-    argument('-v', '--verbose', action='store_true', help='Include full Instance Charge details and Invoice Metadata (tree view only)'),
-    argument('--latest-first', action='store_true', help='Sort by latest first'),
-    usage="vastai show invoices-v1 [OPTIONS]",
-    help="Get billing (invoices/charges) history reports with advanced filtering and pagination",
+    argument("query", help="Search query in simple query syntax (see below)", nargs="*", default=None),
+    description="Search billing invoices with filters",
+    usage="vastai search invoices [--help] [--api-key API_KEY] [--raw] <query>",
+    help="Search billing invoices with filters",
     epilog=deindent("""
-        This command supports colored output and rich formatting if the 'rich' python module is installed!
+        Query syntax:
+
+            query = comparison comparison...
+            comparison = field op value
+            field = <name of a field>
+            op = one of: <, <=, ==, !=, >=, >, in, notin
+            value = <bool, int, float, string> | 'any' | [value0, value1, ...]
+            bool: True, False
+
+        note: to pass '>' and '<' on the command line, make sure to use quotes
+        note: to encode a string query value (ie for gpu_name), replace any spaces ' ' with underscore '_'
 
         Examples:
-            # Show the first 20 invoices in the last week  (note: default window is a 7 day period ending today)
-            vastai show invoices-v1 --invoices
-    
-            # Show the first 50 charges over a 7 day period starting from 2025-11-30 in tree format
-            vastai show invoices-v1 --charges -s 2025-11-30 -f tree -l 50
 
-            # Show the first 20 invoices of specific types for the month of November 2025
-            vastai show invoices-v1 -i -it stripe bitpay transfers --start-date 2025-11-01 --end-date 2025-11-30
+            # search for somewhat reliable single RTX 3090 instances, filter out any duplicates or offers that conflict with our existing stopped instances
+            vastai search invoices 'amount_cents>3000  '
 
-            # Show the first 20 charges for only volumes and serverless instances between two dates, including all details and metadata
-            vastai show invoices-v1 -c --charge-type v s -s 2025-11-01 -e 2025-11-05 --format tree --verbose
+        Available fields:
 
-            # Get the next page of paginated invoices, limit to 50 per page  (note: type/date filters MUST match previous request for pagination to work)
-            vastai show invoices-v1 --invoices --limit 50 --next-token eyJ2YWx1ZXMiOiB7ImlkIjogMjUwNzgyMzR9LCAib3NfcGFnZSI6IDB9
+      Name                  Type       Description
 
-            # Show the last 10 instance (only) charges over a 7 day period ending in 2025-12-25, sorted by latest charges first
-            vastai show invoices-v1 --charges -ct instance --end-date 2025-12-25 -l 10 --latest-first
-    """)
+    id                  int,            
+    user_id             int,            
+    when                float,          utc epoch timestamp of initial invoice creation
+    paid_on             float,          actual payment date (utc epoch timestamp )
+    payment_expected    float,          expected payment date (utc epoch timestamp )
+    amount_cents        int,            amount of payment in cents
+    is_credit           bool,           is a credit purchase
+    is_delayed          bool,           is not yet paid
+    balance_before      float,          balance before
+    balance_after       float,          balance after
+    original_amount     int,            original amount of payment
+    event_id            string,           
+    cut_amount          int,               
+    cut_percent         float,            
+    extra               json,           
+    service             string,         type of payment 
+    stripe_charge       json,           
+    stripe_refund       json,           
+    stripe_payout       json,           
+    error               json,           
+    paypal_email        string,         email for paypal/wise payments
+    transfer_group      string,         
+    failed              bool,                   
+    refunded            bool,                   
+    is_check            bool,                   
+    """),
+    aliases=hidden_aliases(["search invoices"]),
 )
-def show__invoices_v1(args):
-    output_lines = []
+def search__invoices(args):
+    """Creates a query based on search parameters as in the examples above.
+    :param argparse.Namespace args: should supply all the command-line options
+    """
     try:
-        from rich.prompt import Confirm
-        has_rich = True
-    except ImportError:
-        output_lines.append("NOTE: To view results in color and table/tree format please install the 'rich' python module with 'pip install rich'\n")
-        has_rich = False
+        query = {}
+        if args.query is not None:
+            query = parse_query(args.query, query, invoices_fields)
+            query = fix_date_fields(query, ['when', 'paid_on', 'payment_expected', 'balance_before', 'balance_after'])
 
-    # Handle default start and end date values
-    if not args.start_date and not args.end_date:
-        args.end_date = int(time.time())  # Set end date to current time if both are missing
-    if not args.start_date:
-        args.start_date = args.end_date - 7 * 24*60*60  # Default to 7 days before given end date
-    elif not args.end_date:
-        args.end_date = args.start_date + 7 * 24*60*60  # Default to 7 days after given start date
+    except ValueError as e:
+        print("Error: ", e)
+        return 1  
+    url = apiurl(args, "/invoices", {"select_cols" : ['*'], "select_filters" : query})
+    r = http_get(args, url, headers=headers)
+    r.raise_for_status()
+    try:
+        rows = r.json()
+    except JSONDecodeError:
+        print("Error: API returned invalid JSON response", file=sys.stderr)
+        return 1
+    if args.raw:
+        return rows
+    else:
+        display_table(rows, displayable_fields)
+
+
+@parser.command(
+    argument("-t", "--type", default="on-demand", help="Show 'on-demand', 'reserved', or 'bid'(interruptible) pricing. default: on-demand"),
+    argument("-i", "--interruptible", dest="type", const="bid", action="store_const", help="Alias for --type=bid"),
+    argument("-b", "--bid", dest="type", const="bid", action="store_const", help="Alias for --type=bid"),
+    argument("-r", "--reserved", dest="type", const="reserved", action="store_const", help="Alias for --type=reserved"),
+    argument("-d", "--on-demand", dest="type", const="on-demand", action="store_const", help="Alias for --type=on-demand"),
+    argument("-n", "--no-default", action="store_true", help="Disable default query"),
+    argument("--new", action="store_true", help="New search exp"),
+    argument("--limit", type=int, help=""),
+    argument("--disable-bundling", action="store_true", help="Deprecated"),
+    argument("--storage", type=float, default=5.0, help="Amount of storage to use for pricing, in GiB. default=5.0GiB"),
+    argument("-o", "--order", type=str, help="Comma-separated list of fields to sort on. postfix field with - to sort desc. ex: -o 'num_gpus,total_flops-'.  default='score-'", default='score-'),
+    argument("query", help="Query to search for. default: 'external=false rentable=true verified=true', pass -n to ignore default", nargs="*", default=None),
+    description="Search available GPU offers with filters",
+    usage="vastai search offers [--help] [--api-key API_KEY] [--raw] <query>",
+    help="Search available GPU offers with filters",
+    epilog=deindent("""
+        Query syntax:
+
+            query = comparison comparison...
+            comparison = field op value
+            field = <name of a field>
+            op = one of: <, <=, ==, !=, >=, >, in, notin
+            value = <bool, int, float, string> | 'any' | [value0, value1, ...]
+            bool: True, False
+
+        note: to pass '>' and '<' on the command line, make sure to use quotes
+        note: to encode a string query value (ie for gpu_name), replace any spaces ' ' with underscore '_'
+
+        Examples:
+
+            # search for somewhat reliable single RTX 3090 instances, filter out any duplicates or offers that conflict with our existing stopped instances
+            vastai search offers 'reliability > 0.98 num_gpus=1 gpu_name=RTX_3090 rented=False'
+
+            # search for datacenter gpus with minimal compute_cap and total_flops
+            vastai search offers 'compute_cap > 610 total_flops > 5 datacenter=True'
+
+            # search for reliable 4 gpu offers in Taiwan or Sweden
+            vastai search offers 'reliability>0.99 num_gpus=4 geolocation in [TW,SE]'
+
+            # search for reliable RTX 3090 or 4090 gpus NOT in China or Vietnam
+            vastai search offers 'reliability>0.99 gpu_name in ["RTX 4090", "RTX 3090"] geolocation notin [CN,VN]'
+
+            # search for machines with nvidia drivers 535.86.05 or greater (and various other options)
+            vastai search offers 'disk_space>146 duration>24 gpu_ram>10 cuda_vers>=12.1 direct_port_count>=2 driver_version >= 535.86.05'
+
+            # search for reliable machines with at least 4 gpus, unverified, order by num_gpus, allow conflicts
+            vastai search offers 'reliability > 0.99  num_gpus>=4 verified=False rented=any' -o 'num_gpus-'
+
+            # search for arm64 cpu architecture
+            vastai search offers 'cpu_arch=arm64'
+            
+        Available fields:
+
+              Name                  Type       Description
+
+            bw_nvlink               float     bandwidth NVLink
+            compute_cap:            int       cuda compute capability*100  (ie:  650 for 6.5, 700 for 7.0)
+            cpu_arch                string    host machine cpu architecture (e.g. amd64, arm64)
+            cpu_cores:              int       # virtual cpus
+            cpu_ghz:                Float     # cpu clock speed GHZ
+            cpu_cores_effective:    float     # virtual cpus you get
+            cpu_ram:                float     system RAM in gigabytes
+            cuda_vers:              float     machine max supported cuda version (based on driver version)
+            datacenter:             bool      show only datacenter offers
+            direct_port_count       int       open ports on host's router
+            disk_bw:                float     disk read bandwidth, in MB/s
+            disk_space:             float     disk storage space, in GB
+            dlperf:                 float     DL-perf score  (see FAQ for explanation)
+            dlperf_usd:             float     DL-perf/$
+            dph:                    float     $/hour rental cost
+            driver_version:         string    machine's nvidia/amd driver version as 3 digit string ex. "535.86.05,"
+            duration:               float     max rental duration in days
+            external:               bool      show external offers in addition to datacenter offers
+            flops_usd:              float     TFLOPs/$
+            geolocation:            string    Two letter country code. Works with operators =, !=, in, notin (e.g. geolocation not in ['XV','XZ'])
+            gpu_arch                string    host machine gpu architecture (e.g. nvidia, amd)
+            gpu_max_power           float     GPU power limit (watts)
+            gpu_max_temp            float     GPU temp limit (C)
+            gpu_mem_bw:             float     GPU memory bandwidth in GB/s
+            gpu_name:               string    GPU model name (no quotes, replace spaces with underscores, ie: RTX_3090 rather than 'RTX 3090')
+            gpu_ram:                float     per GPU RAM in GB
+            gpu_total_ram:          float     total GPU RAM in GB
+            gpu_frac:               float     Ratio of GPUs in the offer to gpus in the system
+            gpu_display_active:     bool      True if the GPU has a display attached
+            has_avx:                bool      CPU supports AVX instruction set.
+            id:                     int       instance unique ID
+            inet_down:              float     internet download speed in Mb/s
+            inet_down_cost:         float     internet download bandwidth cost in $/GB
+            inet_up:                float     internet upload speed in Mb/s
+            inet_up_cost:           float     internet upload bandwidth cost in $/GB
+            machine_id              int       machine id of instance
+            min_bid:                float     current minimum bid price in $/hr for interruptible
+            num_gpus:               int       # of GPUs
+            pci_gen:                float     PCIE generation
+            pcie_bw:                float     PCIE bandwidth (CPU to GPU)
+            reliability:            float     machine reliability score (see FAQ for explanation)
+            rentable:               bool      is the instance currently rentable
+            rented:                 bool      allow/disallow duplicates and potential conflicts with existing stopped instances
+            storage_cost:           float     storage cost in $/GB/month
+            static_ip:              bool      is the IP addr static/stable
+            total_flops:            float     total TFLOPs from all GPUs
+            ubuntu_version          string    host machine ubuntu OS version
+            verified:               bool      is the machine verified
+            vms_enabled:            bool      is the machine a VM instance
+    """),
+    aliases=hidden_aliases(["search instances"]),
+)
+def search__offers(args):
+    """Creates a query based on search parameters as in the examples above.
+
+    :param argparse.Namespace args: should supply all the command-line options
+    """
+
+    try:
+
+        if args.no_default:
+            query = {}
+        else:
+            query = {"verified": {"eq": True}, "external": {"eq": False}, "rentable": {"eq": True}, "rented": {"eq": False}}
+            #query = {"verified": {"eq": True}, "external": {"eq": False}, "rentable": {"eq": True} }
+
+        if args.query is not None:
+            query = parse_query(args.query, query, offers_fields, offers_alias, offers_mult)
+
+        order = []
+        for name in args.order.split(","):
+            name = name.strip()
+            if not name: continue
+            direction = "asc"
+            field = name
+            if name.startswith("-"):
+                direction = "desc"
+                field = name.lstrip("-")
+            elif name.startswith("+"):
+                direction = "asc"
+                field = name.lstrip("+")
+            #print(f"{field} {name} {direction}")
+            if field in offers_alias:
+                field = offers_alias[field];
+            order.append([field, direction])
+
+        query["order"] = order
+        query["type"] = args.type
+        if (args.limit):
+            query["limit"] = int(args.limit)
+        query["allocated_storage"] = args.storage
+        # For backwards compatibility, support --type=interruptible option
+        if query["type"] == 'interruptible':
+            query["type"] = 'bid'
+        if args.disable_bundling:
+            query["disable_bundling"] = True
+    except ValueError as e:
+        print("Error: ", e)
+        return 1
+
+    new_search_ept = args.new
+    
+    #json_blob = {"select_cols" : ['*'], "q" : query}
+    json_blob = query
+
+    if new_search_ept:
+        #geolocation = query.pop("geolocation", None)
+        #query = {'reliability2': {'gt': '0.1'}}
+        json_blob = {"select_cols" : ['*'], "q" : query}
+        url = apiurl(args, "/search/asks/")
+        stime = time.time()
+
+        if (args.explain):
+            print("request json: ")
+            print(json_blob)
+
+        r = http_put(args, url, headers=headers, json=json_blob)
+        etime = time.time()
+        print(f"request took {etime-stime}s")
+
+    else:
+        if (args.explain):
+            print("request json: ")
+            print(json_blob)
+        #url = apiurl(args, "/bundles", {"q": query})
+        #r = requests.get(url, headers=headers)
+        url = apiurl(args, "/bundles/")
+        r = http_post(args, url, headers=headers, json=json_blob)
+
+    r.raise_for_status()
+   
+    if (r.headers.get('Content-Type') != 'application/json'):
+        print(f"invalid return Content-Type: {r.headers.get('Content-Type')}")
+        return   
+
+    rows = r.json().get("offers", [])
+
+    # TODO: add this post-query geolocation filter to the database call rather than handling it locally
+    if 'rented' in query:
+        filter_q  = query['rented']
+        filter_op = list(filter_q.keys())[0]
+        target    = filter_q[filter_op]
+        new_rows  = []
+        for row in rows:
+            rented = False
+            if "rented" in row and row["rented"] is not None:
+                rented = row["rented"]
+            if filter_op == "eq" and rented == target:
+                new_rows.append(row)
+            if filter_op == "neq" and rented != target:
+                new_rows.append(row)
+            if filter_op == "in" and rented in target:
+                new_rows.append(row)
+            if filter_op == "notin" and rented not in target:
+                new_rows.append(row)
+        rows = new_rows
+
+    if args.raw:
+        return rows
+    else:
+        if args.type == "reserved":           
+            display_table(rows, displayable_fields_reserved)
+        else:
+            display_table(rows, displayable_fields)
+
+
+templates_fields = {
+    "creator_id",#              int        ID of creator
+    "created_at",#              float      time of initial template creation (UTC epoch timestamp)
+    "count_created",#           int        #instances created (popularity)
+    "default_tag",#             string     image default tag
+    "docker_login_repo",#       string     image docker repository
+    "id",#                      int        template unique ID
+    "image",#                   string     image used for benchmark
+    "jup_direct",#              bool       supports jupyter direct
+    "hash_id",#                 string     unique hash ID of template
+    "private",#                 bool       true: only your templates, None: public templates
+    "name",#                    string     displayable name
+    "recent_create_date",#      float      last time of instance creation (UTC epoch timestamp)
+    "recommended_disk_space",#  float      min disk space required
+    "recommended",#             bool       is templated on our recommended list
+    "ssh_direct",#              bool       supports ssh direct
+    "tag",#                     string     image tag
+    "use_ssh",#                 string     supports ssh (direct or proxy)
+}
+
+@parser.command(
+    argument("query", help="Search query in simple query syntax (see below)", nargs="*", default=None),
+    description="Search available templates with filters",
+    usage="vastai search templates [--help] [--api-key API_KEY] [--raw] <query>",
+    help="Search available templates with filters",
+    epilog=deindent("""
+        Query syntax:
+
+            query = comparison comparison...
+            comparison = field op value
+            field = <name of a field>
+            op = one of: <, <=, ==, !=, >=, >, in, notin
+            value = <bool, int, float, string> | 'any' | [value0, value1, ...]
+            bool: True, False
+
+        note: to pass '>' and '<' on the command line, make sure to use quotes
+        note: to encode a string query value (ie for gpu_name), replace any spaces ' ' with underscore '_'
+
+        Examples:
+
+            # search for somewhat reliable single RTX 3090 instances, filter out any duplicates or offers that conflict with our existing stopped instances
+            vastai search templates 'count_created > 100  creator_id in [38382,48982]'
+
+        Available fields:
+
+      Name                  Type       Description
+
+    creator_id              int        ID of creator
+    created_at              float      time of initial template creation (UTC epoch timestamp)
+    count_created           int        #instances created (popularity)
+    default_tag             string     image default tag
+    docker_login_repo       string     image docker repository
+    id                      int        template unique ID
+    image                   string     image used for template
+    jup_direct              bool       supports jupyter direct
+    hash_id                 string     unique hash ID of template
+    name                    string     displayable name
+    recent_create_date      float      last time of instance creation (UTC epoch timestamp)
+    recommended_disk_space  float      min disk space required
+    recommended             bool       is templated on our recommended list
+    ssh_direct              bool       supports ssh direct
+    tag                     string     image tag
+    use_ssh                 bool       supports ssh (direct or proxy)    """),
+    aliases=hidden_aliases(["search templates"]),
+)
+def search__templates(args):
+    """Creates a query based on search parameters as in the examples above.
+    :param argparse.Namespace args: should supply all the command-line options
+    """
+    try:
+        query = {}
+        if args.query is not None:
+            query = parse_query(args.query, query, templates_fields)
+            query = fix_date_fields(query, ['created_at', 'recent_create_date'])
+
+    except ValueError as e:
+        print("Error: ", e)
+        return 1  
+    url = apiurl(args, "/template/", {"select_cols" : ['*'], "select_filters" : query})
+    r = http_get(args, url, headers=headers)
+    if r.status_code != 200:
+        print(r.text)
+        r.raise_for_status()
+    elif 'json' in r.headers.get("Content-Type"):
+        rows = r.json().get('templates', [])
+        if args.raw:
+            return rows
+        else:
+            display_table(rows, displayable_fields)
+    else:
+        print(r.text)
+        print("failed with error {r.status_code}".format(**locals()))
+
+@parser.command(
+    argument("-n", "--no-default", action="store_true", help="Disable default query"),
+    argument("--limit", type=int, help=""),
+    argument("--storage", type=float, default=1.0, help="Amount of storage to use for pricing, in GiB. default=1.0GiB"),
+    argument("-o", "--order", type=str, help="Comma-separated list of fields to sort on. postfix field with - to sort desc. ex: -o 'disk_space,inet_up-'.  default='score-'", default='score-'),
+    argument("query", help="Query to search for. default: 'external=false verified=true disk_space>=1', pass -n to ignore default", nargs="*", default=None),
+    description="Search available volume offers with filters",
+    usage="vastai search volumes [--help] [--api-key API_KEY] [--raw] <query>",
+    help="Search available volume offers with filters",
+    epilog=deindent("""
+        Query syntax:
+
+            query = comparison comparison...
+            comparison = field op value
+            field = <name of a field>
+            op = one of: <, <=, ==, !=, >=, >, in, notin
+            value = <bool, int, float, string> | 'any' | [value0, value1, ...]
+            bool: True, False
+
+        note: to pass '>' and '<' on the command line, make sure to use quotes
+        note: to encode a string query value (ie for gpu_name), replace any spaces ' ' with underscore '_'
+
+        Examples:
+
+            # search for volumes with greater than 50GB of available storage and greater than 500 Mb/s upload and download speed
+            vastai search volumes "disk_space>50 inet_up>500 inet_down>500"
+            
+        Available fields:
+
+              Name                  Type       Description
+
+            cpu_arch:               string    host machine cpu architecture (e.g. amd64, arm64)
+            cuda_vers:              float     machine max supported cuda version (based on driver version)
+            datacenter:             bool      show only datacenter offers
+            disk_bw:                float     disk read bandwidth, in MB/s
+            disk_space:             float     disk storage space, in GB
+            driver_version:         string    machine's nvidia/amd driver version as 3 digit string ex. "535.86.05"
+            duration:               float     max rental duration in days
+            geolocation:            string    Two letter country code. Works with operators =, !=, in, notin (e.g. geolocation not in ['XV','XZ'])
+            gpu_arch:               string    host machine gpu architecture (e.g. nvidia, amd)
+            gpu_name:               string    GPU model name (no quotes, replace spaces with underscores, ie: RTX_3090 rather than 'RTX 3090')
+            has_avx:                bool      CPU supports AVX instruction set.
+            id:                     int       volume offer unique ID
+            inet_down:              float     internet download speed in Mb/s
+            inet_up:                float     internet upload speed in Mb/s
+            machine_id:             int       machine id of volume offer
+            pci_gen:                float     PCIE generation
+            pcie_bw:                float     PCIE bandwidth (CPU to GPU)
+            reliability:            float     machine reliability score (see FAQ for explanation)
+            storage_cost:           float     storage cost in $/GB/month
+            static_ip:              bool      is the IP addr static/stable
+            total_flops:            float     total TFLOPs from all GPUs
+            ubuntu_version:         string    host machine ubuntu OS version
+            verified:               bool      is the machine verified
+    """),
+)
+def search__volumes(args: argparse.Namespace):
+    try:
+
+        if args.no_default:
+            query = {}
+        else:
+            query = {"verified": {"eq": True}, "external": {"eq": False}, "disk_space": {"gte": 1}}
+
+        if args.query is not None:
+            query = parse_query(args.query, query, vol_offers_fields, {}, offers_mult)
+
+        order = []
+        for name in args.order.split(","):
+            name = name.strip()
+            if not name: continue
+            direction = "asc"
+            field = name
+            if name.startswith("-"):
+                direction = "desc"
+                field = name.lstrip("-")
+            elif name.startswith("+"):
+                direction = "asc"
+                field = name.lstrip("+")
+            if field in offers_alias:
+                field = offers_alias[field];
+            order.append([field, direction])
+
+        query["order"] = order
+        if (args.limit):
+            query["limit"] = int(args.limit)
+        query["allocated_storage"] = args.storage
+    except ValueError as e:
+        print("Error: ", e)
+        return 1
+
+    json_blob = query
+
+    if (args.explain):
+        print("request json: ")
+        print(json_blob)
+    url = apiurl(args, "/volumes/search/")
+    r = http_post(args, url, headers=headers, json=json_blob)
+
+    r.raise_for_status()
+   
+    if (r.headers.get('Content-Type') != 'application/json'):
+        print(f"invalid return Content-Type: {r.headers.get('Content-Type')}")
+        return   
+
+    rows = r.json().get("offers", [])
+
+    if args.raw:
+        return rows
+    else:
+        display_table(rows, vol_displayable_fields)
+
+
+
+@parser.command(
+    argument("-n", "--no-default", action="store_true", help="Disable default query"),
+    argument("--limit", type=int, help=""),
+    argument("--storage", type=float, default=1.0, help="Amount of storage to use for pricing, in GiB. default=1.0GiB"),
+    argument("-o", "--order", type=str, help="Comma-separated list of fields to sort on. postfix field with - to sort desc. ex: -o 'disk_space,inet_up-'.  default='score-'", default='score-'),
+    argument("query", help="Query to search for. default: 'external=false verified=true disk_space>=1', pass -n to ignore default", nargs="*", default=None),
+    description="[Host] [Beta] Search available network volume offers with filters",
+    usage="vastai search network volumes [--help] [--api-key API_KEY] [--raw] <query>",
+    help="[Host] [Beta] Search available network volume offers with filters",
+    epilog=deindent("""
+        Query syntax:
+
+            query = comparison comparison...
+            comparison = field op value
+            field = <name of a field>
+            op = one of: <, <=, ==, !=, >=, >, in, notin
+            value = <bool, int, float, string> | 'any' | [value0, value1, ...]
+            bool: True, False
+
+        note: to pass '>' and '<' on the command line, make sure to use quotes
+        note: to encode a string query value (ie for gpu_name), replace any spaces ' ' with underscore '_'
+
+        Examples:
+
+            # search for volumes with greater than 50GB of available storage and greater than 500 Mb/s upload and download speed
+            vastai search volumes "disk_space>50 inet_up>500 inet_down>500"
+            
+        Available fields:
+
+              Name                  Type       Description
+            duration:               float     max rental duration in days
+            geolocation:            string    Two letter country code. Works with operators =, !=, in, notin (e.g. geolocation not in ['XV','XZ'])
+            id:                     int       volume offer unique ID
+            inet_down:              float     internet download speed in Mb/s
+            inet_up:                float     internet upload speed in Mb/s
+            reliability:            float     machine reliability score (see FAQ for explanation)
+            storage_cost:           float     storage cost in $/GB/month
+            verified:               bool      is the machine verified
+    """),
+)
+def search__network_volumes(args: argparse.Namespace):
+    try:
+
+        if args.no_default:
+            query = {}
+        else:
+            query = {"verified": {"eq": True}, "external": {"eq": False}, "disk_space": {"gte": 1}}
+
+        if args.query is not None:
+            query = parse_query(args.query, query, vol_offers_fields, {}, offers_mult)
+
+        order = []
+        for name in args.order.split(","):
+            name = name.strip()
+            if not name: continue
+            direction = "asc"
+            field = name
+            if name.startswith("-"):
+                direction = "desc"
+                field = name.lstrip("-")
+            elif name.startswith("+"):
+                direction = "asc"
+                field = name.lstrip("+")
+            if field in offers_alias:
+                field = offers_alias[field];
+            order.append([field, direction])
+
+        query["order"] = order
+        if (args.limit):
+            query["limit"] = int(args.limit)
+        query["allocated_storage"] = args.storage
+    except ValueError as e:
+        print("Error: ", e)
+        return 1
+
+    json_blob = query
+
+    if (args.explain):
+        print("request json: ")
+        print(json_blob)
+    url = apiurl(args, "/network_volumes/search/")
+    r = http_post(args, url, headers=headers, json=json_blob)
+
+    r.raise_for_status()
+   
+    if (r.headers.get('Content-Type') != 'application/json'):
+        print(f"invalid return Content-Type: {r.headers.get('Content-Type')}")
+        return   
+
+    rows = r.json().get("offers", [])
+
+    if args.raw:
+        return rows
+    else:
+        display_table(rows, nw_vol_displayable_fields)
+
+
+@parser.command(
+    argument("api_key", help="API key to set as currently logged in user"),
+    description="Set the API key for CLI and SDK authentication",
+    usage="vastai set api-key API_KEY",
+    help="Set the API key for CLI and SDK authentication",
+    epilog=deindent("""
+        Stores your Vast.ai API key locally for authentication with all CLI commands.
+        Get your API key from the Vast.ai console: https://console.vast.ai/account/
+
+        Examples:
+            vastai set api-key abc123def456...         # Set your API key
+
+        Security notes:
+          - API key is stored in ~/.config/vastai/vast_api_key
+          - Permissions are set to user-read-only (600)
+          - Do NOT share your API key or commit it to version control
+          - Regenerate your key at https://console.vast.ai/account/ if compromised
+          - You can also use the VAST_API_KEY environment variable instead
+
+        The legacy location ~/.vast_api_key is automatically removed when you set a new key.
+    """),
+)
+def set__api_key(args):
+    """Caution: a bad API key will make it impossible to connect to the servers.
+    :param argparse.Namespace args: should supply all the command-line options
+    """
+    with open(APIKEY_FILE, "w") as writer:
+        writer.write(args.api_key)
+    print("Your api key has been saved in {}".format(APIKEY_FILE))
     
+    APIKEY_FILE_HOME = os.path.expanduser("~/.vast_api_key") # Legacy
+    if os.path.exists(APIKEY_FILE_HOME):
+        os.remove(APIKEY_FILE_HOME)
+        print("Your api key has been removed from {}".format(APIKEY_FILE_HOME))
+
+
+
+@parser.command(
+    argument("--file", help="file path for params in json format", type=str),
+    description="Update account settings from a JSON file",
+    usage="vastai set user --file FILE",
+    help="Update account settings from a JSON file",
+    epilog=deindent("""
+
+    Available fields:
+
+    Name                            Type       Description
+
+    ssh_key                         string
+    paypal_email                    string
+    wise_email                      string
+    email                           string
+    normalized_email                string
+    username                        string
+    fullname                        string
+    billaddress_line1               string
+    billaddress_line2               string
+    billaddress_city                string
+    billaddress_zip                 string
+    billaddress_country             string
+    billaddress_taxinfo             string
+    balance_threshold_enabled       string
+    balance_threshold               string
+    autobill_threshold              string
+    phone_number                    string
+    tfa_enabled                     bool
+    """),
+)
+def set__user(args):
+    params = None
+    with open(args.file, 'r') as file:
+        params = json.load(file)
+    url = apiurl(args, "/users/")
+    r = http_put(args, url, headers=headers, json=params)
+    r.raise_for_status()
     try:
-        # Parse dates - handle both YYYY-MM-DD format and timestamps
-        start_timestamp = to_timestamp_(args.start_date)
-        end_timestamp = to_timestamp_(args.end_date)
-    except Exception as e:
-        print(f"Error parsing dates: {e}")
-        print("Use format YYYY-MM-DD or UNIX timestamp")
-        return
+        print(f"{r.json()}")
+    except JSONDecodeError:
+        print(r.text)
+
+
+
+@parser.command(
+    argument("id", help="id of instance", type=int),
+    description="Generate SSH connection URL for an instance",
+    usage="vastai ssh-url ID",
+    help="Generate SSH connection URL for an instance",
+    epilog=deindent("""
+        Retrieves the SSH connection URL for an instance. Use this to get the host and port
+        information needed to connect via SSH.
+
+        Examples:
+            vastai ssh-url 12345                       # Get SSH URL for instance 12345
+
+        Output format:
+            ssh://root@<ip_address>:<port>
+
+        Use with ssh command:
+            ssh -p <port> root@<ip_address>
+
+        See also: 'vastai scp-url' for SCP file transfer URLs
+    """),
+)
+def ssh_url(args):
+    """
+
+    :param argparse.Namespace args: should supply all the command-line options
+    :rtype:
+    """
+    return _ssh_url(args, "ssh://")
 
-    if has_rich and not args.no_color:
-        print("(use --no-color to disable colored output)\n")
-    
-    start_date = convert_timestamp_to_date(start_timestamp)
-    end_date = convert_timestamp_to_date(end_timestamp)
-    data_type = "Instance Charges" if args.charges else "Invoices"
-    output_lines.append(f"Fetching {data_type} from {start_date} to {end_date}...")
 
-    # Build request parameters
-    date_col = 'day' if args.charges else 'when'
-    params = {
-        'select_filters': {date_col: {'gte': start_timestamp, 'lte': end_timestamp}},
-        'latest_first': args.latest_first,
-        'limit': min(args.limit, 100) if args.limit > 0 else 20,  # Enforce max limit of 100
-    }
-    if args.charges:
-        params['format'] = args.format
-        for ct in args.charge_type or []:
-            filters = params['select_filters'].setdefault('type', {}).setdefault('in', [])
-            if   ct in {'i','instance'}:   filters.append('instance')
-            elif ct in {'v','volume'}:     filters.append('volume')
-            elif ct in {'s','serverless'}: filters.append('serverless')
-    
-    if args.invoices:
-        for it in args.invoice_type or []:
-            filters = params['select_filters'].setdefault('service', {}).setdefault('in', [])
-            filters.append(invoice_types[it])
-    
-    if args.next_token:
-        params['after_token'] = args.next_token
+@parser.command(
+    argument("id",   help="id", type=int),
+    description="Generate SCP file transfer URL for an instance",
+    usage="vastai scp-url ID",
+    help="Generate SCP file transfer URL for an instance",
+    epilog=deindent("""
+        Retrieves the SCP connection URL for an instance. Use this to get the host and port
+        information needed to transfer files via SCP.
 
-    endpoint = '/api/v0/charges/' if args.charges else '/api/v1/invoices/'
-    url = apiurl(args, endpoint, query_args=params)
+        Examples:
+            vastai scp-url 12345                       # Get SCP URL for instance 12345
 
-    found_results, found_count = [], 0
-    looping = True
-    while looping:
-        response = http_get(args, url)
-        response.raise_for_status()
-        response = response.json()
+        Output format:
+            scp://root@<ip_address>:<port>
 
-        found_results += response.get('results', [])
-        found_count += response.get('count', 0)
-        total = response.get('total', 0)
-        next_token = response.get('next_token')
-        
-        if args.raw or has_rich is False:
-            output_lines.append("Raw response:\n" + json.dumps(response, indent=2))
-            if next_token:
-                print(f"Next page token: {next_token}\n")
-        elif not found_results:
-            output_lines.append("No results found")
-        else:  # Display results
-            formatted_results = format_invoices_charges_results(args, deepcopy(found_results))
-            if args.invoices:
-                rich_obj = create_rich_table_for_invoices(formatted_results)
-            elif args.format == 'tree':
-                rich_obj = create_charges_tree(formatted_results)
-            else:
-                rich_obj = create_rich_table_for_charges(args, formatted_results)
+        Use with scp command:
+            scp -P <port> local_file root@<ip_address>:/remote/path
+            scp -P <port> root@<ip_address>:/remote/file ./local_path
 
-            output_lines.append(rich_object_to_string(rich_obj, no_color=args.no_color))
-            output_lines.append(f"Showing {found_count} of {total} results")
-            if next_token:
-                output_lines.append(f"Next page token: {next_token}\n")
-        
-        paging = print_or_page(args, '\n'.join(output_lines))
+        See also: 'vastai ssh-url' for SSH connection URLs, 'vastai copy' for simplified file transfers
+    """),
+)
+def scp_url(args):
+    """
 
-        if next_token and not paging:
-            if has_rich:
-                ans = Confirm.ask("Fetch next page?", show_default=False, default=False)
-            else:
-                ans = input("Fetch next page? (y/N): ").strip().lower() == 'y'
-            if ans:
-                params['after_token'] = next_token
-                url = apiurl(args, endpoint, query_args=params)
-                output_lines.clear()
-                args.full = True
-            else:
-                looping = False
-        else:
-            looping = False
+    :param argparse.Namespace args: should supply all the command-line options
+    :rtype:
+    """
+    return _ssh_url(args, "scp://")
 
-def format_invoices_charges_results(args, results):
-    indices_to_remove = []
-    for i,item in enumerate(results):
-        item['start'] = convert_timestamp_to_date(item['start']) if item['start'] else None
-        item['end'] = convert_timestamp_to_date(item['end']) if item['end'] else None
-        if item['amount'] == 0:
-            indices_to_remove.append(i)  # Removing items that don't contribute to the total
-        elif args.invoices:
-            if item['type'] not in {'transfer', 'payout'}:
-                item['amount'] *= -1  # present amounts intuitively as related to balance
-            item['amount_str'] = f"${item['amount']:.2f}" if item['amount'] > 0 else f"-${abs(item['amount']):.2f}"
-        else:
-            item['amount'] = f"${item['amount']:.3f}"
 
-        if args.charges:
-            if item['type'] in {'instance','volume'} and not args.verbose:
-                item['items'] = []  # Remove instance charge details if verbose is not set
-            if item['source'] and '-' in item['source']:
-                item['type'], item['source'] = item['source'].capitalize().split('-')
-        
-        item['items'] = format_invoices_charges_results(args, item['items'])
-    
-    for i in reversed(indices_to_remove):  # Remove in reverse order to avoid index shifting
-        del results[i]
-    
-    return results
+def _ssh_url(args, protocol):
 
+    json_object = None
 
-def rich_object_to_string(rich_obj, no_color=True):
-    """ Render a Rich object (Table or Tree) to a string. """
-    from rich.console import Console
-    buffer = StringIO()  # Use an in-memory stream to suppress visible output
-    console = Console(record=True, file=buffer)
-    console.print(rich_obj)
-    return console.export_text(clear=True, styles=not no_color)
+    # Opening JSON file
+    try:
+        with open(f"{DIRS['temp']}/ssh_{args.id}.json", 'r') as openfile:
+            json_object = json.load(openfile)
+    except (OSError, json.JSONDecodeError, KeyError):
+        pass
 
-def create_charges_tree(results, parent=None, title="Charges Breakdown"):
-    """ Build and return a Rich Tree from nested charge results. """
-    from rich.text import Text
-    from rich.tree import Tree
-    from rich.panel import Panel
-    if parent is None:  # Create root node if this is the first call
-        root = Tree(Text(title, style="bold red"))
-        create_charges_tree(results, root)
-        return Panel(root, style="white on #000000", expand=False)
-    
-    top_level = (parent.label.plain == title)
-    for item in results:
-        end_date = f" → {item['end']}" if item['start'] != item['end'] else ""
-        label = Text.assemble(
-            (item["type"], "bold cyan"),
-            (f" {item['source']}" if item.get('source') else "", "gold1"), " → ",
-            (f"{item['amount']}", 'bold green1' if top_level else 'green1'),
-            (f" — {item['description']}", "bright_white" if top_level else "dim white"),
-            (f"  ({item['start']}{end_date})", "bold bright_white" if top_level else "white")
-        )
-        node = parent.add(label, guide_style="blue3")
-        if item.get("items"):
-            create_charges_tree(item["items"], node)
-    return parent
+    port      = None
+    ipaddr    = None
 
-def create_rich_table_for_charges(args, results):
-    """ Build and return a Rich Table from charge results. """
-    from rich.table import Table
-    from rich.text import Text
-    from rich import box
-    from rich.padding import Padding
-    table = Table(style="white", header_style="bold bright_yellow", box=box.DOUBLE_EDGE, row_styles=["on grey11", "none"])
-    table.add_column(Text("Type", justify="center"), style="bold steel_blue1", justify="center")
-    table.add_column(Text("ID", justify="center"), style="gold1", justify="center")
-    table.add_column(Text("Amount", justify="center"), style="sea_green2", justify="right")
-    table.add_column(Text("Start", justify="center"), style="bright_white", justify="center")
-    table.add_column(Text("End", justify="center"), style="bright_white", justify="center")
-    if not args.charge_type or 'serverless' in args.charge_type:
-        table.add_column(Text("Endpoint", justify="center"), style="bright_red", justify="center")
-        table.add_column(Text("Workergroup", justify="center"), style="orchid", justify="center")
-    for item in results:
-        row = [item['type'].capitalize(), item['source'], item['amount'], item['start'], item['end']]
-        if not args.charge_type or 'serverless' in args.charge_type:
-            row.append(str(item['metadata'].get('endpoint_id', '')))
-            row.append(str(item['metadata'].get('workergroup_id', '')))
-        table.add_row(*row)
-    return Padding(table, (1, 2), style="on #000000", expand=False)  # Print with a black background
+    if json_object is not None:
+        ipaddr = json_object["ipaddr"]
+        port   = json_object["port"]
 
-def create_rich_table_for_invoices(results):
-    """ Build and return a Rich Table from invoice results. """
-    from rich.table import Table
-    from rich.text import Text
-    from rich import box
-    from rich.padding import Padding
-    invoice_type_to_color = {
-        "credit": "green1",
-        "transfer": "gold1",
-        "payout": "orchid",
-        "reserved": "sky_blue1",
-        "refund": "bright_red",
-    }
-    table = Table(style="white", header_style="bold bright_yellow", box=box.DOUBLE_EDGE, row_styles=["on grey11", "none"])
-    table.add_column(Text("ID", justify="center"), style="bright_white", justify="center")
-    table.add_column(Text("Created", justify="center"), style="yellow3", justify="center")
-    table.add_column(Text("Paid", justify="center"), style="yellow3", justify="center")
-    table.add_column(Text("Type", justify="center"), justify="center")
-    table.add_column(Text("Result", justify="center"), justify="right")
-    table.add_column(Text("Source", justify="center"), style="bright_cyan", justify="center")
-    table.add_column(Text("Description", justify="center"), style="bright_white", justify="left")
-    for item in results:
-        table.add_row(
-            str(item['metadata']['invoice_id']),
-            item['start'],
-            item['end'] if item['end'] else 'N/A',
-            Text(item['type'].capitalize(), style=invoice_type_to_color.get(item['type'], "white")),
-            Text(item['amount_str'], style="sea_green2" if item['amount'] > 0 else "bright_red"),
-            item['source'].capitalize() if item['type'] != 'transfer' else item['source'],
-            item['description'],
-        )
-    return Padding(table, (1, 2), style="on #000000", expand=False)  # Print with a black background
+    if ipaddr is None or ipaddr.endswith('.vast.ai'):
+        req_url = apiurl(args, "/instances", {"owner": "me"})
+        r = http_get(args, req_url)
+        r.raise_for_status()
+        try:
+            rj = r.json()
+        except JSONDecodeError:
+            print("Error: API returned invalid JSON response", file=sys.stderr)
+            return 1
+        rows = rj.get("instances", [])
 
-def create_rich_table_from_rows(rows, headers=None, title='', sort_key=None):
-    """ (Generic) Creates a Rich table from a list of dict rows. """
-    from rich import box
-    from rich.table import Table
-    if not isinstance(rows, list):
-        raise ValueError("Invalid Data Type: rows must be a list")
-    # Handle list of dictionaries
-    if isinstance(rows[0], dict):
-        headers = headers or list(rows[0].keys())
-        rows = [[row_dict.get(h, "") for h in headers] for row_dict in rows]
-    elif headers is None:
-        raise ValueError("Headers must be provided if rows are not dictionaries")
-    # Sort rows if requested
-    if sort_key:
-        rows = sorted(rows, key=sort_key)
-    # Create the Rich table
-    table = Table(title=title, style="white", header_style="bold bright_yellow", box=box.DOUBLE_EDGE)
-    # Add columns
-    for header in headers:
-        # You can customize alignment and style here per column
-        table.add_column(header, justify="left", style="bright_white", no_wrap=True)
-    # Add rows
-    for row in rows:
-        # Convert everything to string to avoid type issues
-        table.add_row(*[str(cell) for cell in row])
-    return table
+        if args.id:
+            matches = [r for r in rows if r['id'] == args.id]
+            if not matches:
+                print(f"error: no instance found with id {args.id}")
+                return 1
+            instance = matches[0]
+        elif len(rows) > 1:
+            print("Found multiple running instances")
+            return 1
+        else:
+            instance = rows[0]
+
+        ports     = instance.get("ports",{})
+        port_22d  = ports.get("22/tcp",None)
+        port      = -1
+        try:
+            if (port_22d is not None):
+                ipaddr = instance["public_ipaddr"]
+                port   = int(port_22d[0]["HostPort"])
+            else:
+                ipaddr = instance["ssh_host"]
+                port   = int(instance["ssh_port"])+1 if "jupyter" in instance["image_runtype"] else int(instance["ssh_port"])
+        except (KeyError, TypeError, ValueError):
+            port = -1
+
+    if (port > 0):
+        print(f'{protocol}root@{ipaddr}:{port}')
+    else:
+        print(f'error: ssh port not found')
 
+   
+    # Writing to sample.json
+    try:
+        with open(f"{DIRS['temp']}/ssh_{args.id}.json", "w") as outfile:
+            json.dump({"ipaddr":ipaddr, "port":port}, outfile)
+    except OSError:
+        pass
 
 @parser.command(
-    argument("id", help="id of instance to get", type=int),
-    usage="vastai show instance [--api-key API_KEY] [--raw]",
-    help="Display user's current instances"
+    argument("id", help="id of API key to show", type=int),
+    description="Show details for a specific API key",
+    usage="vastai show api-key ID",
+    help="Show details for a specific API key",
 )
-def show__instance(args):
-    """
-    Shows the stats on the machine the user is renting.
-
-    :param argparse.Namespace args: should supply all the command-line options
-    :rtype:
-    """
+def show__api_key(args):
+    result = api_call(args, "GET", f"/auth/apikeys/{args.id}/")
+    return output_result(args, result)
 
-    #req_url = apiurl(args, "/instance", {"owner": "me"});
-    req_url = apiurl(args, "/instances/{id}/".format(id=args.id) , {"owner": "me"} )
-   
-    #r = http_get(req_url)
-    r = http_get(args, req_url)
+@parser.command(
+    description="List all API keys for your account",
+    usage="vastai show api-keys",
+    help="List all API keys for your account",
+)
+def show__api_keys(args):
+    url = apiurl(args, "/auth/apikeys/")
+    r = http_get(args, url, headers=headers)
     r.raise_for_status()
-    row = r.json()["instances"]
-    row['duration'] = time.time() - row['start_date']
-    row['extra_env'] = {env_var[0]: env_var[1] for env_var in row['extra_env']}
     if args.raw:
-        return row
+        return r.json()
     else:
-        #print(row)
-        display_table([row], instance_fields)
+        print(r.json())
+
 
 @parser.command(
-    argument("-q", "--quiet", action="store_true", help="only display numeric ids"),
-    usage="vastai show instances [OPTIONS] [--api-key API_KEY] [--raw]",
-    help="Display user's current instances"
+    description="Show account activity and audit logs",
+    usage="vastai show audit-logs [--api-key API_KEY] [--raw]",
+    help="Show account activity and audit logs"
 )
-def show__instances(args = {}, extra = {}):
+def show__audit_logs(args):
     """
-    Shows the stats on the machine the user is renting.
+    Shows the history of ip address accesses to console.vast.ai endpoints
 
     :param argparse.Namespace args: should supply all the command-line options
     :rtype:
     """
-    req_url = apiurl(args, "/instances", {"owner": "me"});
-    #r = http_get(req_url)
-    r = http_get(args, req_url)
-    r.raise_for_status()
-    rows = r.json()["instances"]
-    for row in rows:
-        row = {k: strip_strings(v) for k, v in row.items()} 
-        row['duration'] = time.time() - row['start_date']
-        row['extra_env'] = {env_var[0]: env_var[1] for env_var in row['extra_env']}
-    if 'internal' in extra:
-        return [str(row[extra['field']]) for row in rows]
-    elif args.quiet:
-        for row in rows:
-            id = row.get("id", None)
-            if id is not None:
-                print(id)
-    elif args.raw:
-        return rows
+    rows = api_call(args, "GET", "/audit_logs/")
+    return output_result(args, rows, audit_log_fields)
+
+def normalize_schedule_fields(job):
+    """
+    Mutates the job dict to replace None values with readable scheduling labels.
+    """
+    if job.get("day_of_the_week") is None:
+        job["day_of_the_week"] = "Everyday"
     else:
-        display_table(rows, instance_fields)
+        days = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]
+        job["day_of_the_week"] = days[int(job["day_of_the_week"])]
+    
+    if job.get("hour_of_the_day") is None:
+        job["hour_of_the_day"] = "Every hour"
+    else:
+        hour = int(job["hour_of_the_day"])
+        suffix = "AM" if hour < 12 else "PM"
+        hour_12 = hour % 12
+        hour_12 = 12 if hour_12 == 0 else hour_12
+        job["hour_of_the_day"] = f"{hour_12}_{suffix}"
 
+    if job.get("min_of_the_hour") is None:
+        job["min_of_the_hour"] = "Every minute"
+    else:
+        job["min_of_the_hour"] = f"{int(job['min_of_the_hour']):02d}"
+    
+    return job
 
+def normalize_jobs(jobs):
+    """
+    Applies normalization to a list of job dicts.
+    """
+    return [normalize_schedule_fields(job) for job in jobs]
 
 
 @parser.command(
-    usage="vastai show ipaddrs [--api-key API_KEY] [--raw]",
-    help="Display user's history of ip addresses"
+    description="List all scheduled automation jobs",
+    usage="vastai show scheduled-jobs [--api-key API_KEY] [--raw]",
+    help="List all scheduled automation jobs"
 )
-def show__ipaddrs(args):
+def show__scheduled_jobs(args):
     """
-    Shows the history of ip address accesses to console.vast.ai endpoints
+    Shows the list of scheduled jobs for the account.
 
     :param argparse.Namespace args: should supply all the command-line options
     :rtype:
     """
-
-    req_url = apiurl(args, "/users/me/ipaddrs", {"owner": "me"});
-    r = http_get(args, req_url);
-    r.raise_for_status()
-    rows = r.json()["results"]
+    rows = api_call(args, "GET", "/commands/schedule_job/")
     if args.raw:
         return rows
     else:
-        display_table(rows, ipaddr_fields)
+        rows = normalize_jobs(rows)
+        display_table(rows, scheduled_jobs_fields)
 
+@parser.command(
+    description="List all SSH keys registered to your account",
+    usage="vastai show ssh-keys",
+    help="List all SSH keys registered to your account",
+)
+def show__ssh_keys(args):
+    url = apiurl(args, "/ssh/")
+    r = http_get(args, url, headers=headers)
+    r.raise_for_status()
+    if args.raw:
+        return r.json()
+    else:
+        print(r.json())
 
 @parser.command(
-    usage="vastai show clusters",
-    help="Show clusters associated with your account.",
+    description="List all your autoscaling worker groups",
+    usage="vastai show workergroups [--api-key API_KEY]",
+    help="List all your autoscaling worker groups",
     epilog=deindent("""
-        Show clusters associated with your account.
-    """)
+        Example: vastai show workergroups 
+    """),
 )
-def show__clusters(args: argparse.Namespace):
-    req_url = apiurl(args, "/clusters/")
-    r = http_get(args, req_url)
+def show__workergroups(args):
+    url = apiurl(args, "/autojobs/" )
+    json_blob = {"client_id": "me"}
+    if (args.explain):
+        print("request json: ")
+        print(json_blob)
+    r = http_get(args, url, headers=headers,json=json_blob)
     r.raise_for_status()
-    response_data = r.json()
+    #print("workergroup list ".format(r.json()))
 
-    if args.raw:
-        return response_data
+    rj = r.json();
+    if rj.get("success"):
+        rows = rj.get("results", [])
+        if args.raw:
+            return rows
+        else:
+            #print(rows)
+            print(json.dumps(rows, indent=1, sort_keys=True))
+    else:
+        print(rj.get("msg", "Unknown error"));
 
-    rows = []
-    for cluster_id, cluster_data in response_data['clusters'].items():
-        machine_ids = [ node["machine_id"] for node in cluster_data["nodes"]]
+@parser.command(
+    description="List all your serverless endpoints",
+    usage="vastai show endpoints [--api-key API_KEY]",
+    help="List all your serverless endpoints",
+    epilog=deindent("""
+        Example: vastai show endpoints
+    """),
+)
+def show__endpoints(args):
+    url = apiurl(args, "/endptjobs/" )
+    json_blob = {"client_id": "me"}
+    if (args.explain):
+        print("request json: ")
+        print(json_blob)
+    r = http_get(args, url, headers=headers,json=json_blob)
+    r.raise_for_status()
+    #print("workergroup list ".format(r.json()))
 
-        manager_node = next(node for node in cluster_data['nodes'] if node['is_cluster_manager'])
+    rj = r.json();
+    if rj.get("success"):
+        rows = rj.get("results", [])
+        for row in rows:
+            row.pop("api_key", None)
+            row.pop("auto_delete_in_seconds", None)
+            row.pop("auto_delete_due_24h", None)
+        if args.raw:
+            return rows
+        else:
+            #print(rows)
+            print(json.dumps(rows, indent=1, sort_keys=True))
+    else:
+        print(rj.get("msg", "Unknown error"));
 
-        row_data = {
-            'id': cluster_id,
-            'subnet': cluster_data['subnet'],
-            'node_count': len(cluster_data['nodes']),
-            'machine_ids': str(machine_ids),
-            'manager_id': str(manager_node['machine_id']),
-            'manager_ip': manager_node['local_ip'],
-        }
 
-        rows.append(row_data)
+@parser.command(
+    description="[Beta] Show network connections between instances",
+    usage="vastai show connections [--api-key API_KEY] [--raw]",
+    help="[Beta] Show network connections between instances"
+)
+def show__connections(args):
+    """
+    Shows the stats on the machine the user is renting.
 
-    display_table(rows, cluster_fields, replace_spaces=False)
+    :param argparse.Namespace args: should supply all the command-line options
+    :rtype:
+    """
+    req_url = apiurl(args, "/users/cloud_integrations/");
+    print(req_url)
+    rows = api_call(args, "GET", "/users/cloud_integrations/")
+    return output_result(args, rows, connection_fields)
 
 
 @parser.command(
-    usage="vastai show overlays",
-    help="Show overlays associated with your account.",
-    epilog=deindent("""
-        Show overlays associated with your account.
-    """)
+    argument("id", help="id of instance to get info for", type=int),
+    description="Show prepaid deposit balance for a reserved instance",
+    usage="vastai show deposit ID [options]",
+    help="Show prepaid deposit balance for a reserved instance"
 )
-def show__overlays(args: argparse.Namespace):
-    req_url = apiurl(args, "/overlay/")
-    r = http_get(args, req_url)
-    r.raise_for_status()
-    response_data = r.json()
-    if args.raw:
-        return response_data
-    rows = []
-    for overlay in response_data:
-        row_data = {
-            'overlay_id': overlay['overlay_id'],
-            'name': overlay['name'],
-            'subnet': overlay['internal_subnet'] if overlay['internal_subnet'] else 'N/A',
-            'cluster_id': overlay['cluster_id'],
-            'instance_count': len(overlay['instances']),
-            'instances': str(overlay['instances']),
-        }
-        rows.append(row_data)
-    display_table(rows, overlay_fields, replace_spaces=False)
-
+def show__deposit(args):
+    """
+    Shows reserve deposit info for an instance.
 
+    :param argparse.Namespace args: should supply all the command-line options
+    :rtype:
+    """
+    rows = api_call(args, "GET", f"/instances/balance/{args.id}/", query_args={"owner": "me"})
+    return output_result(args, rows)
 
 
 @parser.command(
-    argument("-q", "--quiet", action="store_true", help="display subaccounts from current user"),
-    usage="vastai show subaccounts [OPTIONS]",
-    help="Get current subaccounts"
+    argument("-q", "--quiet", action="store_true", help="only display numeric ids"),
+    argument("-s", "--start_date", help="start date and time for report. Many formats accepted", type=str),
+    argument("-e", "--end_date", help="end date and time for report. Many formats accepted ", type=str),
+    argument("-m", "--machine_id", help="Machine id (optional)", type=int),
+    description="[Host] Show rental income history for your machines",
+    usage="vastai show earnings [OPTIONS]",
+    help="[Host] Show rental income history for your machines",
 )
-def show__subaccounts(args):
+def show__earnings(args):
     """
-    Shows stats for logged-in user. Does not show API key.
+    Show earnings history for a time range, optionally per machine. Various options available to limit time range and type of items.
 
     :param argparse.Namespace args: should supply all the command-line options
     :rtype:
     """
-    req_url = apiurl(args, "/subaccounts", {"owner": "me"});
-    r = http_get(args, req_url);
-    r.raise_for_status()
-    rows = r.json()["users"]
-    if args.raw:
-        return rows
-    else:
-        display_table(rows, user_fields)
 
-@parser.command(
-    usage="vastai show members",
-    help="Show your team members",
-)
-def show__members(args):
-    url = apiurl(args, "/team/members/")
-    r = http_get(args, url, headers=headers)
-    r.raise_for_status()
+    Minutes = 60.0
+    Hours	= 60.0*Minutes
+    Days	= 24.0*Hours
+    Years	= 365.0*Days
+    cday    = time.time() / Days
+    sday = cday - 1.0
+    eday = cday - 1.0
+
+    try:
+        import dateutil
+        from dateutil import parser
+
+    except ImportError:
+        print("""\nWARNING: Missing dateutil, can't parse time format""")
+
+    if args.end_date:
+        try:
+            end_date = dateutil.parser.parse(str(args.end_date))
+            end_timestamp = end_date.timestamp()
+            eday = end_timestamp / Days
+        except ValueError as e:
+            print(f"Warning: Invalid end date format! Ignoring end date! \n {str(e)}")
+
+    if args.start_date:
+        try:
+            start_date = dateutil.parser.parse(str(args.start_date))
+            start_timestamp = start_date.timestamp()
+            sday = start_timestamp / Days
+        except ValueError as e:
+            print(f"Warning: Invalid start date format! Ignoring start date! \n {str(e)}")
+
+    rows = api_call(args, "GET", "/users/me/machine-earnings", query_args={"owner": "me", "sday": sday, "eday": eday, "machid": args.machine_id})
+    return output_result(args, rows)
 
-    if args.raw:
-        return r
-    else:
-        print(r.json())
 
-@parser.command(
-    argument("NAME", help="name of the role", type=str),
-    usage="vastai show team-role NAME",
-    help="Show your team role",
-)
-def show__team_role(args):
-    url = apiurl(args, "/team/roles/{id}/".format(id=args.NAME))
-    r = http_get(args, url, headers=headers)
-    r.raise_for_status()
-    print(json.dumps(r.json(), indent=1, sort_keys=True))
+def sum_field(X, k):
+    """Sum the values of field k across all items in X."""
+    y = 0
+    for x in X:
+        a = float(x.get(k, 0))
+        y += a
+    return y
+
+def select(X,k):
+    Y = set()
+    for x in X:
+        v = x.get(k,None)
+        if v is not None:
+            Y.add(v)
+    return Y
 
 @parser.command(
-    usage="vastai show team-roles",
-    help="Show roles for a team"
+    argument("-s", "--show-values", action="store_true", help="Show the values of environment variables"),
+    description="List environment variables set for your account",
+    usage="vastai show env-vars [-s]",
+    help="List environment variables set for your account",
 )
-def show__team_roles(args):
-    url = apiurl(args, "/team/roles-full/")
-    r = http_get(args, url, headers=headers)
-    r.raise_for_status()
+def show__env_vars(args):
+    """Show the environment variables for the current user."""
+    result = api_call(args, "GET", "/secrets/")
+    env_vars = result.get("secrets", {})
 
     if args.raw:
-        return r
+        if not args.show_values:
+            # Replace values with placeholder in raw output
+            masked_env_vars = {k: "*****" for k, v in env_vars.items()}
+            # indent was 2
+            return masked_env_vars
+        else:
+            return env_vars
     else:
-        print(r.json())
+        if not env_vars:
+            print("No environment variables found.")
+        else:
+            for key, value in env_vars.items():
+                print(f"Name: {key}")
+                if args.show_values:
+                    print(f"Value: {value}")
+                else:
+                    print("Value: *****")
+                print("---")
+
+    if not args.show_values:
+        print("\nNote: Values are hidden. Use --show-values or -s option to display them.")
 
 @parser.command(
-    argument("-q", "--quiet", action="store_true", help="display information about user"),
-    usage="vastai show user [OPTIONS]",
-    help="Get current user data",
-    epilog=deindent("""
-        Shows stats for logged-in user. These include user balance, email, and ssh key. Does not show API key.
-    """)
+    argument("-q", "--quiet", action="store_true", help="only display numeric ids"),
+    argument("-s", "--start_date", help="start date and time for report. Many formats accepted (optional)", type=str),
+    argument("-e", "--end_date", help="end date and time for report. Many formats accepted (optional)", type=str),
+    argument("-c", "--only_charges", action="store_true", help="Show only charge items"),
+    argument("-p", "--only_credits", action="store_true", help="Show only credit items"),
+    argument("--instance_label", help="Filter charges on a particular instance label (useful for autoscaler groups)"),
+    description="[Deprecated] Get billing history - use show invoices-v1 instead",
+    usage="(DEPRECATED) vastai show invoices [OPTIONS]",
+    help="[Deprecated] Get billing history - use show invoices-v1 instead",
 )
-def show__user(args):
+def show__invoices(args):
     """
-    Shows stats for logged-in user. Does not show API key.
+    Show current payments and charges. Various options available to limit time range and type
+    of items. Default is to show everything for user's entire billing history.
 
     :param argparse.Namespace args: should supply all the command-line options
     :rtype:
     """
-    req_url = apiurl(args, "/users/current", {"owner": "me"});
-    r = http_get(args, req_url);
-    r.raise_for_status()
-    user_blob = r.json()
-    user_blob.pop("api_key")
 
-    if args.raw:
-        return user_blob
-    else:
-        display_table([user_blob], user_fields)
+    sdate,edate = convert_dates_to_timestamps(args)
+    req_url = apiurl(args, "/users/me/invoices", {"owner": "me", "sdate":sdate, "edate":edate, "inc_charges" : not args.only_credits});
 
-@parser.command(
-    argument("-t", "--type", help="volume type to display. Default to all. Possible values are \"local\", \"all\", \"network\"", type=str, default="all"),
-    usage="vastai show volumes [OPTIONS]",
-    help="Show stats on owned volumes.",
-    epilog=deindent("""
-        Show stats on owned volumes
-    """)
-)
-def show__volumes(args: argparse.Namespace):
-    types = {
-        "local": "local_volume",
-        "network": "network_volume",
-        "all": "all_volume"
-    }
-    type = types.get(args.type, "all")
-    req_url = apiurl(args, "/volumes", {"owner": "me", "type" : type});
     r = http_get(args, req_url)
     r.raise_for_status()
-    rows = r.json()["volumes"]
-    processed = []
-    for row in rows:
-        row = {k: strip_strings(v) for k, v in row.items()} 
-        row['duration'] = time.time() - row['start_date']
-        processed.append(row)
-    if args.raw:
-        return processed
-    else:
-        display_table(processed, volume_fields, replace_spaces=False)
+    try:
+        rj = r.json()
+    except JSONDecodeError:
+        print("Error: API returned invalid JSON response", file=sys.stderr)
+        return
+    rows = rj.get("invoices", [])
+    # print("Timestamp for first row: ", rows[0]["timestamp"])
+    invoice_filter_data = filter_invoice_items(args, rows)
+    rows = invoice_filter_data["rows"]
+    filter_header = invoice_filter_data["header_text"]
 
+    contract_ids = None
 
-@parser.command(
-    argument("cluster_id", help="ID of cluster you want to remove machine from.", type=int),
-    argument("machine_id", help="ID of machine to remove from cluster.", type=int),
-    argument("new_manager_id", help="ID of machine to promote to manager. Must already be in cluster", type=int, nargs="?"),
-    usage="vastai remove-machine-from-cluster CLUSTER_ID MACHINE_ID NEW_MANAGER_ID",
-    help="Removes machine from cluster",
-    epilog=deindent("""Removes machine from cluster and also reassigns manager ID, 
-    if we're removing the manager node""")
-)
-def remove_machine_from_cluster(args: argparse.Namespace):
-    json_blob = {
-        "cluster_id": args.cluster_id,
-        "machine_id": args.machine_id,
-    }
+    if (args.instance_label):
+        #print(rows)
+        contract_ids = select(rows, 'instance_id')
+        #print(contract_ids)
 
-    if args.new_manager_id:
-        json_blob["new_manager_id"] = args.new_manager_id
-    if args.explain:
-        print("request json:", json_blob)
+        url = apiurl(args, f"/contracts/fetch/")
 
-    req_url = apiurl(args, "/cluster/remove_machine/")
-    r = http_del(args, req_url, json=json_blob)
-    r.raise_for_status()
+        req_json = {
+            "label": args.instance_label,
+            "contract_ids": list(contract_ids)
+        }
 
-    if args.raw:
-        return r
+        if (args.explain):
+            print("request json: ")
+            print(req_json)
+        
+        result = http_post(args, url, headers=headers,json=req_json)
+        result.raise_for_status()
+        filtered_rows = result.json().get("contracts", [])
+        #print(rows)
+
+        contract_ids = select(filtered_rows, 'id')
+        #print(contract_ids)
 
-    print(r.json()["msg"])
+        rows2 = []
+        for row in rows:
+            instance_id = row.get("instance_id", None)
+            if instance_id in contract_ids:
+                rows2.append(row)
+        rows = rows2
 
+    current_charges = rj.get("current")
+    if args.quiet:
+        for row in rows:
+            row_id = row.get("id", None)
+            if row_id is not None:
+                print(row_id)
+    elif args.raw:
+        # sort keys
+        return rows
+        # print("Current: ", current_charges)
+    else:
+        print(filter_header)
+        display_table(rows, invoice_fields)
+        print(f"Total: ${sum_field(rows, 'amount')}")
+        print("Current: ", current_charges)
 
+# Helper to convert date string or int to timestamp
+def to_timestamp_(val):
+    if isinstance(val, int):
+        return val
+    if isinstance(val, str):
+        if val.isdigit():
+            return int(val)
+        return int(datetime.strptime(val, '%Y-%m-%d').timestamp())
+    raise ValueError("Invalid date format")
 
-def handle_failed_tfa_verification(args, e):
-    error_data = e.response.json()
-    error_msg = error_data.get("msg", str(e))
-    error_code = error_data.get("error", "")
+charge_types = ['instance','volume','serverless', 'i', 'v', 's']
+invoice_types = {
+    "transfers": "stripe_payments",
+    "stripe": "transfer",
+    "bitpay": "bitpay",
+    "coinbase": "coinbase",
+    "crypto.com": "crypto.com",
+    "reserved": "instance_prepay",
+    "payout_paypal": "paypal_manual",
+    "payout_wise": "wise_manual"
+}
 
-    if args.raw:
-        print(json.dumps(error_data, indent=2))
-    
-    print(f"\n{FAIL} Error: {error_msg}")
+@parser.command(
+    argument('-i', '--invoices', mutex_group='grp', action='store_true', required=True, help='Show invoices instead of charges'),
+    argument('-it', '--invoice-type', choices=invoice_types.keys(), nargs='+', metavar='type', help=f'Filter which types of invoices to show: {{{", ".join(invoice_types.keys())}}}'),
+    argument('-c', '--charges', mutex_group='grp', action='store_true', required=True, help='Show charges instead of invoices'),
+    argument('-ct', '--charge-type', choices=charge_types, nargs='+', metavar='type', help='Filter which types of charges to show: {i|instance, v|volume, s|serverless}'),
+    argument('-s', '--start-date', help='Start date (YYYY-MM-DD or timestamp)'),
+    argument('-e', '--end-date', help='End date (YYYY-MM-DD or timestamp)'),
+    argument('-l', '--limit', type=int, default=20, help='Number of results per page (default: 20, max: 100)'),
+    argument('-t', '--next-token', help='Pagination token for next page'),
+    argument('-f', '--format', choices=['table', 'tree'], default='table', help='Output format for charges (default: table)'),
+    argument('-v', '--verbose', action='store_true', help='Include full Instance Charge details and Invoice Metadata (tree view only)'),
+    argument('--latest-first', action='store_true', help='Sort by latest first'),
+    description="Get billing history with invoices and charges",
+    usage="vastai show invoices-v1 [OPTIONS]",
+    help="Get billing history with invoices and charges",
+    epilog=deindent("""
+        This command supports colored output and rich formatting if the 'rich' python module is installed!
+
+        Examples:
+            # Show the first 20 invoices in the last week  (note: default window is a 7 day period ending today)
+            vastai show invoices-v1 --invoices
     
-    # Provide helpful context for common errors
-    if error_code in {"tfa_locked", "2fa_verification_failed"}:
-        fail_count = error_data.get("fail_count", 0)
-        locked_until = error_data.get("locked_until")
-        
-        if fail_count > 0:
-            print(f"   Failed attempts: {fail_count}")
-        if locked_until:
-            lock_time_sec = (datetime.fromtimestamp(locked_until) - datetime.now()).seconds
-            minutes, seconds = divmod(lock_time_sec, 60)
-            print(f"   Time Remaining for 2FA Lock: {minutes} minutes and {seconds} seconds...")
+            # Show the first 50 charges over a 7 day period starting from 2025-11-30 in tree format
+            vastai show invoices-v1 --charges -s 2025-11-30 -f tree -l 50
 
-    elif error_code == "2fa_expired":
-        # Note: Only SMS uses tfa challenges that expire when verifying
-        print("\n   The SMS code and secret have expired. Please start over:")
-        print("     vastai tfa send-sms")
+            # Show the first 20 invoices of specific types for the month of November 2025
+            vastai show invoices-v1 -i -it stripe bitpay transfers --start-date 2025-11-01 --end-date 2025-11-30
+
+            # Show the first 20 charges for only volumes and serverless instances between two dates, including all details and metadata
+            vastai show invoices-v1 -c --charge-type v s -s 2025-11-01 -e 2025-11-05 --format tree --verbose
+
+            # Get the next page of paginated invoices, limit to 50 per page  (note: type/date filters MUST match previous request for pagination to work)
+            vastai show invoices-v1 --invoices --limit 50 --next-token eyJ2YWx1ZXMiOiB7ImlkIjogMjUwNzgyMzR9LCAib3NfcGFnZSI6IDB9
+
+            # Show the last 10 instance (only) charges over a 7 day period ending in 2025-12-25, sorted by latest charges first
+            vastai show invoices-v1 --charges -ct instance --end-date 2025-12-25 -l 10 --latest-first
+    """)
+)
+def show__invoices_v1(args):
+    output_lines = []
+    try:
+        from rich.prompt import Confirm
+        has_rich = True
+    except ImportError:
+        output_lines.append("NOTE: To view results in color and table/tree format please install the 'rich' python module with 'pip install rich'\n")
+        has_rich = False
+
+    # Handle default start and end date values
+    if not args.start_date and not args.end_date:
+        args.end_date = int(time.time())  # Set end date to current time if both are missing
+    if not args.start_date:
+        args.start_date = args.end_date - 7 * 24*60*60  # Default to 7 days before given end date
+    elif not args.end_date:
+        args.end_date = args.start_date + 7 * 24*60*60  # Default to 7 days after given start date
+    
+    try:
+        # Parse dates - handle both YYYY-MM-DD format and timestamps
+        start_timestamp = to_timestamp_(args.start_date)
+        end_timestamp = to_timestamp_(args.end_date)
+    except Exception as e:
+        print(f"Error parsing dates: {e}")
+        print("Use format YYYY-MM-DD or UNIX timestamp")
+        return
 
+    if has_rich and not args.no_color:
+        print("(use --no-color to disable colored output)\n")
+    
+    start_date = convert_timestamp_to_date(start_timestamp)
+    end_date = convert_timestamp_to_date(end_timestamp)
+    data_type = "Instance Charges" if args.charges else "Invoices"
+    output_lines.append(f"Fetching {data_type} from {start_date} to {end_date}...")
 
-def format_backup_codes(backup_codes):
-    """Format backup codes for display or file output."""
-    output_lines = [
-        "=" * 60, "  VAST.AI 2FA BACKUP CODES", "=" * 60,
-        f"\nGenerated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
-        f"\n{WARN}  WARNING: All previous backup codes are now invalid!",
-        "\nYour New Backup Codes (one-time use only):",
-        "-" * 40,
-    ]
+    # Build request parameters
+    date_col = 'day' if args.charges else 'when'
+    params = {
+        'select_filters': {date_col: {'gte': start_timestamp, 'lte': end_timestamp}},
+        'latest_first': args.latest_first,
+        'limit': min(args.limit, 100) if args.limit > 0 else 20,  # Enforce max limit of 100
+    }
+    if args.charges:
+        params['format'] = args.format
+        for ct in args.charge_type or []:
+            filters = params['select_filters'].setdefault('type', {}).setdefault('in', [])
+            if   ct in {'i','instance'}:   filters.append('instance')
+            elif ct in {'v','volume'}:     filters.append('volume')
+            elif ct in {'s','serverless'}: filters.append('serverless')
     
-    for i, code in enumerate(backup_codes, 1):
-        output_lines.append(f"  {i:2d}. {code}")
+    if args.invoices:
+        for it in args.invoice_type or []:
+            filters = params['select_filters'].setdefault('service', {}).setdefault('in', [])
+            filters.append(invoice_types[it])
     
-    output_lines.extend([
-        "-" * 40,
-        "\nIMPORTANT:",
-        " • Each code can only be used once",
-        " • Store them in a secure location",
-        " • Use these codes to log in if you lose access to your 2FA device",
-        "\n" + "=" * 60,
-    ])
-    return "\n".join(output_lines)
+    if args.next_token:
+        params['after_token'] = args.next_token
 
+    endpoint = '/api/v0/charges/' if args.charges else '/api/v1/invoices/'
+    url = apiurl(args, endpoint, query_args=params)
 
-def confirm_destructive_action(prompt="Are you sure? (y/n): "):
-    """Prompt user for confirmation of destructive actions"""
-    try:
-        response = input(f" {prompt}").strip().lower()
-        return 'y' in response
-    except (EOFError, KeyboardInterrupt):
-        print("\nOperation cancelled.")
-        raise
+    found_results, found_count = [], 0
+    looping = True
+    while looping:
+        response = http_get(args, url)
+        response.raise_for_status()
+        try:
+            response = response.json()
+        except JSONDecodeError:
+            print("Error: API returned invalid JSON response", file=sys.stderr)
+            return
 
-def save_to_file(content, filepath):
-    """Save content to file, creating parent directories if needed."""
-    try:
-        filepath = os.path.abspath(os.path.expanduser(filepath))
+        found_results += response.get('results', [])
+        found_count += response.get('count', 0)
+        total = response.get('total', 0)
+        next_token = response.get('next_token')
         
-        # If directory provided, this should be handled by caller
-        parent_dir = os.path.dirname(filepath)
-        if parent_dir:
-            os.makedirs(parent_dir, exist_ok=True)
+        if args.raw or has_rich is False:
+            output_lines.append("Raw response:\n" + json.dumps(response, indent=2))
+            if next_token:
+                print(f"Next page token: {next_token}\n")
+        elif not found_results:
+            output_lines.append("No results found")
+        else:  # Display results
+            formatted_results = format_invoices_charges_results(args, deepcopy(found_results))
+            if args.invoices:
+                rich_obj = create_rich_table_for_invoices(formatted_results)
+            elif args.format == 'tree':
+                rich_obj = create_charges_tree(formatted_results)
+            else:
+                rich_obj = create_rich_table_for_charges(args, formatted_results)
+
+            output_lines.append(rich_object_to_string(rich_obj, no_color=args.no_color))
+            output_lines.append(f"Showing {found_count} of {total} results")
+            if next_token:
+                output_lines.append(f"Next page token: {next_token}\n")
         
-        with open(filepath, "w") as f:
-            f.write(content)
-        return True
-    except (IOError, OSError) as e:
-        print(f"\n{FAIL} Error saving file: {e}")
-        return False
+        paging = print_or_page(args, '\n'.join(output_lines))
 
+        if next_token and not paging:
+            if has_rich:
+                ans = Confirm.ask("Fetch next page?", show_default=False, default=False)
+            else:
+                ans = input("Fetch next page? (y/N): ").strip().lower() == 'y'
+            if ans:
+                params['after_token'] = next_token
+                url = apiurl(args, endpoint, query_args=params)
+                output_lines.clear()
+                args.full = True
+            else:
+                looping = False
+        else:
+            looping = False
 
-def get_backup_codes_filename():
-    """Generate a timestamped filename for backup codes."""
-    timestamp = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
-    return f"vastai_backup_codes_{timestamp}.txt"
+def format_invoices_charges_results(args, results):
+    indices_to_remove = []
+    for i,item in enumerate(results):
+        item['start'] = convert_timestamp_to_date(item['start']) if item['start'] else None
+        item['end'] = convert_timestamp_to_date(item['end']) if item['end'] else None
+        if item['amount'] == 0:
+            indices_to_remove.append(i)  # Removing items that don't contribute to the total
+        elif args.invoices:
+            if item['type'] not in {'transfer', 'payout'}:
+                item['amount'] *= -1  # present amounts intuitively as related to balance
+            item['amount_str'] = f"${item['amount']:.2f}" if item['amount'] > 0 else f"-${abs(item['amount']):.2f}"
+        else:
+            item['amount'] = f"${item['amount']:.3f}"
 
-def save_backup_codes(backup_codes):
-    """Save or display 2FA backup codes based on user choice."""
-    print(f"\nBackup codes regenerated successfully! {SUCCESS}")
-    print(f"\n{WARN}  WARNING: All previous backup codes are now invalid!")
+        if args.charges:
+            if item['type'] in {'instance','volume'} and not args.verbose:
+                item['items'] = []  # Remove instance charge details if verbose is not set
+            if item['source'] and '-' in item['source']:
+                item['type'], item['source'] = item['source'].capitalize().split('-')
+        
+        item['items'] = format_invoices_charges_results(args, item['items'])
     
-    formatted_content = format_backup_codes(backup_codes)
-    filename = get_backup_codes_filename()
+    for i in reversed(indices_to_remove):  # Remove in reverse order to avoid index shifting
+        del results[i]
     
-    while True:
-        print("\nHow would you like to save your new backup codes?")
-        print(f"  1. Save to default location (~/Downloads/{filename})")
-        print(f"  2. Save to a custom path")
-        print(f"  3. Print to screen ({WARN}  potentially unsafe - visible to onlookers)")
-        
-        try:
-            choice = input("\nEnter choice (1-3): ").strip()
-            
-            if choice in {'1', '2'}:
-                # Determine filepath
-                if choice == '1':
-                    downloads_dir = os.path.expanduser("~/Downloads")
-                    filepath = os.path.join(downloads_dir, filename)
-                else:  # choice == '2'
-                    custom_path = input("\nEnter full path for backup codes file: ").strip()
-                    if not custom_path:
-                        print("Error: Path cannot be empty")
-                        continue
-                    
-                    filepath = os.path.abspath(os.path.expanduser(custom_path))
-                    
-                    # If directory provided, add filename
-                    if os.path.isdir(filepath):
-                        filepath = os.path.join(filepath, filename)
-                
-                # Try to save
-                if save_to_file(formatted_content, filepath):
-                    print(f"\n{SUCCESS} Backup codes saved to: {filepath}")
-                    print(f"\nIMPORTANT:")
-                    print(f" • The file contains {len(backup_codes)} one-time use backup codes")
-                    if choice == '1':
-                        print(f" • Move this file to a secure location")
-                    return
-                else:
-                    print("Please try again with a different path.")
-                    continue
-            
-            elif choice == '3':
-                print(f"\n{WARN}  WARNING: Printing sensitive codes to screen!")
-                confirm = input("\nAre you sure? Anyone nearby can see these codes. (yes/no): ").strip().lower()
-                
-                if confirm in {'yes', 'y'}:
-                    print("\n" + formatted_content + "\n")
-                    return
-                else:
-                    print("Cancelled. Please choose another option.")
-                    continue
-            
-            else:
-                print("Invalid choice. Please enter 1, 2, or 3.")
-        
-        except (EOFError, KeyboardInterrupt):
-            print("\n\nOperation cancelled. Your backup codes were generated but not saved.")
-            print("You will need to regenerate them to get new codes.")
-            raise
+    return results
+
+
+def rich_object_to_string(rich_obj, no_color=True):
+    """ Render a Rich object (Table or Tree) to a string. """
+    from rich.console import Console
+    buffer = StringIO()  # Use an in-memory stream to suppress visible output
+    console = Console(record=True, file=buffer)
+    console.print(rich_obj)
+    return console.export_text(clear=True, styles=not no_color)
+
+def create_charges_tree(results, parent=None, title="Charges Breakdown"):
+    """ Build and return a Rich Tree from nested charge results. """
+    from rich.text import Text
+    from rich.tree import Tree
+    from rich.panel import Panel
+    if parent is None:  # Create root node if this is the first call
+        root = Tree(Text(title, style="bold red"))
+        create_charges_tree(results, root)
+        return Panel(root, style="white on #000000", expand=False)
+    
+    top_level = (parent.label.plain == title)
+    for item in results:
+        end_date = f" → {item['end']}" if item['start'] != item['end'] else ""
+        label = Text.assemble(
+            (item["type"], "bold cyan"),
+            (f" {item['source']}" if item.get('source') else "", "gold1"), " → ",
+            (f"{item['amount']}", 'bold green1' if top_level else 'green1'),
+            (f" — {item['description']}", "bright_white" if top_level else "dim white"),
+            (f"  ({item['start']}{end_date})", "bold bright_white" if top_level else "white")
+        )
+        node = parent.add(label, guide_style="blue3")
+        if item.get("items"):
+            create_charges_tree(item["items"], node)
+    return parent
 
+def create_rich_table_for_charges(args, results):
+    """ Build and return a Rich Table from charge results. """
+    from rich.table import Table
+    from rich.text import Text
+    from rich import box
+    from rich.padding import Padding
+    table = Table(style="white", header_style="bold bright_yellow", box=box.DOUBLE_EDGE, row_styles=["on grey11", "none"])
+    table.add_column(Text("Type", justify="center"), style="bold steel_blue1", justify="center")
+    table.add_column(Text("ID", justify="center"), style="gold1", justify="center")
+    table.add_column(Text("Amount", justify="center"), style="sea_green2", justify="right")
+    table.add_column(Text("Start", justify="center"), style="bright_white", justify="center")
+    table.add_column(Text("End", justify="center"), style="bright_white", justify="center")
+    if not args.charge_type or 'serverless' in args.charge_type:
+        table.add_column(Text("Endpoint", justify="center"), style="bright_red", justify="center")
+        table.add_column(Text("Workergroup", justify="center"), style="orchid", justify="center")
+    for item in results:
+        row = [item['type'].capitalize(), item['source'], item['amount'], item['start'], item['end']]
+        if not args.charge_type or 'serverless' in args.charge_type:
+            row.append(str(item['metadata'].get('endpoint_id', '')))
+            row.append(str(item['metadata'].get('workergroup_id', '')))
+        table.add_row(*row)
+    return Padding(table, (1, 2), style="on #000000", expand=False)  # Print with a black background
 
-def build_tfa_verification_payload(args, **kwargs):
-    """Build common payload for TFA verification requests."""
-    payload = {
-        "tfa_method_id": getattr(args, 'method_id', None),
-        "tfa_method": "sms" if getattr(args, 'sms', False) else "totp",
-        "code": getattr(args, 'code', None),
-        "backup_code": getattr(args, 'backup_code', None),
-        "secret": getattr(args, 'secret', None),
+def create_rich_table_for_invoices(results):
+    """ Build and return a Rich Table from invoice results. """
+    from rich.table import Table
+    from rich.text import Text
+    from rich import box
+    from rich.padding import Padding
+    invoice_type_to_color = {
+        "credit": "green1",
+        "transfer": "gold1",
+        "payout": "orchid",
+        "reserved": "sky_blue1",
+        "refund": "bright_red",
     }
-    for key, value in kwargs.items():
-        payload[key] = value
+    table = Table(style="white", header_style="bold bright_yellow", box=box.DOUBLE_EDGE, row_styles=["on grey11", "none"])
+    table.add_column(Text("ID", justify="center"), style="bright_white", justify="center")
+    table.add_column(Text("Created", justify="center"), style="yellow3", justify="center")
+    table.add_column(Text("Paid", justify="center"), style="yellow3", justify="center")
+    table.add_column(Text("Type", justify="center"), justify="center")
+    table.add_column(Text("Result", justify="center"), justify="right")
+    table.add_column(Text("Source", justify="center"), style="bright_cyan", justify="center")
+    table.add_column(Text("Description", justify="center"), style="bright_white", justify="left")
+    for item in results:
+        table.add_row(
+            str(item['metadata']['invoice_id']),
+            item['start'],
+            item['end'] if item['end'] else 'N/A',
+            Text(item['type'].capitalize(), style=invoice_type_to_color.get(item['type'], "white")),
+            Text(item['amount_str'], style="sea_green2" if item['amount'] > 0 else "bright_red"),
+            item['source'].capitalize() if item['type'] != 'transfer' else item['source'],
+            item['description'],
+        )
+    return Padding(table, (1, 2), style="on #000000", expand=False)  # Print with a black background
+
+def create_rich_table_from_rows(rows, headers=None, title='', sort_key=None):
+    """ (Generic) Creates a Rich table from a list of dict rows. """
+    from rich import box
+    from rich.table import Table
+    if not isinstance(rows, list):
+        raise ValueError("Invalid Data Type: rows must be a list")
+    # Handle list of dictionaries
+    if isinstance(rows[0], dict):
+        headers = headers or list(rows[0].keys())
+        rows = [[row_dict.get(h, "") for h in headers] for row_dict in rows]
+    elif headers is None:
+        raise ValueError("Headers must be provided if rows are not dictionaries")
+    # Sort rows if requested
+    if sort_key:
+        rows = sorted(rows, key=sort_key)
+    # Create the Rich table
+    table = Table(title=title, style="white", header_style="bold bright_yellow", box=box.DOUBLE_EDGE)
+    # Add columns
+    for header in headers:
+        # You can customize alignment and style here per column
+        table.add_column(header, justify="left", style="bright_white", no_wrap=True)
+    # Add rows
+    for row in rows:
+        # Convert everything to string to avoid type issues
+        table.add_row(*[str(cell) for cell in row])
+    return table
 
-    return {k:v for k,v in payload.items() if v}
 
 @parser.command(
-    argument("code", help="6-digit verification code from SMS or Authenticator app", type=str),
-    argument("--sms", help="Use SMS 2FA method instead of TOTP", action="store_true"),
-    argument("--secret", help="Secret token from setup process (required)", type=str, required=True),
-    argument("--phone-number", help="Phone number for SMS method (E.164 format)", type=str, default=None),
-    argument("-l", "--label", help="Label for the new 2FA method", type=str, default=None),
-    usage="vastai tfa activate CODE --secret SECRET [--sms] [--phone-number PHONE_NUMBER] [--label LABEL]",
-    help="Activate a new 2FA method by verifying the code",
-    epilog=deindent("""
-        Complete the 2FA setup process by verifying your code.
-        
-        For TOTP (Authenticator app):
-         1. Run 'vastai tfa totp-setup' to get the manual key/QR code and secret
-         2. Enter the manual key or scan the QR code with your Authenticator app
-         3. Run this command with the 6-digit code from your app and the secret token from step 1
-        
-        For SMS:
-         1. Run 'vastai tfa send-sms --phone-number <PHONE_NUMBER>' to receive SMS and get secret token
-         2. Run this command with the code you received via SMS and the phone number it was sent to
-        
-        If this is your first 2FA method, backup codes will be generated and displayed.
-        Save these backup codes in a secure location!
-        
-        Examples:
-         vastai tfa activate --secret abc123def456 123456
-         vastai tfa activate --secret abc123def456 --phone-number +12345678901 123456
-         vastai tfa activate --secret abc123def456 --phone-number +12345678901 --label "Work Phone" 123456
-    """),
+    argument("id", help="id of instance to show", type=int),
+    description="Show details for a specific instance",
+    usage="vastai show instance ID [OPTIONS]",
+    help="Show details for a specific instance"
 )
-def tfa__activate(args):
-    """Activate a new 2FA method by confirming the verification code."""
-    url = apiurl(args, "/api/v0/tfa/test-submit/")
-    
-    # Build the request payload
-    payload = build_tfa_verification_payload(args, phone_number=args.phone_number, label=args.label)
-    
-    r = http_post(args, url, headers=apiheaders(args), json=payload)
-    r.raise_for_status()
-    
-    response_data = r.json()
-    
-    # Display success message
-    method_name = "SMS" if args.phone_number or args.sms else "TOTP (Authenticator App)"
-    print(f"\n{SUCCESS} {method_name} 2FA method activated successfully!")
-    
-    # Display backup codes if this is the first 2FA method
-    if "backup_codes" in response_data:
-        save_backup_codes(response_data["backup_codes"])
+def show__instance(args):
+    """
+    Shows the stats on the machine the user is renting.
 
+    :param argparse.Namespace args: should supply all the command-line options
+    :rtype:
+    """
+    result = api_call(args, "GET", f"/instances/{args.id}/", query_args={"owner": "me"})
+    row = result.get("instances")
+    if not row:
+        print("Error: API response missing required 'instances' field", file=sys.stderr)
+        return
+    row['duration'] = time.time() - row['start_date']
+    row['extra_env'] = {env_var[0]: env_var[1] for env_var in row['extra_env']}
+    return output_result(args, row, instance_fields)
 
 @parser.command(
-    argument("-id", "--id-to-delete", help="ID of the 2FA method to delete (see `vastai tfa status`)", type=int, default=None),
-    argument("-c", "--code", mutex_group='code_grp', required=True, help="2FA code from your Authenticator app or SMS to authorize deletion", type=str),
-    argument("--sms", mutex_group="type_grp", help="Use SMS 2FA method instead of TOTP", action="store_true"),
-    argument("-s", "--secret", help="Secret token (required for SMS authorization)", type=str, default=None),
-    argument("-bc", "--backup-code", mutex_group='code_grp', required=True, help="One-time backup code (alternative to regular 2FA code)", type=str, default=None),
-    argument("--method-id", help="2FA Method ID if you have more than one of the same type ('id' from `tfa status`)", type=str, default=None),
-    usage="vastai tfa delete [--id-to-delete ID] [--code CODE] [--sms] [--secret SECRET] [--backup-code BACKUP_CODE] [--method-id ID]",
-    help="Remove a 2FA method from your account",
-    epilog=deindent(f"""
-        Remove a 2FA method from your account.
-        
-        This action requires 2FA verification to prevent unauthorized removals.
-        
-        {'*'*120}
-        NOTE: If you do not specify --id-to-delete, the system will attempt to delete the method you are using to authenticate.
-              However please be advised, it is much safer to specify the ID to avoid confusion if you have multiple methods.
-        {'*'*120}
+    argument("-q", "--quiet", action="store_true", help="only display numeric ids"),
+    description="List all your running and stopped instances",
+    usage="vastai show instances [OPTIONS] [--api-key API_KEY] [--raw]",
+    help="List all your running and stopped instances",
+    epilog=deindent("""
+        Lists all instances owned by the authenticated user, including running, pending, and stopped instances.
 
-           Use `vastai tfa status` to see your active methods and their IDs.
-        
         Examples:
-         # Delete method #123, authorize with TOTP/Authenticator code
-         vastai tfa delete --id-to-delete 123 --code 456789
-         
-         # Delete method #123, authorize with SMS and secret from `tfa send-sms`
-         vastai tfa delete -id 123 --sms --secret abc123def456 -c 456789
-         
-         # Delete method #123, authorize with backup code
-         vastai tfa delete --id-to-delete 123 --backup-code ABCD-EFGH-IJKL
-         
-         # Delete method #123, specify which TOTP method to use if you have multiple
-         vastai tfa delete -id 123 --method-id 456 -c 456789
+            vastai show instances                      # List all instances in table format
+            vastai show instances --raw                # Output as JSON for scripting
+            vastai show instances --raw | jq '.[0]'   # Get first instance details
+            vastai show instances -q                   # List only instance IDs
 
-         # Delete the TOTP method you are using to authenticate (use with caution)
-         vastai tfa delete -c 456789
+        Output includes: instance ID, machine ID, status, GPU info, rental cost, duration, and connection details.
     """),
 )
-def tfa__delete(args):
-    """Remove a 2FA method from the user's account after verifying authorization."""
-    url = apiurl(args, "/api/v0/tfa/")
+def show__instances(args = {}, extra = {}):
+    """
+    Shows the stats on the machine the user is renting.
 
-    if args.sms and not args.secret:
-        print(f"\n{FAIL} Error: --secret is required for deletion authorization when using --sms.")
-        print("\nPlease use:  `vastai tfa send-sms` to get the missing secret and try again.")
-        return 1
-    
-    # Confirm action since this invalidates existing codes
-    prompt = "\nAre you sure you want to delete this 2FA method? (y|n): "
-    if confirm_destructive_action(prompt) == False:
-        print("Operation cancelled.")
-        return
-    
-    # Build the request payload
-    payload = build_tfa_verification_payload(args, target_id=args.id_to_delete)
+    :param argparse.Namespace args: should supply all the command-line options
+    :rtype:
+    """
+    req_url = apiurl(args, "/instances", {"owner": "me"});
+    #r = http_get(req_url)
+    r = http_get(args, req_url)
+    r.raise_for_status()
     try:
-        r = http_del(args, url, headers=apiheaders(args), json=payload)
-        r.raise_for_status()
-        
-        response_data = r.json()
-        
-        print(f"\n{SUCCESS} 2FA method deleted successfully.")
-        
-        if "remaining_methods" in response_data:
-            remaining = response_data["remaining_methods"]
-            print(f"\nYou have {remaining} 2FA method{'s' if remaining != 1 else ''} remaining.")
-        else:
-            print(f"\n{WARN}  WARNING: You have removed all 2FA methods from your account.")
-            print("Your backup codes have been invalidated and 2FA is now fully disabled.")
-    
-    except requests.exceptions.HTTPError as e:
-        handle_failed_tfa_verification(args, e)
-        return 1
+        rj = r.json()
+    except JSONDecodeError:
+        print("Error: API returned invalid JSON response", file=sys.stderr)
+        return
+    rows = rj.get("instances", [])
+    new_rows = []
+    for row in rows:
+        row = {k: strip_strings(v) for k, v in row.items()}
+        row['duration'] = time.time() - row['start_date']
+        row['extra_env'] = {env_var[0]: env_var[1] for env_var in row['extra_env']}
+        new_rows.append(row)
+    rows = new_rows
+    if 'internal' in extra:
+        return [str(row[extra['field']]) for row in rows]
+    elif args.quiet:
+        for row in rows:
+            row_id = row.get("id", None)
+            if row_id is not None:
+                print(row_id)
+    elif args.raw:
+        return rows
+    else:
+        display_table(rows, instance_fields)
+
+
 
 
 @parser.command(
-    argument("-c", "--code", mutex_group='code_grp', required=True, help="2FA code from Authenticator app (default) or SMS", type=str),
-    argument("--sms", mutex_group="type_grp", help="Use SMS 2FA method instead of TOTP", action="store_true"),
-    argument("-s", "--secret", help="Secret token from previous login step (required for SMS)", type=str, default=None),
-    argument("-bc", "--backup-code", mutex_group='code_grp', required=True, help="One-time backup code (alternative to regular 2FA code)", type=str, default=None),
-    argument("-id", "--method-id", mutex_group="type_grp", help="2FA Method ID if you have more than one of the same type ('id' from `tfa status`)", type=str, default=None),
-    
-    usage="vastai tfa login [--code CODE] [--sms] [--secret SECRET] [--backup-code BACKUP_CODE]",
-    help="Complete 2FA login by verifying code",
+    description="Show history of IP addresses used by your instances",
+    usage="vastai show ipaddrs [--api-key API_KEY] [--raw]",
+    help="Show history of IP addresses used by your instances"
+)
+def show__ipaddrs(args):
+    """
+    Shows the history of ip address accesses to console.vast.ai endpoints
+
+    :param argparse.Namespace args: should supply all the command-line options
+    :rtype:
+    """
+    data = api_call(args, "GET", "/users/me/ipaddrs", query_args={"owner": "me"})
+    rows = data["results"]
+    return output_result(args, rows, ipaddr_fields)
+
+
+@parser.command(
+    description="[Beta] List all your machine clusters",
+    usage="vastai show clusters",
+    help="[Beta] List all your machine clusters",
+    epilog=deindent("""
+        Show clusters associated with your account.
+    """)
+)
+def show__clusters(args: argparse.Namespace):
+    response_data = api_call(args, "GET", "/clusters/")
+
+    if args.raw:
+        return response_data
+
+    rows = []
+    for cluster_id, cluster_data in response_data['clusters'].items():
+        machine_ids = [ node["machine_id"] for node in cluster_data["nodes"]]
+
+        manager_node = next(
+            (node for node in cluster_data['nodes'] if node['is_cluster_manager']),
+            None
+        )
+        if manager_node is None:
+            # Cluster has no manager node, skip displaying this cluster
+            continue
+
+        row_data = {
+            'id': cluster_id,
+            'subnet': cluster_data['subnet'],
+            'node_count': len(cluster_data['nodes']),
+            'machine_ids': str(machine_ids),
+            'manager_id': str(manager_node['machine_id']),
+            'manager_ip': manager_node['local_ip'],
+        }
+
+        rows.append(row_data)
+
+    display_table(rows, cluster_fields, replace_spaces=False)
+
+
+@parser.command(
+    description="[Beta] List all your overlay networks",
+    usage="vastai show overlays",
+    help="[Beta] List all your overlay networks",
     epilog=deindent("""
-        Complete Two-Factor Authentication login by providing the 2FA code.
-        
-        For TOTP (default): Provide the 6-digit code from your Authenticator app
-        For SMS: Include the --sms flag and provide -s/--secret from the `tfa send-sms` command response
-        For backup code: Use --backup-code instead of code (codes may only be used once)
-        
-        Examples:
-         vastai tfa login -c 123456
-         vastai tfa login --code 123456 --sms --secret abc123def456
-         vastai tfa login --backup-code ABCD-EFGH-IJKL
-                    
-    """),
+        Show overlays associated with your account.
+    """)
 )
-def tfa__login(args):
-    """Complete 2FA login and store the session key."""
-    url = apiurl(args, "/api/v0/tfa/")
-    
-    # Build the request payload
-    payload = build_tfa_verification_payload(args)
+def show__overlays(args: argparse.Namespace):
+    response_data = api_call(args, "GET", "/overlay/")
+    if args.raw:
+        return response_data
+    rows = []
+    for overlay in response_data:
+        row_data = {
+            'overlay_id': overlay['overlay_id'],
+            'name': overlay['name'],
+            'subnet': overlay['internal_subnet'] if overlay['internal_subnet'] else 'N/A',
+            'cluster_id': overlay['cluster_id'],
+            'instance_count': len(overlay['instances']),
+            'instances': str(overlay['instances']),
+        }
+        rows.append(row_data)
+    display_table(rows, overlay_fields, replace_spaces=False)
+
 
-    try:
-        r = http_post(args, url, headers=apiheaders(args), json=payload)
-        r.raise_for_status()
-        
-        response_data = r.json()
-        
-        # Check for session_key in response and save it
-        if "session_key" in response_data:
-            session_key = response_data["session_key"]
-            if session_key != args.api_key:
-                # Write the session key to the TFA key file
-                with open(TFAKEY_FILE, "w") as f:
-                    f.write(session_key)
-                print(f"{SUCCESS} 2FA login successful! Session key saved to {TFAKEY_FILE}")
-            else:
-                print(f"{SUCCESS} 2FA login successful! Your session key has been refreshed.")
-            
-            # Display remaining backup codes if present
-            if "backup_codes_remaining" in response_data:
-                remaining = response_data["backup_codes_remaining"]
-                if remaining == 0:
-                    print(f"{WARN}  Warning: You have no backup codes remaining! Please generate new backup codes immediately to avoid being locked out of your account if you lose access to your 2FA device.")
-                elif remaining <= 3:
-                    print(f"{WARN}  Warning: You only have {remaining} backup codes remaining. Consider regenerating them.")
-                else:
-                    print(f"Backup codes remaining: {remaining}")
-        else:
-            print("2FA login successful but a session key was not returned. Please check that you have an API Key that's properly set up")
-    
-    except requests.exceptions.HTTPError as e:
-        handle_failed_tfa_verification(args, e)
-        return 1
 
 
 @parser.command(
-    argument("-p", "--phone-number", help="Phone number to receive SMS code (E.164 format, e.g., +1234567890)", type=str, default=None),
-    argument("-s", "--secret", help="Secret token from the original 2FA login attempt", type=str, required=True),
-    usage="vastai tfa resend-sms --secret SECRET [--phone-number PHONE_NUMBER]",
-    help="Resend SMS 2FA code",
-    epilog=deindent("""
-        Resend the SMS verification code to your phone.
-        
-        This is useful if:
-        • You didn't receive the original SMS
-        • The code expired before you could use it
-        • You accidentally deleted the message
-        
-        You must provide the same secret token from the original request.
-        
-        Example:
-         vastai tfa resend-sms --secret abc123def456
-    """),
+    argument("-q", "--quiet", action="store_true", help="display subaccounts from current user"),
+    description="List all subaccounts under your account",
+    usage="vastai show subaccounts [OPTIONS]",
+    help="List all subaccounts under your account"
 )
-def tfa__resend_sms(args):
-    """Resend SMS 2FA code to the user's phone."""
-    url = apiurl(args, "/api/v0/tfa/resend/")
-    payload = build_tfa_verification_payload(args, phone_number=args.phone_number)
-    
-    r = http_post(args, url, headers=apiheaders(args), json=payload)
-    r.raise_for_status()
-    
-    response_data = r.json()
-    
-    print(f"{SUCCESS} SMS code resent successfully!")
-    print(f"\n{response_data['msg']}")
-    print(f"\nOnce you receive the SMS code, complete your 2FA login with:")
-    print(f"  vastai tfa login --sms --secret {args.secret} -c <CODE>")
+def show__subaccounts(args):
+    """
+    Shows stats for logged-in user. Does not show API key.
 
+    :param argparse.Namespace args: should supply all the command-line options
+    :rtype:
+    """
+    data = api_call(args, "GET", "/subaccounts", query_args={"owner": "me"})
+    rows = data["users"]
+    return output_result(args, rows, user_fields)
 
 @parser.command(
-    argument("-c", "--code", mutex_group='code_grp', required=True, help="2FA code from Authenticator app (default) or SMS", type=str),
-    argument("--sms", mutex_group="type_grp", help="Use SMS 2FA method instead of TOTP", action="store_true"),
-    argument("-s", "--secret", help="Secret token from previous login step (required for SMS)", type=str, default=None),
-    argument("-bc", "--backup-code", mutex_group='code_grp', required=True, help="One-time backup code (alternative to regular 2FA code)", type=str, default=None),
-    argument("-id", "--method-id", mutex_group="type_grp", help="2FA Method ID if you have more than one of the same type ('id' from `tfa status`)", type=str, default=None),
-    usage="vastai tfa regen-codes [--code CODE] [--sms] [--secret SECRET] [--backup-code BACKUP_CODE] [--method-id ID]",
-    help="Regenerate backup codes for 2FA",
-    epilog=deindent("""
-        Generate a new set of backup codes for your account.
-        
-        This action requires 2FA verification to prevent unauthorized regeneration.
-        
-        WARNING: This will invalidate all existing backup codes!
-        Any previously generated codes will no longer work.
-        
-        Backup codes are one-time use codes that allow you to log in
-        if you lose access to your primary 2FA method (lost phone, etc).
-        
-        You should regenerate your backup codes if:
-        • You've used several codes and are running low
-        • You think your codes may have been compromised
-        • You lost your saved codes and need new ones
-        
-        Important: Save the new codes in a secure location immediately!
-        They will not be shown again.
-        
-        Examples:
-         vastai tfa regen-codes --code 123456
-         vastai tfa regen-codes -c 123456 --sms --secret abc123def456
-         vastai tfa regen-codes --backup-code ABCD-EFGH-IJKL
-    """),
+    description="List all members in your team",
+    usage="vastai show members",
+    help="List all members in your team",
 )
-def tfa__regen_codes(args):
-    """Regenerate backup codes for 2FA recovery."""
-    url = apiurl(args, "/api/v0/tfa/regen-backup-codes/")
-    
-    # Confirm action since this invalidates existing codes
-    prompt = "\nThis will invalidate all existing backup codes. Continue? (y|n): "
-    if confirm_destructive_action(prompt) == False:
-        print("Operation cancelled.")
-        return
-    
-    # Build the request payload with verification
-    payload = build_tfa_verification_payload(args)
-    try:
-        r = http_put(args, url, headers=apiheaders(args), json=payload)
-        r.raise_for_status()
-        
-        response_data = r.json()
-        
-        # Display the new backup codes
-        if "backup_codes" in response_data:
-            save_backup_codes(response_data["backup_codes"])
-        else:
-            print(f"\n{SUCCESS} Backup codes regenerated successfully!")
-            print("(No codes returned in response - this may be an error)")
+def show__members(args):
+    result = api_call(args, "GET", "/team/members/")
+    return output_result(args, result)
 
-    except requests.exceptions.HTTPError as e:
-        handle_failed_tfa_verification(args, e)
-        return 1
+@parser.command(
+    argument("NAME", help="name of the role", type=str),
+    description="Show details for a specific team role",
+    usage="vastai show team-role NAME",
+    help="Show details for a specific team role",
+)
+def show__team_role(args):
+    result = api_call(args, "GET", f"/team/roles/{args.NAME}/")
+    return output_result(args, result)
 
+@parser.command(
+    description="List all roles defined for your team",
+    usage="vastai show team-roles",
+    help="List all roles defined for your team"
+)
+def show__team_roles(args):
+    result = api_call(args, "GET", "/team/roles-full/")
+    return output_result(args, result)
 
 @parser.command(
-    argument("-p", "--phone-number", help="Phone number to receive SMS code (E.164 format, e.g., +1234567890)", type=str, default=None),
-    usage="vastai tfa send-sms [--phone-number PHONE_NUMBER]",
-    help="Request a 2FA SMS verification code",
+    argument("-q", "--quiet", action="store_true", help="display information about user"),
+    description="Show your account information and balance",
+    usage="vastai show user [OPTIONS]",
+    help="Show your account information and balance",
     epilog=deindent("""
-        Request a two-factor authentication code to be sent via SMS.
-        
-        If --phone-number is not provided, uses the phone number on your account.
-        The secret token will be returned and must be used with 'vastai tfa activate'.
-        
+        Displays account information for the authenticated user.
+
         Examples:
-         vastai tfa send-sms
-         vastai tfa send-sms --phone-number +12345678901
-    """),
+            vastai show user                           # Show user info in table format
+            vastai show user --raw                     # Output as JSON for scripting
+
+        Information displayed:
+          - Account balance and credit
+          - Email address
+          - Username
+          - SSH public key (if configured)
+          - Account settings
+
+        Note: API key is NOT displayed for security reasons.
+        Use 'vastai set api-key' to update your stored API key.
+    """)
 )
-def tfa__send_sms(args):
-    """Request a 2FA SMS code to be sent to the user's phone."""
-    url = apiurl(args, "/api/v0/tfa/test/")
-    
-    # Build the request payload
-    payload = {}
-    
-    # Add phone number if provided
-    if args.phone_number:
-        payload["phone_number"] = args.phone_number
-    
-    r = http_post(args, url, headers=apiheaders(args), json=payload)
-    r.raise_for_status()
-    
-    response_data = r.json()
-    
-    # Extract and display the secret token
-    secret = response_data["secret"]
-    print(f"{SUCCESS} SMS code sent successfully!")
-    print(f"  Secret token: {secret}")
-    print(f"\nOnce you receive the SMS code:")
-    print(f"\n  If you are setting up SMS 2FA for the first time, run:")
-    phone_num = f"--phone-number {args.phone_number}" if args.phone_number else "[--phone-number <PHONE_NUMBER>]"
-    print(f"    vastai tfa activate --sms --secret {secret} {phone_num} [--label <LABEL>] <CODE>")
-    print(f"\n  Otherwise you can complete your 2FA log in with:")
-    print(f"    vastai tfa login --sms --secret {secret} -c <CODE>\n")
+def show__user(args):
+    """
+    Shows stats for logged-in user. Does not show API key.
 
+    :param argparse.Namespace args: should supply all the command-line options
+    :rtype:
+    """
+    user_blob = api_call(args, "GET", "/users/current", query_args={"owner": "me"})
+    user_blob.pop("api_key")
+    return output_result(args, user_blob, user_fields)
 
-TFA_METHOD_FIELDS = (
-    ("id", "ID", "{}", None, True),
-    ("user_id", "User ID", "{}", None, True),
-    ("is_primary", "Primary", "{}", None, True),
-    ("method", "Method", "{}", None, True),
-    ("label", "Label", "{}", None, True),
-    ("phone_number", "Phone Number", "{}", None, False),
-    ("created_at", "Created", "{}", lambda x: datetime.fromtimestamp(x).strftime('%Y-%m-%d %H:%M:%S') if x else "N/A", True),
-    ("last_used", "Last Used", "{}", lambda x: datetime.fromtimestamp(x).strftime('%Y-%m-%d %H:%M:%S') if x else "Never", True),
-    ("fail_count", "Failures", "{}", None, True),
-    ("locked_until", "Locked Until", "{}", lambda x: datetime.fromtimestamp(x).strftime('%Y-%m-%d %H:%M:%S') if x else "N/A", True),
+@parser.command(
+    argument("-t", "--type", help="volume type to display. Default to all. Possible values are \"local\", \"all\", \"network\"", type=str, default="all"),
+    description="List all your storage volumes and their status",
+    usage="vastai show volumes [OPTIONS]",
+    help="List all your storage volumes and their status",
+    epilog=deindent("""
+        Show stats on owned volumes
+    """)
 )
-def display_tfa_methods(methods):
-    """Helper function to display 2FA methods in a table."""
-    method_fields = TFA_METHOD_FIELDS
-    has_sms = any(m['method'] == 'sms' for m in methods)
-    if not has_sms:  # Don't show Phone Number column if the user has no SMS methods
-        method_fields = tuple(field for field in TFA_METHOD_FIELDS if field[0] != 'phone_number')
-    
-    display_table(methods, method_fields, replace_spaces=False)
+def show__volumes(args: argparse.Namespace):
+    types = {
+        "local": "local_volume",
+        "network": "network_volume",
+        "all": "all_volume"
+    }
+    type = types.get(args.type, "all")
+    result = api_call(args, "GET", "/volumes", query_args={"owner": "me", "type": type})
+    rows = result.get("volumes", [])
+    processed = []
+    for row in rows:
+        row = {k: strip_strings(v) for k, v in row.items()}
+        row['duration'] = time.time() - row['start_date']
+        processed.append(row)
+    if args.raw:
+        return processed
+    else:
+        display_table(processed, volume_fields, replace_spaces=False)
 
 
 @parser.command(
-    help="Shows the current 2FA status and configured methods",
-    epilog=deindent("""
-        Show the current 2FA status for your account, including:
-         • Whether or not 2FA is enabled
-         • A list of active 2FA methods
-         • The number of backup codes remaining (if 2FA is enabled)
-    """)
+    argument("cluster_id", help="ID of cluster you want to remove machine from.", type=int),
+    argument("machine_id", help="ID of machine to remove from cluster.", type=int),
+    argument("new_manager_id", help="ID of machine to promote to manager. Must already be in cluster", type=int, nargs="?"),
+    description="[Host] [Beta] Remove a machine from a cluster",
+    usage="vastai remove-machine-from-cluster CLUSTER_ID MACHINE_ID NEW_MANAGER_ID",
+    help="[Host] [Beta] Remove a machine from a cluster",
+    epilog=deindent("""Removes machine from cluster and also reassigns manager ID, 
+    if we're removing the manager node""")
 )
-def tfa__status(args):
-    """Show the current 2FA status for the user."""
-    url = apiurl(args, "/tfa/status/")
-    r = http_get(args, url)
+def remove_machine_from_cluster(args: argparse.Namespace):
+    json_blob = {
+        "cluster_id": args.cluster_id,
+        "machine_id": args.machine_id,
+    }
+
+    if args.new_manager_id:
+        json_blob["new_manager_id"] = args.new_manager_id
+    if args.explain:
+        print("request json:", json_blob)
+
+    req_url = apiurl(args, "/cluster/remove_machine/")
+    r = http_del(args, req_url, json=json_blob)
     r.raise_for_status()
-    response_data = r.json()
 
     if args.raw:
-        print(json.dumps(response_data, indent=2))
-        return
+        return r.json()
+
+    print(r.json().get("msg", "Unknown error"))
+
+
 
-    tfa_enabled = response_data.get("tfa_enabled", False)
-    methods = response_data.get("methods", [])
-    backup_codes_remaining = response_data.get("backup_codes_remaining", 0)
-    
-    if not tfa_enabled or not methods:
-        print(f"{WARN}  No active 2FA methods found")
-    else:
-        print(f"2FA Status: Enabled {SUCCESS}")
-        print(f"\nActive 2FA Methods:")
-        display_tfa_methods(methods)
-        print(f"\nBackup codes remaining: {backup_codes_remaining}")
 
 
-@parser.command(
-    usage="vastai tfa totp-setup",
-    help="Generate TOTP secret and QR code for Authenticator app setup",
-    epilog=deindent("""
-        Set up TOTP (Time-based One-Time Password) 2FA using an Authenticator app.
-        
-        This command generates a new TOTP secret and displays:
-        • A QR code (for scanning with your app)
-        • A manual entry key (for typing into your app)
-        • A secret token (needed for the next step)
-        
-        Workflow:
-         1. Run this command to generate the TOTP secret
-         2. Add the account to your Authenticator app by either:
-            • Scanning the displayed QR code, OR
-            • Manually entering the key shown
-         3. Once added, your app will display a 6-digit code
-         4. Complete setup by running:
-            vastai tfa activate --secret <SECRET> <CODE>
-        
-        Supported Authenticator Apps:
-         • Google Authenticator
-         • Microsoft Authenticator
-         • Authy
-         • 1Password
-         • Any TOTP-compatible app
-        
-        Example:
-         vastai tfa totp-setup
-    """),
-)
-def tfa__totp_setup(args):
-    """Generate a TOTP secret and QR code for setting up Authenticator app 2FA."""
-    url = apiurl(args, "/api/v0/tfa/totp-setup/")
-    
-    r = http_post(args, url, headers=apiheaders(args), json={})
-    r.raise_for_status()
-    
-    response_data = r.json()
-    if args.raw:
-        print(json.dumps(response_data, indent=2))
-        return
-    
-    # Extract the secret and provisioning URI
-    secret = response_data["secret"]
-    provisioning_uri = response_data["provisioning_uri"]
-    
-    # Display the setup information
-    print("\n" + "="*60)
-    print("TOTP (Authenticator App) 2FA Setup")
-    print("="*60)
 
-    print("\nScan this QR code with your Authenticator app:\n")
-    
-    try:  # Generate and display QR code in terminal
-        import qrcode
-        qr = qrcode.QRCode(border=2)
-        qr.add_data(provisioning_uri)
-        qr.make()
-        qr.print_ascii(tty=True)
-    except ImportError:
-        print("  [QR code display requires 'qrcode' package]")
-        print(f"  Install with: pip install qrcode")
-        print(f"\n  Or manually enter this URI in your app:")
-        print(f"  {provisioning_uri}")
 
-    print("\nOR Manual Entry Key (type this into your Authenticator app):")
-    print(f"  {secret}")
-    
-    print("\nNext Steps:")
-    print("  1. Your Authenticator app should now display a 6-digit code")
-    print("  2. Complete setup by running:")
-    print(f"     vastai tfa activate --secret {secret} <CODE>")
-    print("\n" + "="*60 + "\n")
 
 
-@parser.command(
-    argument("method_id", metavar="METHOD_ID", help="ID of the 2FA method to update (see `vastai tfa status`)", type=int),
-    argument("-l", "--label", help="New label/name for this 2FA method", type=str, default=None),
-    argument("-p", "--set-primary", help="Set this method as the primary/default 2FA method", default=None),
-    usage="vastai tfa update METHOD_ID [--label LABEL] [--set-primary]",
-    help="Update a 2FA method's settings",
-    epilog=deindent("""
-        Update the label or primary status of a 2FA method.
-        
-        The label is a friendly name to help you identify different methods
-        (e.g. "Work Phone", "Personal Authenticator").
-        
-        The primary method is your preferred/default 2FA method.
-        
-        Examples:
-         vastai tfa update 123 --label "Work Phone"
-         vastai tfa update 456 --set-primary
-         vastai tfa update 789 --label "Backup Authenticator" --set-primary
-    """),
-)
-def tfa__update(args):
-    """Update settings for an existing 2FA method."""
-    url = apiurl(args, "/api/v0/tfa/update/")
-    
-    # Build payload with only provided fields
-    payload = {
-        "tfa_method_id": args.method_id
-    }
-    
-    if args.label is not None:
-        payload["label"] = args.label
-    
-    if args.set_primary is not None:
-        if args.set_primary.lower() in {'true', 't'}:
-            args.set_primary = True
-        elif args.set_primary.lower() in {'false', 'f'}:
-            args.set_primary = False
-        else:            
-            print("Error: --set-primary must be <t|true> or <f|false>")
-            return
-        
-        payload["is_primary"] = args.set_primary
-    
-    # Validate that at least one update field was provided
-    if len(payload) == 1:  # only method_id
-        print("Error: You must specify at least one field to update (--label or --set-primary)")
-        return 1
-    
-    r = http_put(args, url, headers=apiheaders(args), json=payload)
-    r.raise_for_status()
-    
-    response_data = r.json()
-    if args.raw:
-        print(json.dumps(response_data, indent=2))
-        return
-    
-    method_info = response_data.get("method", {})
-    
-    print(f"\n{SUCCESS} 2FA method updated successfully!")
-    if args.label:
-        print(f"   New label: {args.label}")
-    if args.set_primary is not None:
-        print(f"   Set as primary method = {args.set_primary}")
-    if method_info:
-        print("\nUpdated 2FA Method:")
-        display_tfa_methods([method_info])
-    
-        
 
 @parser.command(
-    argument("recipient", help="email (or id) of recipient account", type=str),
-    argument("amount",    help="$dollars of credit to transfer ", type=float),
+    argument("recipient_pos", help=argparse.SUPPRESS, type=str, nargs='?', default=None),
+    argument("amount_pos",    help=argparse.SUPPRESS, type=float, nargs='?', default=None),
+    argument("--recipient", "-r", help="email (or id) of recipient account", type=str, default=None),
+    argument("--amount", "-a",    help="dollars of credit to transfer", type=float, default=None),
     argument("--skip",    help="skip confirmation", action="store_true", default=False),
-    usage="vastai transfer credit RECIPIENT AMOUNT",
+    description="Transfer credits to another account",
+    usage="vastai transfer credit [--recipient EMAIL] [--amount DOLLARS] [RECIPIENT AMOUNT]",
     help="Transfer credits to another account",
     epilog=deindent("""
-        Transfer (amount) credits to account with email (recipient).
+        Transfer credits to another account. This action is irreversible.
+
+        Supports two syntax styles (named flags recommended):
+          vastai transfer credit --recipient user@example.com --amount 10.00
+          vastai transfer credit user@example.com 10.00  (legacy positional)
+
+        Examples:
+          vastai transfer credit --recipient user@example.com --amount 25.50
+          vastai transfer credit -r user@example.com -a 25.50
+          vastai transfer credit user@example.com 25.50
     """),
 )
 def transfer__credit(args: argparse.Namespace):
     url = apiurl(args, "/commands/transfer_credit/")
- 
+
+    # Resolve arguments - prefer named flags over positional for clarity
+    recipient = args.recipient if args.recipient is not None else args.recipient_pos
+    amount = args.amount if args.amount is not None else args.amount_pos
+
+    if not recipient or amount is None:
+        print("Error: Both recipient and amount are required.")
+        print("Usage: vastai transfer credit --recipient EMAIL --amount DOLLARS")
+        print("   or: vastai transfer credit EMAIL AMOUNT (legacy)")
+        return
+
     if not args.skip:
-        print(f"Transfer ${args.amount} credit to account {args.recipient}?  This is irreversible.")
+        print(f"Transfer ${amount} credit to account {recipient}?  This is irreversible.")
         ok = input("Continue? [y/n] ")
         if ok.strip().lower() != "y":
             return
 
     json_blob = {
         "sender":    "me",
-        "recipient": args.recipient,
-        "amount":    args.amount,
+        "recipient": recipient,
+        "amount":    amount,
     }
     if (args.explain):
         print("request json: ")
         print(json_blob)
     r = http_put(args, url,  headers=headers,json=json_blob)
     r.raise_for_status()
-
-    if (r.status_code == 200):
-        rj = r.json();
-        if (rj["success"]):
-            print(f"Sent {args.amount} to {args.recipient} ".format(r.json()))
-        else:
-            print(rj["msg"]);
+    rj = r.json();
+    if args.raw:
+        return rj
+    if rj.get("success"):
+        print(f"Sent ${amount} to {recipient}")
     else:
-        print(r.text);
-        print("failed with error {r.status_code}".format(**locals()));
+        print(rj.get("msg", "Unknown error"));
 
 @parser.command(
     argument("id", help="id of autoscale group to update", type=int),
@@ -6598,6 +7024,7 @@ def transfer__credit(args: argparse.Namespace):
     argument("--launch_args",   help="launch args  string for create instance  ex: \"--onstart onstart_wget.sh  --env '-e ONSTART_PATH=https://s3.amazonaws.com/public.vast.ai/onstart_OOBA.sh' --image atinoda/text-generation-webui:default-nightly --disk 64\"", type=str),
     argument("--endpoint_name",   help="deployment endpoint name (allows multiple workergroups to share same deployment endpoint)", type=str),
     argument("--endpoint_id",   help="deployment endpoint id (allows multiple workergroups to share same deployment endpoint)", type=int),
+    description="Update an existing autoscale group",
     usage="vastai update workergroup WORKERGROUP_ID --endpoint_id ENDPOINT_ID [options]",
     help="Update an existing autoscale group",
     epilog=deindent("""
@@ -6605,8 +7032,8 @@ def transfer__credit(args: argparse.Namespace):
     """),
 )
 def update__workergroup(args):
-    id  = args.id
-    url = apiurl(args, f"/autojobs/{id}/" )
+    workergroup_id = args.id
+    url = apiurl(args, f"/autojobs/{workergroup_id}/")
     if args.no_default:
         query = ""
     else:
@@ -6621,7 +7048,10 @@ def update__workergroup(args):
     r.raise_for_status()
     if 'application/json' in r.headers.get('Content-Type', ''):
         try:
-            print("workergroup update {}".format(r.json()))
+            rj = r.json()
+            if args.raw:
+                return rj
+            print("workergroup update {}".format(rj))
         except requests.exceptions.JSONDecodeError:
             print("The response is not valid JSON.")
             print(r)
@@ -6641,6 +7071,7 @@ def update__workergroup(args):
     argument("--cold_workers", help="min number of workers to keep 'cold' when you have no load (default 5)", type=int),
     argument("--max_workers", help="max number of workers your endpoint group can have (default 20)", type=int),
     argument("--endpoint_name",   help="deployment endpoint name (allows multiple workergroups to share same deployment endpoint)", type=str),
+    description="Update an existing endpoint group",
     usage="vastai update endpoint ID [OPTIONS]",
     help="Update an existing endpoint group",
     epilog=deindent("""
@@ -6648,8 +7079,8 @@ def update__workergroup(args):
     """),
 )
 def update__endpoint(args):
-    id  = args.id
-    url = apiurl(args, f"/endptjobs/{id}/" )
+    endpoint_id = args.id
+    url = apiurl(args, f"/endptjobs/{endpoint_id}/")
     json_blob = {"client_id": "me", "endptjob_id": args.id, "min_load": args.min_load, "min_cold_load":args.min_cold_load,"target_util": args.target_util, "cold_mult": args.cold_mult, "cold_workers": args.cold_workers, "max_workers" : args.max_workers, "endpoint_name": args.endpoint_name, "endpoint_state": args.endpoint_state, "autoscaler_instance":args.auto_instance}
     if (args.explain):
         print("request json: ")
@@ -6658,7 +7089,10 @@ def update__endpoint(args):
     r.raise_for_status()
     if 'application/json' in r.headers.get('Content-Type', ''):
         try:
-            print("update endpoint {}".format(r.json()))
+            rj = r.json()
+            if args.raw:
+                return rj
+            print("update endpoint {}".format(rj))
         except requests.exceptions.JSONDecodeError:
             print("The response is not valid JSON.")
             print(r)
@@ -6670,6 +7104,7 @@ def update__endpoint(args):
 @parser.command(
     argument("name", help="Environment variable name to update", type=str),
     argument("value", help="New environment variable value", type=str),
+    description="Update an existing user environment variable",
     usage="vastai update env-var <name> <value>",
     help="Update an existing user environment variable",
 )
@@ -6681,6 +7116,8 @@ def update__env_var(args):
     r.raise_for_status()
 
     result = r.json()
+    if args.raw:
+        return result
     if result.get("success"):
         print(result.get("msg", "Environment variable updated successfully."))
     else:
@@ -6694,8 +7131,9 @@ def update__env_var(args):
     argument("--args", help="new arguments for the instance", type=str),
     argument("--env", help="new environment variables for the instance", type=json.loads),
     argument("--onstart", help="new onstart script for the instance", type=str),
+    description="Update an instance configuration or recreate from a template",
     usage="vastai update instance ID [OPTIONS]",
-    help="Update recreate an instance from a new/updated template",
+    help="Update an instance configuration or recreate from a template",
     epilog=deindent("""
         Example: vastai update instance 1234 --template_hash_id 661d064bbda1f2a133816b6d55da07c3
     """),
@@ -6707,7 +7145,7 @@ def update__instance(args):
     """
     url = apiurl(args, f"/instances/update_template/{args.id}/")
     json_blob = {"id": args.id}
-    
+
     if args.template_id:
         json_blob["template_id"] = args.template_id
     if args.template_hash_id:
@@ -6724,11 +7162,13 @@ def update__instance(args):
     if args.explain:
         print("request json: ")
         print(json_blob)
-    
+
     r = http_put(args, url, headers=headers, json=json_blob)
 
     if r.status_code == 200:
         response_data = r.json()
+        if args.raw:
+            return response_data
         if response_data.get("success"):
             print(f"Instance {args.id} updated successfully.")
             print("Updated instance details:")
@@ -6743,24 +7183,24 @@ def update__instance(args):
     argument("id", help="id of the role", type=int),
     argument("--name", help="name of the template", type=str),
     argument("--permissions", help="file path for json encoded permissions, look in the docs for more information", type=str),
+    description="Update an existing team role",
     usage="vastai update team-role ID --name NAME --permissions PERMISSIONS",
     help="Update an existing team role",
 )
 def update__team_role(args):
-    url = apiurl(args, "/team/roles/{id}/".format(id=args.id))
     permissions = load_permissions_from_file(args.permissions)
-    r = http_put(args, url,  headers=headers, json={"name": args.name, "permissions": permissions})
-    r.raise_for_status()
+    result = api_call(args, "PUT", "/team/roles/{id}/".format(id=args.id), json_body={"name": args.name, "permissions": permissions})
     if args.raw:
-        return r
+        return result
     else:
-        print(json.dumps(r.json(), indent=1))
+        print(json.dumps(result, indent=1))
 
 
 
 @parser.command(
     argument("HASH_ID", help="hash id of the template", type=str),
     *get_template_arguments(),
+    description="Update an existing template",
     usage="vastai update template HASH_ID",
     help="Update an existing template",
     epilog=deindent("""
@@ -6823,8 +7263,8 @@ def update__template(args):
     r.raise_for_status()
     try:
         rj = r.json()
-        if rj["success"]:
-            print(f"updated template: {json.dumps(rj['template'], indent=1)}")
+        if rj.get("success"):
+            print(f"updated template: {json.dumps(rj.get('template', ''), indent=1)}")
         else:
             print("template update failed")
     except requests.exceptions.JSONDecodeError as e:
@@ -6835,22 +7275,21 @@ def update__template(args):
 @parser.command(
     argument("id", help="id of the ssh key to update", type=int),
     argument("ssh_key", help="new public key value", type=str),
+    description="Update an SSH key's label or properties",
     usage="vastai update ssh-key ID SSH_KEY",
-    help="Update an existing SSH key",
+    help="Update an SSH key's label or properties",
 )
 def update__ssh_key(args):
     """Updates an existing SSH key for the authenticated user."""
     ssh_key = get_ssh_key(args.ssh_key)
-    url = apiurl(args, f"/ssh/{args.id}/")
 
     payload = {
         "id": args.id,
         "ssh_key": ssh_key,
     }
 
-    r = http_put(args, url, json=payload)
-    r.raise_for_status()
-    print(r.json())
+    result = api_call(args, "PUT", f"/ssh/{args.id}/", json_body=payload)
+    print(result)
 
 def convert_dates_to_timestamps(args):
     selector_flag = ""
@@ -6866,7 +7305,7 @@ def convert_dates_to_timestamps(args):
         try:
             end_date = dateutil.parser.parse(str(args.end_date))
             end_date_txt = end_date.isoformat()
-            end_timestamp = time.mktime(end_date.timetuple())
+            end_timestamp = calendar.timegm(end_date.timetuple())
         except ValueError as e:
             print(f"Warning: Invalid end date format! Ignoring end date! \n {str(e)}")
     
@@ -6874,9 +7313,9 @@ def convert_dates_to_timestamps(args):
         try:
             start_date = dateutil.parser.parse(str(args.start_date))
             start_date_txt = start_date.isoformat()
-            start_timestamp = time.mktime(start_date.timetuple())
+            start_timestamp = calendar.timegm(start_date.timetuple())
         except ValueError as e:
-            print(f"Warning: Invalid start date format! Ignoring end date! \n {str(e)}")
+            print(f"Warning: Invalid start date format! Ignoring start date! \n {str(e)}")
 
     return start_timestamp, end_timestamp
 
@@ -6921,14 +7360,14 @@ def filter_invoice_items(args: argparse.Namespace, rows: List) -> Dict:
         try:
             end_date = dateutil.parser.parse(str(args.end_date))
             end_date_txt = end_date.isoformat()
-            end_timestamp = time.mktime(end_date.timetuple())
+            end_timestamp = calendar.timegm(end_date.timetuple())
         except ValueError:
             print("Warning: Invalid end date format! Ignoring end date!")
     if args.start_date:
         try:
             start_date = dateutil.parser.parse(str(args.start_date))
             start_date_txt = start_date.isoformat()
-            start_timestamp = time.mktime(start_date.timetuple())
+            start_timestamp = calendar.timegm(start_date.timetuple())
         except ValueError:
             print("Warning: Invalid start date format! Ignoring start date!")
 
@@ -7041,8 +7480,9 @@ def type_filter_fn(row):
     argument("machines", help="ids of machines to add disk to, that is networked to be on the same LAN as machine", type=int, nargs='+'),
     argument("mount_point", help="mount path of disk to add", type=str),
     argument("-d", "--disk_id", help="id of network disk to attach to machines in the cluster", type=int, nargs='?'),
+    description="[Host] [Beta] Attach a network disk to a machine cluster",
     usage="vastai add network-disk MACHINES MOUNT_PATH [options]",
-    help="[Host] Add Network Disk to Physical Cluster.",
+    help="[Host] [Beta] Attach a network disk to a machine cluster",
     epilog=deindent("""
         This variant can be used to add a network disk to a physical cluster.
         When you add a network disk for the first time, you just need to specify the machine(s) and mount_path.
@@ -7065,18 +7505,25 @@ def add__network_disk(args):
         print(json_blob)
     r = http_post(args, url, headers=headers, json=json_blob)
     r.raise_for_status()
- 
+
+    try:
+        rj = r.json()
+    except JSONDecodeError:
+        print("Error: API returned invalid JSON response", file=sys.stderr)
+        return
+
     if args.raw:
-        return r
+        return rj
 
-    print("Attached network disk to machines. Disk id: " + str(r.json()["disk_id"]))
+    print("Attached network disk to machines. Disk id: " + str(rj.get("disk_id", "unknown")))
 
 
 
 @parser.command(
     argument("id", help="id of machine to cancel maintenance(s) for", type=int),
+    description="[Host] Cancel a scheduled maintenance window",
     usage="vastai cancel maint id",
-    help="[Host] Cancel maint window",
+    help="[Host] Cancel a scheduled maintenance window",
     epilog=deindent("""
         For deleting a machine's scheduled maintenance window(s), use this cancel maint command.    
         Example: vastai cancel maint 8207
@@ -7100,8 +7547,13 @@ def cancel__maint(args):
         print(json_blob)
     r = http_put(args, url,  headers=headers,json=json_blob)
     r.raise_for_status()
-    print(r.text)
-    print(f"Cancel maintenance window(s) scheduled for machine {args.id} success".format(r.json()))
+    try:
+        rj = r.json()
+    except JSONDecodeError:
+        rj = {"success": True, "message": r.text}
+    if args.raw:
+        return rj
+    print(f"Cancel maintenance window(s) scheduled for machine {args.id} success")
 
 
 def cleanup_machine(args, machine_id):
@@ -7113,21 +7565,22 @@ def cleanup_machine(args, machine_id):
 
     if (r.status_code == 200):
         rj = r.json()
-        if (rj["success"]):
+        if (rj.get("success")):
             print(json.dumps(r.json(), indent=1))
         else:
             if args.raw:
-                return r
+                return r.json()
             else:
-                print(rj["msg"])
+                print(rj.get("msg", "Unknown error"))
     else:
         print(r.text)
         print("failed with error {r.status_code}".format(**locals()))
 
 @parser.command(
     argument("id", help="id of machine to cleanup", type=int),
+    description="[Host] Clean up expired storage to free disk space",
     usage="vastai cleanup machine ID [options]",
-    help="[Host] Remove all expired storage instances from the machine, freeing up space",
+    help="[Host] Clean up expired storage to free disk space",
     epilog=deindent("""
         Instances expire on their end date. Expired instances still pay storage fees, but can not start.
         Since hosts are still paid storage fees for expired instances, we do not auto delete them.
@@ -7145,8 +7598,9 @@ def cleanup__machine(args):
 
 @parser.command(
     argument("IDs", help="ids of machines", type=int, nargs='+'),
+    description="[Host] Rebuild larger GPU offers from orphaned single GPUs when possible",
     usage="vastai defragment machines IDs ",
-    help="[Host] Defragment machines",
+    help="[Host] Rebuild larger GPU offers from orphaned single GPUs when possible",
     epilog=deindent("""
         Defragment some of your machines. This will rearrange GPU assignments to try and make more multi-gpu offers available.
     """),
@@ -7157,11 +7611,14 @@ def defrag__machines(args):
     if (args.explain):
         print("request json: ")
         print(json_blob)
-    r = requests.put(url, headers=headers,json=json_blob)
+    r = http_put(args, url, headers=headers, json=json_blob)
     r.raise_for_status()
     if 'application/json' in r.headers.get('Content-Type', ''):
         try:
-            print(f"defragment result: {r.json()}")
+            rj = r.json()
+            if args.raw:
+                return rj
+            print(f"defragment result: {rj}")
         except requests.exceptions.JSONDecodeError:
             print("The response is not valid JSON.")
             print(r)
@@ -7172,8 +7629,9 @@ def defrag__machines(args):
 
 @parser.command(
    argument("id", help="id of machine to delete", type=int),
+    description="[Host] Remove a machine from your host account",
     usage="vastai delete machine <id>",
-    help="[Host] Delete machine if the machine is not being used by clients. host jobs on their own machines are disregarded and machine is force deleted.",
+    help="[Host] Remove a machine from your host account",
 ) 
 def delete__machine(args):
     """
@@ -7183,10 +7641,12 @@ def delete__machine(args):
     r = http_post(args, req_url, headers=headers)
     if (r.status_code == 200):
         rj = r.json()
-        if (rj["success"]):
+        if args.raw:
+            return rj
+        if (rj.get("success")):
             print("deleted machine_id ({machine_id}) and all related contracts.".format(machine_id=args.id));
         else:
-            print(rj["msg"]);
+            print(rj.get("msg", "Unknown error"));
     else:
         print(r.text);
         print("failed with error {r.status_code}".format(**locals()));
@@ -7216,7 +7676,7 @@ def list_machine(args, id):
 
     if (r.status_code == 200):
         rj = r.json()
-        if (rj["success"]):
+        if (rj.get("success")):
             price_gpu_ = str(args.price_gpu) if args.price_gpu is not None else "def"
             price_inetu_ = str(args.price_inetu)
             price_inetd_ = str(args.price_inetd)
@@ -7225,7 +7685,7 @@ def list_machine(args, id):
             discount_rate_ = str(args.discount_rate)
             duration_ = str(args.duration)
             if args.raw:
-                return r
+                return r.json()
             else:
                 print("offers created/updated for machine {id},  @ ${price_gpu_}/gpu/hr, ${price_inetu_}/GB up, ${price_inetd_}/GB down, {min_chunk_}/min gpus, max discount_rate {discount_rate_}, till {end_date_}, duration {duration_}".format(**locals()))
                 num_extended = rj.get("extended", 0)
@@ -7235,9 +7695,9 @@ def list_machine(args, id):
 
         else:
             if args.raw:
-                return r
+                return r.json()
             else:
-                print(rj["msg"])
+                print(rj.get("msg", "Unknown error"))
     else:
         print(r.text)
         print("failed with error {r.status_code}".format(**locals()))
@@ -7257,8 +7717,9 @@ def list_machine(args, id):
     argument("-l", "--duration", help="Updates end_date daily to be duration from current date. Cannot be combined with end_date. Format is: `n days`, `n weeks`, `n months`, `n years`, or total intended duration in seconds."),
     argument("-v", "--vol_size", help="Size for volume contract offer. Defaults to half of available disk. Set 0 to not create a volume contract offer.", type=int),
     argument("-z", "--vol_price", help="Price for disk on volume contract offer. Defaults to price_disk. Invalid if vol_size is 0.", type=float),
+    description="[Host] List a single machine for rent on the marketplace",
     usage="vastai list machine ID [options]",
-    help="[Host] list a machine for rent",
+    help="[Host] List a single machine for rent on the marketplace",
     epilog=deindent("""
         Performs the same action as pressing the "LIST" button on the site https://cloud.vast.ai/host/machines.
         On the end date the listing will expire and your machine will unlist. However any existing client jobs will still remain until ended by their owners.
@@ -7276,7 +7737,7 @@ def list__machine(args):
 
 
 @parser.command(
-    argument("ids", help="ids of instance to list", type=int, nargs='+'),
+    argument("ids", help="ids of machines to list", type=int, nargs='+'),
     argument("-g", "--price_gpu", help="per gpu on-demand rental price in $/hour (base price for active instances)", type=float),
     argument("-s", "--price_disk",
              help="storage price in $/GB/month (price for inactive instances), default: $0.10/GB/month", type=float),
@@ -7289,8 +7750,9 @@ def list__machine(args):
     argument("-l", "--duration", help="Updates end_date daily to be duration from current date. Cannot be combined with end_date. Format is: `n days`, `n weeks`, `n months`, `n years`, or total intended duration in seconds."),
     argument("-v", "--vol_size", help="Size for volume contract offer. Defaults to half of available disk. Set 0 to not create a volume contract offer.", type=int),
     argument("-z", "--vol_price", help="Price for disk on volume contract offer. Defaults to price_disk. Invalid if vol_size is 0.", type=float),
-    usage="vastai list machines IDs [options]",
-    help="[Host] list machines for rent",
+    description="[Host] List multiple machines for rent on the marketplace",
+    usage="vastai list machines IDS [OPTIONS]",
+    help="[Host] List multiple machines for rent on the marketplace",
     epilog=deindent("""
         This variant can be used to list or update the listings for multiple machines at once with the same args.
         You could extend the end dates of all your machines using a command combo like this:
@@ -7301,7 +7763,6 @@ def list__machines(args):
     """
     """
     return [list_machine(args, id) for id in args.ids]
-    return res
 
 
 
@@ -7312,8 +7773,9 @@ def list__machines(args):
     argument("-p", "--price_disk", help="storage price in $/GB/month, default: $%(default).2f/GB/month", default=.15, type=float),
     argument("-e", "--end_date", help="contract offer expiration - the available until date (optional, in unix float timestamp or MM/DD/YYYY format), default 1 month", type=str, default=None),
     argument("-s", "--size", help="size of disk space allocated to offer in GB, default %(default)s GB", default=15, type=int),
+    description="[Host] [Beta] List disk space as a rentable network volume",
     usage="vastai list network volume DISK_ID [options]",
-    help="[Host] list disk space for rent as a network volume"
+    help="[Host] [Beta] List disk space as a rentable network volume"
 )
 def list__network_volume(args):
     json_blob = {
@@ -7334,9 +7796,9 @@ def list__network_volume(args):
     r = http_post(args, url, headers=headers, json=json_blob)
     r.raise_for_status()
     if args.raw:
-        return r
+        return r.json()
 
-    print(r.json()["msg"])
+    print(r.json().get("msg", "Unknown error"))
 
 
 
@@ -7346,13 +7808,14 @@ def list__network_volume(args):
              help="storage price in $/GB/month, default: $%(default).2f/GB/month", default=.10, type=float),
     argument("-e", "--end_date", help="contract offer expiration - the available until date (optional, in unix float timestamp or MM/DD/YYYY format), default 3 months", type=str),
     argument("-s", "--size", help="size of disk space allocated to offer in GB, default %(default)s GB", default=15),
+    description="[Host] List disk space as a rentable volume",
     usage="vastai list volume ID [options]",
-    help="[Host] list disk space for rent as a volume on a machine",
+    help="[Host] List disk space as a rentable volume",
     epilog=deindent("""
         Allocates a section of disk on a machine to be used for volumes.  
     """)
 )
-def list__volume(args):        
+def list__volume(args):
     json_blob ={
         "size": int(args.size),
         "machine": int(args.id),
@@ -7370,19 +7833,20 @@ def list__volume(args):
     r = http_post(args, url,  headers=headers,json=json_blob)
     r.raise_for_status()
     if args.raw:
-        return r
+        return r.json()
     else:
         print("Created. {}".format(r.json()))
 
 
 @parser.command(
-    argument("ids", help="id of machines list", type=int, nargs='+'),
+    argument("ids", help="ids of machines to list volumes on", type=int, nargs='+'),
     argument("-p", "--price_disk",
              help="storage price in $/GB/month, default: $%(default).2f/GB/month", default=.10, type=float),
     argument("-e", "--end_date", help="contract offer expiration - the available until date (optional, in unix float timestamp or MM/DD/YYYY format), default 3 months", type=str),
     argument("-s", "--size", help="size of disk space allocated to offer in GB, default %(default)s GB", default=15),
-    usage="vastai list volume IDs [options]",
-    help="[Host] list disk space for rent as a volume on machines",
+    description="[Host] List disk space on multiple machines as rentable volumes",
+    usage="vastai list volumes IDS [OPTIONS]",
+    help="[Host] List disk space on multiple machines as rentable volumes",
     epilog=deindent("""
         Allocates a section of disk on machines to be used for volumes.  
     """)
@@ -7405,7 +7869,7 @@ def list__volumes(args):
     r = http_post(args, url,  headers=headers,json=json_blob)
     r.raise_for_status()
     if args.raw:
-        return r
+        return r.json()
     else:
         print("Created. {}".format(r.json()))
 
@@ -7415,8 +7879,9 @@ def list__volumes(args):
 
 @parser.command(
     argument("id", help="id of machine to remove default instance from", type=int),
+    description="[Host] Remove default background jobs from a machine",
     usage="vastai remove defjob id",
-    help="[Host] Delete default jobs",
+    help="[Host] Remove default background jobs from a machine",
 )
 def remove__defjob(args):
     """
@@ -7431,10 +7896,12 @@ def remove__defjob(args):
 
     if (r.status_code == 200):
         rj = r.json();
-        if (rj["success"]):
+        if args.raw:
+            return rj
+        if (rj.get("success")):
             print("default instance for machine {machine_id} removed.".format(machine_id=args.id));
         else:
-            print(rj["msg"]);
+            print(rj.get("msg", "Unknown error"));
     else:
         print(r.text);
         print("failed with error {r.status_code}".format(**locals()));
@@ -7449,8 +7916,9 @@ def remove__defjob(args):
     argument("--url", help="Server REST API URL", default="https://console.vast.ai"),
     argument("--retry", help="Retry limit", type=int, default=3),
     argument("--ignore-requirements", action="store_true", help="Ignore the minimum system requirements and run the self test regardless"),
+    description="[Host] Run diagnostics on a hosted machine",
     usage="vastai self-test machine <machine_id> [--debugging] [--explain] [--api_key API_KEY] [--url URL] [--retry RETRY] [--raw] [--ignore-requirements]",
-    help="[Host] Perform a self-test on the specified machine",
+    help="[Host] Run diagnostics on a hosted machine",
     epilog=deindent("""
         This command tests if a machine meets specific requirements and 
         runs a series of tests to ensure it's functioning correctly.
@@ -7626,26 +8094,41 @@ def search_offers_and_get_top(machine_id):
             try:
                 progress_print(args, f"Starting test with {docker_image}")
                 response = create__instance(create_args)
-                if isinstance(response, requests.Response):  # Check if it's an HTTP response
-                    if response.status_code == 200:
-                        try:
-                            instance_info = response.json()  # Parse JSON
-                            if args.debugging:
-                                debug_print(args, "Captured instance_info from create__instance:", instance_info)
-                        except json.JSONDecodeError as e:
-                            progress_print(args, f"Error parsing JSON response: {e}")
-                            debug_print(args, f"Raw response content: {response.text}")
-                            raise Exception("Failed to parse JSON from instance creation response.")
-                    else:
-                        progress_print(args, f"HTTP error during instance creation: {response.status_code}")
-                        debug_print(args, f"Response text: {response.text}")
-                        raise Exception(f"Instance creation failed with status {response.status_code}")
+                if isinstance(response, dict):
+                    instance_info = response
+                elif isinstance(response, requests.Response):
+                    instance_info = response.json()
                 else:
-                    raise Exception("Unexpected response type from create__instance.")
+                    raise Exception(f"Unexpected return type from create__instance: {type(response).__name__}")
+                if args.debugging:
+                    debug_print(args, "Captured instance_info from create__instance:", instance_info)
+                if not instance_info.get("success", True):
+                    msg = instance_info.get("msg", "Unknown error")
+                    error_type = instance_info.get("error", "")
+                    raise Exception(f"API error ({error_type}): {msg}")
+            except requests.exceptions.HTTPError as e:
+                status = e.response.status_code
+                try:
+                    err_body = e.response.json()
+                    msg = err_body.get("msg", e.response.text)
+                except (JSONDecodeError, ValueError):
+                    msg = e.response.text
+                error_messages = {
+                    400: f"Bad request: {msg}",
+                    401: f"Unauthorized: {msg}",
+                    403: f"Permission denied: {msg}",
+                    404: f"Offer {ask_contract_id} not found or not available: {msg}",
+                    410: f"Offer {ask_contract_id} is no longer available: {msg}",
+                    429: "Too many API requests. Please wait and try again.",
+                }
+                reason = error_messages.get(status, f"HTTP {status}: {msg}")
+                progress_print(args, f"Error creating instance: {reason}")
+                result["reason"] = reason
+                return result
             except Exception as e:
                 progress_print(args, f"Error creating instance: {e}")
-                result["reason"] = "Failed to create instance. Check the docker configuration. Use the self-test machine function in vast cli "
-                return result  # Cleanup handled in finally block
+                result["reason"] = str(e)
+                return result
 
             # Extract instance ID and proceed
             instance_id = instance_info.get("new_contract")
@@ -7720,8 +8203,9 @@ def set_ask(args):
     argument("--price_inetd", help="price for internet download bandwidth in $/GB", type=float),
     argument("--image", help="docker container image to launch", type=str),
     argument("--args", nargs=argparse.REMAINDER, help="list of arguments passed to container launch"),
+    description="[Host] Configure default background jobs for a machine",
     usage="vastai set defjob id [--api-key API_KEY] [--price_gpu PRICE_GPU] [--price_inetu PRICE_INETU] [--price_inetd PRICE_INETD] [--image IMAGE] [--args ...]",
-    help="[Host] Create default jobs for a machine",
+    help="[Host] Configure default background jobs for a machine",
     epilog=deindent("""
         Performs the same action as creating a background job at https://cloud.vast.ai/host/create.       
                     
@@ -7742,11 +8226,13 @@ def set__defjob(args):
     r = http_put(args, req_url, headers=headers, json=json_blob)
     if (r.status_code == 200):
         rj = r.json();
-        if (rj["success"]):
+        if args.raw:
+            return rj
+        if (rj.get("success")):
             print(
                 "bids created for machine {args.id},  @ ${args.price_gpu}/gpu/day, ${args.price_inetu}/GB up, ${args.price_inetd}/GB down".format(**locals()));
         else:
-            print(rj["msg"]);
+            print(rj.get("msg", "Unknown error"));
     else:
         print(r.text);
         print("failed with error {r.status_code}".format(**locals()));
@@ -7831,8 +8317,9 @@ def pretty_print_POST(req):
 @parser.command(
     argument("id", help="id of machine to set min bid price for", type=int),
     argument("--price", help="per gpu min bid price in $/hour", type=float),
+    description="[Host] Set minimum price for interruptible/spot instance rentals",
     usage="vastai set min_bid id [--price PRICE]",
-    help="[Host] Set the minimum bid/rental price for a machine",
+    help="[Host] Set minimum price for interruptible/spot instance rentals",
     epilog=deindent("""
         Change the current min bid price of machine id to PRICE.
     """),
@@ -7850,7 +8337,10 @@ def set__min_bid(args):
         print(json_blob)
     r = http_put(args, url,  headers=headers,json=json_blob)
     r.raise_for_status()
-    print("Per gpu min bid price changed".format(r.json()))
+    rj = r.json()
+    if args.raw:
+        return rj
+    print("Per gpu min bid price changed".format(rj))
 
 
 @parser.command(
@@ -7858,8 +8348,9 @@ def set__min_bid(args):
     argument("--sdate",      help="maintenance start date in unix epoch time (UTC seconds)", type=float),
     argument("--duration",   help="maintenance duration in hours", type=float),
     argument("--maintenance_category",   help="(optional) can be one of [power, internet, disk, gpu, software, other]", type=str, default="not provided"),
+    description="[Host] Schedule a maintenance window for a machine",
     usage="vastai schedule maintenance id [--sdate START_DATE --duration DURATION --maintenance_category MAINTENANCE_CATEGORY]",
-    help="[Host] Schedule upcoming maint window",
+    help="[Host] Schedule a maintenance window for a machine",
     epilog=deindent("""
         The proper way to perform maintenance on your machine is to wait until all active contracts have expired or the machine is vacant.
         For unplanned or unscheduled maintenance, use this schedule maint command. That will notify the client that you have to take the machine down and that they should save their work. 
@@ -7888,13 +8379,17 @@ def schedule__maint(args):
         print(json_blob)
     r = http_put(args, url,  headers=headers,json=json_blob)
     r.raise_for_status()
-    print(f"Maintenance window scheduled for {dt} success".format(r.json()))
+    rj = r.json()
+    if args.raw:
+        return rj
+    print(f"Maintenance window scheduled for {dt} success".format(rj))
 
 @parser.command(
-    argument("Machine", help="id of machine to display", type=int),
+    argument("id", help="id of machine to display", type=int),
     argument("-q", "--quiet", action="store_true", help="only display numeric ids"),
+    description="[Host] Show details for a specific hosted machine",
     usage="vastai show machine ID [OPTIONS]",
-    help="[Host] Show hosted machines",
+    help="[Host] Show details for a specific hosted machine",
 )
 def show__machine(args):
     """
@@ -7903,12 +8398,11 @@ def show__machine(args):
     :param argparse.Namespace args: should supply all the command-line options
     :rtype:
     """
-    req_url = apiurl(args, f"/machines/{args.Machine}", {"owner": "me"});
-    r = http_get(args, req_url)
-    r.raise_for_status()
-    rows = r.json()
+    rows = api_call(args, "GET", f"/machines/{args.id}", query_args={"owner": "me"})
+    if isinstance(rows, dict):
+        rows = [rows]
     if args.raw:
-        return r
+        return rows
     else:
         if args.quiet:
             ids = [f"{row['id']}" for row in rows]
@@ -7919,8 +8413,9 @@ def show__machine(args):
 
 @parser.command(
     argument("-q", "--quiet", action="store_true", help="only display numeric ids"),
+    description="[Host] List all your hosted machines",
     usage="vastai show machines [OPTIONS]",
-    help="[Host] Show hosted machines",
+    help="[Host] List all your hosted machines",
 )
 def show__machines(args):
     """
@@ -7929,14 +8424,12 @@ def show__machines(args):
     :param argparse.Namespace args: should supply all the command-line options
     :rtype:
     """
-    req_url = apiurl(args, "/machines", {"owner": "me"});
-    r = http_get(args, req_url)
-    r.raise_for_status()
-    rows = r.json()["machines"]
+    result = api_call(args, "GET", "/machines", query_args={"owner": "me"})
+    rows = result.get("machines", [])
     if args.raw:
-        return r
+        return rows
     else:
-        if args.quiet:            
+        if args.quiet:
             ids = [f"{row['id']}" for row in rows]
             print(" ".join(id for id in ids))
         else:
@@ -7944,10 +8437,11 @@ def show__machines(args):
 
 
 @parser.command(
-    argument("-ids", help="comma seperated string of machine_ids for which to get maintenance information", type=str),
+    argument("-i", "--ids", help="comma separated string of machine_ids for which to get maintenance information", type=str),
     argument("-q", "--quiet", action="store_true", help="only display numeric ids of the machines in maintenance"),
-    usage="\nvastai show maints -ids 'machine_id_1' [OPTIONS]\nvastai show maints -ids 'machine_id_1, machine_id_2' [OPTIONS]",
-    help="[Host] Show maintenance information for host machines",
+    description="[Host] List scheduled maintenance windows",
+    usage="vastai show maints --ids MACHINE_IDS [OPTIONS]",
+    help="[Host] List scheduled maintenance windows",
 )
 def show__maints(args):
     """
@@ -7959,14 +8453,11 @@ def show__maints(args):
     machine_ids = args.ids.split(',')
     machine_ids = list(map(int, machine_ids))
 
-    req_url = apiurl(args, "/machines/maintenances", {"owner": "me", "machine_ids" : machine_ids});
-    r = http_get(args, req_url)
-    r.raise_for_status()
-    rows = r.json()
+    rows = api_call(args, "GET", "/machines/maintenances", query_args={"owner": "me", "machine_ids": machine_ids})
     if args.raw:
-        return r
+        return rows
     else:
-        if args.quiet:   
+        if args.quiet:
             ids = [f"{row['machine_id']}" for row in rows]
             print(" ".join(id for id in ids))
         else:
@@ -7974,8 +8465,9 @@ def show__maints(args):
 
 
 @parser.command(
+    description="[Host] [Beta] List network disks attached to your machines",
     usage="vastai show network-disks",
-    help="[Host] Show network disks associated with your account.",
+    help="[Host] [Beta] List network disks attached to your machines",
     epilog=deindent("""
         Show network disks associated with your account.
     """)
@@ -7984,7 +8476,11 @@ def show__network_disks(args: argparse.Namespace):
     req_url = apiurl(args, "/network_disk/")
     r = http_get(args, req_url)
     r.raise_for_status()
-    response_data = r.json()
+    try:
+        response_data = r.json()
+    except JSONDecodeError:
+        print("Error: API returned invalid JSON response", file=sys.stderr)
+        return
 
     if args.raw:
         return response_data
@@ -8008,8 +8504,9 @@ def show__network_disks(args: argparse.Namespace):
 
 @parser.command(
     argument("id", help="id of machine to unlist", type=int),
+    description="[Host] Remove a machine from the rental marketplace",
     usage="vastai unlist machine <id>",
-    help="[Host] Unlist a listed machine",
+    help="[Host] Remove a machine from the rental marketplace",
 )
 
 def unlist__machine(args):
@@ -8023,18 +8520,21 @@ def unlist__machine(args):
     r = http_del(args, req_url, headers=headers)
     if (r.status_code == 200):
         rj = r.json();
-        if (rj["success"]):
+        if args.raw:
+            return rj
+        if (rj.get("success")):
             print("all offers for machine {machine_id} removed, machine delisted.".format(machine_id=args.id));
         else:
-            print(rj["msg"]);
+            print(rj.get("msg", "Unknown error"));
     else:
         print(r.text);
         print("failed with error {r.status_code}".format(**locals()));
 
 @parser.command(
     argument("id", help="id of network volume offer to unlist", type=int),
+    description="[Host] [Beta] Remove a network volume offer from the marketplace",
     usage="vastai unlist network volume OFFER_ID",
-    help="[Host] Unlists network volume offer",
+    help="[Host] [Beta] Remove a network volume offer from the marketplace",
 )
 def unlist__network_volume(args):
     json_blob = {
@@ -8050,20 +8550,21 @@ def unlist__network_volume(args):
     r = http_post(args, url, headers=headers, json=json_blob)
     r.raise_for_status()
     if args.raw:
-        return r
- 
-    print(r.json()["msg"])
+        return r.json()
+
+    print(r.json().get("msg", "Unknown error"))
 
 @parser.command(
     argument("id", help="volume ID you want to unlist", type=int),
+    description="[Host] Remove a volume offer from the marketplace",
     usage="vastai unlist volume ID",
-    help="[Host] unlist volume offer"
+    help="[Host] Remove a volume offer from the marketplace",
 )
 def unlist__volume(args):
-    id = args.id
+    volume_id = args.id
 
     json_blob = {
-        "id": id
+        "id": volume_id
     }
 
     url = apiurl(args, "/volumes/unlist")
@@ -8074,9 +8575,9 @@ def unlist__volume(args):
     r = http_post(args, url, headers, json_blob)
     r.raise_for_status()
     if args.raw:
-        return r
+        return r.json()
     else:
-        print(r.json()["msg"])
+        print(r.json().get("msg", "Unknown error"))
 
 
 def suppress_stdout():
@@ -8297,7 +8798,7 @@ def is_instance(instance_id):
             return 'unknown'
 
     # Prepare destroy_args with required attributes set to False as needed
-    destroy_args = argparse.Namespace(api_key=api_key, url="https://console.vast.ai", retry=3, explain=False, raw=args.raw, debbuging=args.debugging,)
+    destroy_args = argparse.Namespace(api_key=api_key, url="https://console.vast.ai", retry=3, explain=False, raw=args.raw, debugging=args.debugging,)
 
     # Delay start if specified
     if delay > 0:
@@ -8327,16 +8828,31 @@ def is_instance(instance_id):
                 return False, reason
 
             # Attempt to connect to the progress endpoint
+            # Use a fresh session with custom SSL adapter to avoid state pollution
             try:
                 if args.debugging:
                     debug_print(args, f"Sending GET request to https://{ip_address}:{port}/progress")
-                response = requests.get(f'https://{ip_address}:{port}/progress', verify=False, timeout=10)
-                
-                if response.status_code == 200 and not first_connection_established:
-                    progress_print(args, "Successfully established HTTPS connection to the server.")
-                    first_connection_established = True
 
-                message = response.text.strip()
+                from requests.adapters import HTTPAdapter
+                from urllib3.util.ssl_ import create_urllib3_context
+
+                class FreshSSLAdapter(HTTPAdapter):
+                    def init_poolmanager(self, *args, **kwargs):
+                        ctx = create_urllib3_context()
+                        ctx.check_hostname = False
+                        ctx.verify_mode = ssl.CERT_NONE
+                        kwargs['ssl_context'] = ctx
+                        return super().init_poolmanager(*args, **kwargs)
+
+                with requests.Session() as session:
+                    session.mount('https://', FreshSSLAdapter())
+                    response = session.get(f'https://{ip_address}:{port}/progress', verify=False, timeout=10)
+
+                    if response.status_code == 200 and not first_connection_established:
+                        progress_print(args, "Successfully established HTTPS connection to the server.")
+                        first_connection_established = True
+
+                    message = response.text.strip()
                 if args.debugging:
                     debug_print(args, f"Received message: '{message}'")
             except requests.exceptions.RequestException as e:
@@ -8505,7 +9021,7 @@ def check_requirements(machine_id, api_key, args):
         # 8. System RAM vs. Total GPU RAM
         gpu_total_ram = safe_float(top_offer.get('gpu_total_ram'))  # in MB
         cpu_ram = safe_float(top_offer.get('cpu_ram'))  # in MB
-        if cpu_ram < .95*gpu_total_ram: # .95 to allow for reserved hardware memory
+        if cpu_ram < .95*gpu_total_ram:  # .95 to allow for reserved hardware memory
             unmet_reasons.append("System RAM is less than total VRAM.")
 
         # Debugging Information for RAM
@@ -8658,7 +9174,7 @@ def quote_completions(self, completions: List[str], cword_prequote: str, last_wo
       pre = super().quote_completions(completions, cword_prequote, last_wordbreak_pos)
       # preference the non-hyphenated options first
       return sorted(pre, key=lambda x: x.startswith('-'))
-except:
+except (NameError, AttributeError):
   pass
 
 
@@ -8705,17 +9221,13 @@ def main():
         try:
             res = args.func(args)
             if args.raw and res is not None:
-                # There's two types of responses right now
-                try:
-                    print(json.dumps(res, indent=1, sort_keys=True))
-                except:
-                    print(json.dumps(res.json(), indent=1, sort_keys=True))
+                print(json.dumps(res, indent=1, sort_keys=True))
                 sys.exit(0)
             sys.exit(res)
-        
+
         except requests.exceptions.HTTPError as e:
             try:
-                errmsg = e.response.json().get("msg");
+                errmsg = e.response.json().get("msg")
             except JSONDecodeError:
                 if e.response.status_code == 401:
                     errmsg = "Please log in or sign up"
@@ -8737,11 +9249,19 @@ def main():
                         print("Please log in using the `tfa login` command and try again.")
                         break
 
-            print(f"Failed with error {e.response.status_code}: {errmsg}")
+            if hasattr(args, 'raw') and args.raw:
+                error = {"error": True, "status_code": e.response.status_code, "msg": errmsg}
+                print(json.dumps(error, indent=1))
+            else:
+                print(f"Failed with error {e.response.status_code}: {errmsg}")
             break
-        
+
         except ValueError as e:
-            print(e)
+            if hasattr(args, 'raw') and args.raw:
+                error = {"error": True, "msg": str(e)}
+                print(json.dumps(error, indent=1))
+            else:
+                print(e)
             break
 
 
diff --git a/vastai/__init__.py b/vastai/__init__.py
new file mode 100644
index 00000000..3f8faa29
--- /dev/null
+++ b/vastai/__init__.py
@@ -0,0 +1,48 @@
+"""
+vastai - Vast.ai SDK and CLI package.
+
+Main entry point for the SDK. Provides VastAI class for programmatic access
+to the Vast.ai API, plus lazy-loaded serverless client/server classes.
+"""
+
+from .sdk import VastAI
+
+# Lazy imports for serverless classes (PEP 562)
+# These are only loaded when accessed, avoiding heavy dependencies
+# for users who only need the core SDK.
+_LAZY_IMPORTS = {
+    "Serverless": ".serverless.client.client",
+    "ServerlessRequest": ".serverless.client.client",
+    "Endpoint": ".serverless.client.endpoint",
+    "Worker": ".serverless.server.worker",
+    "WorkerConfig": ".serverless.server.worker",
+    "HandlerConfig": ".serverless.server.worker",
+    "LogActionConfig": ".serverless.server.worker",
+    "BenchmarkConfig": ".serverless.server.worker",
+}
+
+__all__ = [
+    "VastAI",
+    "Serverless",
+    "ServerlessRequest",
+    "Endpoint",
+    "Worker",
+    "WorkerConfig",
+    "HandlerConfig",
+    "LogActionConfig",
+    "BenchmarkConfig",
+]
+
+
+def __getattr__(name: str) -> type:
+    if name in _LAZY_IMPORTS:
+        import importlib
+        try:
+            module = importlib.import_module(_LAZY_IMPORTS[name], __name__)
+        except ImportError as exc:
+            raise ImportError(
+                f"Cannot import {name!r} because a required dependency is missing: {exc}. "
+                f"Install serverless extras with: pip install vastai[serverless]"
+            ) from exc
+        return getattr(module, name)  # type: ignore[no-any-return]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
diff --git a/vastai/__main__.py b/vastai/__main__.py
new file mode 100644
index 00000000..d6c0c6cd
--- /dev/null
+++ b/vastai/__main__.py
@@ -0,0 +1,6 @@
+"""Support running vastai as a module: python -m vastai"""
+
+from vast import main
+
+if __name__ == "__main__":
+    main()  # type: ignore[no-untyped-call]
diff --git a/vastai/sdk.py b/vastai/sdk.py
new file mode 100644
index 00000000..043feaf6
--- /dev/null
+++ b/vastai/sdk.py
@@ -0,0 +1,672 @@
+"""
+Vast.ai Python SDK.
+
+This module provides the VastAI class, a Python SDK client for the Vast.ai GPU
+cloud platform. It wraps the vast.py CLI commands and exposes them as Python
+methods with proper type hints and docstrings.
+
+Example:
+    Basic usage::
+
+        from vastai import VastAI
+
+        client = VastAI(api_key="your-api-key")
+        offers = client.search_offers(limit=10)
+        print(f"Found {len(offers)} offers")
+
+    Creating an instance::
+
+        offer_id = offers[0]["id"]
+        result = client.create_instance(id=offer_id, image="pytorch/pytorch:latest")
+
+    Checking instances::
+
+        instances = client.show_instances()
+        for inst in instances:
+            print(f"ID: {inst['id']}, Status: {inst['actual_status']}")
+
+The SDK automatically handles authentication, retries, and output capture.
+All methods return parsed JSON when ``raw=True`` (the default for SDK usage).
+"""
+
+import types
+import argparse
+from typing import Any, Callable
+import io
+import inspect
+import re
+import os
+import sys
+import logging
+from pyparsing import Word, alphas, alphanums, oneOf, Group, ZeroOrMore, quotedString, delimitedList, Suppress
+
+from .vastai_base import VastAIBase
+from vast import parser, APIKEY_FILE
+import vast as _vast
+from textwrap import dedent
+
+#ogging.basicConfig(level=os.getenv('LOGLEVEL') or logging.INFO)
+logger = logging.getLogger()
+
+
+_regions = {
+  'AF': ('DZ,AO,BJ,BW,BF,BI,CM,CV,CF,TD,KM,CD,CG,DJ,EG,GQ,ER,ET,GA,GM,GH,GN,'
+         'GW,KE,LS,LR,LY,MW,MA,ML,MR,MU,MZ,NA,NE,NG,RW,SH,ST,SN,SC,SL,SO,ZA,'
+         'SS,SD,SZ,TZ,TG,TN,UG,YE,ZM,ZW'),  # Africa
+  'AS': ('AE,AM,AR,AU,AZ,BD,BH,BN,BT,MM,KH,KW,KP,IN,ID,IR,IQ,IL,JP,JO,KZ,LV,'
+         'LI,MY,MV,MN,NP,KR,PK,PH,QA,SA,SG,LK,SY,TW,TJ,TH,TR,TM,VN,YE,HK,'
+         'CN,OM'),  # Asia
+  'EU': ('AL,AD,AT,BY,BE,BA,BG,HR,CY,CZ,DK,EE,'
+         'FI,FR,GE,DE,GR,HU,IS,IT,KZ,LV,LI,LT,'
+         'LU,MT,MD,MC,ME,NL,NO,PL,PT,RO,RU,RS,'
+         'SK,SI,ES,SE,CH,UA,GB,VA,MK'),  # Europe
+  'LC': ('AG,AR,BS,BB,BZ,BO,BR,CL,CO,CR,CU,DO,EC,SV,GY,HT,HN,JM,MX,NI,PA,PY,'
+         'PE,PR,RD,SUR,TT,UR,VZ'),  # Latin America and the Caribbean
+  'NA': 'CA,US',  # Northern America
+  'OC': ('AU,FJ,GU,KI,MH,FM,NR,NZ,PG,PW,SL,TO,TV,VU'),  # Oceania
+}
+
+def reverse_mapping(regions: dict[str, str]) -> dict[str, str]:
+    """
+    Create a reverse mapping from country codes to region codes.
+
+    Args:
+        regions: Dict mapping region codes (e.g., 'NA', 'EU') to comma-separated
+            country codes (e.g., 'CA,US').
+
+    Returns:
+        Dict mapping each country code to its region code.
+
+    Example:
+        >>> regions = {'NA': 'CA,US', 'EU': 'DE,FR'}
+        >>> reverse_mapping(regions)
+        {'CA': 'NA', 'US': 'NA', 'DE': 'EU', 'FR': 'EU'}
+    """
+    reversed_mapping: dict[str, str] = {}
+    for region, countries in regions.items():
+        for country in countries.split(','):
+            reversed_mapping[country] = region
+    return reversed_mapping
+
+_regions_rev = reverse_mapping(_regions)
+
+
+def queryParser(kwargs: dict[str, Any], instance: "VastAI") -> tuple[dict[str, bool], dict[str, Any]]:
+    """
+    Pre-process query parameters before API call.
+
+    Parses the query string to extract state flags (georegion, chunked) and
+    transforms geolocation queries when georegion mode is enabled.
+
+    Args:
+        kwargs: Keyword arguments passed to the SDK method, including 'query'.
+        instance: The VastAI instance for context.
+
+    Returns:
+        A tuple of (state_dict, modified_kwargs) where:
+            - state_dict contains boolean flags for 'georegion' and 'chunked'
+            - modified_kwargs has the transformed query string
+
+    Note:
+        - 'georegion=true' in query enables region-based geolocation expansion
+        - 'chunked=true' enables value chunking for SkyPilot compatibility
+    """
+    # georegion uses the region modifiers as top level
+    # descriptors
+    #
+    # chunked reduces values communicated to more usable chunks
+    state: dict[str, bool] = {'georegion': False, 'chunked': False }
+
+    if kwargs.get('query') is not None:
+        qstr = kwargs['query']
+
+        key = Word(alphas + "_-")
+        operator = oneOf("= in != > < >= <=")
+        single_value = Word(alphanums + "_.-") | quotedString
+
+        array_value = (
+            Suppress("[") + delimitedList(quotedString) + Suppress("]")
+        ).setParseAction(lambda t: f"[{','.join(t)}]")
+        value = single_value | array_value
+        expr = Group(key + operator + value)
+        query = ZeroOrMore(expr)
+        parsed = query.parseString(qstr)
+
+        toPass = []
+
+        for state_key in state.keys():
+            state[state_key] = any([state_key, '=', 'true'] == list(expr) for expr in parsed)
+
+        for expr in parsed:
+            if expr[0] in state.keys():
+                continue
+
+            elif expr[0] == 'geolocation' and state['georegion']:
+                region = _regions.get(str(expr[2]).strip('"'))
+                expr_list: list[str] = ['geolocation', 'in', f'[{region}]']
+                toPass.append(' '.join(expr_list))
+                continue
+
+            toPass.append(' '.join(str(e) for e in expr))
+
+        kwargs['query'] = ' '.join(toPass)
+
+    return (state, kwargs)
+
+def queryFormatter(state: dict[str, bool], obj: list[dict[str, Any]], instance: "VastAI") -> list[dict[str, Any]]:
+    """
+    Post-process search results based on query state flags.
+
+    Transforms search results by:
+    - Adding 'datacenter' boolean field
+    - Expanding geolocation to include region code when georegion=true
+    - Filtering and chunking values when chunked=true (for SkyPilot)
+
+    Args:
+        state: State dict from queryParser with 'georegion' and 'chunked' flags.
+        obj: List of offer dictionaries from the API response.
+        instance: The VastAI instance for context.
+
+    Returns:
+        Filtered and transformed list of offer dictionaries.
+
+    Note:
+        This algorithm is designed for SkyPilot integration to provide
+        standardized catalog offerings with chunked resource values.
+    """
+    # This algo is explicitly designed for skypilot to add
+    # depth to our catalog offerings
+    cutoff: dict[str, int] = {
+        'cpu_ram': 64 * 1024,
+        'cpu_cores': 32,
+        'min_bid': 0
+    }
+
+    filtered: list[dict[str, Any]] = []
+    for res in obj:
+        res['datacenter'] = (res['hosting_type'] == 1)
+        if state['georegion'] and res['geolocation'] is not None:
+            country = res['geolocation'][-2:]
+            res['geolocation'] += f', {_regions_rev[country]}'
+
+        if state['chunked']:
+            good = True
+
+            try:
+                for k, v in cutoff.items():
+                    if res[k] is not None and (res[k] < cutoff[k]):
+                        good = False
+                    else:
+                        res[k] = cutoff[k]
+            except (KeyError, TypeError):
+                good = False
+
+            if not good:
+                continue
+
+            #res['cpu_ram'] = upper(res['cpu_ram'])
+            #res['cpu_cores'] = max(res['cpu_cores'] & 0xffff8, 4)
+            res['gpu_ram'] = res['gpu_ram'] & 0xffffffffff0
+            res['disk_space'] = int(res['disk_space']) & 0xffffffffffc0
+
+        filtered.append(res)
+
+    return filtered
+
+def lastOutput(state: dict[str, bool] | None, obj: Any, instance: "VastAI") -> str | None:
+    """
+    Return captured stdout output from the last command.
+
+    Used as a post-hook for commands like 'logs' and 'execute' where the
+    important output is printed to stdout rather than returned.
+
+    Args:
+        state: State dict (unused, for hook signature compatibility).
+        obj: Return value from the CLI function (unused).
+        instance: The VastAI instance containing last_output.
+
+    Returns:
+        The captured stdout content from the last command execution.
+    """
+    return instance.last_output
+
+# Hook functions: [pre_hook, post_hook] for each command
+# Pre-hooks transform kwargs, post-hooks transform results
+_hooks: dict[str, list[Callable[..., Any] | None]] = {
+    'search__offers': [queryParser, queryFormatter],
+    'logs': [None, lastOutput],
+    'execute': [None, lastOutput]
+}
+
+class VastAI(VastAIBase):
+    """
+    Python SDK client for the Vast.ai GPU cloud platform.
+
+    VastAI provides programmatic access to all Vast.ai CLI commands through
+    a clean Python interface. Each CLI command maps to a method on this class,
+    with 130+ methods covering instances, offers, billing, teams, and more.
+
+    Example:
+        Basic usage::
+
+            >>> from vastai import VastAI
+            >>> client = VastAI(api_key="your-api-key")
+            >>> offers = client.search_offers()
+            >>> print(offers[:3])  # First 3 offers
+
+        Creating an instance::
+
+            >>> offer_id = offers[0]["id"]
+            >>> result = client.create_instance(id=offer_id, image="pytorch/pytorch:latest")
+            >>> print(result)
+
+        Checking instances::
+
+            >>> instances = client.show_instances()
+            >>> for inst in instances:
+            ...     print(f"ID: {inst['id']}, Status: {inst['actual_status']}")
+
+    Attributes:
+        api_key: The Vast.ai API key for authentication.
+        raw: If True, methods return raw JSON dicts. If False, output is printed.
+        retry: Number of retry attempts for failed requests (default: 3).
+        server_url: Base URL for the Vast.ai API (default: https://console.vast.ai).
+        explain: If True, print API endpoint details before requests.
+        quiet: If True, suppress non-essential output.
+        curl: If True, print equivalent curl commands.
+        creds_source: Read-only property indicating API key source ('CODE', 'FILE', 'NONE').
+
+    Note:
+        Methods that return lists (search_*, show_*s) return ``list[dict[str, Any]]``.
+        Methods that return single objects return ``dict[str, Any]``.
+        Check method docstrings for specific return types.
+
+    See Also:
+        - :doc:`/sdk/quickstart` for a step-by-step guide
+        - :doc:`/sdk/reference/vastai` for full API reference
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        server_url: str = "https://console.vast.ai",
+        retry: int = 3,
+        raw: bool = True,
+        explain: bool = False,
+        quiet: bool = False,
+        curl: bool = False,
+    ) -> None:
+        """
+        Initialize a VastAI client.
+
+        Args:
+            api_key: Vast.ai API key. If not provided, reads from environment
+                variable VAST_API_KEY or ~/.config/vastai/vast_api_key file.
+            server_url: Base URL for the Vast.ai API. Override for testing or
+                alternate endpoints. Defaults to "https://console.vast.ai".
+            retry: Number of retry attempts for transient failures (429, 5xx errors).
+                Defaults to 3.
+            raw: If True, methods return parsed JSON. If False, output is printed
+                to stdout (CLI behavior). Defaults to True for SDK usage.
+            explain: If True, print HTTP method and URL before each request.
+                Useful for debugging. Defaults to False.
+            quiet: If True, suppress progress messages and other non-essential
+                output. Defaults to False.
+            curl: If True, print equivalent curl commands for each API call.
+                Useful for debugging. Defaults to False.
+
+        Raises:
+            ValueError: If api_key is not provided and cannot be found in
+                environment or config file (raised by some methods, not __init__).
+
+        Example:
+            Basic initialization::
+
+                >>> client = VastAI(api_key="your-key")
+
+            With custom options::
+
+                >>> client = VastAI(
+                ...     api_key="your-key",
+                ...     retry=5,
+                ...     explain=True,
+                ...     quiet=True
+                ... )
+
+            Using stored credentials::
+
+                >>> # After running: vastai set api-key YOUR_KEY
+                >>> client = VastAI()  # Reads from config file
+        """
+        # Instance attribute type declarations
+        self._creds: str
+        self._KEYPATH: str
+        self.api_key: str | None
+        self.api_key_access: str | None
+        self.server_url: str
+        self.retry: int
+        self.raw: bool
+        self.explain: bool
+        self.quiet: bool
+        self.curl: bool
+        self.imported_methods: dict[str, dict[str, Any]]
+        self.last_output: str | None
+
+        if not api_key:
+            if os.path.exists(APIKEY_FILE):
+                with open(APIKEY_FILE, "r") as reader:
+                    api_key = reader.read().strip()
+                    self._creds = "FILE"
+            else:
+                self._creds = "NONE"
+        else:
+            self._creds = "CODE"
+
+        self._KEYPATH = APIKEY_FILE
+        self.api_key = api_key
+        self.api_key_access = api_key
+        self.server_url = server_url
+        self.retry = retry
+        self.raw = raw
+        self.explain = explain
+        self.quiet = quiet
+        self.curl = curl
+        self.imported_methods = {}
+        self.last_output = None
+        self.import_cli_functions()
+
+    @property
+    def creds_source(self) -> str:
+        """
+        Return the source of the API key credentials.
+
+        Returns:
+            One of:
+                - 'CODE': API key was passed to constructor
+                - 'FILE': API key was read from config file
+                - 'NONE': No API key found
+        """
+        return self._creds
+
+    def generate_signature_from_argparse(
+        self, parser: argparse.ArgumentParser
+    ) -> tuple[inspect.Signature, str]:
+        """
+        Generate a Python function signature from an argparse ArgumentParser.
+
+        Introspects the parser's actions to build an inspect.Signature and
+        corresponding docstring Args section for the wrapped method.
+
+        Args:
+            parser: The argparse.ArgumentParser for a CLI subcommand.
+
+        Returns:
+            A tuple of (Signature, docstring) where:
+                - Signature is an inspect.Signature with typed parameters
+                - docstring is a Google-style Args section string
+        """
+        parameters: list[inspect.Parameter] = [inspect.Parameter("self", inspect.Parameter.POSITIONAL_OR_KEYWORD)]
+        isFirst: bool = True
+        docstring: str = ''
+
+        for action in sorted(parser._actions,  key=lambda action: len(action.option_strings) > 0):
+            if action.dest == 'help':
+                continue
+            if action.help and "Alias" in action.help:
+                continue
+
+            # Determine parameter kind
+            kind: inspect._ParameterKind = inspect.Parameter.POSITIONAL_OR_KEYWORD
+            if action.option_strings:
+                kind = inspect.Parameter.KEYWORD_ONLY
+
+            # Determine default and annotation
+            default = action.default if action.default != argparse.SUPPRESS else None
+            annotation = action.type if action.type else Any
+
+            # Create the parameter
+            param = inspect.Parameter(
+                action.dest,
+                kind=kind,
+                default=default,
+                annotation=annotation
+            )
+            parameters.append(param)
+
+            if isFirst:
+                docstring = 'Args:\n'
+                isFirst = False
+
+            param_type = annotation.__name__ if hasattr(annotation, "__name__") else "Any"
+            help_text = f"{action.help or 'No description'}"
+            docstring += f"\t{action.dest} ({param_type}): {help_text}\n"
+            if default is not None:
+                docstring += f"\t\tDefault is {default}.\n"
+
+        # Return a custom Signature object
+        sig = inspect.Signature(parameters)
+        return sig, docstring
+
+    def import_cli_functions(self) -> None:
+        """
+        Dynamically import functions from vast.py and bind them as instance methods.
+
+        Iterates through all subparsers in the CLI argument parser and creates
+        wrapper methods for each command. The wrapper handles argument validation,
+        stdout capture, and hook execution.
+
+        This is called automatically during __init__ and populates the
+        imported_methods dict with argument metadata for each command.
+        """
+        if hasattr(parser, "subparsers_") and parser.subparsers_:
+            for name, subparser in parser.subparsers_.choices.items():
+                if name == "help":
+                    continue
+                if hasattr(subparser, "default") and callable(subparser.default):
+                    func = subparser.default
+                elif hasattr(subparser, "_defaults") and "func" in subparser._defaults:
+                    func = subparser._defaults["func"]
+                else:
+                    print(
+                        f"Command {subparser.prog} does not have an associated function."
+                    )
+                    continue
+
+                func_name = func.__name__.replace("__", "_")
+                wrapped_func = self.create_wrapper(func, func_name)
+                setattr(self, func_name, types.MethodType(wrapped_func, self))
+                arg_details = {}
+                if hasattr(subparser, "_actions"):
+                    for action in subparser._actions:
+                        if action.dest != "help" and hasattr(action, "option_strings"):
+                            arg_details[action.dest] = {
+                                "option_strings": action.option_strings,
+                                "help": action.help,
+                                "default": action.default,
+                                "type": str(action.type) if action.type else None,
+                                "required": action.default is None and action.required,
+                                "choices": getattr(
+                                    action, "choices", None
+                                ),  # Capture choices
+                            }
+
+                #globals()[func_name] = arg_details
+                self.imported_methods[func_name] = arg_details
+        else:
+            print("No subparsers have been configured.")
+
+    def create_wrapper(
+        self, func: Callable[..., Any], method_name: str
+    ) -> Callable[..., Any]:
+        """
+        Create a wrapper function for a CLI command.
+
+        The wrapper handles:
+        - Required argument validation
+        - Choice validation for enum-like arguments
+        - Default value injection from argparse
+        - SDK-level defaults (api_key, server_url, etc.)
+        - Pre/post hooks for query transformation
+        - Stdout capture in raw mode
+        - SystemExit handling for CLI functions
+
+        Args:
+            func: The CLI function to wrap (e.g., search__offers).
+            method_name: The SDK method name (e.g., 'search_offers').
+
+        Returns:
+            A wrapper function that can be bound as an instance method.
+        """
+
+        def wrapper(self: "VastAI", **kwargs: Any) -> Any:
+            arg_details = self.imported_methods.get(method_name, {})
+            for arg, details in arg_details.items():
+                if details["required"] and arg not in kwargs:
+                    raise ValueError(f"Missing required argument: {arg}")
+                if (
+                    arg in kwargs
+                    and details.get("choices") is not None
+                    and kwargs[arg] not in details["choices"]
+                ):
+                    raise ValueError(
+                        f"Invalid choice for {arg}: {kwargs[arg]}. Valid options are {details['choices']}"
+                    )
+                kwargs.setdefault(arg, details["default"])
+
+            kwargs.setdefault("api_key", self.api_key)
+            kwargs.setdefault("url", self.server_url)
+            kwargs.setdefault("retry", self.retry)
+            kwargs.setdefault("raw", self.raw)
+            kwargs.setdefault("explain", self.explain)
+            kwargs.setdefault("quiet", self.quiet)
+            kwargs.setdefault("curl", self.curl)
+
+            # if we specified hooks we get that now
+            state: dict[str, bool] | None = None
+            hooks_list = _hooks.get(func.__name__)
+            if hooks_list is not None:
+              pre_hook = hooks_list[0]
+              if pre_hook is not None:
+                state, kwargs = pre_hook(kwargs, self)
+
+            namespace_args: argparse.Namespace = argparse.Namespace(**kwargs)
+            _vast.ARGS = namespace_args  # type: ignore[assignment]
+
+            if logger.isEnabledFor(logging.DEBUG):
+                kwargs_repr = {key: repr(value) for key, value in kwargs.items()}
+                logging.debug(f"Calling {func.__name__} with arguments: kwargs={kwargs_repr}")
+
+            # Setup stdout capture with proper cleanup via finally block
+            out_b = None
+            out_o = None
+            if not logger.isEnabledFor(logging.DEBUG):
+                out_b = io.StringIO()
+                out_o = sys.stdout
+                sys.stdout = out_b
+
+            res: Any = None
+            try:
+                res = func(namespace_args)
+            except SystemExit as e:
+                # CLI functions call sys.exit(); capture exit code as return value
+                if e.code is not None and e.code != 0:
+                    logging.warning(f"CLI function {func.__name__} exited with code {e.code}")
+                res = e.code
+            except Exception as e:
+                logging.warning(f"Error calling {func.__name__}: {e}")
+                res = None
+            finally:
+                # ALWAYS restore stdout, even if unexpected exceptions occur
+                if out_o is not None:
+                    sys.stdout = out_o
+                if out_b is not None:
+                    try:
+                        self.last_output = out_b.getvalue()
+                    finally:
+                        out_b.close()
+
+            hooks_list_post = _hooks.get(func.__name__)
+            if hooks_list_post is not None:
+              post_hook = hooks_list_post[1]
+              if post_hook is not None:
+                res = post_hook(state, res, self)
+
+            if hasattr(res, 'json'):
+               logging.debug(f" └-> {res.json()}")
+               return res.json()
+
+            logging.debug(f" └-> {res}")
+
+            return res
+
+        func_name = func.__name__.replace("__", "_")
+        wrapper.__name__ = func_name
+
+        wrapper.__doc__ = ''
+        hasDoc = False
+        # We don't want to be redundant so we look for help in various places and
+        # if it's not empty after we parse through it then we use it as our
+        # canonical help. So we go in this order:
+        #
+        #   func.__doc__
+        #   sig.epilog
+        #   sig.help
+        #
+
+        if func.__doc__:
+            doc = dedent(re.sub(r'\s(:param|@).*', '', func.__doc__, flags=re.DOTALL)).strip()
+            if doc:
+               hasDoc = True
+               wrapper.__doc__ += f"{doc}\n\n"
+
+        sig = getattr(func, "mysignature", None)
+        sig_help = getattr(func, "mysignature_help", None)
+
+        if sig:
+            wrapper.__signature__, docappend = self.generate_signature_from_argparse(sig)  # type: ignore[attr-defined]
+
+            # append epilog if exists
+            if getattr(sig, "epilog", None):
+                wrapper.__doc__ = f"{wrapper.__doc__.rstrip()}\n\n{sig.epilog.strip()}\n"
+
+            # if no epilog or func docstring, fall back to parser help text
+            elif sig_help and not hasDoc:
+                wrapper.__doc__ += f"\n\n{sig_help}"
+
+            # finally append the arg details
+            wrapper.__doc__ = f"{wrapper.__doc__.rstrip()}\n\n{docappend}"
+
+        return wrapper
+
+    def credentials_on_disk(self) -> None:
+        """
+        No-operation method for credential validation.
+
+        This method exists to ensure library compatibility and verify that
+        API key file handling doesn't cause crashes. It performs no action.
+
+        Note:
+            This is a stub method that may be overridden by subclasses
+            for actual credential validation.
+        """
+        pass
+
+    def __getattr__(self, name: str) -> Any:
+        """
+        Handle attribute access for dynamically imported methods.
+
+        Provides a fallback for attribute lookup that checks imported_methods
+        before raising AttributeError.
+
+        Args:
+            name: The attribute name being accessed.
+
+        Returns:
+            The requested attribute if found in imported_methods.
+
+        Raises:
+            AttributeError: If the attribute is not found.
+        """
+        if name in self.imported_methods:
+            return getattr(self, name)
+        raise AttributeError(f"{type(self).__name__} has no attribute {name}")
diff --git a/vastai/serverless/__init__.py b/vastai/serverless/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/vastai/serverless/client/__init__.py b/vastai/serverless/client/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/vastai/serverless/client/client.py b/vastai/serverless/client/client.py
new file mode 100644
index 00000000..f81bbc43
--- /dev/null
+++ b/vastai/serverless/client/client.py
@@ -0,0 +1,326 @@
+from .connection import _make_request
+from .endpoint import Endpoint
+from .worker import Worker
+import asyncio
+import aiohttp
+import ssl
+import os
+import tempfile
+import logging
+import random
+import time
+import collections
+from typing import Any, Awaitable, Callable, Deque, Dict, Optional, Union, List
+
+class ServerlessRequest(asyncio.Future):
+    """A request to a Serverless endpoint managed by the client"""
+    def __init__(self):
+        super().__init__()
+        self.status = "New"
+        self.create_time = time.time()
+        self.start_time = None
+        self.complete_time = None
+        self.req_idx = 0
+
+    def then(self, callback) -> "ServerlessRequest":
+        def _done(fut):
+            if fut.exception() is not None:
+                print(fut.exception())
+                return
+            callback(fut.result())
+        self.add_done_callback(_done)
+        return self
+
+class Serverless:
+    SSL_CERT_URL        = "https://console.vast.ai/static/jvastai_root.cer"
+    VAST_WEB_URL        = "https://console.vast.ai"
+    VAST_SERVERLESS_URL = "https://run.vast.ai"
+
+    def __init__(
+        self,
+        api_key: Optional[str] = os.environ.get("VAST_API_KEY", None),
+        *,
+        debug: bool = False,
+        instance: str = "prod",
+        connection_limit: int = 500,
+        default_request_timeout: float = 600.0,
+        max_poll_interval: float = 15.0
+    ):
+        if api_key is None or api_key == "":
+            raise AttributeError("API key missing. Please set VAST_API_KEY in your environment variables.")
+        self.api_key = api_key
+
+        match instance:
+            case "prod":
+                self.autoscaler_url = "https://run.vast.ai"
+            case "alpha":
+                self.autoscaler_url = "https://run-alpha.vast.ai"
+            case "local":
+                self.autoscaler_url = "http://localhost:8080"
+            case _:
+                self.autoscaler_url = "https://run.vast.ai"
+
+        self.latencies = collections.deque(maxlen=50)
+        self.debug = debug
+        self.default_request_timeout = float(default_request_timeout)
+        self.max_poll_interval = float(max_poll_interval)
+        self.logger = logging.getLogger(self.__class__.__name__)
+
+        if self.debug:
+            # Only set up logging if debug is True
+            handler = logging.StreamHandler()
+            formatter = logging.Formatter(
+                '[%(asctime)s] %(name)s - %(levelname)s - %(message)s'
+            )
+            handler.setFormatter(formatter)
+            self.logger.addHandler(handler)
+            self.logger.setLevel(logging.DEBUG)
+        else:
+            # If debug is False, disable logging
+            self.logger.addHandler(logging.NullHandler())
+        self.logger.propagate = False
+
+        self.connection_limit = connection_limit
+        self._session: aiohttp.ClientSession | None = None
+        self._ssl_context: ssl.SSLContext | None = None
+
+    async def __aenter__(self):
+        await self._get_session()
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        await self.close()
+
+    async def _get_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self.logger.info("Started aiohttp ClientSession")
+            connector = aiohttp.TCPConnector(limit=self.connection_limit, ssl= await self.get_ssl_context())
+            self._session = aiohttp.ClientSession(connector=connector)
+        return self._session
+    
+    def is_open(self):
+        return self._session is not None and not self._session.closed
+
+    async def close(self):
+        if self._session and not self._session.closed:
+            await self._session.close()
+            self.logger.info("Closed aiohttp ClientSession")
+
+    async def get_ssl_context(self) -> ssl.SSLContext:
+        """Download Vast.ai root cert and build SSL context (cached)."""
+        if self._ssl_context is None:
+            # Download the Vast root cert
+            async with aiohttp.ClientSession() as s:
+                async with s.get(self.SSL_CERT_URL) as resp:
+                    if resp.status != 200:
+                        raise Exception(f"Failed to fetch SSL cert: {resp.status}")
+                    cert_bytes = await resp.read()
+
+            # Write to a temporary PEM file
+            tmpfile = tempfile.NamedTemporaryFile(delete=False, suffix=".cer")
+            tmpfile.write(cert_bytes)
+            tmpfile.close()
+
+            try:
+                # Start with system defaults
+                ctx = ssl.create_default_context()
+                ctx.load_verify_locations(cafile=tmpfile.name)
+                self.logger.info("Loaded Vast.ai SSL certificate")
+                self._ssl_context = ctx
+            finally:
+                os.unlink(tmpfile.name)
+
+        return self._ssl_context
+
+    def get_avg_request_time(self) -> float:
+        """
+        Rolling estimate for routing timeout. A small safety margin is added.
+        Currently unused. default to 60.0
+        """
+        return 60.0
+        if len(self.latencies) < 10:
+            return 30.0  # conservative default until we have data
+        avg = sum(self.latencies) / len(self.latencies)
+        # Clamp to reasonable bounds
+        return float(max(5.0, min(avg + 2.0, 600.0)))
+
+    async def get_endpoint(self, name="") -> Endpoint:
+        endpoints = await self.get_endpoints()
+        for e in endpoints:
+            if e.name == name:
+                return e
+        raise Exception(f"Endpoint {name} could not be found")
+
+    async def get_endpoints(self) -> list[Endpoint]:
+        try:
+            response = await _make_request(
+                client=self,
+                url=self.VAST_WEB_URL,
+                route="/api/v0/endptjobs/",
+                api_key=self.api_key,
+                params={"client_id": "me"}
+            )
+        except Exception as ex:
+            raise Exception(
+                f"Failed to get endpoints:\nReason={ex}"
+            )
+        endpoints = []
+        for e in response["results"]:
+            endpoints.append(Endpoint(client=self, name=e["endpoint_name"], id=e["id"], api_key=e["api_key"]))
+        self.logger.info(f"Found {len(endpoints)} endpoints")
+        return endpoints
+    
+    async def get_endpoint_workers(self, endpoint: Endpoint) -> List[Worker]:
+        """
+        Equivalent to:
+          curl -X POST https://run.vast.ai/get_endpoint_workers/ \
+               -H "Content-Type: application/json" \
+               -d '{"id": <endpoint_id>, "api_key": "<VAST_API_KEY>"}'
+        """
+        if not isinstance(endpoint, Endpoint):
+            raise ValueError("endpoint must be an Endpoint")
+
+        url = f"{self.autoscaler_url}/get_endpoint_workers/"
+        payload = {"id": endpoint.id, "api_key": self.api_key}
+
+        async with self._session.post(url, json=payload, timeout=aiohttp.ClientTimeout(total=30)) as resp:
+            if resp.status != 200:
+                text = await resp.text()
+                raise RuntimeError(f"get_endpoint_workers failed: HTTP {resp.status} - {text}")
+
+            data = await resp.json(content_type=None)
+
+            # If error message from authenticate_endpoint_apikey_by_id occurs, there is a possibility that
+            # the endpoint's worker instances are not ready to be queried. If an error message occurs,
+            # return an empty list and print the error message to the user. The endpoint get_endpoint_workers
+            # should normally return a list of dictionaries containing worker instance information.
+            if isinstance(data,dict):
+                if 'error_msg' in data.keys():
+                    self.logger.warning(f"Received the following error from get_endpoint_workers:{data['error_msg']}.\nEndpoint may not be ready for query. Check credentials or wait a few minutes and try again.")
+                    return []
+
+            
+            if not isinstance(data, list):
+                raise RuntimeError(f"Unexpected response type (wanted list): {type(data)}")
+
+            return [Worker.from_dict(item) for item in data]
+
+    def queue_endpoint_request(
+        self,
+        endpoint: Endpoint,
+        worker_route: str,
+        worker_payload: dict,
+        serverless_request: Optional[ServerlessRequest] = None,
+        cost: int = 100,
+        max_wait_time: Optional[float] = None,
+        retry: bool = True,
+        max_retries: int = None,
+        stream: bool = False
+    ) -> ServerlessRequest:
+        """Return a Future that will resolve once the request completes."""
+        if serverless_request is None:
+            serverless_request = ServerlessRequest()
+
+        async def task(request: ServerlessRequest):
+            request_idx: int = 0
+            total_attempts = 0
+            try:
+                while True:
+                    total_attempts += 1
+                    request.status = "Queued"
+                    self.logger.debug("Sending initial route call")
+
+                    route = await endpoint._route(cost=cost, req_idx=request_idx, timeout=self.get_avg_request_time())
+                    request_idx = route.request_idx
+                    if (request_idx):
+                        self.logger.debug(f"Got initial request index {request_idx}")
+                    else:
+                        self.logger.error("Did not get request_idx from initial route")
+
+                    poll_interval = 1
+                    elapsed_time = 0
+                    attempt = 0
+                    while route.status != "READY":
+                        request.status = "Polling"
+                        if max_wait_time is not None and elapsed_time >= max_wait_time:
+                            raise asyncio.TimeoutError("Timed out waiting for worker to become ready")
+
+                        await asyncio.sleep(poll_interval)
+                        elapsed_time += poll_interval
+
+                        route = await endpoint._route(cost=cost, req_idx=request_idx, timeout=self.get_avg_request_time())
+                        request_idx = route.request_idx or request_idx
+
+                        # exponential backoff + jitter (cap)
+                        attempt += 1
+                        poll_interval = min((2 ** attempt) + random.uniform(0, 1), self.max_poll_interval)
+                        self.logger.debug("Polling route...")
+
+                    # Now, route is ready for sending request to worker
+                    worker_url = route.get_url()
+                    auth_data = route.body
+                    payload = worker_payload
+                    worker_request_body = {
+                                            "auth_data" : auth_data,
+                                            "payload" : payload
+                                        }
+                    
+                    try:
+                        self.logger.debug("Found worker machine, starting work")
+                        if request.status != "Retrying":
+                            request.status = "In Progress"
+                            request.start_time = time.time()
+                        worker_response = await _make_request(
+                            client=self,
+                            url=worker_url,
+                            route=worker_route,
+                            api_key=endpoint.api_key,
+                            body=worker_request_body,
+                            method="POST",
+                            retries=1,
+                            timeout=600,
+                            stream=stream
+                        )
+                    except Exception as ex:
+                        if retry and (max_retries is None or total_attempts < max_retries):
+                            request.status = "Retrying"
+                            await asyncio.sleep(min((2 ** total_attempts) + random.uniform(0, 1), self.max_poll_interval))
+                            continue
+                        raise
+
+                    # Resolve future, task complete 
+                    request.status = "Complete"
+                    request.complete_time = time.time()
+                    self.latencies.append(request.complete_time - request.start_time)
+                    self.logger.info("Endpoint request task completed")
+
+                    response = {
+                        "response" : worker_response,
+                        "latency" : request.complete_time - request.start_time,
+                        "url" : worker_url,
+                        "request_idx" : request_idx
+                    }
+                    request.set_result(response)
+                    return
+
+            except asyncio.CancelledError:
+                request.status = "Cancelled"
+                request.set_exception(asyncio.CancelledError())
+                return
+            except Exception as ex:
+                request.status = "Errored"
+                # Fail the future so awaiters / then().catch() are notified
+                request.set_exception(ex)
+                self.logger.error(f"Request errored: {ex}")
+                return
+
+        # Create asyncio task for request lifetime management
+        bg_task = asyncio.create_task(task(serverless_request))
+
+        def _propagate_cancel(fut: ServerlessRequest):
+            if fut.cancelled():
+                bg_task.cancel()
+
+        serverless_request.add_done_callback(_propagate_cancel)
+        self.logger.info("Queued endpoint request")
+        return serverless_request
\ No newline at end of file
diff --git a/vastai/serverless/client/connection.py b/vastai/serverless/client/connection.py
new file mode 100644
index 00000000..3913cef0
--- /dev/null
+++ b/vastai/serverless/client/connection.py
@@ -0,0 +1,197 @@
+import aiohttp
+import asyncio
+import random
+import json
+from typing import AsyncIterator, Dict, Optional, Union
+
+_JITTER_CAP_SECONDS = 5.0
+
+def _retryable(status: int) -> bool:
+    return status in (408, 429) or (500 <= status < 600)
+
+def _backoff_delay(attempt: int) -> float:
+    # capped exponential backoff with jitter
+    return min((2 ** attempt) + random.uniform(0, 1), _JITTER_CAP_SECONDS)
+
+def _build_kwargs(
+    *,
+    headers: Dict[str, str],
+    params: Dict[str, str],
+    ssl_context,
+    timeout: Optional[float],
+    body: Optional[dict],
+    method: str,
+    stream: bool,
+) -> Dict:
+    return {
+        "headers": headers,
+        "params": params,
+        "ssl": ssl_context,
+        "timeout": aiohttp.ClientTimeout(total=None if stream else timeout),
+        **({"json": body} if method != "GET" and body else {}),
+    }
+
+async def _iter_sse_json(resp: aiohttp.ClientResponse) -> AsyncIterator[dict]:
+    """
+    Yield JSON objects from an SSE/text stream. Accepts lines starting with 'data:' or raw JSONL.
+    """
+    buffer = b""
+    async for chunk in resp.content.iter_any():
+        if not chunk:
+            continue
+        buffer += chunk
+        while b"\n" in buffer:
+            line, buffer = buffer.split(b"\n", 1)
+            line = line.strip()
+            if not line:
+                continue
+            if line.startswith(b"data:"):
+                line = line[5:].strip()
+            try:
+                yield json.loads(line.decode("utf-8"))
+            except Exception:
+                # Ignore keepalives/bad fragments
+                continue
+
+    # flush tail if present
+    tail = buffer.strip()
+    if tail:
+        try:
+            yield json.loads(tail.decode("utf-8"))
+        except Exception:
+            pass
+
+async def _open_once(
+    *,
+    session: aiohttp.ClientSession,
+    method: str,
+    url: str,
+    route: str,
+    kwargs: Dict,
+):
+    """
+    Execute one HTTP attempt and return the aiohttp response object.
+    Caller is responsible for reading/closing via 'async with'.
+    """
+    request_fn = session.get if method == "GET" else session.post
+    return request_fn(url + route, **kwargs)
+
+async def _make_request(
+    client,
+    route: str,
+    api_key: str,
+    url: str = "",
+    body: Optional[dict] = None,
+    params: Optional[dict] = None,
+    method: str = "GET",
+    retries: int = 5,
+    timeout: float = 30,
+    stream: bool = False,
+) -> Union[dict, AsyncIterator[dict]]:
+    """
+    Make an HTTP request with capped exponential backoff + jitter.
+
+    - On success (non-stream): returns parsed JSON (dict/list).
+    - On success (stream=True): returns an async iterator yielding parsed JSON objects.
+    - Raises Exception with last status/text after exhausting retries.
+    """
+    method = method.upper()
+    body = body or {}
+    # copy so we don't mutate caller's dict
+    params = {**(params or {})}
+    params["api_key"] = api_key
+
+    headers = {"Authorization": f"Bearer {api_key}"}
+
+    session = await client._get_session()
+    ssl_context = await client.get_ssl_context() if client else None
+
+    last_text = ""
+    last_status = None
+
+    if stream:
+        async def _stream_gen() -> AsyncIterator[dict]:
+            nonlocal last_text, last_status
+            for attempt in range(1, retries + 1):
+                try:
+                    kwargs = _build_kwargs(
+                        headers=headers,
+                        params=params,
+                        ssl_context=ssl_context,
+                        timeout=timeout,
+                        body=body,
+                        method=method,
+                        stream=True,
+                    )
+                    async with await _open_once(
+                        session=session,
+                        method=method,
+                        url=url,
+                        route=route,
+                        kwargs=kwargs,
+                    ) as resp:
+                        last_status = resp.status
+                        if resp.status != 200:
+                            text = await resp.text()
+                            last_text = text
+                            if not _retryable(resp.status) or attempt == retries:
+                                raise Exception(f"HTTP {resp.status} from {url + route}: {text}")
+                            await asyncio.sleep(_backoff_delay(attempt))
+                            continue
+
+                        async for obj in _iter_sse_json(resp):
+                            yield obj
+
+                        return
+
+                except Exception as ex:
+                    client.logger.error(f"Stream attempt {attempt} failed: {ex}")
+                    if attempt == retries:
+                        raise
+                    await asyncio.sleep(_backoff_delay(attempt))
+
+        return _stream_gen()
+
+    # Non-streaming path
+    for attempt in range(1, retries + 1):
+        try:
+            kwargs = _build_kwargs(
+                headers=headers,
+                params=params,
+                ssl_context=ssl_context,
+                timeout=timeout,
+                body=body,
+                method=method,
+                stream=False,
+            )
+            async with await _open_once(
+                session=session,
+                method=method,
+                url=url,
+                route=route,
+                kwargs=kwargs,
+            ) as resp:
+                last_status = resp.status
+                text = await resp.text()
+                last_text = text
+
+                if resp.status == 200:
+                    try:
+                        return await resp.json(content_type=None)
+                    except Exception:
+                        raise Exception(f"Invalid JSON from {url + route}:\n{text}")
+
+                if not _retryable(resp.status):
+                    raise Exception(f"HTTP {resp.status} from {url + route}: {text}")
+
+                await asyncio.sleep(_backoff_delay(attempt))
+
+        except Exception as ex:
+            client.logger.error(f"Attempt {attempt} failed: {ex}")
+            if attempt == retries:
+                break
+            await asyncio.sleep(_backoff_delay(attempt))
+
+    raise Exception(
+        f"Too many retries for {url + route} (last_status={last_status}, last_text={last_text[:256]!r})"
+    )
diff --git a/vastai/serverless/client/endpoint.py b/vastai/serverless/client/endpoint.py
new file mode 100644
index 00000000..5beed4fc
--- /dev/null
+++ b/vastai/serverless/client/endpoint.py
@@ -0,0 +1,82 @@
+from .connection import _make_request
+
+class Endpoint:
+    name: str
+    id: int
+
+    def __repr__(self):
+        return f"<Endpoint {self.name} (id={self.id})>"
+
+    def __init__(self, client, name, id, api_key):
+        if client is None:
+            raise ValueError("Endpoint cannot be created without client reference")
+        if not name:
+            raise ValueError("Endpoint name cannot be empty")
+        if id is None:
+            raise ValueError("Endpoint id cannot be empty")
+        self.client = client
+        self.name = name
+        self.id = id
+        self.api_key = api_key
+
+    def request(self, route, payload, serverless_request=None, cost: int = 100, retry: bool = True, stream: bool = False):
+        """Forward requests to the parent client."""
+        return self.client.queue_endpoint_request(
+            endpoint=self,
+            worker_route=route,
+            worker_payload=payload,
+            serverless_request=serverless_request,
+            cost=cost,
+            retry=retry,
+            stream=stream
+        )
+
+    
+    def get_workers(self):
+        return self.client.get_endpoint_workers(self)
+
+    async def _route(self, cost: float = 0.0, req_idx: int = 0, timeout: float = 60.0):
+            if self.client is None or not self.client.is_open():
+                raise ValueError("Client is invalid")
+            try:
+                response = await _make_request(
+                    client=self.client,
+                    url=self.client.autoscaler_url,
+                    route="/route/",
+                    api_key=self.api_key,
+                    body={
+                        "endpoint": self.name,
+                        "api_key": self.api_key,
+                        "cost": cost,
+                        "request_idx": req_idx,
+                        "replay_timeout": timeout,
+                    },
+                    method="POST",
+                    timeout=max(10.0, timeout),
+                )
+            except Exception as ex:
+                raise RuntimeError(f"Failed to route endpoint: {ex}") from ex
+            return RouteResponse(response)
+    
+class RouteResponse:
+    status: str
+    body: dict
+    request_idx: int
+    def __repr__(self):
+        return f"<RouteResponse status={self.status}>"
+
+    def __init__(self, body: dict):
+        if "request_idx" in body.keys():
+            self.request_idx = body.get("request_idx")
+        else:
+            self.request_idx = 0
+        if "url" in body.keys():
+            self.status = "READY"
+            self.body = body
+        else:
+            self.status = "WAITING"
+            self.body = body
+            
+    def get_url(self):
+        return self.body.get("url")
+        
\ No newline at end of file
diff --git a/vastai/serverless/client/worker.py b/vastai/serverless/client/worker.py
new file mode 100644
index 00000000..37688ea1
--- /dev/null
+++ b/vastai/serverless/client/worker.py
@@ -0,0 +1,41 @@
+from dataclasses import dataclass
+from typing import Any, Dict, List, Tuple, Optional
+
+@dataclass
+class Worker:
+    id: int
+    status: str
+    cur_load: float
+    new_load: float
+    cur_load_rolling_avg: float
+    cur_perf: float
+    perf: float
+    measured_perf: float
+    dlperf: float
+    reliability: float
+    reqs_working: int
+    disk_usage: float
+    loaded_at: float
+    started_at: float
+
+    @staticmethod
+    def from_dict(d: Dict[str, Any]) -> "Worker":
+        # Be resilient to missing / extra fields
+        status = d.get("status") or "UNKNOWN"
+
+        return Worker(
+            id=int(d.get("id")),
+            status=status,
+            cur_load=float(d.get("cur_load", 0.0)),
+            new_load=float(d.get("new_load", 0.0)),
+            cur_load_rolling_avg=float(d.get("cur_load_rolling_avg", 0.0)),
+            cur_perf=float(d.get("cur_perf", 0.0)),
+            perf=float(d.get("perf", 0.0)),
+            measured_perf=float(d.get("measured_perf", 0.0)),
+            dlperf=float(d.get("dlperf", 0.0)),
+            reliability=float(d.get("reliability", 0.0)),
+            reqs_working=int(d.get("reqs_working", 0)),
+            disk_usage=float(d.get("disk_usage", 0.0)),
+            loaded_at=float(d.get("loaded_at", 0.0)),
+            started_at=float(d.get("started_at", 0.0)),
+        )
diff --git a/vastai/serverless/server/__init__.py b/vastai/serverless/server/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/vastai/serverless/server/lib/__init__.py b/vastai/serverless/server/lib/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/vastai/serverless/server/lib/backend.py b/vastai/serverless/server/lib/backend.py
new file mode 100644
index 00000000..73102c32
--- /dev/null
+++ b/vastai/serverless/server/lib/backend.py
@@ -0,0 +1,514 @@
+import os
+import json
+import time
+import base64
+import dataclasses
+import logging
+from asyncio import wait, sleep, gather, Semaphore, FIRST_COMPLETED, create_task
+from typing import Tuple, Awaitable, NoReturn, List, Union, Callable, Optional
+from functools import cached_property
+from distutils.util import strtobool
+from collections import deque
+from asyncio import sleep, CancelledError
+
+from anyio import open_file
+from aiohttp import web, ClientResponse, ClientSession, ClientConnectorError, ClientTimeout, TCPConnector
+import asyncio
+
+import requests
+from Crypto.Signature import pkcs1_15
+from Crypto.Hash import SHA256
+from Crypto.PublicKey import RSA
+
+from .metrics import Metrics
+from .data_types import (
+    AuthData,
+    EndpointHandler,
+    LogAction,
+    ApiPayload_T,
+    JsonDataException,
+    RequestMetrics,
+    BenchmarkResult
+)
+
+VERSION = "1.0.0"
+
+MSG_HISTORY_LEN = 100
+log = logging.getLogger(__file__)
+
+# defines the minimum wait time between sending updates to autoscaler
+LOG_POLL_INTERVAL = 0.1
+BENCHMARK_INDICATOR_FILE = ".has_benchmark"
+MAX_PUBKEY_FETCH_ATTEMPTS = 3
+
+
+@dataclasses.dataclass
+class Backend:
+    """
+    This class is responsible for:
+    1. Tailing logs and updating load time metrics
+    2. Taking an EndpointHandler alongside incoming payload, preparing a json to be sent to the model, and
+    sending the request. It also updates metrics as it makes those requests.
+    3. Running a benchmark from an EndpointHandler
+    """
+
+    model_server_url: str
+    model_log_file: str
+    benchmark_handler: (
+        EndpointHandler  # this endpoint handler will be used for benchmarking
+    )
+    log_actions: List[Tuple[LogAction, str]]
+    reqnum = -1
+    version = VERSION
+    msg_history = []
+    sem: Semaphore = dataclasses.field(default_factory=Semaphore)
+    queue: deque = dataclasses.field(default_factory=deque, repr=False)
+    unsecured: bool = dataclasses.field(
+        default_factory=lambda: bool(strtobool(os.environ.get("UNSECURED", "false"))),
+    )
+    report_addr: str = dataclasses.field(
+        default_factory=lambda: os.environ.get("REPORT_ADDR", "https://run.vast.ai")
+    )
+    mtoken: str = dataclasses.field(
+        default_factory=lambda: os.environ.get("MASTER_TOKEN", "")
+    )
+    healthcheck_url: str = dataclasses.field(
+        default_factory=lambda: os.environ.get("MODEL_HEALTH_ENDPOINT", "")
+    )
+
+    def __post_init__(self):
+        self.metrics = Metrics()
+        self.metrics._set_version(self.version)
+        self.metrics._set_mtoken(self.mtoken)
+        self._total_pubkey_fetch_errors = 0
+        self._pubkey = self._fetch_pubkey()
+        self.__start_healthcheck: bool = False
+
+    @property
+    def pubkey(self) -> Optional[RSA.RsaKey]:
+        if self._pubkey is None:
+            self._pubkey = self._fetch_pubkey()
+        return self._pubkey
+
+    @cached_property
+    def session(self):
+        log.debug(f"Starting TCP session with model server at {self.model_server_url}")
+        connector = TCPConnector(
+            force_close=True, # Required for long running jobs
+            enable_cleanup_closed=True,
+        )
+        
+        timeout = ClientTimeout(total=None)
+        return ClientSession(self.model_server_url, timeout=timeout, connector=connector)
+
+    def create_handler(
+        self,
+        handler: EndpointHandler[ApiPayload_T],
+    ) -> Callable[[web.Request], Awaitable[Union[web.Response, web.StreamResponse]]]:
+        async def handler_fn(
+            request: web.Request,
+        ) -> Union[web.Response, web.StreamResponse]:
+            return await self.__handle_request(handler=handler, request=request)
+
+        return handler_fn
+
+    #######################################Private#######################################
+    def _fetch_pubkey(self) -> Optional[RSA.RsaKey]:
+        """Fetch the serverless public key using HTTP.
+
+        Uses requests library instead of subprocess+curl for better error handling
+        and to avoid shell dependency issues.
+        """
+        report_addr = self.report_addr.rstrip("/")
+        url = f"{report_addr}/pubkey/"
+        try:
+            response = requests.get(url, timeout=30)
+            response.raise_for_status()
+            result = response.text
+            log.debug("Serverless Public Key:")
+            log.debug(result)
+            key = RSA.import_key(result)
+            if key is not None:
+                return key
+        except requests.RequestException as e:
+            log.debug(f"Error downloading key: {e}")
+        except ValueError as e:
+            log.debug(f"Error parsing key: {e}")
+        self.backend_errored("Failed to get Serverless public key")
+        return None
+
+    async def _fetch_pubkey_async(self) -> Optional[RSA.RsaKey]:
+        """Fetch the serverless public key using async HTTP (aiohttp).
+
+        For use in async contexts. Prefer this over _fetch_pubkey when running
+        in an async event loop.
+        """
+        report_addr = self.report_addr.rstrip("/")
+        url = f"{report_addr}/pubkey/"
+        try:
+            async with ClientSession() as session:
+                async with session.get(url, timeout=ClientTimeout(total=30)) as response:
+                    if response.status == 200:
+                        result = await response.text()
+                        log.debug("Serverless Public Key:")
+                        log.debug(result)
+                        key = RSA.import_key(result)
+                        if key is not None:
+                            return key
+                    else:
+                        log.debug(f"Failed to fetch pubkey: HTTP {response.status}")
+        except Exception as e:
+            log.debug(f"Error downloading key: {e}")
+        self.backend_errored("Failed to get Serverless public key")
+        return None
+       
+
+    async def __handle_request(
+        self,
+        handler: EndpointHandler[ApiPayload_T],
+        request: web.Request,
+    ) -> Union[web.Response, web.StreamResponse]:
+        """use this function to forward requests to the model endpoint"""
+        try:
+            data = await request.json()
+            auth_data, payload = handler.get_data_from_request(data)
+        except JsonDataException as e:
+            return web.json_response(data=e.message, status=422)
+        except json.JSONDecodeError:
+            return web.json_response(dict(error="invalid JSON"), status=422)
+        workload = payload.count_workload()
+        request_metrics: RequestMetrics = RequestMetrics(request_idx=auth_data.request_idx, reqnum=auth_data.reqnum, workload=workload, status="Created")
+
+
+        def advance_queue_after_completion(event: asyncio.Event):
+            """Pop current head and wake next waiter, if any."""
+            # If this event is current head, wake next waiter
+            if self.queue and self.queue[0] is event:
+                self.queue.popleft()
+                if self.queue:
+                    self.queue[0].set()
+            else:
+                # Else, remove it from the queue
+                try:
+                    self.queue.remove(event)
+                except ValueError:
+                    pass
+
+        async def cancel_api_call_if_disconnected() -> None:
+            await request.wait_for_disconnection()
+            self.metrics._request_canceled(request_metrics)
+            return
+
+        async def make_request() -> Union[web.Response, web.StreamResponse]:
+            try:
+                response = await self.__call_api(handler=handler, payload=payload)
+                res = await handler.generate_client_response(request, response)
+                self.metrics._request_success(request_metrics)
+                return res
+            except asyncio.CancelledError:
+                raise
+            except Exception as e:
+                self.metrics._request_errored(request_metrics, str(e))
+                return web.Response(status=500)
+
+        ###########
+
+        if self.__check_signature(auth_data) is False:
+            self.metrics._request_reject(request_metrics)
+            return web.Response(status=401)
+        
+        if self.metrics.model_metrics.wait_time > handler.max_queue_time:
+            self.metrics._request_reject(request_metrics)
+            return web.Response(status=429)
+
+        disconnect_task = create_task(cancel_api_call_if_disconnected())
+        next_request_task = None
+        work_task = None
+        event = asyncio.Event() # Used in finally block, so initialize here
+
+        self.metrics._request_start(request_metrics)
+
+        try:
+            if handler.allow_parallel_requests:
+                work_task = create_task(make_request())
+                done, pending = await wait([work_task, disconnect_task], return_when=FIRST_COMPLETED)
+
+                for t in pending:
+                    t.cancel()
+                await asyncio.gather(*pending, return_exceptions=True)
+
+                if disconnect_task in done:
+                    return web.Response(status=499)
+
+                # otherwise work_task completed
+                return await work_task
+            
+            # FIFO-queue branch
+            else:
+                # Insert a Event into the queue for this request
+                # Event.set() == our request is up next
+                self.queue.append(event)
+                if self.queue and self.queue[0] is event:
+                    event.set()
+
+                # Race between our request being next and request being cancelled
+                next_request_task = create_task(event.wait())
+                first_done, first_pending = await wait(
+                    [next_request_task, disconnect_task], return_when=FIRST_COMPLETED
+                )
+
+                # If the disconnect task wins the race
+                if disconnect_task in first_done:
+                    # Clean up the next_request_task, then exit
+                    for t in first_pending:
+                        t.cancel()
+                    await asyncio.gather(*first_pending, return_exceptions=True)
+                    return web.Response(status=499)
+
+                # We are the next-up request in the queue
+                log.debug(f"Starting work on request {request_metrics.reqnum}")
+
+                # Race the backend API call with the disconnect task
+                work_task = create_task(make_request())
+
+                done, pending = await wait([work_task, disconnect_task], return_when=FIRST_COMPLETED)
+                for t in pending:
+                    t.cancel()
+                await asyncio.gather(*pending, return_exceptions=True)
+
+                if disconnect_task in done:
+                    return web.Response(status=499)
+
+                # otherwise work_task completed
+                return await work_task
+            
+        except asyncio.CancelledError:
+            return web.Response(status=499)
+        
+        except Exception as e:
+            log.debug(f"Exception in main handler loop {e}")
+            return web.Response(status=500)
+        
+        finally:
+            if not handler.allow_parallel_requests:
+                advance_queue_after_completion(event)
+
+            self.metrics._request_end(request_metrics)
+            cleanup_tasks = [t for t in (next_request_task, work_task, disconnect_task) if t]
+            for t in cleanup_tasks:
+                if not t.done():
+                    t.cancel()
+            if cleanup_tasks:
+                await asyncio.gather(*cleanup_tasks, return_exceptions=True)
+
+    async def __healthcheck(self) -> None:
+        """
+        Periodically hit the healthcheck endpoint using the same session
+        configuration as normal API calls.
+        """
+        health_check_url = self.healthcheck_url
+        if not health_check_url:
+            log.debug("No healthcheck endpoint defined, skipping healthcheck")
+            return
+
+        # Per-request timeout for healthchecks
+        timeout = ClientTimeout(total=10)
+
+        while True:
+            try:
+                await sleep(10)
+
+                if not self.__start_healthcheck:
+                    continue
+
+                log.debug(f"Performing healthcheck on {health_check_url}")
+
+                async with self.session.get(
+                    health_check_url,
+                    timeout=timeout,
+                ) as response:
+                    status = response.status
+
+                    if status == 200:
+                        log.debug("Healthcheck successful")
+                    elif status == 503:
+                        msg = f"Healthcheck failed with status: {status}"
+                        log.debug(msg)
+                        self.backend_errored(msg)
+                    else:
+                        log.debug(f"Healthcheck endpoint not ready: {status}")
+
+            except CancelledError:
+                log.debug("Healthcheck task cancelled; exiting loop")
+                break
+
+            except Exception as e:
+                log.debug(f"Healthcheck failed with exception: {e}")
+                self.backend_errored(str(e))
+
+    async def _start_tracking(self) -> None:
+        await gather(
+            self.__read_logs(), self.metrics._send_metrics_loop(), self.__healthcheck(), self.metrics._send_delete_requests_loop()
+        )
+
+    def backend_errored(self, msg: str) -> None:
+        self.metrics._model_errored(msg)
+
+    async def __call_api(
+        self, handler: EndpointHandler[ApiPayload_T], payload: ApiPayload_T
+    ) -> ClientResponse:
+        api_payload = payload.generate_payload_json()
+        log.debug(f"Posting to '{handler.endpoint}', payload: {api_payload}")
+        return await self.session.post(url=handler.endpoint, json=api_payload)
+
+    def __check_signature(self, auth_data: AuthData) -> bool:
+        if self.unsecured is True:
+            return True
+
+        def verify_signature(message, signature):
+            if self.pubkey is None:
+                log.debug(f"No Public Key!")
+                return False
+
+            h = SHA256.new(message.encode())
+            try:
+                pkcs1_15.new(self.pubkey).verify(h, base64.b64decode(signature))
+                return True
+            except (ValueError, TypeError):
+                return False
+
+        message = {
+            key: value
+            for (key, value) in (dataclasses.asdict(auth_data).items())
+            if key != "signature" and key != "__request_id"
+        }
+        if auth_data.reqnum < (self.reqnum - MSG_HISTORY_LEN):
+            log.error(f"Signature error: reqnum failure, got {auth_data.reqnum}, current_reqnum: {self.reqnum}")
+            return False
+        elif message in self.msg_history:
+            log.error(f"Signature error: message {message} already in message history")
+            return False
+        elif verify_signature(json.dumps(message, indent=4, sort_keys=True), auth_data.signature):
+            self.reqnum = max(auth_data.reqnum, self.reqnum)
+            self.msg_history.append(message)
+            self.msg_history = self.msg_history[-MSG_HISTORY_LEN:]
+            return True
+        else:
+            log.error(f"Signature error: signature verification failed, sig:{auth_data.signature}, message: {message}")
+            return False
+
+    async def __read_logs(self) -> Awaitable[NoReturn]:
+
+        async def run_benchmark() -> float:
+            log.debug("Model load detected")
+            try:
+                with open(BENCHMARK_INDICATOR_FILE, "r") as f:
+                    perf = float(f.readline())
+                    log.debug(f"Already ran benchmark for perf score of {perf}")
+                    return perf
+            except FileNotFoundError:
+                pass
+            log.debug(f"Performing benchmark on endpoint {self.benchmark_handler.endpoint}")
+            log.debug("Initial run to trigger model loading...")
+            payload = self.benchmark_handler.make_benchmark_payload()
+            await self.__call_api(handler=self.benchmark_handler, payload=payload)
+
+            max_throughput = 0
+            sum_throughput = 0
+            concurrent_requests = self.benchmark_handler.concurrency if self.benchmark_handler.allow_parallel_requests else 1
+            for run in range(1, self.benchmark_handler.benchmark_runs + 1):
+                start = time.time()
+                benchmark_requests = []
+
+                for i in range(concurrent_requests):
+                    payload = self.benchmark_handler.make_benchmark_payload()
+                    workload = payload.count_workload()
+                    task = self.__call_api(handler=self.benchmark_handler, payload=payload)
+                    benchmark_requests.append(
+                        BenchmarkResult(request_idx=i, workload=workload, task=task)
+                    )
+
+                responses = await gather(*[br.task for br in benchmark_requests])
+                for br, response in zip(benchmark_requests, responses):
+                    br.response = response
+
+                total_workload = sum(br.workload for br in benchmark_requests if br.is_successful)
+                time_elapsed = time.time() - start
+                successful_responses = sum([1 for br in benchmark_requests if br.is_successful])
+                if successful_responses == 0:
+                    self.backend_errored("No successful responses from benchmark")
+                    log.error(f"Benchmark Failed: No successful responses")
+                    return 0.0
+                throughput = total_workload / time_elapsed
+                sum_throughput += throughput
+                max_throughput = max(max_throughput, throughput)
+
+                # Log results for debugging
+                log.debug(
+                    "\n".join(
+                        [
+                            "#" * 60,
+                            f"Run: {run}, concurrent_requests: {concurrent_requests}",
+                            f"Total workload: {total_workload}, time_elapsed: {time_elapsed}s",
+                            f"Throughput: {throughput} workload/s",
+                            f"Successful responses: {successful_responses}/{concurrent_requests}",
+                            "#" * 60,
+                        ]
+                    )
+                )
+
+            average_throughput = sum_throughput / self.benchmark_handler.benchmark_runs
+            log.debug( f"Benchmark complete: average perf is {average_throughput}, measured perf is {max_throughput}")
+            with open(BENCHMARK_INDICATOR_FILE, "w") as f:
+                f.write(str(max_throughput))
+            return max_throughput
+
+        async def handle_log_line(log_line: str) -> None:
+            """
+            Implement this function to handle each log line for your model.
+            This function should mutate self.system_metrics and self.model_metrics
+            """
+            for action, msg in self.log_actions:
+                match action:
+                    case LogAction.ModelLoaded if msg in log_line:
+                        log.debug(
+                            f"Got log line indicating model is loaded: {log_line}"
+                        )
+                        # some backends need a few seconds after logging successful startup before
+                        # they can begin accepting requests
+                        # await sleep(5)
+                        try:
+                            max_throughput = await run_benchmark()
+                            self.__start_healthcheck = True
+                            self.metrics._model_loaded(
+                                max_throughput=max_throughput,
+                            )
+                        except ClientConnectorError as e:
+                            log.debug(
+                                f"failed to connect to comfyui api during benchmark"
+                            )
+                            self.backend_errored(str(e))
+                    case LogAction.ModelError if msg in log_line:
+                        log.debug(f"Got log line indicating error: {log_line}")
+                        self.backend_errored(msg)
+                        break
+                    case LogAction.Info if msg in log_line:
+                        log.debug(f"Info from model logs: {log_line}")
+
+        async def tail_log():
+            log.debug(f"tailing file: {self.model_log_file}")
+            async with await open_file(self.model_log_file, encoding='utf-8', errors='ignore') as f:
+                while True:
+                    line = await f.readline()
+                    if line:
+                        await handle_log_line(line.rstrip())
+                    else:
+                        await asyncio.sleep(LOG_POLL_INTERVAL)
+
+        ###########
+
+        while True:
+            if os.path.isfile(self.model_log_file) is True:
+                return await tail_log()
+            else:
+                await sleep(1)
diff --git a/vastai/serverless/server/lib/data_types.py b/vastai/serverless/server/lib/data_types.py
new file mode 100644
index 00000000..149e02d1
--- /dev/null
+++ b/vastai/serverless/server/lib/data_types.py
@@ -0,0 +1,328 @@
+import time
+import logging
+from dataclasses import dataclass, field
+from enum import Enum
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Union, Tuple, Optional, Set, TypeVar, Generic, Type, Callable, Awaitable
+from aiohttp import web, ClientResponse
+import inspect
+import random
+import json
+import psutil
+import os
+
+"""
+type variable representing an incoming payload to pyworker that will used to calculate load and will then
+be forwarded to the model
+"""
+
+log = logging.getLogger(__file__)
+
+
+class JsonDataException(Exception):
+    def __init__(self, json_msg: Dict[str, Any]):
+        self.message = json_msg
+
+
+ApiPayload_T = TypeVar("ApiPayload_T", bound="ApiPayload")
+
+
+@dataclass
+class ApiPayload(ABC):
+
+    @classmethod
+    @abstractmethod
+    def for_test(cls: Type[ApiPayload_T]) -> ApiPayload_T:
+        """defines how to create a payload for load testing"""
+        pass
+
+    @abstractmethod
+    def generate_payload_json(self) -> Dict[str, Any]:
+        """defines how to convert an ApiPayload to JSON that will be sent to model API"""
+        pass
+
+    @abstractmethod
+    def count_workload(self) -> float:
+        """defines how to calculate workload for a payload"""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def from_json_msg(
+        cls: Type[ApiPayload_T], json_msg: Dict[str, Any]
+    ) -> ApiPayload_T:
+        """
+        defines how to create an API payload from a JSON message,
+        it should throw an JsonDataException if there are issues with some fields
+        or they are missing in the format of
+        {
+            "field": "error msg"
+        }
+        """
+        pass
+
+
+@dataclass
+class AuthData:
+    """data used to authenticate requester"""
+
+    cost: str
+    endpoint: str
+    reqnum: int
+    request_idx: int
+    signature: str
+    url: str
+
+    @classmethod
+    def from_json_msg(cls, json_msg: Dict[str, Any]):
+        errors = {}
+        for param in inspect.signature(cls).parameters:
+            if param not in json_msg:
+                errors[param] = "missing parameter"
+        if errors:
+            raise JsonDataException(errors)
+        return cls(
+            **{
+                k: v
+                for k, v in json_msg.items()
+                if k in inspect.signature(cls).parameters
+            }
+        )
+
+
+@dataclass
+class EndpointHandler(ABC, Generic[ApiPayload_T]):
+    """
+    Each model endpoint will have a handler responsible for counting workload from the incoming ApiPayload
+    and converting it to json to be forwarded to model API
+    """
+
+    has_benchmark: bool = True
+    concurrency: int = 10
+    benchmark_runs: int = 8
+    allow_parallel_requests: bool = False
+    max_queue_time: float = 30.0
+
+    @property
+    @abstractmethod
+    def endpoint(self) -> str:
+        """the endpoint on the model API"""
+        pass
+
+    @property
+    @abstractmethod
+    def healthcheck_endpoint(self) -> Optional[str]:
+        """the endpoint on the model API that is used for healthchecks"""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def payload_cls(cls) -> Type[ApiPayload_T]:
+        """ApiPayload class"""
+        pass
+
+    @abstractmethod
+    def make_benchmark_payload(self) -> ApiPayload_T:
+        """defines how to create an ApiPayload for benchmarking."""
+        pass
+
+    @abstractmethod
+    async def generate_client_response(
+        self, client_request: web.Request, model_response: ClientResponse
+    ) -> Union[web.Response, web.StreamResponse]:
+        """
+        defines how to convert a model API response to a response to PyWorker client
+        """
+        pass
+
+    @classmethod
+    def get_data_from_request(
+        cls, req_data: Dict[str, Any]
+    ) -> Tuple[AuthData, ApiPayload_T]:
+        errors = {}
+        auth_data: Optional[AuthData] = None
+        payload: Optional[ApiPayload_T] = None
+        try:
+            if "auth_data" in req_data:
+                auth_data = AuthData.from_json_msg(req_data["auth_data"])
+            else:
+                errors["auth_data"] = "field missing"
+        except JsonDataException as e:
+            errors["auth_data"] = e.message
+        try:
+            if "payload" in req_data:
+                payload_cls = cls.payload_cls()
+                payload = payload_cls.from_json_msg(req_data["payload"])
+            else:
+                errors["payload"] = "field missing"
+        except JsonDataException as e:
+            errors["payload"] = e.message
+        if errors:
+            raise JsonDataException(errors)
+        if auth_data and payload:
+            return (auth_data, payload)
+        else:
+            raise Exception("error deserializing request data")
+
+
+@dataclass
+class SystemMetrics:
+    """General system metrics"""
+
+    model_loading_start: float
+    model_loading_time: Union[float, None]
+    last_disk_usage: float
+    additional_disk_usage: float
+    model_is_loaded: bool
+
+    @staticmethod
+    def get_disk_usage_GB():
+        return psutil.disk_usage("/").used / (2**30)  # want units of GB
+
+    @classmethod
+    def empty(cls):
+        return cls(
+            model_loading_start=time.time(),
+            model_loading_time=None,
+            last_disk_usage=SystemMetrics.get_disk_usage_GB(),
+            additional_disk_usage=0.0,
+            model_is_loaded=False,
+        )
+
+    def update_disk_usage(self):
+        disk_usage = SystemMetrics.get_disk_usage_GB()
+        self.additional_disk_usage = disk_usage - self.last_disk_usage
+        self.last_disk_usage = disk_usage
+
+    def reset(self, expected: float | None) -> None:
+        # autoscaler expects model_loading_time to be populated only once, when the instance has
+        # finished benchmarking and is ready to receive requests. This applies to restarted instances
+        # as well: they should send model_loading_time once when they are done loading
+        if self.model_loading_time == expected:
+            self.model_loading_time = None
+
+
+@dataclass
+class RequestMetrics:
+    """Tracks metrics for an active request."""
+    request_idx: int
+    reqnum: int
+    workload: float
+    status: str
+    success: bool = False
+
+@dataclass
+class BenchmarkResult:
+    request_idx: int
+    workload: float
+    task: Awaitable[ClientResponse]
+    response: Optional[ClientResponse] = None
+
+    @property
+    def is_successful(self) -> bool:
+        return self.response is not None and self.response.status == 200
+
+@dataclass
+class ModelMetrics:
+    """Model specific metrics"""
+
+    # these are reset after being sent to autoscaler
+    workload_served: float
+    workload_received: float
+    workload_cancelled: float
+    workload_errored: float
+    workload_rejected: float
+    # these are not
+    workload_pending: float
+    error_msg: Optional[str]
+    max_throughput: float
+    requests_recieved: Set[int] = field(default_factory=set)
+    requests_working: dict[int, RequestMetrics] = field(default_factory=dict)
+    requests_deleting: list[RequestMetrics] = field(default_factory=list)
+    last_update: float = field(default_factory=time.time)
+
+    @classmethod
+    def empty(cls):
+        return cls(
+            workload_pending=0.0,
+            workload_served=0.0,
+            workload_cancelled=0.0,
+            workload_errored=0.0,
+            workload_rejected=0.0,
+            workload_received=0.0,
+            error_msg=None,
+            max_throughput=0.0,
+        )
+    
+    @property
+    def workload_processing(self) -> float:
+        return max(self.workload_received - self.workload_cancelled, 0.0)
+
+    @property
+    def wait_time(self) -> float:
+        if (len(self.requests_working) == 0):
+            return 0.0
+        return sum([request.workload for request in self.requests_working.values()]) / max(self.max_throughput, 0.00001)
+    
+    @property
+    def cur_load(self) -> float:
+        return sum([request.workload for request in self.requests_working.values()])
+
+    @property
+    def working_request_idxs(self) -> list[int]:
+        return [req.request_idx for req in self.requests_working.values()]
+
+    def set_errored(self, error_msg):
+        self.reset()
+        self.error_msg = error_msg
+
+    def reset(self):
+        self.workload_served = 0
+        self.workload_received = 0
+        self.workload_cancelled = 0
+        self.workload_errored = 0
+        self.workload_rejected = 0
+        self.last_update = time.time()
+
+
+@dataclass
+class WorkerStatusData:
+    """Data that is reported to autoscaler's on_status endpoint"""
+
+    id: int
+    mtoken: str
+    version: str
+    loadtime: float
+    cur_load: float
+    rej_load: float
+    new_load: float
+    error_msg: str
+    max_perf: float
+    cur_perf: float
+    cur_capacity: float
+    max_capacity: float
+    num_requests_working: int
+    num_requests_recieved: int
+    additional_disk_usage: float
+    working_request_idxs: list[int]
+    url: str
+
+
+class LogAction(Enum):
+    """
+    These actions tell the backend what a log value means, for example:
+    actions [
+        # this marks the model server as loaded
+        (LogAction.ModelLoaded, "Starting server"),
+        # these mark the model server as errored
+        (LogAction.ModelError, "Exception loading model"),
+        (LogAction.ModelError, "Server failed to bind to port"),
+        # this tells the backend to print any logs containing the string into its own logs
+        # which are visible in the vast console instance logs
+        (LogAction.Info, "Starting model download"),
+    ]
+    """
+
+    ModelLoaded = 1
+    ModelError = 2
+    Info = 3
\ No newline at end of file
diff --git a/vastai/serverless/server/lib/metrics.py b/vastai/serverless/server/lib/metrics.py
new file mode 100644
index 00000000..2909210b
--- /dev/null
+++ b/vastai/serverless/server/lib/metrics.py
@@ -0,0 +1,287 @@
+import os
+import time
+import logging
+import json
+from asyncio import sleep
+from dataclasses import dataclass, asdict, field
+from functools import cache
+import asyncio
+from aiohttp import ClientSession, ClientTimeout, TCPConnector, ClientResponseError
+
+from .data_types import WorkerStatusData, SystemMetrics, ModelMetrics, RequestMetrics
+from typing import Awaitable, NoReturn, List
+
+METRICS_UPDATE_INTERVAL = 1
+DELETE_REQUESTS_INTERVAL = 1
+
+log = logging.getLogger(__file__)
+
+
+@cache
+def get_url() -> str:
+    use_ssl = os.environ.get("USE_SSL", "false") == "true"
+    worker_port = os.environ[f"VAST_TCP_PORT_{os.environ['WORKER_PORT']}"]
+    public_ip = os.environ["PUBLIC_IPADDR"]
+    return f"http{'s' if use_ssl else ''}://{public_ip}:{worker_port}"
+
+
+@dataclass
+class Metrics:
+    version: str = "0"
+    mtoken: str = ""
+    last_metric_update: float = 0.0
+    last_request_served: float = 0.0
+    update_pending: bool = False
+    id: int = field(default_factory=lambda: int(os.environ["CONTAINER_ID"]))
+    report_addr: List[str] = field(
+        default_factory=lambda: os.environ["REPORT_ADDR"].split(",")
+    )
+    url: str = field(default_factory=get_url)
+    system_metrics: SystemMetrics = field(default_factory=SystemMetrics.empty)
+    model_metrics: ModelMetrics = field(default_factory=ModelMetrics.empty)
+    _session: ClientSession | None = field(default=None, init=False, repr=False)
+
+    async def http(self) -> ClientSession:
+        if self._session is None:
+            self._session = ClientSession(
+                timeout=ClientTimeout(total=10),
+                connector=TCPConnector(limit=8, limit_per_host=4, force_close=True, enable_cleanup_closed=True)
+            )
+        return self._session
+    
+    async def aclose(self) -> None:
+        if self._session is not None:
+            await self._session.close()
+            self._session = None
+
+    def _request_start(self, request: RequestMetrics) -> None:
+        """
+        this function is called prior to forwarding a request to a model API.
+        """
+        log.debug(f"Starting request {request.reqnum}")
+        request.status = "Started"
+        self.model_metrics.workload_pending += request.workload
+        self.model_metrics.workload_received += request.workload
+        self.model_metrics.requests_recieved.add(request.reqnum)
+        self.model_metrics.requests_working[request.reqnum] = request
+        self.update_pending = True
+
+    def _request_end(self, request: RequestMetrics) -> None:
+        """
+        this function is called after handling of a request ends, regardless of the outcome
+        """
+        log.debug(f"Ending request {request.reqnum}")
+        self.model_metrics.workload_pending -= request.workload
+        self.model_metrics.requests_working.pop(request.reqnum, None)
+        self.model_metrics.requests_deleting.append(request)
+        self.last_request_served = time.time()
+
+    def _request_success(self, request: RequestMetrics) -> None:
+        """
+        this function is called after a response from model API is received and forwarded.
+        """
+        log.debug(f"Request {request.reqnum} succeeded")
+        self.model_metrics.workload_served += request.workload
+        request.status = "Success"
+        request.success = True
+        self.update_pending = True
+
+    def _request_errored(self, request: RequestMetrics, message: str) -> None:
+        """
+        this function is called if model API returns an error
+        """
+        log.error(f"Request {request.reqnum} errored: {message}")
+        self.model_metrics.workload_errored += request.workload
+        request.status = "Error"
+        request.success = False
+        self.update_pending = True
+
+    def _request_canceled(self, request: RequestMetrics) -> None:
+        """
+        this function is called if client drops connection before model API has responded
+        """
+        log.debug(f"Canceling request {request.reqnum}")
+        self.model_metrics.workload_cancelled += request.workload
+        request.success = True
+        request.status = "Cancelled"
+    
+    def _request_reject(self, request: RequestMetrics):
+        """
+        this function is called if the current wait time for the model is above max_queue_time
+        """
+        self.model_metrics.requests_recieved.add(request.reqnum)
+        self.model_metrics.requests_deleting.append(request)
+        self.model_metrics.workload_rejected += request.workload
+        request.success = False
+        request.status = "Rejected"
+        self.update_pending = True
+
+    async def _send_delete_requests_loop(self) -> Awaitable[NoReturn]:
+        while True:
+            await sleep(DELETE_REQUESTS_INTERVAL)
+            if len(self.model_metrics.requests_deleting) > 0:
+                await self.__send_delete_requests_and_reset()
+
+    async def _send_metrics_loop(self) -> Awaitable[NoReturn]:
+        while True:
+            await sleep(METRICS_UPDATE_INTERVAL)
+            elapsed = time.time() - self.last_metric_update
+            if self.system_metrics.model_is_loaded is False and elapsed >= 10:
+                await self.__send_metrics_and_reset()
+            elif self.update_pending or elapsed > 10:
+                await self.__send_metrics_and_reset()
+
+    def _model_loaded(self, max_throughput: float) -> None:
+        self.system_metrics.model_loading_time = (
+            time.time() - self.system_metrics.model_loading_start
+        )
+        self.system_metrics.model_is_loaded = True
+        self.model_metrics.max_throughput = max_throughput
+
+    def _model_errored(self, error_msg: str) -> None:
+        self.model_metrics.set_errored(error_msg)
+        self.system_metrics.model_is_loaded = True
+
+    def _set_version(self, version: str) -> None:
+        self.version = version
+
+    def _set_mtoken(self, mtoken: str) -> None:
+        self.mtoken = mtoken
+
+    #######################################Private#######################################
+
+    async def __send_delete_requests_and_reset(self):
+        async def post(report_addr: str, idxs: list[int], success_flag: bool) -> bool:
+            data = {
+                "worker_id": self.id,
+                "mtoken": self.mtoken,
+                "request_idxs": idxs,
+                "success": success_flag,
+            }
+            log.debug(
+                f"Deleting requests that {'succeeded' if success_flag else 'failed'}: {data['request_idxs']}"
+            )
+            full_path = report_addr.rstrip("/") + "/delete_requests/"
+            for attempt in range(1, 4):
+                try:
+                    session = await self.http()
+                    async with session.post(full_path, json=data) as res:
+                        log.debug(f"delete_requests response: {res.status}")
+                        res.raise_for_status()
+                    return True
+                except asyncio.TimeoutError:
+                    log.debug("delete_requests timed out")
+                except (ClientResponseError, Exception) as e:
+                    log.debug(f"delete_requests failed with error: {e}")
+                await asyncio.sleep(2)
+                log.debug(f"Retrying delete_request, attempt: {attempt}")
+            return False
+
+        # Take a snapshot of what we plan to send this tick.
+        # New arrivals after this snapshot will remain in the queue for the next tick.
+        snapshot = list(self.model_metrics.requests_deleting)
+        success_idxs = [r.request_idx for r in snapshot if r.success is True]
+        failed_idxs  = [r.request_idx for r in snapshot if r.success is False]
+
+        if not success_idxs and not failed_idxs:
+            return  # nothing to do
+
+        for report_addr in self.report_addr:
+            # TODO: Add a Redis subscriber queue for delete_requests
+            if report_addr == "https://cloud.vast.ai/api/v0":
+                # Patch: ignore the Redis API report_addr
+                continue
+            sent_success = True
+            sent_failed  = True
+
+            if success_idxs:
+                sent_success = await post(report_addr, success_idxs, True)
+            if failed_idxs:
+                sent_failed = await post(report_addr, failed_idxs, False)
+
+            if sent_success and sent_failed:
+                # Remove only the items we actually sent from the live queue.
+                sent_set = set(success_idxs) | set(failed_idxs)
+                self.model_metrics.requests_deleting[:] = [
+                    r for r in self.model_metrics.requests_deleting
+                    if r.request_idx not in sent_set
+                ]
+                break
+
+
+    async def __send_metrics_and_reset(self):
+
+        loadtime_snapshot = self.system_metrics.model_loading_time
+
+        def get_worker_status_data() -> WorkerStatusData:
+            return WorkerStatusData(
+                id=self.id,
+                mtoken=self.mtoken,
+                version=self.version,
+                loadtime=(loadtime_snapshot or 0.0), 
+                new_load=self.model_metrics.workload_processing,
+                cur_load=self.model_metrics.cur_load,
+                rej_load=self.model_metrics.workload_rejected,
+                max_perf=self.model_metrics.max_throughput,
+                cur_perf=self.model_metrics.workload_served,
+                error_msg=self.model_metrics.error_msg or "",
+                num_requests_working=len(self.model_metrics.requests_working),
+                num_requests_recieved=len(self.model_metrics.requests_recieved),
+                additional_disk_usage=self.system_metrics.additional_disk_usage,
+                working_request_idxs=self.model_metrics.working_request_idxs,
+                cur_capacity=0,
+                max_capacity=0,
+                url=self.url,
+            )
+
+        async def send_data(report_addr: str) -> bool:
+            data = get_worker_status_data()
+            log_data = asdict(data)
+            def obfuscate(secret: str) -> str:
+                if secret is None:
+                    return ""
+                return secret[:7] + "..." if len(secret) > 12 else ("*" * len(secret))
+            
+            log_data["mtoken"] = obfuscate(log_data.get("mtoken"))
+            log.debug(
+                "\n".join(
+                    [
+                        "\n" + "#" * 20 + " Worker Status " + "#" * 20,
+                        f"{json.dumps(log_data, indent=2)}",
+                        "#" * 55,
+                    ]
+                )
+            )
+
+            full_path = report_addr.rstrip("/") + "/worker_status/"
+            for attempt in range(1, 4):
+                try:
+                    session = await self.http()
+                    async with session.post(full_path, json=asdict(data)) as res:
+                        res.raise_for_status()
+                    return True
+                except asyncio.TimeoutError:
+                    log.debug(f"Request to /worker_status/ timed out")
+                except (ClientResponseError, Exception)  as e:
+                    log.debug(f"Request to /worker_status/ failed with error: {e}")
+                await asyncio.sleep(2)
+                log.debug(f"Retrying /worker_status/ request, attempt: {attempt}")
+            log.debug(f"Failed to send worker status through {report_addr}")
+            return False
+
+        ###########
+
+        self.system_metrics.update_disk_usage()
+
+        sent = False
+        for report_addr in self.report_addr:
+            if await send_data(report_addr):
+                sent = True
+                break
+
+        if sent:
+            # clear the one-shot loadtime only if we actually sent *this* value
+            self.system_metrics.reset(expected=loadtime_snapshot)
+            self.update_pending = False
+            self.model_metrics.reset()
+            self.last_metric_update = time.time()
diff --git a/vastai/serverless/server/lib/server.py b/vastai/serverless/server/lib/server.py
new file mode 100644
index 00000000..7044b878
--- /dev/null
+++ b/vastai/serverless/server/lib/server.py
@@ -0,0 +1,65 @@
+import os
+import logging
+from typing import List
+import ssl
+from asyncio import run, gather
+import asyncio
+
+from .backend import Backend
+from .metrics import Metrics
+from aiohttp import web
+
+log = logging.getLogger(__file__)
+
+async def start_server_async(backend: Backend, routes: List[web.RouteDef], **kwargs):
+    try:
+        use_ssl = os.environ.get("USE_SSL", "false") == "true"
+        if use_ssl is True:
+            log.debug("Getting SSL Certificate from /etc/instance.crt")
+            try:
+                ssl_context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
+                ssl_context.load_cert_chain(
+                    certfile="/etc/instance.crt",
+                    keyfile="/etc/instance.key",
+                )
+            except Exception as ex:
+                raise Exception(f"Failed to get SSL Certificate: {ex}")
+        else:
+            ssl_context = None
+
+        log.debug("Starting Worker Server...")
+        app = web.Application()
+        app.add_routes(routes)
+        runner = web.AppRunner(app)
+        await runner.setup()
+        site = web.TCPSite(
+            runner,
+            ssl_context=ssl_context,
+            port=int(os.environ["WORKER_PORT"]),
+            **kwargs
+        )
+        await gather(site.start(), backend._start_tracking())
+
+    except Exception as e:
+        err_msg = f"Worker Server failed to launch: {e}"
+        log.error(err_msg)
+
+        async def beacon():
+            metrics = Metrics()
+            metrics._set_version(getattr(backend, "version", "0"))
+            metrics._set_mtoken(getattr(backend, "mtoken", ""))
+            try:
+                while True:
+                    metrics._model_errored(err_msg)
+                    await metrics._Metrics__send_metrics_and_reset()
+                    await asyncio.sleep(10)
+            finally:
+                await metrics.aclose()
+
+        await beacon()
+
+
+
+def start_server(backend: Backend, routes: List[web.RouteDef], **kwargs):
+    run(start_server_async(backend, routes, **kwargs))
+
diff --git a/vastai/serverless/server/worker.py b/vastai/serverless/server/worker.py
new file mode 100644
index 00000000..75cdf3e1
--- /dev/null
+++ b/vastai/serverless/server/worker.py
@@ -0,0 +1,343 @@
+from vastai.serverless.server.lib import backend, server
+from vastai.serverless.server.lib.data_types import ApiPayload, EndpointHandler, LogAction, JsonDataException
+from dataclasses import dataclass, field
+from aiohttp import web, ClientResponse
+import logging
+import json
+import random
+import logging
+from typing import Optional, Dict, Callable, Awaitable, Union, Any, Type
+
+# Callable types
+RequestPayloadParser = Callable[[Dict[str, Any]], Dict[str, Any]]
+ClientResponseGenerator = Callable[[web.Request, ClientResponse], Awaitable[Union[web.Response, web.StreamResponse]]]
+WorkloadCalculator = Callable[[Dict[str, Any]], float]
+
+@dataclass
+class LogActionConfig:
+    """Configuration for defining log actions"""
+    on_load: list[str] = field(default_factory=list)
+    on_error: list[str] = field(default_factory=list)
+    on_info: list[str] = field(default_factory=list)
+
+    @property
+    def log_actions(self) -> list[LogAction]:
+        log_actions_ = []
+        log_actions_.extend([(LogAction.ModelLoaded, log) for log in self.on_load])
+        log_actions_.extend([(LogAction.ModelError,  log) for log in self.on_error])
+        log_actions_.extend([(LogAction.Info,        log) for log in self.on_info])
+        return log_actions_
+    
+@dataclass
+class BenchmarkConfig:
+    """Configuration for defining a benchmark"""
+    dataset: list[dict] | None = None
+    generator: Callable[[], dict] | None = None  # optional sample factory
+    runs: int = 8
+    concurrency: int | None = 10
+
+@dataclass
+class HandlerConfig:
+    """Configuration for defining handlers"""
+    route: str
+    allow_parallel_requests: bool = False
+    max_queue_time: Optional[float] = 30.0
+    benchmark_config: Optional[BenchmarkConfig] = None
+    handler_class: Optional[Type[EndpointHandler]] = None
+    payload_class: Optional[Type[ApiPayload]] = None
+    request_parser: Optional[RequestPayloadParser] = None
+    response_generator: Optional[ClientResponseGenerator] = None
+    workload_calculator: Optional[WorkloadCalculator] = None
+
+
+@dataclass
+class WorkerConfig:
+    model_server_url: str = None
+    model_server_port: int = None
+    model_log_file: str = None
+    model_healthcheck_url: str = None
+    handlers: list[HandlerConfig] = field(default_factory=list)
+    log_action_config: LogActionConfig = field(default_factory=LogActionConfig)
+
+
+class EndpointHandlerFactory:
+    """Factory for creating endpoint handlers from WorkerConfig"""
+    
+    def __init__(self, config: WorkerConfig):
+        self.config = config
+        self._handlers: Dict[str, EndpointHandler] = {}
+        self._build_handlers()
+    
+    def _build_handlers(self) -> None:
+        """Build endpoint handlers from config"""
+        # If no handlers, create a default handler at /
+        if not self.config.handlers:
+            default_handler_config = HandlerConfig(
+                route="/",
+            )
+            handler = self._create_handler(default_handler_config)
+            self._handlers["/"] = handler
+        else:
+            # Build handlers from config
+            for handler_config in self.config.handlers:
+                # TODO: Override values from handler class with HandlerConfig values
+                if handler_config.handler_class is not None:
+                    # Use custom handler class
+                    handler = handler_config.handler_class()
+                    self._handlers[handler_config.route] = handler
+                    continue
+                handler = self._create_handler(handler_config)
+                self._handlers[handler_config.route] = handler
+    
+    def _create_handler(self, handler_config: HandlerConfig) -> EndpointHandler:
+        """Create a generic endpoint handler from HandlerConfig"""
+        
+        # Extract config values with defaults
+        route_path = handler_config.route
+        benchmark_config = handler_config.benchmark_config
+        user_payload_class = handler_config.payload_class
+        user_request_parser = handler_config.request_parser
+        user_response_generator = handler_config.response_generator
+        user_workload_calculator = handler_config.workload_calculator
+        
+        # If user provided a custom payload class, use it
+        if user_payload_class:
+            PayloadClass = user_payload_class
+        else:
+            # Create a generic ApiPayload class
+            @dataclass
+            class GenericApiPayload(ApiPayload):
+                input: Dict[str, Any] = field(default_factory=dict)
+                
+                @classmethod
+                def for_test(cls) -> "GenericApiPayload":
+                    # Use random.choice from benchmark_data if available
+                    if benchmark_config:
+                        if benchmark_config.dataset:
+                            test_data = random.choice(benchmark_config.dataset)
+                        elif benchmark_config.generator:
+                            try:
+                                test_data = benchmark_config.generator()
+                            except Exception as ex:
+                                raise(Exception(f"Error generating benchmark data for \"{handler_config.route}\" handler: {ex}"))
+                    else:
+                        raise(Exception(f"Error generating benchmark data for \"{handler_config.route}\" handler: Missing BenchmarkConfig!"))
+                    return cls(input=test_data.copy())
+                
+                def generate_payload_json(self) -> Dict[str, Any]:
+                    return self.input
+                
+
+                @classmethod
+                def from_dict(cls, input: Dict[str, Any]) -> "GenericApiPayload":
+                    return cls(input=input)
+
+                def count_workload(self) -> float:
+                    # Use custom workload calculator if provided
+                    if user_workload_calculator:
+                        return user_workload_calculator(self.input)
+                    # Default to 100 unless overridden
+                    return 100.0
+                
+                @classmethod
+                def from_json_msg(cls, json_msg: Dict[str, Any]) -> "GenericApiPayload":
+                    if not isinstance(json_msg, dict):
+                        raise JsonDataException({"data": "payload must be a dictionary"})
+                    
+                    # Apply user's request parser if provided
+                    if user_request_parser:
+                        try:
+                            json_msg = user_request_parser(json_msg)
+                        except Exception as e:
+                            raise Exception(f"Error in user response handler: {e}")
+                        
+                    try:
+                        return cls.from_dict(json_msg)
+                    except (json.JSONDecodeError, JsonDataException) as e:
+                        raise JsonDataException(f"Error in user response handler: {e}")
+
+            
+            PayloadClass = GenericApiPayload
+        
+        # Create a generic EndpointHandler class
+        @dataclass
+        class GenericEndpointHandler(EndpointHandler[PayloadClass]):
+            _route: str = field(default=route_path)
+            has_benchmark: bool = field(
+                default=(
+                    True if handler_config.benchmark_config
+                    else False
+                )
+            )
+            allow_parallel_requests: bool = field(
+                default=handler_config.allow_parallel_requests
+            )
+            max_queue_time: float = field(
+                default=handler_config.max_queue_time
+            )
+            benchmark_runs: int = field(
+                default=(
+                    handler_config.benchmark_config.runs
+                    if handler_config.benchmark_config
+                    else 8
+                )
+            )
+            concurrency: int = field(
+                default=(
+                    handler_config.benchmark_config.concurrency
+                    if handler_config.benchmark_config and handler_config.benchmark_config.concurrency
+                    else 10
+                )
+            )
+            @property
+            def endpoint(self) -> str:
+                """The endpoint is the same as the route"""
+                return self._route
+
+            @property
+            def healthcheck_endpoint(self) -> Optional[str]:
+                return None
+            
+            @classmethod
+            def payload_cls(cls) -> Type[PayloadClass]:
+                return PayloadClass
+            
+            def make_benchmark_payload(self) -> PayloadClass:
+                """Just call the payload class's for_test() method"""
+                return PayloadClass.for_test()
+            
+            async def generate_client_response(
+                self,
+                client_request: web.Request,
+                model_response: ClientResponse,
+            ) -> Union[web.Response, web.StreamResponse]:
+                # User implemented override
+                if user_response_generator:
+                    try:
+                        return await user_response_generator(client_request, model_response)
+                    except Exception as e:
+                        raise Exception(f"Error in user response generator: {e}")
+
+                # Reasonable default: return response, handle streaming if present
+                # Detect streaming
+                content_type = model_response.content_type or ""
+                is_stream = (
+                    content_type.startswith("text/event-stream") or
+                    content_type in ("application/x-ndjson", "application/jsonl") or
+                    "stream" in content_type.lower()
+                ) or (model_response.headers.get("Transfer-Encoding") == "chunked")
+
+                if is_stream:
+                    # Streaming passthrough
+                    res = web.StreamResponse(
+                        status=model_response.status,
+                    )
+                    if content_type:
+                        res.content_type = content_type
+
+                    await res.prepare(client_request)
+
+                    async for chunk in model_response.content.iter_any():
+                        if not chunk:
+                            continue
+                        await res.write(chunk)
+
+                    await res.write_eof()
+                    return res
+                else:
+                    # Non-streaming
+                    body = await model_response.read()
+
+                    headers = model_response.headers.copy()
+                    headers.pop("Content-Type", None)
+
+                    return web.Response(
+                        body=body,
+                        status=model_response.status,
+                        content_type=content_type or None,
+                        headers=headers,
+                    )
+        
+        return GenericEndpointHandler()
+    
+    def get_handler(self, route: str) -> Optional[EndpointHandler]:
+        """Get handler for a specific route"""
+        return self._handlers.get(route)
+    
+    def get_all_handlers(self) -> Dict[str, EndpointHandler]:
+        """Get all registered handlers"""
+        return self._handlers.copy()
+    
+    def get_benchmark_handler(self) -> Optional[EndpointHandler]:
+        """
+        Get the benchmark handler. 
+        Raises errors if there are too many / too little BenchmarkConfigs
+        Should be exactly one EndpointHandler with a BenchmarkConfig
+        """
+        if not self._handlers:
+            return None
+
+        benchmark_handler: EndpointHandler = None
+        for handler in self._handlers.values():
+            if handler.has_benchmark:
+                if benchmark_handler is not None:
+                    raise Exception("Cannot define BenchmarkConfig for more than one EndpointHandler!")
+                else:
+                    benchmark_handler = handler
+        if not benchmark_handler:
+            raise Exception("Missing EndpointHandler with BenchmarkConfig")
+        return benchmark_handler
+    
+    def has_handlers(self) -> bool:
+        """Check if any handlers are registered"""
+        return len(self._handlers) > 0
+    
+    @property
+    def model_server_base_url(self) -> str:
+        """Get the full model server base URL"""
+        return f"{self.config.model_server_url}:{self.config.model_server_port}"
+    
+class Worker:
+    """
+    This class provides a simple to use abstraction over the pyworker backend.
+    All custom implementations of pyworker can be created by configuring a Worker object.
+    The pyworker starts by calling Worker.run()
+    """
+
+    def __init__(self, config: WorkerConfig):
+        
+        # Configure logging for the pyworker internals
+        logging.basicConfig(
+            level=logging.DEBUG,
+            format="%(asctime)s[%(levelname)-5s] %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+        
+        handler_factory = EndpointHandlerFactory(config)
+        
+        # Get all endpoint handlers
+        handlers = handler_factory.get_all_handlers()
+        benchmark_handler = handler_factory.get_benchmark_handler()
+        
+        # Create backend
+        self.backend = backend.Backend(
+            model_server_url=f"{config.model_server_url}:{config.model_server_port}",
+            model_log_file=config.model_log_file,
+            benchmark_handler=benchmark_handler,
+            log_actions=config.log_action_config.log_actions,
+            healthcheck_url=config.model_healthcheck_url
+        )
+        
+        # Attach endpoint handlers to HTTP routes
+        self.routes = []
+        for route_path, handler in handlers.items():
+            self.routes.append(
+                web.post(route_path, self.backend.create_handler(handler))
+            )
+        
+    async def run_async(self, **kwargs):
+        await server.start_server_async(self.backend, self.routes, **kwargs)
+
+    def run(self, **kwargs):
+        server.start_server(self.backend, self.routes, **kwargs)
+
diff --git a/vastai/vastai_base.py b/vastai/vastai_base.py
new file mode 100644
index 00000000..b4a8b290
--- /dev/null
+++ b/vastai/vastai_base.py
@@ -0,0 +1,1317 @@
+from abc import ABC
+from typing import Any
+
+
+class VastAIBase(ABC):
+    """VastAI SDK base class that defines the methods to be implemented by the VastAI class."""
+
+    def attach_ssh(self, instance_id: int, ssh_key: str) -> dict[str, Any]:
+        """Attach an SSH key to an instance."""
+        pass
+
+    def cancel_copy(self, dst: str) -> dict[str, Any]:
+        """Cancel a file copy operation."""
+        pass
+
+    def cancel_sync(self, dst: str) -> dict[str, Any]:
+        """Cancel a file sync operation."""
+        pass
+
+    def change_bid(self, id: int, price: float | None = None) -> dict[str, Any]:
+        """Change the bid price for a machine."""
+        pass
+
+    def copy(self, src: str, dst: str, identity: str | None = None) -> dict[str, Any]:
+        """Copy files between instances."""
+        pass
+
+    def cloud_copy(
+        self,
+        src: str | None = None,
+        dst: str | None = "/workspace",
+        instance: str | None = None,
+        connection: str | None = None,
+        transfer: str = "Instance to Cloud",
+    ) -> dict[str, Any]:
+        """Copy files between cloud and instance."""
+        pass
+
+    def create_api_key(
+        self,
+        name: str | None = None,
+        permission_file: str | None = None,
+        key_params: str | None = None,
+    ) -> dict[str, Any]:
+        """Create a new API key."""
+        pass
+
+    def create_ssh_key(self, ssh_key: str) -> dict[str, Any]:
+        """Create a new SSH key."""
+        pass
+
+    def create_workergroup(
+        self,
+        test_workers: int = 3,
+        gpu_ram: float | None = None,
+        template_hash: str | None = None,
+        template_id: int | None = None,
+        search_params: str | None = None,
+        launch_args: str | None = None,
+        endpoint_name: str | None = None,
+        endpoint_id: int | None = None,
+        min_load: float | None = None,
+        target_util: float | None = None,
+        cold_mult: float | None = None,
+    ) -> dict[str, Any]:
+        """Create a new workergroup (autoscaler)."""
+        pass
+
+    # Backwards compatibility alias (deprecated: use create_workergroup)
+    create_autogroup = create_workergroup
+
+    def create_endpoint(
+        self,
+        min_load: float = 0.0,
+        target_util: float = 0.9,
+        cold_mult: float = 2.5,
+        cold_workers: int = 5,
+        max_workers: int = 20,
+        endpoint_name: str | None = None,
+    ) -> dict[str, Any]:
+        """Create a new serverless endpoint."""
+        pass
+
+    def create_instance(
+        self,
+        id: int,
+        price: float | None = None,
+        disk: float | None = 10,
+        image: str | None = None,
+        login: str | None = None,
+        label: str | None = None,
+        onstart: str | None = None,
+        onstart_cmd: str | None = None,
+        entrypoint: str | None = None,
+        ssh: bool = False,
+        jupyter: bool = False,
+        direct: bool = False,
+        jupyter_dir: str | None = None,
+        jupyter_lab: bool = False,
+        lang_utf8: bool = False,
+        python_utf8: bool = False,
+        extra: str | None = None,
+        env: str | None = None,
+        args: list[str] | None = None,
+        force: bool = False,
+        cancel_unavail: bool = False,
+        template_hash: str | None = None,
+    ) -> dict[str, Any]:
+        """Create a new instance from a contract offer ID."""
+        pass
+
+    def create_subaccount(
+        self,
+        email: str | None = None,
+        username: str | None = None,
+        password: str | None = None,
+        type: str | None = None,
+    ) -> dict[str, Any]:
+        """Create a new subaccount."""
+        pass
+
+    def create_team(self, team_name: str | None = None) -> dict[str, Any]:
+        """Create a new team."""
+        pass
+
+    def create_team_role(
+        self, name: str | None = None, permissions: str | None = None
+    ) -> dict[str, Any]:
+        """Create a new team role."""
+        pass
+
+    def create_template(
+        self,
+        name: str | None = None,
+        image: str | None = None,
+        image_tag: str | None = None,
+        login: str | None = None,
+        env: str | None = None,
+        ssh: bool = False,
+        jupyter: bool = False,
+        direct: bool = False,
+        jupyter_dir: str | None = None,
+        jupyter_lab: bool = False,
+        onstart_cmd: str | None = None,
+        search_params: str | None = None,
+        disk_space: str | None = None,
+    ) -> dict[str, Any]:
+        """Create a new template."""
+        pass
+
+    def delete_api_key(self, id: int) -> dict[str, Any]:
+        """Delete an API key."""
+        pass
+
+    def delete_ssh_key(self, id: int) -> dict[str, Any]:
+        """Delete an SSH key."""
+        pass
+
+    def delete_workergroup(self, id: int) -> dict[str, Any]:
+        """Delete a workergroup."""
+        pass
+
+    # Backwards compatibility alias (deprecated: use delete_workergroup)
+    delete_autoscaler = delete_workergroup
+
+    def delete_endpoint(self, id: int) -> dict[str, Any]:
+        """Delete a serverless endpoint."""
+        pass
+
+    def destroy_instance(self, id: int) -> dict[str, Any]:
+        """Destroy an instance."""
+        pass
+
+    def destroy_instances(self, ids: list[int]) -> dict[str, Any]:
+        """Destroy multiple instances."""
+        pass
+
+    def destroy_team(self) -> dict[str, Any]:
+        """Destroy the current team."""
+        pass
+
+    def detach_ssh(self, instance_id: int, ssh_key_id: str) -> dict[str, Any]:
+        """Detach an SSH key from an instance."""
+        pass
+
+    def execute(self, id: int, COMMAND: str) -> dict[str, Any]:
+        """Execute a command on an instance."""
+        pass
+
+    def invite_team_member(
+        self, email: str | None = None, role: str | None = None
+    ) -> dict[str, Any]:
+        """Invite a new member to the team."""
+        pass
+
+    def label_instance(self, id: int, label: str) -> dict[str, Any]:
+        """Label an instance."""
+        pass
+
+    def launch_instance(
+        gpu_name: str,
+        num_gpus: str,
+        image: str,
+        region: str = None,
+        disk: float = 16.0,
+        limit: int = 3,
+        order: str = "score-",
+        login: str = None,
+        label: str = None,
+        onstart: str = None,
+        onstart_cmd: str = None,
+        entrypoint: str = None,
+        ssh: bool = False,
+        jupyter: bool = False,
+        direct: bool = False,
+        jupyter_dir: str = None,
+        jupyter_lab: bool = False,
+        lang_utf8: bool = False,
+        python_utf8: bool = False,
+        extra: str = None,
+        env: str = None,
+        args: list[str] | None = None,
+        force: bool = False,
+        cancel_unavail: bool = False,
+        template_hash: str = None,
+        explain: bool = False,
+        raw: bool = False,
+    ) -> dict[str, Any]:
+        """
+        Launches the top instance from the search offers based on the given parameters.
+
+        Returns:
+            str: Confirmation message of the instance launch or details about the operation.
+        """
+        pass
+
+    def logs(self, INSTANCE_ID: int, tail: str | None = None) -> dict[str, Any]:
+        """Retrieve logs for an instance."""
+        pass
+
+    def prepay_instance(self, id: int, amount: float) -> dict[str, Any]:
+        """Prepay for an instance."""
+        pass
+
+    def reboot_instance(self, id: int) -> dict[str, Any]:
+        """Reboot an instance."""
+        pass
+
+    def recycle_instance(self, id: int) -> dict[str, Any]:
+        """Recycle an instance."""
+        pass
+
+    def remove_team_member(self, id: int) -> dict[str, Any]:
+        """Remove a member from the team."""
+        pass
+
+    def remove_team_role(self, NAME: str) -> dict[str, Any]:
+        """Remove a role from the team."""
+        pass
+
+    def reports(self, id: int) -> dict[str, Any]:
+        """Generate reports for a machine."""
+        pass
+
+    def reset_api_key(self) -> dict[str, Any]:
+        """Reset the API key."""
+        pass
+
+    def start_instance(self, id: int) -> dict[str, Any]:
+        """Start an instance."""
+        pass
+
+    def start_instances(self, ids: list[int]) -> dict[str, Any]:
+        """Start multiple instances."""
+        pass
+
+    def stop_instance(self, id: int) -> dict[str, Any]:
+        """Stop an instance."""
+        pass
+
+    def stop_instances(self, ids: list[int]) -> dict[str, Any]:
+        """Stop multiple instances."""
+        pass
+
+    def search_benchmarks(self, query: str | None = None) -> list[dict[str, Any]]:
+        """Search for benchmarks based on a query."""
+        pass
+
+    def search_invoices(self, query: str | None = None) -> list[dict[str, Any]]:
+        """Search for invoices based on a query."""
+        pass
+
+    def search_offers(
+        self,
+        type: str | None = None,
+        no_default: bool = False,
+        new: bool = False,
+        limit: int | None = None,
+        disable_bundling: bool = False,
+        storage: float | None = None,
+        order: str | None = None,
+        query: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """Search for offers based on various criteria."""
+        pass
+
+    def search_templates(self, query: str | None = None) -> list[dict[str, Any]]:
+        """Search for templates based on a query."""
+        pass
+
+    def set_api_key(self, new_api_key: str) -> dict[str, Any]:
+        """Set a new API key."""
+        pass
+
+    def set_user(self, file: str | None = None) -> dict[str, Any]:
+        """Set user parameters from a file."""
+        pass
+
+    def ssh_url(self, id: int) -> dict[str, Any]:
+        """Get the SSH URL for an instance."""
+        pass
+
+    def scp_url(self, id: int) -> dict[str, Any]:
+        """Get the SCP URL for transferring files to/from an instance."""
+        pass
+
+    def show_api_key(self, id: int) -> dict[str, Any]:
+        """Show details of an API key."""
+        pass
+
+    def show_api_keys(self) -> list[dict[str, Any]]:
+        """Show all API keys."""
+        pass
+
+    def show_ssh_keys(self) -> list[dict[str, Any]]:
+        """Show all SSH keys."""
+        pass
+
+    def show_workergroups(self) -> list[dict[str, Any]]:
+        """Show all workergroups (autoscalers)."""
+        pass
+
+    # Backwards compatibility alias (deprecated: use show_workergroups)
+    show_autoscalers = show_workergroups
+
+    def show_endpoints(self) -> list[dict[str, Any]]:
+        """Show all endpoints."""
+        pass
+
+    def show_connections(self) -> list[dict[str, Any]]:
+        """Show all connections."""
+        pass
+
+    def show_deposit(self, Id: int) -> dict[str, Any]:
+        """Show deposit details for an instance."""
+        pass
+
+    def show_earnings(
+        self,
+        quiet: bool = False,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        machine_id: int | None = None,
+    ) -> list[dict[str, Any]]:
+        """Show earnings information."""
+        pass
+
+    def show_invoices(
+        self,
+        quiet: bool = False,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        only_charges: bool = False,
+        only_credits: bool = False,
+        instance_label: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """Show invoice details."""
+        pass
+
+    def show_instance(self, id: int) -> dict[str, Any]:
+        """Show details of an instance."""
+        pass
+
+    def show_instances(self, quiet: bool = False) -> list[dict[str, Any]]:
+        """Show all instances."""
+        pass
+
+    def show_ipaddrs(self) -> list[dict[str, Any]]:
+        """Show IP addresses."""
+        pass
+
+    def show_user(self, quiet: bool = False) -> dict[str, Any]:
+        """Show user details."""
+        pass
+
+    def show_subaccounts(self, quiet: bool = False) -> list[dict[str, Any]]:
+        """Show all subaccounts of the current user."""
+        pass
+
+    def show_team_members(self) -> list[dict[str, Any]]:
+        """Show all team members."""
+        pass
+
+    def show_team_role(self, NAME: str) -> dict[str, Any]:
+        """Show details of a specific team role."""
+        pass
+
+    def show_team_roles(self) -> list[dict[str, Any]]:
+        """Show all team roles."""
+        pass
+
+    def transfer_credit(self, recipient: str, amount: float) -> dict[str, Any]:
+        """Transfer credit to another account."""
+        pass
+
+    def update_workergroup(
+        self,
+        id: int,
+        min_load: float | None = None,
+        target_util: float | None = None,
+        cold_mult: float | None = None,
+        test_workers: int | None = None,
+        gpu_ram: float | None = None,
+        template_hash: str | None = None,
+        template_id: int | None = None,
+        search_params: str | None = None,
+        launch_args: str | None = None,
+        endpoint_name: str | None = None,
+        endpoint_id: int | None = None,
+    ) -> dict[str, Any]:
+        """Update a workergroup (autoscaler)."""
+        pass
+
+    # Backwards compatibility alias (deprecated: use update_workergroup)
+    update_autoscaler = update_workergroup
+
+    def update_endpoint(
+        self,
+        id: int,
+        min_load: float | None = None,
+        target_util: float | None = None,
+        cold_mult: float | None = None,
+        cold_workers: int | None = None,
+        max_workers: int | None = None,
+        endpoint_name: str | None = None,
+    ) -> dict[str, Any]:
+        """Update a serverless endpoint configuration."""
+        pass
+
+    def update_team_role(
+        self, id: int, name: str | None = None, permissions: str | None = None
+    ) -> dict[str, Any]:
+        """Update details of a team role."""
+        pass
+
+    def update_ssh_key(self, id: int, ssh_key: str) -> dict[str, Any]:
+        """Update an SSH key."""
+        pass
+
+    def generate_pdf_invoices(
+        self,
+        quiet: bool = False,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        only_charges: bool = False,
+        only_credits: bool = False,
+    ) -> dict[str, Any]:
+        """Generate PDF invoices based on filters."""
+        pass
+
+    def cleanup_machine(self, id: int) -> dict[str, Any]:
+        """Clean up a machine's configuration and resources."""
+        pass
+
+    def list_machine(
+        self,
+        id: int,
+        price_gpu: float | None = None,
+        price_disk: float | None = None,
+        price_inetu: float | None = None,
+        price_inetd: float | None = None,
+        discount_rate: float | None = None,
+        min_chunk: int | None = None,
+        end_date: str | None = None,
+    ) -> dict[str, Any]:
+        """List details of a single machine with optional pricing and configuration parameters."""
+        pass
+
+    def list_machines(
+        self,
+        ids: list[int],
+        price_gpu: float | None = None,
+        price_disk: float | None = None,
+        price_inetu: float | None = None,
+        price_inetd: float | None = None,
+        discount_rate: float | None = None,
+        min_chunk: int | None = None,
+        end_date: str | None = None,
+    ) -> dict[str, Any]:
+        """List details of multiple machines with optional pricing and configuration parameters."""
+        pass
+
+    def remove_defjob(self, id: int) -> dict[str, Any]:
+        """Remove the default job from a machine."""
+        pass
+
+    def set_defjob(
+        self,
+        id: int,
+        price_gpu: float | None = None,
+        price_inetu: float | None = None,
+        price_inetd: float | None = None,
+        image: str | None = None,
+        args: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Set a default job on a machine with specified parameters."""
+        pass
+
+    def set_min_bid(self, id: int, price: float | None = None) -> dict[str, Any]:
+        """Set the minimum bid price for a machine."""
+        pass
+
+    def schedule_maint(
+        self, id: int, sdate: float | None = None, duration: float | None = None
+    ) -> dict[str, Any]:
+        """Schedule maintenance for a machine."""
+        pass
+
+    def cancel_maint(self, id: int) -> dict[str, Any]:
+        """Cancel scheduled maintenance for a machine."""
+        pass
+
+    def unlist_machine(self, id: int) -> dict[str, Any]:
+        """Unlist a machine from being available for new jobs."""
+        pass
+
+    def show_machines(self, quiet: bool = False, filter: str | None = None) -> list[dict[str, Any]]:
+        """
+        Retrieve and display a list of machines based on specified criteria.
+
+        Parameters:
+        - quiet (bool): If True, limit the output to minimal details such as IDs.
+        - filter (str, optional): A string used to filter the machines based on specific criteria.
+
+        Returns:
+        - list[dict[str, Any]]: A list of machine information dictionaries.
+        """
+        pass
+
+    # Volume Methods
+
+    def clone_volume(
+        self,
+        source: int,
+        dest: int,
+        size: float | None = None,
+        disable_compression: bool = False,
+    ) -> dict[str, Any]:
+        """Clone an existing volume to a new location.
+
+        Args:
+            source: ID of the volume contract being cloned.
+            dest: ID of the volume offer the volume is being copied to.
+            size: Size of the new volume contract in GB. Must be >= source and <= dest offer.
+            disable_compression: If True, do not compress volume data before copying.
+
+        Returns:
+            Confirmation message or volume creation details.
+        """
+        pass
+
+    def create_volume(
+        self,
+        id: int,
+        size: float = 15,
+        name: str | None = None,
+    ) -> dict[str, Any]:
+        """Create a new volume from an offer ID.
+
+        Args:
+            id: ID of the volume offer (from search volumes).
+            size: Size in GB of the volume. Default is 15 GB.
+            name: Optional name for the volume.
+
+        Returns:
+            Confirmation message with volume creation details.
+        """
+        pass
+
+    def delete_volume(self, id: int) -> dict[str, Any]:
+        """Delete a volume.
+
+        Args:
+            id: ID of the volume contract to delete.
+
+        Returns:
+            Confirmation message of deletion.
+        """
+        pass
+
+    def list_volume(
+        self,
+        id: int,
+        price_disk: float = 0.10,
+        size: int = 15,
+        end_date: str | None = None,
+    ) -> dict[str, Any]:
+        """List disk space for rent as a volume on a machine.
+
+        Args:
+            id: ID of the machine to list volume on.
+            price_disk: Storage price in $/GB/month. Default is $0.10/GB/month.
+            size: Size of disk space allocated to offer in GB. Default is 15 GB.
+            end_date: Contract offer expiration date (unix timestamp or MM/DD/YYYY format).
+
+        Returns:
+            Confirmation message with listing details.
+        """
+        pass
+
+    def list_volumes(
+        self,
+        ids: list[int],
+        price_disk: float = 0.10,
+        size: int = 15,
+        end_date: str | None = None,
+    ) -> dict[str, Any]:
+        """List disk space for rent as volumes on multiple machines.
+
+        Args:
+            ids: List of machine IDs to list volumes on.
+            price_disk: Storage price in $/GB/month. Default is $0.10/GB/month.
+            size: Size of disk space allocated to offer in GB. Default is 15 GB.
+            end_date: Contract offer expiration date (unix timestamp or MM/DD/YYYY format).
+
+        Returns:
+            Confirmation message with listing details.
+        """
+        pass
+
+    def search_volumes(
+        self,
+        query: str | None = None,
+        no_default: bool = False,
+        limit: int | None = None,
+        storage: float = 1.0,
+        order: str = "score-",
+    ) -> list[dict[str, Any]]:
+        """Search for volume offers using custom query.
+
+        Args:
+            query: Query string for filtering volumes.
+            no_default: If True, disable default query filters.
+            limit: Maximum number of results to return.
+            storage: Amount of storage for pricing in GiB. Default is 1.0 GiB.
+            order: Comma-separated list of fields to sort on. Default is 'score-'.
+
+        Returns:
+            List of matching volume offers.
+        """
+        pass
+
+    def show_volumes(self, type: str = "all") -> list[dict[str, Any]]:
+        """Show stats on owned volumes.
+
+        Args:
+            type: Volume type to display. Options: 'local', 'network', 'all'. Default is 'all'.
+
+        Returns:
+            List of owned volumes with their details.
+        """
+        pass
+
+    def unlist_volume(self, id: int) -> dict[str, Any]:
+        """Unlist a volume offer.
+
+        Args:
+            id: Volume ID to unlist.
+
+        Returns:
+            Confirmation message of unlisting.
+        """
+        pass
+
+    # Network Volume Methods
+
+    def create_network_volume(
+        self,
+        id: int,
+        size: float = 15,
+        name: str | None = None,
+    ) -> dict[str, Any]:
+        """Create a new network volume from an offer ID.
+
+        Args:
+            id: ID of the network volume offer (from search network volumes).
+            size: Size in GB of the network volume. Default is 15 GB.
+            name: Optional name for the network volume.
+
+        Returns:
+            Confirmation message with network volume creation details.
+        """
+        pass
+
+    def list_network_volume(
+        self,
+        disk_id: int,
+        price_disk: float = 0.15,
+        size: int = 15,
+        end_date: str | None = None,
+    ) -> dict[str, Any]:
+        """List disk space for rent as a network volume.
+
+        Args:
+            disk_id: ID of the network disk to list.
+            price_disk: Storage price in $/GB/month. Default is $0.15/GB/month.
+            size: Size of disk space allocated to offer in GB. Default is 15 GB.
+            end_date: Contract offer expiration date (unix timestamp or MM/DD/YYYY format).
+
+        Returns:
+            Confirmation message with listing details.
+        """
+        pass
+
+    def search_network_volumes(
+        self,
+        query: str | None = None,
+        no_default: bool = False,
+        limit: int | None = None,
+        storage: float = 1.0,
+        order: str = "score-",
+    ) -> list[dict[str, Any]]:
+        """Search for network volume offers using custom query.
+
+        Args:
+            query: Query string for filtering network volumes.
+            no_default: If True, disable default query filters.
+            limit: Maximum number of results to return.
+            storage: Amount of storage for pricing in GiB. Default is 1.0 GiB.
+            order: Comma-separated list of fields to sort on. Default is 'score-'.
+
+        Returns:
+            List of matching network volume offers.
+        """
+        pass
+
+    def unlist_network_volume(self, id: int) -> dict[str, Any]:
+        """Unlist a network volume offer.
+
+        Args:
+            id: Network volume offer ID to unlist.
+
+        Returns:
+            Confirmation message of unlisting.
+        """
+        pass
+
+    # Cluster Methods
+
+    def create_cluster(
+        self,
+        subnet: str,
+        manager_id: int,
+    ) -> dict[str, Any]:
+        """Create a new Vast cluster.
+
+        Args:
+            subnet: Local subnet for cluster (e.g., '0.0.0.0/24').
+            manager_id: Machine ID of manager node in cluster. Must exist already.
+
+        Returns:
+            Confirmation message with cluster creation details.
+        """
+        pass
+
+    def delete_cluster(self, cluster_id: int) -> dict[str, Any]:
+        """Delete a cluster.
+
+        Args:
+            cluster_id: ID of the cluster to delete.
+
+        Returns:
+            Confirmation message of deletion.
+        """
+        pass
+
+    def join_cluster(
+        self,
+        cluster_id: int,
+        machine_ids: list[int],
+    ) -> dict[str, Any]:
+        """Join machines to a cluster.
+
+        Args:
+            cluster_id: ID of the cluster to add machines to.
+            machine_ids: List of machine IDs to join to the cluster.
+
+        Returns:
+            Confirmation message of machines joining cluster.
+        """
+        pass
+
+    def show_clusters(self) -> list[dict[str, Any]]:
+        """Show clusters associated with your account.
+
+        Returns:
+            List of clusters with their details (id, subnet, node count, etc.).
+        """
+        pass
+
+    # Overlay Methods
+
+    def create_overlay(
+        self,
+        cluster_id: int,
+        name: str,
+    ) -> dict[str, Any]:
+        """Create an overlay network on top of a physical cluster.
+
+        Args:
+            cluster_id: ID of the cluster to create overlay on.
+            name: Overlay network name.
+
+        Returns:
+            Confirmation message with overlay creation details.
+        """
+        pass
+
+    def delete_overlay(self, overlay_identifier: str) -> dict[str, Any]:
+        """Delete an overlay network.
+
+        Args:
+            overlay_identifier: ID (int) or name (str) of the overlay to delete.
+
+        Returns:
+            Confirmation message of deletion.
+        """
+        pass
+
+    def join_overlay(
+        self,
+        name: str,
+        instance_id: int,
+    ) -> dict[str, Any]:
+        """Add an instance to an overlay network.
+
+        Args:
+            name: Overlay network name to join instance to.
+            instance_id: Instance ID to add to overlay.
+
+        Returns:
+            Confirmation message of instance joining overlay.
+        """
+        pass
+
+    def show_overlays(self) -> list[dict[str, Any]]:
+        """Show overlay networks associated with your account.
+
+        Returns:
+            List of overlays with their details (id, name, subnet, cluster_id, instances).
+        """
+        pass
+
+    # Environment Variable Methods
+
+    def create_env_var(
+        self,
+        name: str,
+        value: str,
+    ) -> dict[str, Any]:
+        """Create a new user environment variable.
+
+        Args:
+            name: Environment variable name.
+            value: Environment variable value.
+
+        Returns:
+            Confirmation message with creation details.
+        """
+        pass
+
+    def delete_env_var(self, name: str) -> dict[str, Any]:
+        """Delete an environment variable.
+
+        Args:
+            name: Name of the environment variable to delete.
+
+        Returns:
+            Confirmation message of deletion.
+        """
+        pass
+
+    def update_env_var(
+        self,
+        name: str,
+        value: str,
+    ) -> dict[str, Any]:
+        """Update an existing environment variable.
+
+        Args:
+            name: Environment variable name to update.
+            value: New value for the environment variable.
+
+        Returns:
+            Confirmation message with update details.
+        """
+        pass
+
+    def show_env_vars(self, show_values: bool = False) -> list[dict[str, Any]]:
+        """Show user environment variables.
+
+        Args:
+            show_values: If True, display actual values. Default is False (masked).
+
+        Returns:
+            List of environment variables (values masked unless show_values=True).
+        """
+        pass
+
+    # Miscellaneous Methods
+
+    def create_account(
+        self,
+        email: str,
+        username: str,
+        password: str,
+    ) -> dict[str, Any]:
+        """Create a new account.
+
+        Note: This command is deprecated. Use the web interface instead.
+
+        Args:
+            email: Email address for the new account.
+            username: Username for the new account.
+            password: Password for the new account.
+
+        Returns:
+            Deprecation message.
+        """
+        pass
+
+    def add_network_disk(
+        self,
+        instance_id: int,
+        volume_id: int,
+        mount_path: str = "/mnt/network",
+    ) -> dict[str, Any]:
+        """Add a network disk (volume) to an instance.
+
+        Args:
+            instance_id: ID of the instance to add the network disk to.
+            volume_id: ID of the network volume to attach.
+            mount_path: Path where the volume will be mounted. Default is '/mnt/network'.
+
+        Returns:
+            Confirmation message with attachment details.
+        """
+        pass
+
+    # Machine Management Methods
+
+    def defrag_machines(self, ids: list[int]) -> dict[str, Any]:
+        """Defragment machines to optimize GPU assignments.
+
+        Rearranges GPU assignments to make more multi-GPU offers available.
+
+        Args:
+            ids: List of machine IDs to defragment.
+
+        Returns:
+            Defragment result message.
+        """
+        pass
+
+    def delete_machine(self, id: int) -> dict[str, Any]:
+        """Delete a machine if not in use by clients.
+
+        Force deletes a machine, disregarding host jobs on own machines.
+
+        Args:
+            id: ID of the machine to delete.
+
+        Returns:
+            Confirmation message of deletion.
+        """
+        pass
+
+    def self_test_machine(
+        self,
+        machine_id: int,
+        debugging: bool = False,
+        ignore_requirements: bool = False,
+    ) -> dict[str, Any]:
+        """Perform a self-test on a machine.
+
+        Verifies machine compliance with required specifications and functionality.
+
+        Args:
+            machine_id: ID of the machine to test.
+            debugging: Enable debugging output. Default is False.
+            ignore_requirements: Ignore minimum system requirements. Default is False.
+
+        Returns:
+            Self-test results.
+        """
+        pass
+
+    def show_machine(self, id: int, quiet: bool = False) -> dict[str, Any]:
+        """Show details of a single machine.
+
+        Args:
+            id: ID of the machine to display.
+            quiet: If True, only display numeric IDs. Default is False.
+
+        Returns:
+            Machine details.
+        """
+        pass
+
+    # Template Methods
+
+    def delete_template(
+        self,
+        template_id: int | None = None,
+        hash_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Delete a template by ID or hash.
+
+        Note: Deleting a template only removes the user's relationship to a template.
+
+        Args:
+            template_id: Template ID to delete.
+            hash_id: Hash ID of template to delete.
+
+        Returns:
+            Confirmation message.
+        """
+        pass
+
+    def update_template(
+        self,
+        hash_id: str,
+        name: str | None = None,
+        image: str | None = None,
+        image_tag: str | None = None,
+        login: str | None = None,
+        env: str | None = None,
+        ssh: bool = False,
+        jupyter: bool = False,
+        direct: bool = False,
+        jupyter_dir: str | None = None,
+        jupyter_lab: bool = False,
+        onstart_cmd: str | None = None,
+        search_params: str | None = None,
+        disk_space: str | None = None,
+        no_default: bool = False,
+    ) -> dict[str, Any]:
+        """Update an existing template.
+
+        Args:
+            hash_id: Hash ID of the template to update.
+            name: New name for the template.
+            image: Docker image for the template.
+            image_tag: Image tag.
+            login: Docker login credentials.
+            env: Environment variables string.
+            ssh: Enable SSH access.
+            jupyter: Enable Jupyter.
+            direct: Enable direct port access.
+            jupyter_dir: Jupyter working directory.
+            jupyter_lab: Use JupyterLab instead of Jupyter Notebook.
+            onstart_cmd: Command to run on startup.
+            search_params: Search parameters for matching offers.
+            disk_space: Recommended disk space.
+            no_default: Disable default query filters.
+
+        Returns:
+            Update confirmation message.
+        """
+        pass
+
+    # Snapshot Methods
+
+    def take_snapshot(
+        self,
+        instance_id: int,
+        repo: str | None = None,
+        container_registry: str = "docker.io",
+        docker_login_user: str | None = None,
+        docker_login_pass: str | None = None,
+        pause: str = "true",
+    ) -> dict[str, Any]:
+        """Take a container snapshot and push to registry.
+
+        Args:
+            instance_id: ID of the instance to snapshot.
+            repo: Docker repository to push snapshot to.
+            container_registry: Container registry URL. Default is 'docker.io'.
+            docker_login_user: Registry username.
+            docker_login_pass: Registry password or token.
+            pause: Pause container during commit ('true'/'false'). Default is 'true'.
+
+        Returns:
+            Snapshot scheduling confirmation.
+        """
+        pass
+
+    # Instance Update Methods
+
+    def update_instance(
+        self,
+        id: int,
+        template_id: int | None = None,
+        template_hash_id: str | None = None,
+        image: str | None = None,
+        args: str | None = None,
+        env: str | None = None,
+        onstart: str | None = None,
+    ) -> dict[str, Any]:
+        """Update instance configuration from a new/updated template.
+
+        Args:
+            id: ID of the instance to update.
+            template_id: New template ID to associate.
+            template_hash_id: New template hash ID to associate.
+            image: New image UUID.
+            args: New arguments for the instance.
+            env: New environment variables.
+            onstart: New onstart script.
+
+        Returns:
+            Update confirmation message.
+        """
+        pass
+
+    # VM Copy Methods
+
+    def vm_copy(self, src: int, dst: int) -> dict[str, Any]:
+        """Copy VM image from one instance to another.
+
+        Note: Destination VM must be stopped during copy. Source VM does not need
+        to be stopped, but it's recommended to stop it for the duration.
+
+        Args:
+            src: Instance ID of the source VM.
+            dst: Instance ID of the destination VM.
+
+        Returns:
+            Copy operation confirmation.
+        """
+        pass
+
+    # Team Member Methods
+
+    def invite_member(
+        self,
+        email: str,
+        role: str | None = None,
+    ) -> dict[str, Any]:
+        """Invite a member to the team.
+
+        Args:
+            email: Email address of the user to invite.
+            role: Role to assign to the invited user.
+
+        Returns:
+            Invitation confirmation message.
+        """
+        pass
+
+    def remove_member(self, id: int) -> dict[str, Any]:
+        """Remove a member from the team.
+
+        Args:
+            id: ID of the team member to remove.
+
+        Returns:
+            Removal confirmation message.
+        """
+        pass
+
+    def show_members(self) -> list[dict[str, Any]]:
+        """Show team members.
+
+        Returns:
+            List of team members.
+        """
+        pass
+
+    # Log Methods
+
+    def get_endpt_logs(
+        self,
+        id: int,
+        level: int = 1,
+        tail: int | None = None,
+    ) -> dict[str, Any]:
+        """Get logs for a serverless endpoint.
+
+        Args:
+            id: ID of the endpoint group to fetch logs from.
+            level: Log detail level (0-3). Default is 1.
+            tail: Number of log lines to return from the end.
+
+        Returns:
+            Endpoint logs.
+        """
+        pass
+
+    def get_wrkgrp_logs(
+        self,
+        id: int,
+        level: int = 1,
+        tail: int | None = None,
+    ) -> dict[str, Any]:
+        """Get logs for a serverless worker group.
+
+        Args:
+            id: ID of the worker group to fetch logs from.
+            level: Log detail level (0-3). Default is 1.
+            tail: Number of log lines to return from the end.
+
+        Returns:
+            Worker group logs.
+        """
+        pass
+
+    def show_audit_logs(self) -> list[dict[str, Any]]:
+        """Show account audit logs.
+
+        Displays history of important actions and IP address accesses.
+
+        Returns:
+            List of audit log entries.
+        """
+        pass
+
+    # Scheduled Job Methods
+
+    def delete_scheduled_job(self, id: int) -> dict[str, Any]:
+        """Delete a scheduled job.
+
+        Args:
+            id: ID of the scheduled job to delete.
+
+        Returns:
+            Deletion confirmation message.
+        """
+        pass
+
+    def show_scheduled_jobs(self) -> list[dict[str, Any]]:
+        """Show scheduled jobs.
+
+        Returns:
+            List of scheduled jobs for the account.
+        """
+        pass
+
+    # Maintenance Methods
+
+    def show_maints(self, ids: str, quiet: bool = False) -> list[dict[str, Any]]:
+        """Show maintenance information for host machines.
+
+        Args:
+            ids: Comma-separated string of machine IDs.
+            quiet: If True, only display numeric IDs. Default is False.
+
+        Returns:
+            Maintenance information for specified machines.
+        """
+        pass
+
+    # Network Disk Methods
+
+    def show_network_disks(self) -> list[dict[str, Any]]:
+        """Show network disks associated with your account.
+
+        Returns:
+            Network disk information grouped by cluster.
+        """
+        pass
+
+    # Invoice V1 Methods
+
+    def show_invoices_v1(
+        self,
+        invoices: bool = False,
+        charges: bool = False,
+        invoice_type: list[str] | None = None,
+        charge_type: list[str] | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        limit: int = 20,
+        next_token: str | None = None,
+        format: str = "table",
+        verbose: bool = False,
+        latest_first: bool = False,
+    ) -> dict[str, Any]:
+        """Show invoices or charges with advanced filtering (v1 API).
+
+        Args:
+            invoices: Show invoices instead of charges.
+            charges: Show charges instead of invoices.
+            invoice_type: Filter by invoice types (transfers, stripe, bitpay, etc.).
+            charge_type: Filter by charge types (instance, volume, serverless).
+            start_date: Start date (YYYY-MM-DD or timestamp).
+            end_date: End date (YYYY-MM-DD or timestamp).
+            limit: Number of results per page (default: 20, max: 100).
+            next_token: Pagination token for next page.
+            format: Output format ('table' or 'tree'). Default is 'table'.
+            verbose: Include full details (tree view only). Default is False.
+            latest_first: Sort by latest first. Default is False.
+
+        Returns:
+            Invoice or charge information based on selected filters.
+        """
+        pass
diff --git a/vastai/vastai_sdk.py b/vastai/vastai_sdk.py
new file mode 100644
index 00000000..d0988715
--- /dev/null
+++ b/vastai/vastai_sdk.py
@@ -0,0 +1,18 @@
+"""
+Backwards-compatibility shim for ``from vastai.vastai_sdk import VastAI``.
+
+The canonical import path is now ``from vastai.sdk import VastAI``
+(or simply ``from vastai import VastAI``).
+"""
+
+import warnings
+
+warnings.warn(
+    "Importing from 'vastai.vastai_sdk' is deprecated. "
+    "Use 'from vastai import VastAI' or 'from vastai.sdk import VastAI' instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+from .sdk import *  # noqa: F401,F403
+from .sdk import VastAI  # explicit re-export for type checkers
diff --git a/vastai_sdk/__init__.py b/vastai_sdk/__init__.py
new file mode 100644
index 00000000..e600fcf6
--- /dev/null
+++ b/vastai_sdk/__init__.py
@@ -0,0 +1,21 @@
+# vastai_sdk/__init__.py
+
+# Backward-compatibility shim: allow "import vastai_sdk" to reference "vastai"
+# This package is deprecated. Use "import vastai" instead.
+
+import sys
+import warnings
+import importlib
+
+warnings.warn(
+    "The 'vastai_sdk' package is deprecated. "
+    "Use 'from vastai import VastAI' instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+# Import the real package
+_vastai = importlib.import_module("vastai")
+
+# Register it under the old name so attribute access works
+sys.modules[__name__] = _vastai