The proxy: Scheme

What is it?

The FoxyProxy team has designed a URI (Uniform Resource Identifier) scheme to programmatically interact with proxy-related software such as FoxyProxy. The scheme is the proxy: scheme. Currently, FoxyProxy is the only software known to implement this scheme, but you are encouraged to support it in your software, too. Please contact us if you do so we can add your software to this page.

How to use it?

You can put proxy: links in webpages, web mail, or type them into the address bar to interact with FoxyProxy (proxy:// is also accepted but semantically incorrect). You can also leverage this ability to control FoxyProxy in a headless or batch environment such as Selenium. Commands to FoxyProxy are specified through URL query parameters--name/value pairs in the URL.

You can disable this feature with the ignoreProxyScheme hidden setting. To use: close firefox. In foxyproxy.xml, change the new ignoreProxyScheme attribute from its default of false to true.

Here are some proxy: scheme examples to get you started. All names and values are case-sensitive!

proxy:host=foo.com&port=9999
proxy:host=foo.com&port=999&foxyProxyMode=this&confirmation=https://getfoxyproxy.org/proxyservice/geoip/
proxy:host=foo.com&port=1080&isSocks=true&enabled=false
proxy:url=http://foo.com/proxy.pac
proxy:host=foo.com&port=999&action=deleteOne

API Specification

Here is a complete list of supported parameters, values, and default values. All names and values are case-sensitive! Don't forget FoxyProxy also has a more limited command-line interface.

Name	`action`
Description	The action to perform with the specified `proxy:` info
Valid values	`update` `add` `updateOrAdd` `deleteOne` `deleteMultiple`
Default if not specified	`updateOrAdd`
Required?	no
Examples	proxy:host=foo.com&port=999 proxy:host=foo.com&port=999&action=add proxy:host=foo.com&port=999&action=deleteMultiple proxy:host=foo.com&port=999&name=Australia Proxy proxy:host=bar.com&port=888&name=Australia Proxy&action=update
Notes	`updateOrAdd`: if a proxy with the specified `name` exists, it is updated with the information specified in the `proxy:` URI. `name` is calculated by default if no `name` query parameter is specified. If no proxy with the specified `name` exists, FoxyProxy behaves as if `action` is specified as `add`. That is, a new proxy is added. `update`: if a proxy with the specified `name` exists, it is updated with only the information specified in the `proxy:` URI. `name` is calculated by default if no `name` query parameter is specified. If no proxy with the specified `name` exists, no update is performed. If more than one proxy with the specified `name` exists, only the first is updated. `add`: a new proxy with the specified name is added to FoxyProxy. `name` is calculated by default if no `name` query parameter is specified. Names need not be unique, so if an existing proxy with `name` already exists, the effect is that two proxies with the same name will exist. `deleteOne`: if a proxy with the specified `name` exists, it is deleted. `name` is calculated by default if no `name` query parameter is specified. If FoxyProxy's mode was set to use the deleted proxy for all URLs, FoxyProxy changes its mode to disabled to avoid a broken configuration. If no proxy with the specified `name` exists, no delete is performed. If more than one proxy with the specified `name` exists, only the first is deleted. `deleteMultiple`: if a proxy with the specified `name` exists, it is deleted. `name` is calculated by default if no `name` query parameter is specified. If FoxyProxy's mode was set to use the deleted proxy for all URLs, FoxyProxy changes its mode to disabled to avoid a broken configuration. If no proxy with the specified `name` exists, no delete is performed. If more than one proxy with the specified `name` exists, all of them are deleted.

Name	`foxyProxyMode`
Description	Changes FoxyProxy's current mode [screenshot]
Valid values	`this` `proxy name` `patterns` `previous` `disabled` `random (not supported)` `roundrobin (not supported)`
Default if not specified	No default
Required?	no
Examples	proxy:host=foo.com&port=999&foxyProxyMode=this proxy:foxyProxyMode=disabled proxy:foxyProxyMode=Australia Proxy proxy:host=foo.com&port=999&&name=UK Proxy¬es=London server&foxyProxyMode=French Proxy
Notes	`this`: Sets FoxyProxy to `Use Proxy XXXX for all URLs` for the newly-added or updated proxy. If `action` is `deleteOne` or `deleteMultiple`, FoxyProxy's mode remains unchanged. `proxy name`: Sets FoxyProxy to `Use Proxy XXXX for all URLs` where XXXX is the proxy specified in place of `proxy name`. If more than one proxy with the same `name` exists, the first is selected. If no proxy with the specified `name` exists, FoxyProxy sets its mode to `disabled`. `patterns`: Sets FoxyProxy to `Use proxies based on their pre-defined patterns and priorities`. `disabled`: Sets FoxyProxy to `disabled` mode.

Name	`name`
Description	Name of the proxy being added/updated/deleted [screenshot]
Default if not specified	If `host` and `port` parameters are specified, and `mode` is `manual`, `name` defaults to `host:port`. If a `url` parameter is specified and `mode` is `auto`, `name` defaults to the value of `url`.
Required?	no
Examples	proxy:host=foo.com&port=999&name=Australia Proxy proxy:name=Australia Proxy&enabled=false

Name	`mode`
Description	Mode of the proxy being added/updated
Valid values	`manual` `auto` `direct` `system (not supported)`
Default if not specified	If `host` and `port` parameters are specified, `mode` defaults to `manual`. If `url` is specified but no `host` and `port`, `mode` defaults to `auto`. If `host` and `port` and `url` aren't specified, `mode` defaults to `direct`.
Required?	no, but (`host` and `port or url should be specified if name is not`
Examples	proxy:name=Australia Proxy&mode=direct proxy:name=Australia Proxy&mode=manual&host=localhost&port=8080&action=update
Notes	`manual`: Sets this proxy to "Manual Proxy Configuration" [screenshot] `auto`: Sets this proxy to "Automatic proxy configuration URL" [screenshot] `direct`: Sets this proxy to "Direct internet connection (no proxy" [screenshot]

Name	`host`
Description	Hostname or IP address of the proxy being added/updated/deleted [screenshot]
Valid values	Any hostname or IP address
Default if not specified	No default
Required?	no, but `name` should be specified if (`host` and `port`) or `url` are not
Examples	proxy:host=foo.com&port=8888 proxy:host=localhost&port=999 proxy:host=192.168.1.1&port=1080

Name	`port`
Description	Port of the proxy being added/updated/deleted [screenshot]
Valid values	Any valid port number
Default if not specified	No default
Required?	no, but `name` should be specified if (`host` and `port`) or `url` are not
Examples	proxy:host=foo.com&port=8888 proxy:host=localhost&port=999 proxy:host=192.168.1.1&port=1080&name=MyProxy

Name	`isSocks`
Description	`true` or `false` depending on if the proxy being added/updated is a SOCKS proxy server [screenshot]
Valid values	`true` or `false`
Default if not specified	`false`
Required?	no
Examples	proxy:host=foo.com&port=1080&isSocks=true proxy:host=localhost&port=1080&isSocks=true&socksversion=4 proxy:host=localhost&port=1080&isSocks=false&action=update

Name	`socksversion`
Description	The version of the SOCKS server implemented by the proxy server being added/updated [screenshot]
Valid values	`5` `4a` `4`
Default if not specified	`5`
Required?	no
Examples	proxy:host=foo.com&port=1080&isSocks=true&socksversion=4a proxy:host=localhost&port=1080&isSocks=false&socksversion=4

Name	`url`
Description	URL to a PAC file [screenshot]
Valid values	Any URL accepted by FoxyProxy, including `relative://`, `file://`, `http://`, `ftp://`, `https://`
Default if not specified	No default
Required?	no
Examples	proxy:url=http://google.com/proxy.pac proxy:host=localhost&port=1080&pac=http://foo.com/mypac.txt&mode=auto

Name	`autoReload`
Description	`true` or `false` depending on if the PAC file should be automatically reloaded periodically [screenshot]
Valid values	`true` or `false`
Default if not specified	`false`
Required?	no
Examples	proxy:url=http://foobar.com/pac.txt&autoReload=true&reloadFreqMins=10 proxy:url=http://foobar.com:8080/pac.txt&autoReload=false

Name	`reloadFreqMins`
Description	Number of minutes after which the PAC file is reloaded [screenshot]
Valid values	Any positive integer
Default if not specified	`60`
Required?	no
Examples	proxy:url=http://foobar.com/pac.txt&autoReload=true&reloadFreqMins=10

Name	`loadNotification`
Description	Whether or not pop-up notifications should be shown when the PAC file fails to load [screenshot]
Valid values	`true` or `false`
Default if not specified	`true`
Required?	no
Examples	proxy:url=http://foobar.com/pac.txt&autoReload=true&reloadFreqMins=10&loadNotification=false

Name	`errorNotification`
Description	Whether or not pop-up notifications should be shown when the PAC file contains errors [screenshot]
Valid values	`true` or `false`
Default if not specified	`true`
Required?	no
Examples	proxy:url=http://foobar.com/pac.txt&errorNotification=false&loadNotification=false

Name	`disableOnBadPAC`
Description	Whether or not this proxy should switch its mode to `disabled` if its PAC file can't load or has errors.
Valid values	`true` or `false`
Default if not specified	`true`
Required?	no
Examples	>proxy:url=http://foobar.com:8080/mypac.pac&disableOnBadPAC=false

Name	`enabled`
Description	Whether or not the proxy being added/updated is to be enabled/disabled [screenshot]
Valid values	`true` or `false`
Default if not specified	`true`
Required?	no
Examples	proxy:host=foo.com&port=8080&enabled=false proxy:name=Work Proxy&enabled=true

Name	`notes`
Description	Notes for the proxy being added/updated is to be enabled/disabled [screenshot]
Default if not specified	No default
Required?	no
Examples	proxy:host=foo.com&port=8080¬es=This is my home proxy proxy:name=Work Proxy¬es=This is my work proxy&enabled=false

Name	`animatedIcons`
Description	Whether or not the icon for the proxy being added/updated should animate when in use [screenshot]
Valid values	`true` or `false`
Default if not specified	`true`
Required?	no
Examples	proxy:host=foo.com&port=8080&animatedIcons=false

Name	`includeInCycle`
Description	Whether or not the proxy being added/updated should be included in proxy cycling [screenshot]
Valid values	`true` or `false`
Default if not specified	`true`
Required?	no
Examples	proxy:host=foo.com&port=8080&includeInCycle=false

Name	`proxyDNS`
Description	Whether or not the proxy being added/updated should send DNS requests through the proxy server [screenshot]
Valid values	`true` or `false`
Default if not specified	`true`
Required?	no
Examples	proxy:host=localhost&port=1080&isSocks=true&proxyDNS=false

Name	`color`
Description	Hex color code that the FoxyProxy icon should change to when this proxy is in use [screenshot]
Valid values	Any 6-digit hex color code. Be sure to precede the code with a hash/pound symbol
Default if not specified	`#65BAD7`
Required?	no
Examples	proxy:host=localhost&port=8888&color=#8765D6

Name	`selectedTabIndex`
Description	The tab that should be focused when the user opens the proxy details page in FoxyProxy. Tabs are zero-indexed.
Valid values	FoxyProxy Basic and Standard: `0`, `1`, `2` FoxyProxy Plus: `0`, `1`, `2`, `3`
Default if not specified	`1`
Required?	no
Examples	proxy:host=localhost&port=8888&selectedTabIndex=0

Name	`confirmation`
Description	Show confirmation message after all `proxy:` configuration changes are complete
Valid values	`popup` or any compete URL
Required?	no
Examples	proxy:host=localhost&port=8888&confirmation=popup proxy:host=localhost&port=8888&confirmation=http://getfoxyproxy.org/geoip/
Notes	`popup`: Displays a popup confirmating that the proxy has been added/updated/deleted [screenshot] `URL`: Redirects the browser to the specified URL after the proxy has been added/updated/deleted. This URL must start with a scheme/protocol (example: http://). If the URL includes query parameters of its own, `confirmation` must be the final query parameter in the `proxy:` URI.

Name	`username`
Description	The username to use for HTTP(S) proxy authentication (SOCKS authentication not supported)
Default if not specified	No default
Required?	no
Examples	proxy:host=localhost&port=8888&username=jonathan
Notes	This is only available with FoxyProxy Plus.

Name	`password`
Description	The password to use for HTTP(S) proxy authentication (SOCKS authentication not supported)
Default if not specified	No default
Required?	no
Examples	proxy:host=localhost&port=8888&username=jonathan&password=foobar
Notes	This is only available with FoxyProxy Plus.

Name	`domain`
Description	The NTLM domain to use for HTTP(S) proxy authentication (SOCKS authentication not supported)
Default if not specified	No default
Required?	no
Examples	proxy:host=localhost&port=8888&username=jonathan&password=foobar&domain=cicero
Notes	This is only available with FoxyProxy Plus.