How Lepton Handles Network Proxy Configurations for API Requests

Lepton reads proxy settings from the user's .leptonrc configuration file and injects a centralized ProxyAgent instance into every GitHub API request made via the request-promise library.

Lepton is an open-source GitHub Gist client built on Electron that synchronizes code snippets across devices. For users operating behind corporate firewalls or restrictive network environments, understanding how Lepton manages network proxy configurations for API requests is essential to ensuring uninterrupted access to GitHub's services. The implementation centralizes proxy handling within the GitHub API utility module, requiring no per-request code changes from developers.

Configuration via .leptonrc

Lepton stores proxy settings in a JSON-based configuration system that layers default values with user-specific overrides.

Default Configuration Structure

The base configuration defines the proxy schema in [configs/defaultConfig.js](https://github.com/hackjutsu/Lepton/blob/master/configs/defaultConfig.js). By default, proxy support is disabled with a placeholder address:

"proxy": {
    "enable": false,
    "address": "socks://localhost:1080"
}

Users override these values by creating a ~/.leptonrc file in their home directory. Lepton uses the nconf library to merge these configurations at runtime, with user settings taking precedence over defaults.

Loading Configuration in the Main Process

In the Electron main process, Lepton exposes the configuration object globally. The GitHub API module accesses these settings via Electron's remote module:

const conf = remote.getGlobal('conf')

This line appears at the top of [app/utilities/githubApi/index.js](https://github.com/hackjutsu/Lepton/blob/master/app/utilities/githubApi/index.js#L10-L12), ensuring the proxy configuration is available to all API methods.

Implementing the ProxyAgent

The GitHub API module conditionally instantiates a ProxyAgent based on the loaded configuration. This occurs once during module initialization, creating a reusable agent for all subsequent requests.

Conditional Agent Creation

When the module loads, it checks the proxy:enable flag. If enabled, it constructs a ProxyAgent using the URI specified in proxy:address:

import ProxyAgent from 'proxy-agent'

let proxyAgent = null
if (conf && conf.get('proxy:enable')) {
  const proxyUri = conf.get('proxy:address')
  proxyAgent = new ProxyAgent(proxyUri)
  logger.info('[.leptonrc] Use proxy', proxyUri)
}

This logic, found at [lines 15-21 of app/utilities/githubApi/index.js](https://github.com/hackjutsu/Lepton/blob/master/app/utilities/githubApi/index.js#L15-L21), ensures the agent is only created when explicitly requested by the user.

Injecting Proxies into HTTP Requests

Once instantiated, the proxyAgent is injected into every HTTP request to the GitHub API. Lepton uses the request-promise library (aliased as ReqPromise) for asynchronous operations, though the underlying request library handles the actual socket creation.

Request-Level Agent Assignment

Every API helper function includes the agent property in its request options. For example, when fetching a user profile:

return ReqPromise({
  uri: USER_PROFILE_URI,
  agent: proxyAgent,
  headers: { ... },
  method: 'GET',
  json: true,
  timeout: 2 * kTimeoutUnit
})

This pattern appears at [lines 48-50 of app/utilities/githubApi/index.js](https://github.com/hackjutsu/Lepton/blob/master/app/utilities/githubApi/index.js#L48-L50). The same agent: proxyAgent assignment is used consistently across all API interactions, including exchangeAccessToken, getSingleGist, makeOptionForGetAllGists, and createSingleGist.

Universal Proxy Application

Because the proxyAgent variable is defined at the module scope, all API methods share the same agent instance. This design ensures that network proxy configurations apply transparently to every request without requiring individual function modifications.

Enterprise Mode Compatibility

Lepton supports GitHub Enterprise installations through a separate enterprise configuration section. When enterprise:enable is set to true, the API module swaps the base host URL for GitHub API calls. However, the proxy handling remains identical—the same proxyAgent instance is reused regardless of whether the target is GitHub.com or an Enterprise instance, ensuring consistent network behavior across deployment modes.

Practical Configuration Examples

To enable proxy support, create or edit ~/.leptonrc in your home directory:

{
  "proxy": {
    "enable": true,
    "address": "http://proxy.mycompany.com:3128"
  }
}

Lepton supports standard proxy URI formats including http://, https://, and socks:// protocols. After saving the configuration, restart the application. The main process logs proxy activation during startup:

[.leptonrc] Use proxy http://proxy.mycompany.com:3128

This log entry confirms that [app/utilities/githubApi/index.js](https://github.com/hackjutsu/Lepton/blob/master/app/utilities/githubApi/index.js#L20-L21) has successfully initialized the proxy agent.

Summary

• Centralized Configuration: Proxy settings are defined in .leptonrc and managed through configs/defaultConfig.js, allowing users to override defaults without modifying source code.
• Single Agent Instance: The ProxyAgent is instantiated once in app/utilities/githubApi/index.js based on the proxy:enable flag and proxy:address value.
• Universal Injection: Every GitHub API request made via request-promise includes the agent: proxyAgent option, ensuring all traffic routes through the configured proxy.
• Protocol Support: Lepton supports HTTP, HTTPS, and SOCKS proxies through the proxy-agent library.
• Enterprise Ready: The proxy implementation works identically for both GitHub.com and GitHub Enterprise installations.

Frequently Asked Questions

Where does Lepton store proxy configuration settings?

Lepton stores proxy configuration in the user's home directory inside a file named .leptonrc. This file overrides the default settings defined in configs/defaultConfig.js. The configuration uses JSON format with a proxy object containing enable (boolean) and address (string) properties.

What proxy protocols does Lepton support?

Lepton supports any proxy protocol compatible with the proxy-agent npm package, including HTTP (http://), HTTPS (https://), and SOCKS (socks://). The default configuration demonstrates SOCKS with socks://localhost:1080, but HTTP proxies like http://proxy.company.com:8080 are equally valid.

Does Lepton require code changes to use a proxy?

No code changes are required. Once you set proxy.enable to true and specify proxy.address in your .leptonrc file, Lepton automatically creates the ProxyAgent and injects it into all API requests. The application handles proxy routing transparently for all GitHub API interactions.

How can I verify that Lepton is using my proxy settings?

Check the application logs for the message [.leptonrc] Use proxy followed by your proxy URI. This log entry is generated in app/utilities/githubApi/index.js when the module initializes and confirms that the ProxyAgent is active. If this message does not appear, verify that your .leptonrc file is valid JSON and located in your home directory.

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