Configuration

gpulse works out of the box with zero configuration. For advanced tuning, you can create a TOML configuration file to adjust monitoring intervals, detection thresholds, UI preferences, and more.

Config File Location

gpulse looks for configuration files in this order:

  1. Path specified via --config /path/to/file.toml
  2. ./gpu-leak-detector.toml (current directory)
  3. ~/.config/gpulse/config.toml (user config)

If no config file exists, gpulse uses sensible defaults.

Example Configuration

A minimal configuration file with the most commonly tuned options:

toml 
# gpulse configuration
# See: https://gpulse.ai/docs/configuration

[monitoring]
# Sampling interval in seconds (1-3600)
interval-seconds = 30

# Number of memory snapshots to keep for analysis
history-size = 1000

[detection]
# Minimum R² for leak trend significance (0.0-1.0)
min-r-squared = 0.8

# Confidence threshold for leak alerts (0.0-1.0)
confidence-threshold = 0.75

# Minimum samples before analysis starts
minimum-samples = 20

# Analysis window in hours
analysis-window-hours = 1.0

[ui]
# Color theme (see /docs/themes for full list)
theme = "monokai"

# Default view on startup
default-view = "grid"

[alerts]
# Enable leak detection alerts
enabled = true

# Maximum alerts per hour to prevent spam
max-rate-per-hour = 10

Configuration Sections

[monitoring]

Controls how frequently gpulse samples GPU data and how much history it retains.

Option Default Description
interval-seconds 30 Seconds between GPU metric samples (1-3600)
history-size 1000 Number of snapshots to keep in memory (100-10000)
enable-process-attribution true Track per-process GPU memory usage

[detection]

Tune the leak detection algorithm sensitivity.

Option Default Description
min-r-squared 0.8 Minimum R² for trend significance (0.0-1.0)
min-slope-mb-per-sec 1.0 Minimum memory growth rate to flag (MB/sec)
confidence-threshold 0.75 Minimum confidence to trigger an alert (0.0-1.0)
minimum-samples 20 Snapshots required before analysis begins (10-1000)
analysis-window-hours 1.0 How far back to analyze for trends (0.5-24.0)
ignore-patterns [] Regex patterns for process names to exclude from analysis

[ui]

Customize the terminal interface appearance and behavior.

Option Default Description
theme "monokai" Color theme name (see Themes)
default-view "grid" View to show on startup (grid, list, detail, compare, topology, predict)

[alerts]

Configure the alert system for leak detection notifications.

Option Default Description
enabled true Enable or disable the alert system
max-rate-per-hour 10 Maximum alerts per hour to prevent notification fatigue

[gpu]

Hardware discovery and GPU-specific settings.

Option Default Description
gpu-indices [] Specific GPU indices to monitor (empty = all GPUs)
discovery-timeout 30 Timeout for GPU discovery operations in seconds

Environment Variables

You can override any configuration value with an environment variable. The naming convention is:

GPULSE_<SECTION>_<KEY>

Example: [monitoring] interval-seconds = 30 becomes GPULSE_MONITORING_INTERVAL_SECONDS=30

bash 
# Override monitoring interval
export GPULSE_MONITORING_INTERVAL_SECONDS=60

# Override theme
export GPULSE_UI_THEME=dracula

# Override detection confidence
export GPULSE_DETECTION_CONFIDENCE_THRESHOLD=0.9

Command-Line Overrides

Common configuration can also be set via command-line flags, which take highest precedence:

bash 
# Use a specific config file
gpulse dashboard --config /path/to/config.toml

# Override refresh interval
gpulse dashboard --interval 10

# Start in a specific view
gpulse dashboard --view predict

# Monitor specific GPUs only
gpulse dashboard --gpus 0,1

Precedence Order

When multiple sources set the same value, the highest precedence wins:

  1. Command-line flags (highest)
  2. Environment variables
  3. Config file
  4. Built-in defaults (lowest)