# How to Configure Proxy Settings for Network Requests in PicList-Core

> Learn how to configure proxy settings for network requests in PicList-Core using CLI or programmatically. Ensure all upload traffic uses your specified proxy with these easy steps.

- Repository: [Kuingsmile/piclist-core](https://github.com/kuingsmile/piclist-core)
- Tags: how-to-guide
- Published: 2026-03-05

---

**To configure proxy settings in PicList-Core, set the `picBed.proxy` configuration key via the CLI (`picgo proxy -p <url>`) or programmatically, and the `Request` class will automatically route all upload traffic through the specified proxy.**

PicList-Core (from the `kuingsmile/piclist-core` repository) implements a centralized proxy configuration system that intercepts all network requests. When you configure proxy settings for network requests, the framework reads this value, converts it to an Axios-compatible proxy object, and injects it into every upload operation, including specialized handling for HTTPS-over-HTTP tunneling.

## Where Proxy Configuration is Stored

The proxy setting persists under the configuration key `picBed.proxy`. This value can be set through the built-in CLI command defined in [`src/plugins/commander/proxy.ts`](https://github.com/kuingsmile/piclist-core/blob/main/src/plugins/commander/proxy.ts), which registers the `-p, --proxy <url>` flag:

```typescript
// src/plugins/commander/proxy.ts
cmd.program.option('-p, --proxy <url>', 'set proxy for uploading', (proxy: string) => {
  ctx.setConfig({ 'picBed.proxy': proxy })
})

```

When executed, this command writes the proxy URL directly to the user’s configuration store, making it available for all subsequent network operations.

## How the Proxy is Applied to Network Requests

The `Request` class in [`src/lib/Request.ts`](https://github.com/kuingsmile/piclist-core/blob/main/src/lib/Request.ts) manages proxy application through three distinct mechanisms:

### Initialization

Upon instantiation, the `Request` constructor reads the current configuration:

```typescript
// src/lib/Request.ts (init)
private init(): void {
  const proxy = this.ctx.getConfig<Undefinable<string>>('picBed.proxy')
  if (proxy) {
    this.proxy = proxy
  }
}

```

### Runtime Updates

If the configuration changes while the application is running, an event listener updates the internal proxy field dynamically:

```typescript
// src/lib/Request.ts (listener)
eventBus.on(IBusEvent.CONFIG_CHANGE, (data) => {
  switch (data.configName) {
    case 'picBed':
      if ((data.value as IConfig['picBed'])?.proxy) {
        this.proxy = (data.value as IConfig['picBed']).proxy
      }
      break
    case 'picBed.proxy':
      this.proxy = data.value as string
      break
  }
})

```

### Request-Time Processing

Before each HTTP request, the `handleProxy()` method parses the stored string into an Axios-compatible object:

```typescript
// src/lib/Request.ts (handleProxy)
private handleProxy(): AxiosRequestConfig['proxy'] | false {
  if (this.proxy) {
    try {
      const proxyOptions = new URL(this.proxy)
      return {
        host: proxyOptions.hostname,
        port: parseInt(proxyOptions.port || '0', 10),
        protocol: proxyOptions.protocol,
      }
    } catch {}
  }
  return false
}

```

For HTTPS destinations tunneled through HTTP proxies, the implementation configures a specialized agent:

```typescript
// src/lib/Request.ts (request)
this.options.proxy = this.handleProxy()
…
if (this.options.proxy && options.url?.startsWith('https://')) {
  this.options.httpsAgent = httpsOverHttp({
    proxy: {
      host: this.options.proxy.host,
      port: this.options.proxy.port,
    },
  })
  this.options.proxy = false
}

```

## Configuration Methods

### Using the CLI Command

The simplest way to configure proxy settings for network requests is via the built-in proxy command:

```bash
picgo proxy -p http://127.0.0.1:1080

```

This writes the value to `picBed.proxy` in your configuration file.

### Programmatic Configuration

For plugin development or custom integrations, set the configuration directly through the PicGo context:

```typescript
import PicGo from 'piclist-core'

const ctx = new PicGo()
ctx.setConfig({ 'picBed.proxy': 'http://127.0.0.1:1080' })

```

### Removing the Proxy

To disable proxy routing, delete the configuration key:

```bash
picgo config delete picBed.proxy

```

## Summary

- PicList-Core stores proxy settings under the `picBed.proxy` configuration key
- The `Request` class in [`src/lib/Request.ts`](https://github.com/kuingsmile/piclist-core/blob/main/src/lib/Request.ts) automatically applies these settings to every upload request
- Configuration supports both CLI (`-p, --proxy`) and programmatic (`ctx.setConfig`) methods
- HTTPS-over-HTTP proxying is handled automatically via the `httpsOverHttp` agent
- Runtime configuration changes are detected and applied without requiring a restart

## Frequently Asked Questions

### What URL format should I use for the proxy setting?

PicList-Core accepts standard URL formats such as `http://127.0.0.1:1080` or `http://username:password@proxy.example.com:8080`. The `handleProxy()` method in [`src/lib/Request.ts`](https://github.com/kuingsmile/piclist-core/blob/main/src/lib/Request.ts) parses this using the Node.js `URL` constructor, extracting the `hostname`, `port`, and `protocol` fields for the Axios configuration.

### Does PicList-Core support HTTPS proxies?

Yes. When the target upload URL uses HTTPS, the framework automatically creates an `httpsOverHttp` agent using the proxy host and port, then sets `this.options.proxy = false` to prevent double-proxying. This ensures secure connections route correctly through your HTTP proxy.

### Will proxy settings apply to all upload requests automatically?

Yes. Once `picBed.proxy` is configured, every network request made through the `Request` class will include the proxy configuration. This covers all uploads performed via `picgo upload` commands or programmatic API calls using the core request library.

### How do I verify the proxy is working?

Check your proxy server logs for incoming connections from PicList-Core during uploads, or enable debug logging in your application. The framework applies the proxy immediately after configuration changes through the `IBusEvent.CONFIG_CHANGE` event listener, so changes take effect on the next request without requiring a restart.