Rotate your Tor exit IP on a schedule — with a live terminal dashboard.

---

Nyx is a Tor identity rotator with a real-time TUI. It cycles your exit node on a schedule — pulling a fresh IP each time — and shows the new address and its geolocation live. It talks to Tor the way it's meant to be driven: a NEWNYM signal over the control port, not crude service restarts.

  +---------------------------+-------------------------------+
  |  CURRENT EXIT             |  STATUS                       |
  |  185.220.101.4            |  State    : RUNNING           |
  |  Country: Germany         |  Rotations: 3 / ∞             |
  |  Region : Hesse           |  Next in  : 42s               |
  |  City   : Frankfurt       |                               |
  +---------------------------+-------------------------------+
  |  ROTATION LOG                                             |
  |  14:02:11  [+] 185.220.101.4 (Frankfurt, Germany)         |
  +-----------------------------------------------------------+

Table of contents

• Features
• Why not just restart Tor?
• Install
• Usage
• How it works
• Configuration
• Troubleshooting
• Roadmap
• Contributing
• Legal
• License

Features

• Automatic rotation on a user-defined interval and cycle count (or run forever)
• Live TUI — current IP, country/region/city, rotation count, and a countdown to the next change
• NEWNYM over the control port — faster and cleaner than restarting the service
• Waits for the real flip — polls until the exit IP actually changes, so you never see a stale node
• No leaks — every check (including DNS and geolocation) is routed back through Tor via socks5h
• SOCKS5 ready at 127.0.0.1:9050 for routing any application
• Hotkeys — rotate now, pause/resume, quit

Why not just restart Tor?

Most "IP changer" scripts kick the whole tor service and immediately read the IP — which needs root every time and often reports the old exit because the new circuit isn't ready yet. Nyx does it properly:

	service-restart scripts	Nyx
Identity change	restart the daemon	NEWNYM over the control port
Privilege	root on every rotation	none after setup
IP readout	immediate, often stale	polls until it genuinely changes
DNS	may leak	resolved through Tor (socks5h)
Geo lookup	leaks request path	runs through Tor, one request returns IP + location
Interface	scrolling text	live reactive dashboard

Install

git clone https://github.com/keirsalterego/nyx.git
cd nyx
sudo bash install.sh        # installs tor, opens the control port, builds a venv
. .venv/bin/activate
nyx

The installer detects apt / dnf / pacman, installs Tor, enables ControlPort 9051 with cookie auth, and pip installs Nyx into a virtualenv.

Manual install

pip install -e .            # or: pip install -r requirements.txt

You'll also need Tor running with these lines in your torrc:

ControlPort 9051
CookieAuthentication 1
CookieAuthFileGroupReadable 1

Usage

nyx                          # rotate every 60s, forever
nyx -i 30 -c 5               # every 30s, stop after 5 rotations
nyx --check                  # print the current exit IP once, no TUI

Flag	Default	Meaning
-i, --interval	60	seconds between rotations (min 10)
-c, --count	0	number of rotations, 0 = infinite
--socks-port	9050	Tor SOCKS proxy port
--control-port	9051	Tor control port
--control-password	—	only if you use a HashedControlPassword
--check	—	one-shot IP check, no UI

In-app keys: n rotate now · space pause/resume · q quit.

Then point any application at the SOCKS proxy — 127.0.0.1:9050, SOCKS v5.

How it works

1. New circuit. engine.py opens Tor's control port, authenticates via the auth cookie, and sends a NEWNYM signal to build fresh circuits.
2. Confirm the flip. It queries ip-api.com through the SOCKS proxy, so the response describes the exit node (not you), and polls until the IP actually changes before reporting it.
3. Render. tui.py runs that on a background worker and streams updates into the dashboard via Textual's reactive widgets.

ℹ️ Tor rate-limits NEWNYM to roughly once per 10 seconds, so intervals below 10s won't give you a genuinely new exit each time. Nyx clamps to a 10s minimum.

Configuration

Everything is flag-driven (see Usage) — there's no config file to babysit. If you run Tor on non-standard ports or in a container, override --socks-port and --control-port to match.

Troubleshooting

Can't reach Tor control port — Tor isn't running or ControlPort 9051 isn't in your torrc. Re-run install.sh or add it manually and restart Tor.

control authentication failed — your user can't read Tor's auth cookie. Add yourself to the Tor group and re-login:

sudo usermod -aG debian-tor $USER     # 'tor' on Arch/Fedora

The IP isn't changing — you're likely rotating faster than Tor's ~10s NEWNYM limit, or Tor is reusing a circuit. Raise --interval.

Roadmap

• --exit-country de — pin exit nodes to a country via Tor's ExitNodes
• JSONL audit log of every exit IP for later analysis
• --strict mode that aborts if an exit IP ever matches your real IP
• Country-diversity sparkline in the dashboard

Contributing

Issues and PRs are welcome. For larger changes, open an issue first to discuss the direction. Keep modules small — engine.py stays UI-agnostic so it can be reused headless.

Legal

Rotating your own Tor identity is a normal, legitimate privacy practice. Use Nyx only on systems and networks you're authorized to use, and don't use it to evade detection while doing things that are illegal where you live. The author assumes no liability for misuse.

License

MIT © contributors