Firefox Proxy Switcher

Proxy Switcher is a Firefox WebExtension that routes requests for selected domains through HTTP or SOCKS5 proxies. Settings and proxy credentials stay in Firefox local extension storage.

Features

• Configure a different proxy for each domain.
• Use HTTP or SOCKS5 proxies.
• Store optional proxy username and password per domain.
• Save reusable proxy profiles.
• Enable or disable a configured domain from the popup.
• Search domains and filter them by tags.
• Choose a System, Light, or Dark theme in Advanced Settings.
• Use the same theme in the options page and popup.
• Run on Firefox desktop and Firefox Android versions that support the declared minimum version.
• Build a separate Manifest V3 package for Chrome and Chromium-based desktop browsers.

How it works

On Firefox, the background script listens to browser.proxy.onRequest. On Chrome and Chromium, the background service worker generates a PAC script through chrome.proxy.settings. Both implementations extract the request host and route only enabled matching domains; all other domains use a direct connection. Proxy authentication is supplied only when the matching domain has credentials.

The extension does not collect browsing history or send configuration to a server. Domain entries, profiles, theme selection, and credentials are saved with browser.storage.local. The extension does not implement an additional encryption layer, so protect the Firefox profile and device that contain the data.

Use the popup

1. Open a website and click the Proxy Switcher toolbar button.
2. If the domain already has a configuration, use Use proxy for this domain to enable or disable it.
3. For a new domain, enable the switch, enter the proxy host and port, then select Apply & Reload.
4. Open Advanced Settings for the complete domain and profile manager.

Advanced Settings

The options page provides:

• Proxy profiles that can be reused while editing domains.
• Domain entries with proxy type, host, port, optional credentials, tags, and enabled state.
• Search and tag filtering.
• Bulk deletion of domains, profiles, or all extension data.
• Theme selection: System, Light, or Dark.

Permissions

The manifest requests these permissions:

• proxy — route requests through the selected proxy.
• storage — store domains, profiles, theme, and credentials locally.
• tabs and activeTab — identify the active tab's domain and reload it after changes.
• webRequest and webRequestBlocking — provide proxy authentication credentials.
• <all_urls> — apply the domain routing policy to web requests.

These permissions are used for proxy management. The extension does not collect or transmit data.

Installation

Firefox desktop

For a temporary development install:

1. Open about:debugging#/runtime/this-firefox.
2. Select Load Temporary Add-on.
3. Choose manifest.json or a freshly built XPI.

For a normal install, use an XPI signed by Mozilla/AMO. Firefox may reject an unsigned or stale-signed package.

Firefox Android

Firefox Android requires a signed extension package. Submit the build through addons.mozilla.org/developers and download the signed XPI after review, or follow Mozilla's self-distributed extension instructions. The manifest includes browser_specific_settings.gecko_android so AMO can mark the extension as Android-compatible.

The manifest targets Firefox Android 113 or newer. The proxy.onRequest API is supported there, but the extension still needs to be tested on the target Firefox version and device.

Chrome and Chromium desktop

Chrome and Chromium do not use the Firefox proxy API, so the project includes a separate Manifest V3 package. It works on desktop Chrome, Chromium, Edge, Brave, Opera, and other Chromium browsers that expose the chrome.proxy API. Chrome Android and Chrome iOS do not support installing ordinary extensions; this project cannot enable extensions on those platforms.

Build and install the unpacked package:

make build-chrome

Then open chrome://extensions (or the equivalent page), enable Developer mode, and select Load unpacked using a directory containing the Chrome build. The ZIP at web-ext-artifacts/proxyswitcherforkbywt-chrome.zip can be uploaded to the Chrome Web Store or unpacked for local testing.

The Chrome build uses a PAC script because Chrome's proxy API is global rather than Firefox's per-request proxy.onRequest API. Changing a proxy configuration regenerates that PAC script. Chrome proxy credentials are provided through webRequest.onAuthRequired.

Build

Install web-ext, then run:

make build

The package is created at web-ext-artifacts/proxyswitcherforkbywt.xpi. This local build is not an AMO signature. After changing any file, rebuild and sign again; do not reuse old META-INF signature files.

For Chrome/Chromium, run make build-chrome. That creates web-ext-artifacts/proxyswitcherforkbywt-chrome.zip from manifest.chrome.json and the shared UI files.

GitHub Actions release publishing

.github/workflows/release.yml builds both packages on every push. The run exposes a downloadable extension-packages-<commit> artifact containing the Firefox XPI and Chrome ZIP. When a GitHub Release is published, it checks that both manifests match the release tag, submits the Firefox package to AMO for signing and review, uploads and submits the Chrome package through the Chrome Web Store API v2, and attaches the signed Firefox XPI and Chrome ZIP to the release card.

Configure these repository or environment secrets before publishing:

• AMO_JWT_ISSUER and AMO_JWT_SECRET — AMO API credentials for web-ext sign.
• CWS_PUBLISHER_ID and CWS_EXTENSION_ID — Chrome Web Store publisher and existing item IDs.
• CWS_CLIENT_ID, CWS_CLIENT_SECRET, and CWS_REFRESH_TOKEN — Google OAuth credentials with Chrome Web Store API access.

The stores must already contain their initial listings and required privacy information. Store review still applies; the workflow submits the update and does not bypass review. Never commit any of these credentials.

To remove generated packages:

make clean

Validation

node --check background.js
node --check config-manager.js
node --check popup.js
node --check options.js
python -m json.tool manifest.json >/dev/null

Project version

Current version: 1.0.1