Achernar's programming page
Last update: 2020/09/13

Tiny Proxy help

Tiny Proxy ("TP") is an extension originally designed to have the smallest memory footprint as possible. Considering that the extension itself doesn't handle proxying in the browser, and only provides an interface to modify its settings, it should not add bloat. TP transmits the proxy configuration chosen by the user – it writes a PAC script which in turn is handled entirely by your browser.

Tiny Proxy is available in the Chrome web store.

By default, TP is not enabled in your browser incognito mode.
If you want to use it also in this mode, right-click TP's iconin chrome toolbar. Click "Manage extensions". It should open a new tab with TP extension settings. Scroll down and enable "Allow in incognito".
If you ever desire you can revert the option as easily.

Browser warning

Several times, days after the installation, your browser will display this security message at startup. It's perfectly normal. If you want to continue to use Tiny Proxy click "Keep changes".


The settings page is accessible from the contextual menu of Tiny Proxy's icon. Right-click TP's icon in chrome toolbar, and click "Options". From there you can add/remove/modify proxies, and configure the extension.

To use a proxy defined in your settings, left-click TP's icon to open the popup window.

Basic settings

Proxy server

To start using TP you have to define a proxy server.
This can be done either by adding a new "server" proxy, or a "PAC" proxy. By default, when a new proxy is added, it doesn't appear in the popup window. To make it visible click the checkbox next to its name in the proxies list on the left side of the settings page.

Bypass list

The bypass list is used to prevent local addresses from being processed by a proxy.
It can be modified from the top menu. Note that this list is local to TP. It only affects proxies/settings defined in TP.

You can fine-tune the list in each proxy profile. But the modified list will only be used if that particular proxy is used as the "root" proxy (the one that appears selected in the popup window).

The default proxies

TP popup window displays 2 specials proxies.

Default options

TP default setting tells your browser that it can decide which extension can set a proxy when TP is "idle" (when the current proxy is "[ System ]" without temporary rules).

The icons

If at any moment Tiny Proxy icon looks like this, it means that another extension with higher priority over chrome's proxy settings has set a proxy.

If Tiny Proxy is enabled in incognito mode, you can encounter an intermediate state of priority conflict.
If present, these red dotsmean that Tiny Proxy has only partial control. The upper dot indicates no control on standard tabs, and the lower dot, on incognito tabs.

Other icons are indicative of the type of proxy currently selected.

pac script
a temporary filter is set (in combination with any of the icons above)
TP is set to [system] but another extension with lower priority has set a proxy

Only if the option is enabled (not by default):
A temporary proxy has been set with [ System ] as current proxy, but TP has no "System proxy" defined.

See below for more information on using "System proxy".

Settings - overview

Naming convention

Two proxies of the same type can't use the same name. Identical names can be used as long as it is for different types of proxies. It doesn't add much confusion, since, throughout the interface, proxies are sorted by type and/or prefixed with the symbol associated with their type.

User proxies

Tiny Proxy offers 5 types of user defined proxies.

Server proxy

Available proxy protocols are HTTP, HTTPS, socks4 and socks5.
As usual, you can assign a different proxy to http:// https// and ftp:// sites.

You can paste complex syntax into the "server" input field. TP will separate protocol, server and port if it recognizes the syntax. It currently supports: meth://addr:port | meth addr:port | addr port | addr:port | addr [+-]port | addr:port meth .

Starting with version 0.5, a new scheme has been added: "[ auto ]" will create a server that behind the scene is a "pool" proxy with the 4 schemes. Preferably this option is only for testing a server. I don't recommend using it in an everyday situation. It can, more than often, create a "time-out" period of more than a minute before actually connecting for the first time (and that, whenever a modification is done to the current proxy tree). This is the reason why this option is only available in the "all" line.

Note: Tiny Proxy doesn't handle proxy server authentication yet. It's probably only a matter of testing. You're free to volunteer.


Tiny Proxy warns you if you enter a server IP/name already used in another server proxy.

In this image you can see 3 different matches.
The red icon indicates complete match, and the yellow icon, incomplete match (on the hostname only). Clicking the icon shows the list of matching servers.
Lines #1 and #2 show the same kind of complete match (name + port)
Line #3 shows a complete match, but only on the name (this line has no port)
Line #4 shows an incomplete match on the name. Matched servers have a different port.
Lines #1 and #2 also show incomplete matches alongside complete matches. (in versions >=0.5)

Switch proxy

With the switch proxy you can build a list of rules to fine-tune the websites to use with or without a proxy.
Available condition types are:

Switches included by the "Include" condition are stripped of their "everything else" rule.

Rules can be reordered one row at a time using the up/down arrows . They can also be dragged to another position. A condition can be disabled by selecting the checkbox, or deleted by clicking the red X mark . The arrow  is used to access the proxy profile used in a rule.

Instead of selecting a proxy from the dropdown list, you can drag it from the global list on the left side of the screen, and drop it on the chosen field. (new in version 0.6)

Pool proxy

A pool proxy is a set of "server" proxies.
It can be used when you have unreliable servers and still want/need to use them. When a url needs to be proxied through this king of proxy, the browser will try to use them, starting with the first one. The process of finding the first working server can be long if failing ones are timing out. But once one works it sticks to it as long as it can.
The process is restarted if anything is changed in your active proxy: changing an alias, adding/removing a temporary rule, editing an element of the proxy tree (if you are using switches or other pools).

Servers can be reordered one row at a time using the up/down arrows . They can also be dragged to another position. A server can be disabled by selecting the checkbox, or deleted by clicking the red X mark . The arrow  is used to access the server profile.

Instead of selecting a proxy from the dropdown list, you can drag it from the global list on the left side of the screen, and drop it on the chosen field or on the "add server" button. (new in version 0.6 and 0.6.3)

Important note: a "pool" proxy will fail if the first reactive server accepts connections but sends empty responses to the browser (a faulty server or one with invalid credentials). Then, the servers following it in the list won't be tested. You'll have to identify the faulty server and disable it to fix the behavior. A future version of Tiny Proxy might come with a way to detect such servers. But until then...

PAC proxy

If you want more details about the structure of a PAC script, see this documentation (mozilla).

Syntax errors here, or other types of errors, won't cause problems in the rest of your proxy config. (new in version 0.6)

Alias proxy

An alias proxy can point to any other proxy profile. It has the advantage of allowing the modification of the target in one place, instead of changing it wherever the target is used (mainly switches).
When in use by the current proxy, they appear in the popup window and can be changed from there.

Instead of selecting a proxy from the dropdown list, you can drag it from the global list on the left side of the screen, and drop it on the chosen field. (new in version 0.6)

Bypass list

Each proxy profile has an associated bypass list. This list is only used when this particular proxy is the root proxy (the one selected in the popup window). It is ignored if the proxy is used for a temporary rule, in a switch, a pool...

By default, the bypass list is the default list, editable from the top menu.
You can either leave it unchanged, append new lines, or replace the default list with the content of the new list (which can be empty).

The alias proxy has a special default option, "Use option of aliased proxy". Which means that, if it is the root proxy, it will use the bypass option of the aliased proxy (alias proxies can be chained).

In summary, only one bypass list is used. The one associated with the root proxy. (If [ System ] or [ Direct ] is used with a temporary proxy, the bypass list used is TP's default one).

Selecting a proxy

Wherever you need to select a proxy you will see this list.
The green line is the current value (if there is one set)
The red lines are invalid values, disabled to prevent proxy loops.

Proxies are grouped by type and prefixed with the symbol of that type. The same symbol is used in the popup window.

[ Direct ] tells the browser to send the requests directly to the web server
[ System / Direct ] the proxy to be used is Tiny Proxy's "System proxy". If none is defined, it falls back to "direct".

"Used by"

Each proxy configuration page has a section named "Used by". It displays a list of all other proxies using this one. You can follow the links to these proxies editing form.
A proxy currently used by at least one other proxy, can't be deleted.

Proxies - errors and colors   (new in version 0.6)

User's settings can be color-coded to indicate errors. (See options panel; option enabled by default)






Fields colored in red indicate a syntax error, an invalid, or an empty value. Purple has to be investigated, but is not always fatal.

In all examples above, red will prevent TP from creating a valid proxy with these values. They will be ignored when it creates a script and transmits it to chrome.

#1, when parts of the "all" line are invalid, will cause failure in a switch (prior to version 0.6.1 it was redirecting to "direct") and will be ignored elsewhere. The other scheme lines will just be ignored in case of error, just like if they were empty.

#2 A red proxy is ignored, while a purple one is valid, and used. Purple in this case indicates that invalid values have been filled into the schemes fields, which isn't problematic (only) here (they aren't used in pools anyway).

#3 indicates an invalid proxy name. Rules using it will be ignored.
#4 means that the proxy profile aliased contains invalid values that will cause failure for this alias. It will probably redirect to "direct" or be ignored.

#5 like for aliases, purple indicates errors in sub-proxy. Rules can be ignored due to this.
(Proxy used in line 2 is invalid because it must be a switch.)

The System proxy

The "System proxy" is a special proxy. It is used to mimic your system proxy – either the proxy settings defined by your operating system, by your browser, or by any program installed to handle this.

Due to limitations of the proxy system implemented for extensions, an extension can't access your system's proxy settings. If you want to use these settings in TP, you need to fill in the "System proxy" (from the top menu).
Note that selecting [ System ] in the popup window will use the real system proxy. But once TP adds any proxying (eg. temporary rules) it has to use its own definition (or fall back to [ Direct ] if none is set).

The "System proxy" can be defined as a server, a switch, a PAC script, or disabled. Disabling doesn't clear the settings. They can still be used if you decide to enable it again.

For most of you, your system has no proxy defined. TP has this special proxy to help you in case you need it.

The options panel

The modification of an option takes effect immediately.

The popup window

By default, newly created proxies don't appear in the popup window. You can choose which proxies you want to see in the list by checking the checkbox next to their name in the proxy list on the settings page.




The popup window is the interface between the user and Tiny Proxy. The user can select a proxy from the list displayed, and the browser will automatically switch to that proxy. If somehow the proxy profile is invalid (or incomplete), TP falls back to [ System ] or [ Direct ] (screenshot #4).

Screenshot #2 shows an alias used by the proxy in use, and #3 another alias used by a temporary rule.
#3 shows a list of temporary rules.

#4 also shows the "add" panel. This is the interface used for adding temporary rules.


Temporary rules

If the current tab is a website, its domain name is displayed. You can choose the part you want to base your rule on by clicking it. This fills the input field where you can still modify it. If a page contains a frame, the right-click context menu on that frame shows a command to add its hostname to the list in the popup window.

If the input field is empty, the list of available proxies (next to "Use:") displays only "switch" proxies. When the input field contains a hostname, the list is filled with all types of proxies except "switch".
Currently, the only available type of condition for a temporary rule is a host wildcard. Except for a switch proxy which contains its own conditions.

A temporary rule can be placed before or after the bypass list verification. Note that bypass lists associated with proxies used in temporary rules, are ignored.

The bypass list used while a temporary rule is set, is the one associated with the profile currently selected in the popup menu. or the default one when [ System ] or [ Direct ] is the choice.

Exporting and importing

Full export

You can save your data and settings by going to the "Export / Import" panel on the settings page.

Partial export New in version 0.6.3

If you want to export or share a small set of your proxies, drag them from the list on the left to the drop zone. The area will expand, and display 3 lists.

You add proxies by dropping them in the first zone. You can remove them individually using the X icon  . Once a proxy is added, its structure is analyzed and all proxies it depends on (eg. switch and pool) are added (to the 3rd list). Moreover servers (":" prefix) are also added to the second list (as well as in the 3rd) when an alias (if it points to a server, as "youtube" in picture #2), a pool, or a server is added in the drop zone.

The behavior allows you to export a proxy structure without - if you cross the checkbox - giving out your actual servers. This, while still being able to export some servers (present in the second list).



Import from file

You can select which element(s) to restore. Proxies, options, "system proxy", bypass list, can be restored separately.
This is the method used to import data exported using the 2 methods above.

Importing raw servers listing New in version 0.5

Tiny Proxy can import servers' listing from raw data pasted from webpages.
For pages without a scheme specified in each proxy line, TP can select a default value to apply during the import process. It can also override schemes in case you deemed them incorrect – which is more common than you think.

In these circumstances, if you want to foolproof any possible scheme, you can select:

Duplicates (of already defined servers, or from within the import list itself) will be marked and ignored.


Tiny Proxy doesn't handle proxy server authentication. It's probably only a matter of testing. You're free to volunteer.

All settings must be saved to take effect.
The only exceptions are for the settings of the "options" panel, and the "in popup" checkboxes, whose modifications are immediate.

The export file format is only compatible with Tiny Proxy. TP understands only its own export files. If you need another format, point me to a description of that other format.

Feel free to report bugs or ask for improvements. Use the extension page to post comments.