I'm trying to write a firefox extension that can automatically trigger the "New Tor circuit for this site" action.

I'm not familiar with writing extensions, so I' don't know where I can find the API call I'm suppose to make to launch this action.

Could someone point me to it?


  • 1
    Out of curiosity, when does the action get triggered? Commented Jul 28, 2016 at 15:04
  • it gets called depending on the content of the page on a specific url. So i plan to use pageMod.PageMod on this url and make a call to the tor button if the content of the page matches some criteria.
    – allafleche
    Commented Jul 28, 2016 at 15:14
  • does it work with the last tor ?
    – torfan
    Commented Nov 4, 2022 at 6:14

2 Answers 2


Tor Button handles the domain islation, which also includes how the "New Tor Circuit for this Site" button works.

IsolateSOCKSAuth is a default enabled isolation flag for a tor SocksPort. It means that it takes the SOCKS5 username and password authentication credentials and if they're different from others, it will use a new circuit. Tor Browser is patched to allow Tor Button to edit the authentication credentials for the SocksProxy.

When you load up example.org Tor Button creates a new set of credentials for it, these are example.org for the login and a random hex string for the password. These will be re-used for each resource associated with that "first party" domain.

When you use Tor Button to choose a new circuit for the site, Tor Button generates a new hex string for the password (it used to just use 0,1,2,..etc but this was changed recently, see #19206 but it's possible this is still the current behaviour in versions included in Tor Browser releases), this therefor causes it to use a new circuit.

The code you want to read is in Tor Button at src/components/domain-isolator.js, I recant my earlier assertion of there not being an API call available, it may be possible if you can call the tor.newCircuitForDomain() function in Tor Button from another extension (just how bad is browser security anyway?).

However, from your description you probably never actually want to do this and I'm guessing that you're going to be a bit of a bastard and abuse Tor to bypass blacklisting, giving it an even worse reputation and I'd kindly ask you not to, even if that isn't your plan it may be what the effects of your plan look like to website administrators. Thanks.

  • thanks for you response. I can't get the call to work, so i'm not sure i'll continue with this anyway.
    – allafleche
    Commented Jul 30, 2016 at 20:00

Checkout my extension at https://gitlab.torproject.org/lansi90/google-captcha-bypass-extension. It has a function newCircuitForDomain that does what you want. You can use it as a basis for your work. It is under CC0 public domain.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .