How to Set the Proxy Configuration for ModLens API Providers

ModLens routes API requests through HTTP proxies defined either globally in ~/.modlens/config.json, per-provider via nested configuration keys, or through standard environment variables like HTTPS_PROXY, with provider-specific settings always taking precedence.

ModLens is an open-source CLI tool for interacting with AI API providers. Setting the proxy configuration for ModLens API providers ensures reliable connectivity when operating behind corporate firewalls or routing traffic through intermediary gateways.

Global Proxy Configuration

The global proxy applies to every provider that does not define its own proxy setting. According to the liustack/modlens source code, the configuration loader in src/config.ts reads the top-level proxy key and copies it to any provider lacking an explicit definition (lines 258‑260).

# Set a global proxy for all providers

modlens config set proxy http://proxy.example.com:8080

When present, this URL becomes the default dispatcher for all outgoing requests unless overridden at the provider level.

Provider-Specific Proxy Configuration

You can override the global setting for individual providers by specifying a proxy under the provider’s namespace. In src/config.ts, the configuration merge logic treats a provider’s proxy field as authoritative, ignoring the global value when the provider-specific key exists (lines 277‑281).

# Set a proxy only for the OpenAI provider

modlens config set openai.proxy http://openai-proxy.example.com:3128

This allows you to route sensitive providers through dedicated gateways while sending other traffic through the global proxy.

Configuration Precedence and Resolution

ModLens resolves proxy settings through a strict precedence chain implemented in src/net/proxy.ts:

1. Provider-level proxy (e.g., openai.proxy)
2. Global proxy defined at the root of config.json
3. Environment variables (HTTPS_PROXY, HTTP_PROXY, https_proxy, http_proxy)

When an effective proxy URL is determined, the apiFetch wrapper constructs a ProxyAgent from Undici and injects it into the request dispatcher (lines 22‑24). If no configuration is found, the system falls back to standard environment variables (lines 26‑28) before connecting directly to the endpoint.

CLI Commands for Proxy Setup

Use the built-in configuration CLI to persist proxy settings without manually editing JSON:

# Configure global proxy

modlens config set proxy http://proxy.example.com:8080

# Configure provider-specific proxy (overrides global)

modlens config set openai.proxy http://openai-proxy.example.com:3128

# Verify effective configuration

modlens config show

# Execute a request using the resolved proxy

modlens -i screenshot.png -p openai

Environment Variable Fallback

If you prefer not to commit proxy URLs to the configuration file, ModLens detects standard proxy environment variables. As implemented in src/net/proxy.ts, the dispatcher checks for HTTPS_PROXY, HTTP_PROXY, and their lowercase variants (lines 26‑28).

export HTTPS_PROXY="http://proxy.example.com:8080"
modlens -i screenshot.png -p gemini-api

This approach is ideal for ephemeral environments or CI/CD pipelines where configuration files are not persisted.

Security Considerations

Proxy URLs containing authentication credentials are automatically redacted in logs. The src/util/redact.ts utility parses proxy strings to mask usernames and passwords before writing to stdout or logfiles, preventing accidental credential leakage in shared environments.

Summary

• Global proxy: Set via modlens config set proxy and stored at the root of ~/.modlens/config.json; applies to all providers without specific overrides.
• Provider-specific proxy: Set via modlens config set <provider>.proxy; takes precedence over global settings as enforced in src/config.ts.
• Resolution order: Provider config > Global config > Environment variables (HTTPS_PROXY, HTTP_PROXY) > Direct connection.
• Implementation: Proxy agents are constructed in src/net/proxy.ts using Undici’s ProxyAgent dispatched at lines 22‑24.
• Logging safety: Credentials embedded in proxy URLs are sanitized by src/util/redact.ts before output.

Frequently Asked Questions

How do I set a global proxy for all ModLens providers?

Run modlens config set proxy <url> to write the proxy URL to the top-level proxy key in ~/.modlens/config.json. This value is inherited by every provider unless they define their own proxy setting, as handled by the merge logic in src/config.ts (lines 258‑260).

Can I use different proxies for different API providers?

Yes. Use the command modlens config set <provider>.proxy <url> to define a provider-specific proxy. According to the source in src/config.ts (lines 277‑281), provider-level settings override the global configuration, allowing you to route OpenAI traffic through one gateway and Gemini through another.

What environment variables does ModLens check for proxy settings?

ModLens checks HTTPS_PROXY, HTTP_PROXY, https_proxy, and http_proxy as fallbacks when no configuration file settings exist. This behavior is implemented in src/net/proxy.ts (lines 26‑28) and follows standard Node.js conventions.

How does ModLens handle proxy authentication credentials?

You may embed credentials directly in the proxy URL (e.g., http://user:pass@proxy.example.com:8080). The src/util/redact.ts module automatically detects and masks these credentials in log output, ensuring that sensitive authentication details are not exposed in console history or logfiles.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}