proxy.md

Proxy

AIUsage.NET can route provider HTTP requests through an optional proxy.

• Supported fully: http://, https://
• Read but degraded: socks5:// (see Limitation below)
• Config file: ~/.aiusage/config.json (resolves to %USERPROFILE%\.aiusage\config.json)
• Default: off
• UI: none — file only

Config file

{
  "proxy": {
    "enabled": true,
    "url": "http://127.0.0.1:8080"
  }
}

Authenticated proxies put credentials in the URL:

{
  "proxy": {
    "enabled": true,
    "url": "http://user:pass@proxy.example.com:8080"
  }
}

When the URL has no port, the scheme's default applies (socks5 → 1080, http → 80, https → 443).

Behavior

• The config is read once at process startup — restart the tray app (or the CLI invocation) after changing the file.
• localhost, 127.0.0.1, and ::1 always bypass the proxy.
• A missing, disabled, invalid, or unreadable config simply leaves proxying off.

Limitation

System.Net.Http.HttpClientHandler (the underlying .NET HTTP stack) has no native SOCKS5 support — this is a platform limitation, not a design choice. A socks5:// URL in the config is parsed and accepted, but ProxyConfig.ToWebProxy() builds a plain WebProxy from it, which only works correctly for HTTP/HTTPS. If you need SOCKS5, route through a local HTTP-to-SOCKS bridge, or use an http:///https:// proxy instead. See PORTING_NOTES.md for the option of adding a dedicated SOCKS5 library later.

Scope

Applies to provider HTTP requests made by the app, including the hourly model pricing refresh. It is not a system-wide proxy.