Introduction

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

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

Unified Code

FoxyProxy 8 code has been unified for Chrome and Firefox, and Standard and Basic versions.
Unified code for FoxyProxy and FoxyProxy Basic, on both on Chrome and Firefox, enables users to share their preferences.

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 and importing are non-destructive. Click SAVE to apply the changes.

See also: Destructive vs Nondestructive Editing

Proxy Authentication

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

Proxying Order

1. Global Exclude
2. Tab Proxy (Firefox only)
3. Tab Proxy by patterns(Firefox only) (v9.0)
4. Incognito Proxy
5. Container Proxy (Firefox only)
6. Individual Proxy or Proxy by Patterns

Proxy by Patterns Order

• Active proxies are checked in order
• If it is a tab URL and one of Tab Proxy patterns matches, then that proxy is used (Firefox only)
• 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

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

At least one include pattern has to be set and available for the menu to show

If there are no patterns that match the URL being loaded, connections are made without a proxy (i.e. Direct)

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

Disable

Proxying is set to system and handled by the browser

Individual Proxy

All connections are passed through the selected proxy (or PAC)

Patterns are not applicable in this case

▶ More

Show or hide additional options

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

Include Host and Exclude Host (not available on managed storage or FoxyProxy Basic)

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

Only top 10 active proxies are listed

Only HTTP/HTTPS are processed

Tab Proxy (Firefox only)

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

Select the blank option to unset

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

Search Filter

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

Use :port-number to filter by port

Options

Open the Options page

Log

Open the Options page, Log Tab

IP

Get IP from FoxyProxy servers

Location

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

Context Menu

Context Menu is available on page and toolbar icon

Include Host and Exclude Host (not available on managed storage or FoxyProxy Basic)

Same as Toolbar Popup

Tab Proxy (Firefox only)

Same as Toolbar Popup

Open Link in New Tab Proxy

Open the link in a new Tab Proxy set to the selected proxy

Keyboard Shortcut (not available on Android)

You can change/set keyboard shortcuts.

Click 🔗 on Options page to open the keyboard shortcuts page in Chrome and Firefox 137+.

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 and Firefox.

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.

• Sync is disabled on managed storage
• At the moment, storage.sync is not supported on Firefox for Android
• Mode and 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)

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

This setting allows users to specify the media performance/privacy tradeoffs which affect how WebRTC traffic will be routed and how much local address information is exposed.

Option changes the browser preferences and does not require SAVE.

default

Exposes user's public and local IPs. This is the default behavior. When this policy is used, WebRTC has the right to enumerate all interfaces and bind them to discover public interfaces.

Public Interface Only

Exposes user's public IP, but does not expose user's local IP. When this policy is used, WebRTC should only use the default route used by http. This doesn't expose any local addresses.

Public and Private Interfaces

Exposes user's public and local IPs. When this policy is used, WebRTC should only use the default route used by http. This also exposes the associated default private address. Default route is the route chosen by the OS on a multi-homed endpoint.

Disable Non-Proxied

Does not expose public or local IPs. When this policy is used, WebRTC should only use TCP to contact peers or servers unless the proxy server supports UDP.

Proxy Only (Firefox only)

Only connections using TURN on a TCP connection through a proxy are allowed.

Theme

Change to alternative themes

Incognito and 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"
• Click "Add" for a new custom container option
• Custom containers without a proxy will be deleted

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 ⓘ

The numbers corresponds to container IDs and not their order. If containers are not deleted or reordered, IDs should match the order. Otherwise, user should get the correct ID (e.g. from containers.json).

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)
  

  Users can change the behaviour. This is generally only needed for test setups. Beware of the security implications to proxying localhost.
  Chrome: Bypass rule: Subtract implicit rules
  Edge and Firefox: Intercept requests to localhost

• 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 following table 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 do 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

Delete Browser Data (requires "browsingData" permission)

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

A proxy server is identified by "hostname:port" or PAC URL.

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

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 available for SOCKS and HTTPS (Firefox < 125) and HTTP (Firefox 125+).
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

Click to add a new proxy at the end

Ctrl-Click to add a new proxy at the start

Search Filter

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

Use :port to filter by port

Ping

Check server response (active, http/https only)

The method only provides an indication, as it is affected by many other factors

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 ▲ ▼

Move the proxy up or down

Title

Set the proxy title

Type

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

PAC to be used with PAC URL

QUIC (HTTP/3) proxy is only supported by Chrome (not available on Firefox ⓘ)

Country

Set the proxy country flag

City

Set the proxy city

Color

Set the proxy color

Hostname and Port

Required for HTTP/HTTPS/SOCKS type

Username and Password

To be used for HTTP/HTTPS/SOCKS types

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

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

Username and 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 (defaults to true)

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, Support proxy.settings API on Android

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. Few auto-fill options are added for convenience.

• Go to Proxy tab ➤ Add a new proxy
• Fill the details according to own preference
• 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

➕ Add Pattern

Click to add a new pattern at the end

Ctrl-Click to add a new pattern at the start

Quick Add

Add ready-made patterns

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

Include, Exclude, and Tab Proxy

Select to include or exclude URLs that match the pattern

Select Tab Proxy to set for URLs that match the pattern (Firefox only)

Type

Select Wildcard (Glob), Match (Pattern), or Reg Exp (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), Match Pattern, or Regular Expression
• In practice, including specific URL pathname 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

Pattern can match the entire URL or only part of it

Include :// to ensure it matches the host

Leading or trailing * is not necessary

Match (v9.0)

Match patterns are a way to specify groups of URLs and have strict rules

Match pattern matches the entire URL

Scheme, host, and path must be included

Scheme can be "*", "http", "https", "ws", or "wss" (for proxying purpose)

"*" in host must be at the start

"*" in host must be the only character or be followed by "."

Host starting with "*." matches the domains and its subdomains

Host must not include a port number

Regular Expression

Pattern can match the entire URL or only part of it

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

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

Beginning assertion ^ is usually not necessary with (scheme):// pattern

Bulk Edit

Bulk Edit is non-destructive. Click SAVE to apply the changes.

Bulk Edit User Interface (v9.0)

• Numbers are positions, starting from 1
• Sources will be moved to before the target
• If target location does not exist (empty or n/a), sources will be moved to the end of the target group
• Last input box accepts text value, or a mix of separated (space, comma, etc) numbers and ranges e.g. 2 6 10-15 18
• Duplicate and overlapping numbers in the last input box will be removed

Developer Tools

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

Code Examples

Change all types	document.querySelectorAll('[data-id="type"]').forEach(i => i.value = 'https')
Change all ports	document.querySelectorAll('[data-id="port"]').forEach(i => i.value = '443')
Change all titles	document.querySelectorAll('[data-id="title"]').forEach(i => i.value += '-set')
Change all usernames	document.querySelectorAll('[data-id="username"]').forEach(i => i.value = 'user')
Change all passwords	document.querySelectorAll('[data-id="password"]').forEach(i => i.value = 'pass')
Open all proxies	document.querySelectorAll('details.proxy').forEach(i => i.open = true)
Close all proxies	document.querySelectorAll('details.proxy').forEach(i => i.open = false)

Import

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

FoxyProxy Account

Import proxies from FoxyProxy account

Imported content will be added to the existing proxies

Options allow user to select to import as http/https/socks, use hostname/ip, use main/alternative server

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)

Chrome FoxyProxy v3 with authentication can be imported in FoxyProxy v8.10

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

Pattern Tester

Pattern

Enter a pattern to test if it matches any of the entered URLs

• Select the pattern type
• Enter pattern
• Enter URLs to test
• Click "Test"
• Test also runs on changing the pattern type
• "Back" button goes back if coming from proxies page

Proxy by Patterns

Enter a URL to test if it matches any of the saved active proxy patterns

• Enter URL
• Click "Test"

Log

Get Associated Domains

Open Log

Go to the site to generate log results

Enter a Document URL string (e.g. domain) and get all the associated domains displayed in the log that were requested by that Document URL

Select a proxy from the drop-down to add generated patterns

As a side-effect, you can click the button which opens an empty popup, enter a list of domains and generate include patterns

Log Table

Live Log displays the web requests in reverse 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

Document URL displays the web page

URL displays the requests made from that Document URL

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

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 (v8.2)
• If managed data is found:
  • Managed data will be used
  • Toolbar popup and 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",
  "description": "ignored",
  "type": "storage",
  "data": {
    "mode": "disable",
    "sync": false,
    "autoBackup": false,
    "passthrough": "",
    "theme": "",
    "container": {},
    "commands": {},
    "data": []
  }
}

Support

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