nvcurve/docs/Overview.md

NVCurve

NVCurve is a Linux-based voltage-frequency (V/F) curve editor and overclocking tool for NVIDIA GPUs. It brings per-point V/F curve control — similar to MSI Afterburner on Windows — directly to Linux, using undocumented NvAPI functions exposed through libnvidia-api.so.

What It Does

At its core, NVCurve lets you adjust the frequency offset for any voltage point on your GPU's V/F curve. This gives you fine-grained control over how your GPU clocks at different voltage levels, enabling both performance-oriented overclocking and efficiency-oriented undervolting.

Two Interfaces, One Tool

NVCurve provides two ways to interact with your GPU:

• Web UI — A modern React-based interface with an interactive curve graph, real-time hardware monitoring, point table editor, and profile management. This is the primary interface for most users.
• CLI — A Python command-line tool for scripting, headless systems, automation, and quick one-off operations. Works independently of the web server.

Key Capabilities

• Per-Point Curve Editing — Adjust the frequency offset for any individual voltage point on the V/F curve.
• Extended Memory Offset — Memory clock offset up to +3000 MHz (Blackwell GPUs). Standard NVCurve caps at +1000 MHz.
• Fan Curve Control — Custom temperature-to-fan-speed curves via NVML, adjustable through the web UI and savable in profiles.
• Curve Flattening — Select multiple points and flatten them to a common frequency using anchor-point targeting.
• Live Monitoring — Track GPU voltage, clock speed, temperature, and power draw in real time via NvAPI and NVML.
• Profile Management — Save, load, and switch between named profiles. Set a default profile that auto-applies on startup.
• Multi-GPU Support (experimental) — Manage multiple NVIDIA GPUs from a single server instance with a GPU selector in the web UI.
• Snapshots — Automatic snapshot-and-restore before every write, so you can always revert changes.

Architecture

NVCurve consists of two components:

Component	Description
Python Backend	Talks directly to libnvidia-api.so (via ctypes) and libnvidia-ml.so to read and write GPU hardware state. Exposes functionality through a FastAPI REST + WebSocket server.
React Frontend	Runs in the browser and communicates with the backend over HTTP and WebSockets. Handles curve visualization, point editing, live monitoring, and profile management.

The backend keeps all privileged operations isolated from the browser. The CLI can operate entirely standalone, bypassing the server for direct hardware access.

Important Notes

Experimental Software — NVCurve uses undocumented NvAPI functions that may change between driver releases. It has been tested on a range of NVIDIA GPUs including RTX 5090 (Blackwell), but compatibility is not guaranteed on all hardware/driver combinations.

Read vs. Write Safety — Read operations are generally safe. Write operations alter live GPU operational parameters. Always run the hardware compatibility check (nvcurve setup) before applying changes.

Requirements

• OS: Linux
• GPU: NVIDIA GPU with a supported driver
• Python: 3.12 or later
• Privileges: Root access for hardware interactions (CLI prompts for sudo when needed)