# How Lepton Handles Network Proxy Configurations for API Requests

> Learn how Lepton manages network proxy configurations for API requests by reading your .leptonrc file and injecting a centralized ProxyAgent for seamless integration with request-promise.

- Repository: [CosmoX/Lepton](https://github.com/hackjutsu/lepton)
- Tags: internals
- Published: 2026-02-23

---

**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/main/configs/defaultConfig.js)](https://github.com/hackjutsu/Lepton/blob/master/configs/defaultConfig.js). By default, proxy support is disabled with a placeholder address:

```json
"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:

```javascript
const conf = remote.getGlobal('conf')

```

This line appears at the top of [[`app/utilities/githubApi/index.js`](https://github.com/hackjutsu/Lepton/blob/main/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`:

```javascript
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/main/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:

```javascript
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/main/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:

```json
{
  "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/main/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`](https://github.com/hackjutsu/Lepton/blob/main/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`](https://github.com/hackjutsu/Lepton/blob/main/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`](https://github.com/hackjutsu/Lepton/blob/main/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`](https://github.com/hackjutsu/Lepton/blob/main/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.