Introduction

First released in 2006, FoxyProxy is the original proxy switching tool, used by millions daily!
To support this free software, please donate or buy VPN/Proxy Servers in over 100 countries (including such remote places as Reunion Island).

If you upgraded from a previous version, and your proxy settings are missing, please import them.

Unified Code

FoxyProxy 8.* code has been unified for Chrome & Firefox, and Standard & Basic versions.

Users can import/export settings between all above mentioned.

FoxyProxy uses user-agent to identify browser-specific code and altering the user-agent at browser level (not webpage level) can interfere with its operation.

Private Browsing Permission

Chrome

On Chrome, users must enable "Allow in Incognito", if proxying in incognito mode is required

How to: Extensions in Incognito mode

Firefox

On Firefox, users must enable "Run in Private Windows", as it is required by Firefox for proxy settings

How to: Enabling or disabling extensions in private windows

Non-Destructive Editing

Editing & importing are non-destructive. Save must be clicked to apply changes.

See also: Destructive vs Nondestructive Editing

Proxy Authentication

• HTTP/HTTPS proxy servers authentication (Chrome/Firefox)
• SOCKS5 proxy servers authentication (Firefox only)
• Port-specific authentication
  There can be different user/pass for example.com:3128 & example.com:443

Proxying Order

• localhost passthrough
• Global Exclude
• Tab Proxy (Firefox only)
• Incognito Proxy
• Container Proxy (Firefox only)
• Individual Proxy or Proxy by Patterns

Proxy by Patterns Order

• Active proxies are checked in order
• If one of exclude patterns matches, then that proxy is skipped
• If one of include patterns matches, then that proxy is used, otherwise the next proxy is checked

Share Preferences

Unified code for FoxyProxy & FoxyProxy Basic, on both on Chrome & Firefox, enables users to share their preferences.

Light/Dark Theme

FoxyProxy's theme is based on the browser's default light/dark theme.

Firefox on Android

Support is experimental and based on user feedback.

Show Hidden Elements

Some elements on the Toolbar Popup and Options page are disabled or hidden in FoxyProxy Basic and/or on Chrome.
You can toggle to view/enable them by clicking the FoxyProxy icon (on the top of the page).

How to Use

Toolbar Icon

• Grey icon indicates proxying is handled by another extension
• Icons badge indicates selection
• Mouse-over title displays selection details

Toolbar Popup

Changing options is disabled on managed storage.

Proxy by Patterns

Connections are proxied based on patterns

If there are no patterns that match the URL being loaded, connections are made without a proxy

Patterns are not applicable in remote PAC type (but apply to Store Locally)

Disable or Direct

Normal proxying is set to system and handled by the browser

Individual Proxy

Connections are passed through the selected proxy (or PAC)

▶ More

Show or hide additional options

User choice is temporarily stored in localStorage (not available in Private/Incognito)

Search Filter

Proxy Title, Hostname, & Port are searched and display filtered based on the input value (case-insensitive)

Use :port to filter by port

Quick Add

Add current page's host pattern to the selected proxy's include

Only top 10 active proxies are listed

Exclude Host

Add host (with its protocol) to the Global Exclude

Set Tab Proxy (Firefox only)

Select a proxy from the drop-down list for the current tab

Click button to set

Tab Proxy is processed before normal proxy settings

Only top 10 active proxies are listed

Toolbar badge shows the proxy and mouse-over title displays the selection details

Unset Tab Proxy (Firefox only)

Unset proxy for the current tab

Options

Open the Options page

IP

Get IP from FoxyProxy servers

Location

Open FoxyProxy site in a new tab to show location as well as any WebRTC leaks

Keyboard Shortcut (not available on Android)

You can change/set keyboard shortcuts.

Chrome

Go to: chrome://extensions/shortcuts

Firefox

Click the menu button ☰, click Add-ons and Themes and select Extensions.

Click the Tools for all add-ons cogwheel.

Click Manage Extension Shortcuts in the menu.

You will see the shortcut options (if available) for your installed add-ons.

See also: Manage extension shortcuts in Firefox

Options

Some options are not available in Chrome, but have been left for when sharing preferences between Chrome & Firefox.

Enable Storage Sync

Enable to sync storage if it is under 100KB. If the storage is over 100KB, there will be a notification and the Sync will be turned off automatically to avoid repeated errors.

storage.sync is not supported on Firefox for Android.

• Sync is disabled on managed storage
• At the moment, Firefox does not support sync to Firefox on Android
• Mode & Sync option is not synced to give users choice on different machines

For Firefox a user must have Add-ons checked under the "Sync Settings" options in "about:preferences".

The main use case of this API is to store preferences about your extension and allow the user to sync them to different profiles. You can store up to 100KB of data using this API. If you try to store more than this, the call will fail with an error message. The API is provided without any guarantees about uptime or performance.

storage.sync

Storage quotas for sync data

• Maximum total size 102,400 bytes (100KB)
• Maximum item size 8,192 bytes (8KB)
• Maximum number of items 512

Auto Backup

Automatically backup settings to the browser configured downloads folder on save

Limit WebRTC (requires "privacy" permission)

Toggle WebRTC browser settings as it has been known to leak real IP

Toggle changes the browser preferences and does not require SAVE.

Incognito/Container

Set a proxy for Incognito (Private Mode) and/or Containers

Incognito proxy behaviour is slightly different in Chrome and Firefox.

• Only active proxies are listed
• Set proxy will clear if it is deleted or deactivated
• Patterns are not applicable in incognito/container settings
• Incognito/Container are processed independently, therefore they function even with normal operation set to "Disable"

Chrome

Only Incognito option is available

If incognito is not set, normal settings apply to both regular and incognito windows

Firefox

Incognito/Container are processed before standard proxy settings (and after Tab Proxy)

Generic names are used for containers since getting their details requires "contextualIdentities" permissions which would enable containers automatically for the user ⓘ

Keyboard Shortcut (not available on Android)

Preselect a proxy to associate with a keyboard shortcut action

• Only active proxies are listed
• Set proxy will clear if it is deleted or deactivated

Global Exclude

List of hosts that should not be proxied

• Connections to localhost, 127.0.0.1/8, and ::1 are never proxied (by the browser)
• The passthrough implementation is slightly different in Chrome and Firefox
• Entries can be separated by comma (as in Firefox), or space, or new line
• The tables shows if the process is handled by the browser or FoxyProxy
• Supported formats are listed under passthrough in each section
• Scheme is supported by FoxyProxy and Chrome, but not Firefox (PAC URL)
• CIDR only applies to URLs that are IP literals and does not block hostnames that resolve to the IP address range (10.0.0.0/8 is not "no proxy for intranet hostnames")
• Only IPv4 CIDR is implemented by FoxyProxy
• The literal string <local> matches simple hostnames (no dots)
• A leading "." is interpreted as a "*."
• host without a wildcard is the most compatible format

See also

• Chrome Bypass list
• Proxy bypass rules
• Implicit bypass rules
• No Proxy for
• Connection settings in Firefox
• Firefox passthrough

Delete Browser Data

Delete cookies, indexedDB storage, DOM local storage

Restore Defaults

Restore all FoxyProxy settings to default values

Browser settings are not changed (e.g. previously set proxy values or Limit WebRTC).

Preferences: Import/Export

You can import/export Preferences (for backup or sharing) from/to a local file on your computer.

Import is non-destructive. Click Save to apply the changes.

Save

Please note that changes will not take effect until they are saved.

Save is disabled on managed storage.

Proxies

FoxyProxy identifies proxies by their "hostname:post" or PAC URL.

In case more than one proxy with the same "hostname:post" is needed, one or more letters can be added to the port to separate them, and FoxyProxy will remove the letters later. (v8.8) (Firefox only, not practical on Chrome)

127.0.0.1:9050
127.0.0.1:9050a
127.0.0.1:9050b
127.0.0.1:9050c

The augmented port method is only only available for SOCKS & HTTPS (not HTTP, due to the limitation of the Firefox API).
For Unix Domain Sockets, where port is ignored, only numbers should be used.

Another solution is to prepend hostnames where possible e.g. <sometext>.localhost since they all resolve to 127.0.0.1 internally.

Proxy

Add

Add a new proxy entry

Search Filter

Proxy Title, Hostname, & Port are searched and display filtered based on the input value (case-insensitive)

Use :port to filter by port

Get Location (optional)

Get location details for proxies from FoxyProxy Servers

Individual Proxy

If FoxyProxy is to set to use an Individual Proxy/PAC, editing proxy's hostname, port, or PAC URL, may result in a mismatch until it is set again.

Toggle Button

Toggle proxy active or inactive

Inactive proxies do not show in the toolbar popup select

⎘ Duplicate Proxy

Click to duplicate proxy and its patterns

Delete

Delete the proxy and its patterns

Up/Down Triangle

Move the proxy up or down

Title

Set the proxy title

Type

HTTP/HTTPS/SOCKS4/SOCKS5 to be used with hostname & port

PAC to be used with PAC URL

QUIC (HTTP/3) proxy is only supported by Chrome (not available on Firefox). Support for QUIC proxies in Chrome is currently experimental and not ready for production use. ⓘ

Country

Set the proxy country flag

City

Set the proxy city

Color

Set the proxy color

Hostname & Port

Required for HTTP/HTTPS/SOCKS type

Username & Password

To be used for HTTP/HTTPS/SOCKS types

SOCKS5 username & password is only supported by Firefox (not available on Chrome)

If not set, HTTP/HTTPS authentication will be handled by the browser

Username & Password are port specific and different ones can be set for different ports

Proxy DNS (Firefox only)

Option to pass DNS to the SOCKS proxy when using SOCKS

See also:

• Proxy DNS by default when using SOCKS v5 (Firefox 123)
• DNS leaks with proxy extension
• Firefox queries DNS of Proxy destination
• Despite the fact that DNS over HTTPS is switched off on Privacy and Security bar in Settings it still leaks my DNS
• Impossible to use proxies with DoH
• DNS search domain bypassing SOCKS proxy
• "Proxy DNS when using SOCKS v5" should be greyed out when "Enable DNS over HTTPS" is enabled

PAC URL (not available on Android)

Required for PAC type

Proxy Auto-Configuration file (PAC) can be used to handle all proxying configurations

PAC is a configuration file, not a proxy server

Patterns are not applicable in PAC type

See also: Proxy Auto-Configuration (PAC) file

Store Locally (Chrome only)

Option to store PAC locally

Option should only be used for altering remote PAC rules

Storing large or many PACs locally is not recommended and can prevent browser sync

There are limits on the overall PAC length when set locally (could be 512kb)

Individual Proxy

• All PACs will be set as remote PAC, regardless of the checkbox state

Proxy by Patterns

• Locally stored PACs will be processed in order, after processing other proxy patterns

View

Click to fetch and display the remote PAC

DNS (Domain Name System) Resolution

Following table demonstrates the DNS resolution when a proxy is used.

Local Servers

FoxyProxy can be used with local proxy servers:

• Go to Proxy tab ➤ Add a new proxy
• Fill the details according to own preference e.g. Title: TOR
• Add patterns to limit to some URLs only

Patterns

Add patterns to be used in "Proxy by Patterns"

Duplicate patterns will be removed.

📥 Import

Import patterns that were exported

📤 Export

Export patterns to import later

Quick Add

Add ready-made patterns

Plain Host matches hostnames that contain no dots, e.g. http://intranet/

Include/Exclude

Select to include or exclude URL that matches the pattern

Type

Select Wildcard or Regular Expression

Title

Set the pattern title

Pattern

Set the pattern

Enable

Enable/disable the pattern

Selectors only show enabled patterns

Delete

Delete the pattern

Pattern Guide

• Patterns can be Wildcard (globs) or Regular Expression
• Patterns can be full or partial match which means it can match the entire URL or only part of it
• Include ://... to ensure it matches the host
• In practice, including URL pathname with host is rarely necessary

Wildcard

A glob is just a string that may contain wildcards

There are two types of wildcard, and you can combine them in the same glob:

1. * matches zero or more characters
2. ? matches exactly one character

Leading or trailing * is not necessary

Regular Expression

Regular expressions are created using new RegExp() so there is no need to escape forward slashes

There is no need to double escape special characters (already happens when saved to storage)

Bulk Edit

Bulk edit examples for the advanced users

• Go to the Options ➢ Proxies
• Open Developer Tools (F12) or (Ctrl+Shift+I)
• Go to the Console tab
• Paste the following Code (edit as required)
• Hit Enter
• Click SAVE to apply changes

Import

FoxyProxy Account

Import proxies from FoxyProxy account

Imported content will be added to the existing proxies

Import from URL

Import preferences (as valid JSON) from a remote URL

Imported content will be added to the existing proxies

Proxy List

Imported content will be added to the existing proxies

Simple

1.2.3.4:1080
example.com:443
example.com:3128:user:pass

Extended

All applicable parameters can be passed as search parameters (case-insensitive) (v8.0+)
e.g. active, title, color, type (http, https , socks4, socks5, pac), username, password, cc, city

http://1.2.3.4:1080
https://example.com:443
http://user:pass@1.2.3.4?color=663300
socks5://100.10.11.12:1080?title=China&cc=CN&city=Beijing
https://user:password@78.205.12.1:21?color=ff00bc&title=work%20proxy

https://example.com:443?active=false&title=Work&username=abcd&password=1234&cc=US&city=Miami
http://pac-url.com/etc?type=pac&title=Work PAC&color=663300

Import from older versions

Import older settings JSON (e.g. FoxyProxy_YYYY-MM-DD.json)

Old foxyproxy.xml format can be imported in FoxyProxy v7.5.1 and then exported as JSON

Pattern Tester

1. Enter URL to test
2. Select the pattern type
3. Enter pattern details
4. Click Test when ready
5. Result will be match ✅ or fail ❌

Log (Firefox mainly) (limited on Chrome v8.9)

• Live Log displays the web requests in reversed order (new one on top)
• It will continue to display while the Options page is open and will stop logging as soon as the page is closed
• Log data is not stored
• Patterns will show if FoxyProxy was in Proxy by Patterns mode when the log page is loaded (refresh if necessary)
• Limited logging on chrome since Chrome webRequest.onBeforeRequest API does not provide proxyInfo (and some others)
  • No Incognito or Container data on Chrome
  • No proxy data on Chrome

Enterprise Policy (v8.2)

FoxyProxy supports enterprise policy and managed storage, and they can be configured to set FoxyProxy options.

storage.managed is not supported on Firefox for Android.

• FoxyProxy checks for enterprise policy and managed storage at start-up, and when background script is reloaded in MV3
• If managed data is found:
  • Managed data will be used
  • Toolbar popup & Options page work normally but changes will not apply
  • Managed data can set all, or some of the options (the rest will be set to their default values)
  • Managed data format is the same as FoxyProxy export format
  • The easiest way to create a managed data JSON is to set all values in FoxyProxy and export options

Default Options (v8.9)

{
  "mode": "disable",          // mandatory: current option, necessary to enable
  "sync": false,              // optional:  not necessary as it will be disabled on managed storage
  "autoBackup": false,        // optional:  not necessary as save is disabled on managed storage
  "passthrough": "",          // optional:  Global Exclude
  "theme": "",                // optional:  set the theme
  "container": {},            // optional:  Incognito/Container settings
  "commands": {},             // optional:  keyboard shortcut settings
  "data": []                  // mandatory: array of proxies and their patterns
}

{

  "3rdparty": {
    "extensions": {
      "gcknhkkoolaabfmlnjonogaaifnjlfnp": {
        "mode": "pattern",
        "data": []
      }
    }
  }

}

{
  "policies": {
    "3rdparty": {
      "Extensions": {
        "foxyproxy@eric.h.jung": {
          "mode": "pattern",
          "data": []
        }
      }
    }
  }
}

Managed Storage

A storage.managed object that represents the managed storage area. Items in managed storage are set by the domain administrator or other native applications installed on the user's computer and are read-only for the extension.

Native manifests are specially formatted JSON files that are provisioned on the user's computer by some means outside the extension installation process. For example, a native manifest might be provisioned by a device administrator or by a native application installer

{
  "name": "foxyproxy@eric.h.jung",
  "type": "storage",
  "data": {
    "mode": "disable",
    "sync": false,
    "passthrough": "",
    "container": {},
    "commands": {},
    "data": []
  }
}

See also

• storage.managed
• Managed storage manifests

Support

• GitHub Community Support
• Source Code
• Open a Support Ticket (no registration required)
• Email Support