CheckCircuit is a small command-line program as an executable that is able to check whether a tor instance has an established circuit. CheckCircuit is designed to connect to the tor OR port, optionally protected by a password, and then accept in turn TCP connections from client on a listening IP address. When a client connects to the TCP server of CheckCircuit, then CheckCircuit will pass a value to the client that indicates whether the tor instance that it is connected to has an established circuit.

The main necessity for this program is justified by the need to scale up tor instances that also need a strong and reliable check that individual tor instances are running and that clients are able to connect in order to proxy traffic though the tor instance.

This program could perhaps be replaced by a shell script or even better, a node.js or python script but that will require the interpreter to be installed such that "CheckCircuit" provides a binary solution for all platforms that consists in one single bundle and is ready to be pulled in by containerization or clustering solutions such as Docker.

Lastly, tor refuses to open up the control port on the ANY address, which makes the control port unusable for containerization solutions such as Docker where the internal IP addresses of the container are irrelevant and in such cases, "CheckCircuit" functions as a bridge and exposes the control port to the local network.

• CheckCircuit

You can check out the source using the Subversion URL:

• https://svn.grimore.org/CheckCircuit

The bundle for the given architecture can be downloaded from the download link and then unpacked somewhere in the path. On Windows, this is typically C:\Windows\System32 but the PATH environment variable can be altered in order to include a directory where the bundle would have been extracted.

After extracting the bundle, the CheckCircuit.exe or CheckCircuit binary can be ran from a terminal or command line prompt (on Windows) and, without any parameters, the command will display a quick help message detailing the syntax.

In principle, the command would be ran similar to the following:

CheckCircuit -l 192.168.1.100:5000 -c 127.0.0.1:8050 -p tor

where:

• 192.168.1.100:5000 represents the local IP address and port to listen to,
• 127.0.0.1:8050 represents the remote tor control port instance to connect to,
• tor is the tor control-port password

Note that for this to work, tor must be configured to open up the control port, with an example configuration that matches the above command, similar to the following:

ControlPort 8050
HashedControlPassword 16:9F840FFC85EF83CE60469C431DC9FF43DB889305B7653C2CB653302594

where:

• 16:9F840FFC85EF83CE60469C431DC9FF43DB889305B7653C2CB653302594 is the tor control port password (in this case, the hash corresponds to the string tor)

CheckCircuit was released on the 6th of March 2025 and is licensed under the MIT license.

Credits for the icons goes to flaticons.com.