Tamagonion

Instructions

This is Stinky, it's a Tamagonion and it's running your Tor relay. Tamagonions are cyber creatures that have bravely stepped out of the Tor network to learn what life is like in the clearnet and to help you monitor your relay. It mostly loafs around and browses the Web anonymously, but it's more entertaining than looking at a graph!

More seriously, this program is meant to help you monitor your Tor relay in a more fun way. Start Tamagonion and just let it do its thing in the corner of your desktop or in a tmux split to get a general idea of the state of your relay. It is built to have minimal dependencies, only relying on Stem.

             ▌▌
             ▓▓▀
         ▄▄▄▀▀▀▀▄▄▄
        █   ─  ─   █
       █    ▄  ▄    █
      █     ▀  ▀     █
      █      ──      █
      █              █
       █▄▄▄▄▄▄▄▄▄▄▄▄█

Activation

To activate the viewport, use the tamagonion command as such:

# Install tamagonion
# If you'd rather run it directly from this repository, you can use `uv run tamagonion` instead
$ pip install tamagonion

# By default, we will try to connect to the control port at 127.0.0.1:9051
$ tamagonion

# If you use password authentication, you can supply it with -P or with the TAMAGONION_PASSWORD environment variable
$ tamagonion -P my_password
$ TAMAGONION_PASSWORD=my_password tamagonion

# If the port is listening somewhere else, you can specify it with -i and -p
$ tamagonion -i 192.168.0.10 -p 9999

# If you are connecting using a Unix socket, you can point to it with -s
$ tamagonion -s /var/run/tor/control

Home screen

┌──────────────────────────────────────────────┐
│Relay nickname: exitgpjkoely                  │
│Uptime: 0d 02h 58m 19s                        │
│Connections (N/L/Co/F/Cl): 0/0/7/0/0          │
│Download (Cur/Avg/Tot): 353B / 201B / 2MB     │
│Upload (Cur/Avg/Tot): 1KB / 389B / 4MB        │
│Version: 0.4.9.11                             │
│                                              │
│                              ░░░░░░░░        │
│                             ░╔══════╗░   █▄  │
│             ▌▌              ░║ EXIT ║░ █████ │
│             ▓▓▀             ░╚══════╝░   █▀  │
│         ▄▄▄▀▀▀▀▄▄▄           ░░░░░░░░        │
│        █   ─  ─    ▄▄▄▄▄                     │
│       █    ▄  ▄   █  █  █                    │
│      █     ▀  ▀  █  ▀█▀  █  ╓───┬───╖╤═══╕   │
│ ____ █      ──    █  █  █   ║---│---║╧╤══╧╤  │
││oV2o│█             ▀▀▀▀▀    ║---│---║╒╧══╤╧  │
│╘════╛ █▄▄▄▄▄▄▄▄▄▄▄▄█        ╙───┴───╜╘═══╧   │
└───────────────────────|Home│Status│Hints│Quit┘

The top of the viewport contains various information about your relay. More specifically:

• The relay nickname as defined in your Tor configuration
• The uptime since the Tor daemon has started
• The number of connections
  • NEW: We have received a new incoming OR connection, and are starting the server-side handshake
  • LAUNCHED: We have launched a new outgoing OR connection, and are starting the client-side handshake
  • CONNECTED: The OR connection has been connected and the handshake is done
  • FAILED: Our attempt to open the OR connection failed
  • CLOSED: The OR connection closed in an unremarkable way
• The current, average and total amount of data that was downloaded and uploaded
• The version of the Tor binary

You can always come back home by pressing H, and quit the app using Q.

Biology

Tamagonions are very attuned to a relay's operation. You can know how your relay is going by looking at how Stinky is feeling or behaving.

Room status check

Stinky's room can get a bit crowded with things it collected along the way. But everything it collects means something special to it.

Status check

To get an explanation of Stinky's state, press S and you will be shown details about the reason behind its behaviour.

┌──────────────────────────────────────────────┐
│┌Status──────────────────────────────────────┐│
││Network liveness: Live                      ││
││Bootstrap progress: 100%                    ││
││Enough directory info: Yes                  ││
││Good server descriptor: Yes                 ││
││Reachability: Reachable                     ││
││Version status: none recommended            ││
││Flags: Exit, Fast, Guard, HSDir, Running    ││
││       V2Dir, Valid                         ││
││                                            ││
││                                            ││
││                                            ││
││                                            ││
││                                            ││
││                                            ││
││                                            ││
││                                            ││
│└────────────────────────────────────────────┘│
└───────────────────────|Home│Status│Hints│Quit┘

Caretaking hints

To get hints on how to address the various states of Stinky, press I. Use U and D to scroll.

┌──────────────────────────────────────────────┐
│┌Hints───────────────────────────────────────┐│
││Missing Stable flag: Your relay has         ││
││not been up for long enough or its mean time││
││between failure is too low. Is the Tor      ││
││process occasionally crashing? Is your      ││
││server rebooting? Is your network stable?   ││
││                                            ││
││Missing Fast flag: Your relay               ││
││doesn't have enough bandwidth to build high-││
││bandwidth circuits. Fit a bigger pipe, or   ││
││accept that your relay will be underused.   ││
││                                            ││
││                                            ││
││                                            ││
││                                            ││
││                                            ││
││                                            ││
│└──────────────────────|Scroll up|Scroll down┘│
└───────────────────────|Home│Status│Hints│Quit┘

Adjusting the viewport

Here are a few examples of how you could typically launch Tamagonion:

# If you are using Kitty, you can start a new terminal running only tamagonion with the correct dimensions
$ TAMAGONION_PASSWORD=my_password kitty --override remember_window_size=no --override initial_window_width=48c --override initial_window_height=20c tamagonion

# If you are using tmux, you can add a bind as such to create a popup that will quickly show you tamagonion
echo 'bind-key T display-popup -E -w 50 -h 22 -x R -y S -- env TAMAGONION_PASSWORD=my_password /home/user/.pyenv/shims/tamagonion' >> ~/.tmux.conf

# Or if you want a permanent split
pane=$(tmux split-window -h -d -l 48 -P -F '#{pane_id}'); tmux split-window -v -d -l 20 -t "$pane" env TAMAGONION_PASSWORD=my_password tamagonion

You may also like...

• Testing Tor Network - CLI tool to setup a testing TOR network with Docker
• Tor HashedControlPassword Brute - C program to execute a dictionary attack against a Tor HashedControlPassword value

This repository contains no AI-generated code and was made with ❤️ by @daxAKAhackerman