ProxyWhirl Docs

Configuration

TOML configuration, environment variables, CLIConfig fields, and validation rules for ProxyWhirl.

Configuration

Complete reference for ProxyWhirl configuration: TOML files, environment variables, and programmatic setup.

See also: Quickstart for initial setup, Proxy Lists for proxy_file exports, and Troubleshooting for config errors.

Discovery Order

  1. Explicit --config path
  2. Project-local ./pyproject.toml[tool.proxywhirl]
  3. User-global ~/.config/proxywhirl/config.toml
  4. Built-in defaults
from pathlib import Path
from proxywhirl.config import discover_config, load_config

config_path = discover_config()
config = load_config(config_path)
config = load_config(Path("./custom-config.toml"))  # explicit

ProxyWhirl uses TOML, not YAML.

TOML Example

[tool.proxywhirl]
rotation_strategy = "round-robin"
timeout = 30
max_retries = 3
cache_enabled = true
cache_default_ttl = 3600
encrypt_credentials = true

[[tool.proxywhirl.proxies]]
url = "http://proxy1.example.com:8080"
username = "user1"
password = "pass1"

[tool.proxywhirl.data_storage]
pool_size = 5
persist_geo_data = false

User-global config (~/.config/proxywhirl/config.toml) uses root-level keys without the [tool.proxywhirl] wrapper.

Environment Variables

Security

VariablePurpose
PROXYWHIRL_KEYMaster Fernet key for credential encryption (default: ~/.config/proxywhirl/key.enc)
PROXYWHIRL_CACHE_ENCRYPTION_KEYOptional cache-tier encryption key
export PROXYWHIRL_KEY=$(python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")

REST API

VariableDefaultPurpose
PROXYWHIRL_REQUIRE_AUTHfalseEnable API key auth
PROXYWHIRL_API_KEYAPI key when auth enabled
PROXYWHIRL_STORAGE_PATH./proxywhirl.dbSQLite path
PROXYWHIRL_STRATEGYround-robinDefault rotation strategy
PROXYWHIRL_TIMEOUT30Request timeout (seconds)
PROXYWHIRL_MAX_RETRIES3Max retry attempts
PROXYWHIRL_CORS_ORIGINS""Comma-separated CORS origins

CLIConfig Fields

Proxy pool & rotation

FieldTypeDefaultNotes
proxieslist[ProxyConfig][]Inline proxy entries
proxy_filePath | NoneNoneOne proxy per line
rotation_strategystrround-robinSee strategy aliases below
health_check_intervalint3000 = disabled

Request & output

FieldTypeDefault
timeoutint30
max_retriesint3
follow_redirectsbooltrue
verify_sslbooltrue
default_formatstrtext (text, json, csv)
colorbooltrue
verboseboolfalse

Cache (three-tier)

FieldDefaultValidation
cache_enabledtrue
cache_l1_max_entries1000
cache_l2_max_entries5000
cache_l3_max_entriesNoneunlimited when None
cache_default_ttl3600>= 60
cache_cleanup_interval60>= 10
cache_l2_dir.cache/proxies
cache_l3_db_path.cache/db/proxywhirl.db
cache_health_invalidationtrue
cache_failure_threshold3>= 1

Rate limiting (API)

FieldDefault
rate_limit_by_keytrue
rate_limit_per_key100/minute
rate_limit_per_ip100/minute

DataStorageConfig (selected)

FieldDefaultNotes
async_drivertrueaiosqlite
pool_size51–100
pool_max_overflow100–100
pool_timeout30.0seconds
persist_geo_datafalseprivacy-sensitive, opt-in
persist_ip_intelligencefalseopt-in
persist_request_logsfalseheavy storage

ProxyConfig

FieldRequiredValidation
urlYeshttp://, https://, socks4://, socks5://
usernameNoAuto-encrypted on save
passwordNoAuto-encrypted on save

Programmatic Usage

from pathlib import Path
from pydantic import SecretStr
from proxywhirl.config import CLIConfig, ProxyConfig, DataStorageConfig, load_config, save_config

config = CLIConfig(
    proxies=[ProxyConfig(url="http://proxy.example.com:8080", username=SecretStr("u"), password=SecretStr("p"))],
    rotation_strategy="weighted",
    timeout=45,
    data_storage=DataStorageConfig(pool_size=10, persist_geo_data=False),
)

save_config(config, Path("./pyproject.toml"))

Validation Rules

Rotation strategies: round-robin, random, weighted, least-used, performance-based, session / session-persistence, geo-targeted, cost-aware. Underscore aliases (round_robin, geo_targeted, …) are accepted.

Numeric constraints:

FieldMinMax
cache_default_ttl60
cache_cleanup_interval10
max_error_history0100
max_health_transitions0500
pool_size1100

Preset Profiles

Minimal:

[tool.proxywhirl]
rotation_strategy = "round-robin"
[[tool.proxywhirl.proxies]]
url = "http://proxy.example.com:8080"

High performance: weighted strategy, timeout = 10, larger connection pool, disable heavy persistence.

Privacy-focused: encrypt_credentials = true, cache_enabled = false, all geo/IP persistence off.

Security Notes

  • Config files are created with mode 600.
  • Enable PROXYWHIRL_REQUIRE_AUTH and a strong PROXYWHIRL_API_KEY for REST deployments.
  • Regenerating key.enc makes old encrypted credentials unrecoverable.

Troubleshooting Config

config_path = discover_config()
print("No config" if config_path is None else f"Using {config_path}")

Common TOML mistake — nested tables use section headers, not =:

# Wrong: [tool.proxywhirl.data_storage] = {...}
# Right:
[tool.proxywhirl.data_storage]
persist_geo_data = false

See Also

On this page