Tor Proxy

Send Node.js web requests through Tor, with an optional “new identity” switch. Built with a modern, security-first approach.

GitHub: https://github.com/hrach347/tor-proxy-agent

Install

npm install tor-proxy-agent

Usage

Minimal usage,request through Tor

import tor from "tor-proxy-agent";

const { response, body } = await tor.request({url: "https://api.ipify.org",});

console.log(response.statusCode);
console.log(body);

Change SOCKS address/port/type

import tor from "tor-proxy-agent";

// ip, port, type (5 = socks5, 4 = socks4)
tor.setTorAddress("127.0.0.1", 9050, 5);

const { body } = await tor.request({ url: "https://api.ipify.org" });
console.log(body);

New identity (NEWNYM) + request

import tor from "tor-proxy-agent";

await tor.newTorSession();
// Tor can rate-limit NEWNYM; waiting helps in practice.
await new Promise(r => setTimeout(r, 10_000));

const { body } = await tor.request({url: "https://api.ipify.org"});

console.log(body);

Note: SIGNAL NEWNYM requests a new circuit, but it does not guarantee a new exit IP immediately.

---

Environment (optional)

If you use HashedControlPassword, set the ControlPort password for your app:

Create a .env file in your project:

TOR_CONTROL_PORT_PASSWORD=my_secret_password

Requirements

• Node.js >= 18
• Tor installed and running
  • SOCKS port (default): 127.0.0.1:9050
  • ControlPort (optional): 127.0.0.1:9051

Install and Run Tor

Debian/Ubuntu

sudo apt update
sudo apt install tor
sudo systemctl enable --now tor

macOS (Homebrew)

brew install tor
tor

---

Tor configuration (torrc)

Your torrc is commonly located at one of:

• /etc/tor/torrc
• /usr/local/etc/tor/torrc

Enable ControlPort

Generate the hash

tor --hash-password "my_secret_password"

Put the hash into torrc

ControlPort 9051
HashedControlPassword 16:REPLACE_WITH_HASH_OUTPUT

Restart tor

sudo systemctl restart tor

---

Windows (Tor Expert Bundle)

If you want Tor running like a real local service (best for dev), use the Tor Expert Bundle.

Download

Get Tor Expert Bundle from the official Tor Project website.

Run Tor

Extract it, then run tor.exe from a terminal (PowerShell / CMD).

Configure torrc

Create/edit torrc and add:

SocksPort 9050
ControlPort 9051
CookieAuthentication 1
HashedControlPassword 16:REPLACE_WITH_HASH_OUTPUT

Note: create hash in Windows - tor.exe --hash-password "my_secret_password"

---

---

---

---

License

• MIT

Enjoy

If this package helped, drop a ⭐ on the repo.